# haowang-astro/jetsimpy architecture

> Architecture diagram of the GitHub repository haowang-astro/jetsimpy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/haowang-astro/jetsimpy
- Repository: https://github.com/haowang-astro/jetsimpy

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer" 
        direction TB
        User["User / CLI"]:::user
        EX1["centroid_motion.py"]:::user
        EX2["customized_radiation_model.py"]:::user
        EX3["light_curves.py"]:::user
        EX4["quick_start.py"]:::user
        EX5["sky_map.py"]:::user
    end

    %% Python API Layer
    subgraph "Python API Layer" 
        direction TB
        API_Init["__init__.py"]:::python
        Grid["_grid.py"]:::python
        JetType["_jet_type.py"]:::python
        Jetsimpy["_jetsimpy.py"]:::python
        Shortcut["_shortcut.py"]:::python
    end

    %% Binding Layer
    subgraph "Binding Layer" 
        direction TB
        BindingCPP["binding.cpp"]:::cplusplus
        JetsimpyCPP["jetsimpy.cpp / jetsimpy.h"]:::cplusplus
    end

    %% C++ Simulation Core
    subgraph "C++ Simulation Core"
        direction TB
        subgraph "Afterglow Module" 
            direction TB
            AG_CPP["afterglow.cpp"]:::cplusplus
            AG_H["afterglow.h"]:::cplusplus
            Blast["blast.h"]:::cplusplus
            EATS_CPP["eats.cpp"]:::cplusplus
            EATS_H["eats.h"]:::cplusplus
            Models_CPP["models.cpp\n(plugin ext)"]:::cplusplus
            Models_H["models.h"]:::cplusplus
        end
        subgraph "Hydro Module" 
            direction TB
            Config["config.h"]:::cplusplus
            Interp_CPP["interpolate.cpp"]:::cplusplus
            Interp_H["interpolate.h"]:::cplusplus
            SimBox_CPP["sim_box.cpp"]:::cplusplus
            SimBox_H["sim_box.h"]:::cplusplus
            Tools_CPP["tools.cpp"]:::cplusplus
            Tools_H["tools.h"]:::cplusplus
        end
        subgraph "Math Module"
            direction TB
            Integral["integral.h"]:::cplusplus
            Optimize["optimize.h"]:::cplusplus
            Root["root.h"]:::cplusplus
        end
        Env["environment.h"]:::cplusplus
    end

    %% Build & Packaging
    subgraph "Build & Packaging"
        direction TB
        Setup["setup.py"]:::build
        PyProj["pyproject.toml"]:::build
        Manifest["MANIFEST.in"]:::build
    end

    %% Documentation & Examples
    subgraph "Documentation & RTD"
        direction TB
        Index["index.rst"]:::docs
        QuickRTD["quickstart.rst"]:::docs
        AfterRTD["afterglow.rst"]:::docs
        HydroRTD["hydro.rst"]:::docs
        CustomRTD["custom.rst"]:::docs
        WeightedRTD["weighted.rst"]:::docs
        Conf["conf.py"]:::docs
        Makefile["Makefile"]:::docs
        RTDConfig[".readthedocs.yaml"]:::docs
    end

    %% Connections
    User -->|runs examples| EX1
    User --> EX2
    User --> EX3
    User --> EX4
    User --> EX5
    EX1 -->|imports| API_Init
    EX2 --> API_Init
    EX3 --> API_Init
    EX4 --> API_Init
    EX5 --> API_Init

    API_Init --> Grid
    API_Init --> JetType
    API_Init --> Jetsimpy
    API_Init --> Shortcut

    Jetsimpy --> BindingCPP
    BindingCPP --> JetsimpyCPP
    JetsimpyCPP --> AG_CPP
    JetsimpyCPP --> AG_H
    JetsimpyCPP --> Blast
    JetsimpyCPP --> EATS_CPP
    JetsimpyCPP --> EATS_H
    JetsimpyCPP --> Models_CPP
    JetsimpyCPP --> Models_H
    JetsimpyCPP --> Config
    JetsimpyCPP --> Interp_CPP
    JetsimpyCPP --> Interp_H
    JetsimpyCPP --> SimBox_CPP
    JetsimpyCPP --> SimBox_H
    JetsimpyCPP --> Tools_CPP
    JetsimpyCPP --> Tools_H
    JetsimpyCPP --> Integral
    JetsimpyCPP --> Optimize
    JetsimpyCPP --> Root
    JetsimpyCPP --> Env

    AG_CPP -->|returns data| JetsimpyCPP
    Interp_CPP --> JetsimpyCPP
    Integral --> JetsimpyCPP

    Setup -->|compiles extension| BindingCPP
    PyProj --> BindingCPP
    Manifest --> BindingCPP

    Index -->|docs build| RTDConfig
    QuickRTD --> RTDConfig
    AfterRTD --> RTDConfig
    HydroRTD --> RTDConfig
    CustomRTD --> RTDConfig
    WeightedRTD --> RTDConfig
    Conf --> Makefile
    Makefile --> RTDConfig

    %% Click Events for component mapping
    click EX1 "https://github.com/haowang-astro/jetsimpy/blob/public/examples/centroid_motion.py"
    click EX2 "https://github.com/haowang-astro/jetsimpy/blob/public/examples/customized_radiation_model.py"
    click EX3 "https://github.com/haowang-astro/jetsimpy/blob/public/examples/light_curves.py"
    click EX4 "https://github.com/haowang-astro/jetsimpy/blob/public/examples/quick_start.py"
    click EX5 "https://github.com/haowang-astro/jetsimpy/blob/public/examples/sky_map.py"
    click API_Init "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/__init__.py"
    click Grid "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/_grid.py"
    click JetType "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/_jet_type.py"
    click Jetsimpy "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/_jetsimpy.py"
    click Shortcut "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/_shortcut.py"
    click BindingCPP "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/binding.cpp"
    click JetsimpyCPP "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/jetsimpy.cpp"
    click JetsimpyCPP "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/jetsimpy.h"
    click AG_CPP "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/Afterglow/afterglow.cpp"
    click AG_H "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/Afterglow/afterglow.h"
    click Blast "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/Afterglow/blast.h"
    click EATS_CPP "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/Afterglow/eats.cpp"
    click EATS_H "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/Afterglow/eats.h"
    click Models_CPP "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/Afterglow/models.cpp"
    click Models_H "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/Afterglow/models.h"
    click Config "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/Hydro/config.h"
    click Interp_CPP "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/Hydro/interpolate.cpp"
    click Interp_H "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/Hydro/interpolate.h"
    click SimBox_CPP "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/Hydro/sim_box.cpp"
    click SimBox_H "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/Hydro/sim_box.h"
    click Tools_CPP "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/Hydro/tools.cpp"
    click Tools_H "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/Hydro/tools.h"
    click Integral "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/Math/integral.h"
    click Optimize "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/Math/optimize.h"
    click Root "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/Math/root.h"
    click Env "https://github.com/haowang-astro/jetsimpy/blob/public/jetsimpy/src/environment.h"
    click Setup "https://github.com/haowang-astro/jetsimpy/blob/public/setup.py"
    click PyProj "https://github.com/haowang-astro/jetsimpy/blob/public/pyproject.toml"
    click Manifest "https://github.com/haowang-astro/jetsimpy/blob/public/MANIFEST.in"
    click Index "https://github.com/haowang-astro/jetsimpy/blob/public/docs/source/index.rst"
    click QuickRTD "https://github.com/haowang-astro/jetsimpy/blob/public/docs/source/quickstart.rst"
    click AfterRTD "https://github.com/haowang-astro/jetsimpy/blob/public/docs/source/afterglow.rst"
    click HydroRTD "https://github.com/haowang-astro/jetsimpy/blob/public/docs/source/hydro.rst"
    click CustomRTD "https://github.com/haowang-astro/jetsimpy/blob/public/docs/source/custom.rst"
    click WeightedRTD "https://github.com/haowang-astro/jetsimpy/blob/public/docs/source/weighted.rst"
    click Conf "https://github.com/haowang-astro/jetsimpy/blob/public/docs/source/conf.py"
    click Makefile "https://github.com/haowang-astro/jetsimpy/tree/public/docs/Makefile"
    click RTDConfig "https://github.com/haowang-astro/jetsimpy/blob/public/.readthedocs.yaml"

    %% Styles
    classDef python fill:#ccf,stroke:#333,stroke-width:1px
    classDef cplusplus fill:#cfc,stroke:#333,stroke-width:1px
    classDef build fill:#eee,stroke:#333,stroke-width:1px
    classDef docs fill:#ddd,stroke:#333,stroke-width:1px
    classDef user fill:#ccf,stroke:#333,stroke-width:1px
```
