How haowang-astro/jetsimpy works
Project type and purpose
• jetsimpy is a scientific computation library (Python package) that wraps a high-performance C++ simulation engine for modeling relativistic blastwaves and GRB afterglows.
• It is not a web or full-stack app, but rather a hybrid Python/C++ extension module with a plugin-style design for custom radiation models.
File structure
Top level:
• setup.py, pyproject.toml – Python packaging and build integration.
• docs/ – Sphinx-based documentation source.
• examples/ – User-facing example scripts.
• jetsimpy/ – The Python package and C++ source.
– Python wrappers and shortcuts (_grid.py, _jet_type.py, _jetsimpy.py, _shortcut.py).
– src/ – C++ engine:
• Afterglow/ (afterglow.cpp/h, blast.h, eats.cpp/h, models.cpp/h)
• Hydro/ (sim_box, interpolate, tools)
• Math/ (integral, optimize, root)
• binding.cpp, jetsimpy.cpp/h, environment.h – glue and environment definitions.
README for technical stack and extensibility points
• Core simulation in C++ with user-selectable “radiation models” implemented in models.cpp.
• Python API provides functions like FluxDensity_gaussian.
• Build and install via pip / setup.py.
• Documentation hosted via ReadTheDocs (Sphinx config in docs/).
Main components
a. User Layer
– Example scripts & user code (examples/*.py)
– Interactive sessions (noted as “User” or “CLI”)
b. Python API Layer (jetsimpy/*.py)
– High-level functions (FluxDensity_*, SkyMap, etc.)
– Data-structure helpers (_grid, _jet_type)
c. Binding Layer
– binding.cpp + jetsimpy.cpp/h – pybind11 (or Python C-API) glue
d. C++ Simulation Core
– Afterglow module (physics of blast wave)
– Hydro module (hydrodynamic simulation tools)
– Math module (numerical routines)
– Environment definitions
– Custom model plug-in point (models.cpp)
e. Build & Packaging
– setup.py / pyproject.toml
– Extension compilation step
f. Documentation & Examples
– Sphinx (docs/source/*.rst)
– Hosted on ReadTheDocs
Relationships and data flow
1. User code → Python API
2. Python API calls → Binding Layer
3. Binding Layer invokes → C++ Core modules
4. C++ Core returns computed arrays/results → Binding Layer → Python API → User
Architectural patterns & design principles
• Layered architecture: clear separation of concerns
• Plugin extensibility: custom radiation models in C++
• Reuse of numerical libraries internally (Math module)
• Standard Python packaging for distribution