# afd-illinois/ebhlight architecture

> Architecture diagram of the GitHub repository afd-illinois/ebhlight, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/afd-illinois/ebhlight
- Repository: https://github.com/afd-illinois/ebhlight

## Overview

##### Project Type and Purpose
- This is a high-performance scientific simulation code (“EBHLIGHT/BHLIGHT”) for general relativistic radiation magnetohydrodynamics (GRRMHD) using Monte Carlo radiation transport.
- Core is written in C99 with MPI/HDF5 parallel I/O; Python 3.6 is used for build configuration, machine-specific setup, analysis, and testing.

##### File-Structure Analysis
- Top-level:
- core/            – Simulation engine: physics modules (metric, fluid integration, radiation, interactions), I/O, MPI support, utilities, main driver.
- prob/            – Problem directories: each subfolder (e.g., sod, bondi, torus) has a build.py that assembles core + problem.c into a problem-specific executable.
- script/          – Python scripts:
– machine/     – Cluster/machine-specific compile settings.
– analysis/    – Post-processing (plots, diagnostics) of HDF5 outputs.
– bhlight.py, config.py, util.py  – Glue for build & invocation.
- test/            – Python test harnesses for regressions; each test calls a problem run and compares to analytic/data.
- Build artifacts and config:
- build.py (per problem) invokes bhl.config to set compile-time & runtime parameters, writes makefile, calls make.
- VERSION, LICENSE, .gitignore at root.
- External dependencies spotted:
- GSL, MPI, Parallel HDF5 for core.
- Python libs: matplotlib, numpy, h5py for scripts.

##### Key Insights from README
- Separation of concerns: fluid solver (HARM), radiation solver (GRMONTY), operator-split coupling.
- Runtime: executable reads param.dat via -p flag, outputs HDF5 dumps/ and restarts/.
- Tests automate runs of various problems and plot results.
- Build scripts manage machine-specific flags and gather sources.

##### Detailed Notes
- For each problem, show “Problem Definition → Build Script → Linked into Core” as repeating pattern.
- Machine abstraction layer for compiler flag management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Config Layer
    subgraph "Build & Config Layer"
        direction TB
        PB["Problem Builder (provj)"]:::python
        BW["bhlight.py"]:::python
        CF["config.py"]:::python
        UT["util.py"]:::python
        MC["Machine Configs"]:::python
    end

    %% Core Simulation Engine
    subgraph "Core Simulation Engine"
        direction TB
        CE["Core Engine"]:::cmod
        subgraph "Physics Modules"
            direction TB
            MTR["metric.c"]:::cmod
            FLD1["step.c"]:::cmod
            FLD2["reconstruction.c"]:::cmod
            FLD3["phys.c"]:::cmod
            RAD1["radiation.c"]:::cmod
            RAD2["make_superphotons.c"]:::cmod
            RAD3["push_superphotons.c"]:::cmod
            INT1["interact.c"]:::cmod
            INT2["emissivity.c"]:::cmod
            INT3["scattering.c"]:::cmod
            EOS["electrons.c"]:::cmod
            RNG["random.c"]:::cmod
        end
        subgraph "Infrastructure Modules"
            direction TB
            MPI["mpi.c"]:::cmod
            IO1["io.c"]:::cmod
            IO2["io.h"]:::cmod
            IO3["xdmf_output.c"]:::cmod
            TMG["timing.c"]:::cmod
            UTL["utils.c"]:::cmod
            MAIN["main.c"]:::cmod
        end
    end

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        LIBMPI["MPI"]:::external
        LIBH5["Parallel HDF5"]:::external
        LIBGSL["GSL"]:::external
    end

    %% Executable
    EXE["bhlight Executable"]:::cmod

    %% Run & Data Layer
    subgraph "Run & Data"
        direction TB
        PARAM["param.dat"]:::io
        MPI_RUN["MPI Runtime"]:::cmod
        H5D["HDF5 Outputs & Restarts"]:::io
    end

    %% Analysis Layer
    subgraph "Analysis Scripts"
        direction TB
        AP1["plot.py"]:::python
        AP2["diag.py"]:::python
        AP3["spec.py"]:::python
        AM1["movie.py"]:::python
        AM2["snap.py"]:::python
        AH1["hdf5_to_dict.py"]:::python
        AH2["hdr.py"]:::python
    end

    %% Test Harness
    subgraph "Test Harness"
        direction TB
        TT["test_auto.py"]:::test
        TB1["bondi.py"]:::test
        TB2["sod.py"]:::test
        TB3["mhdmodes1d.py"]:::test
        TM1["sod_mpi.py"]:::test
        TM2["mhdmodes2d_mpi.py"]:::test
        TM3["thermalization_mpi.py"]:::test
        TDAT["kshocks.txt"]:::test
    end

    %% Problem Examples
    subgraph "Problems"
        direction TB
        PB1["bondi/build.py"]:::python
        PP1["bondi/problem.c"]:::cmod
        PB2["sod/build.py"]:::python
        PP2["sod/problem.c"]:::cmod
        PB3["thermalization/build.py"]:::python
        PP3["thermalization/problem.c"]:::cmod
    end

    %% Connections - Build Phase
    PB1 & PB2 & PB3 -->|uses| CE
    PB1 & PB2 & PB3 -->|uses| LIBMPI
    PB1 & PB2 & PB3 -->|uses| LIBH5
    PB1 & PB2 & PB3 -->|uses| LIBGSL
    BW & CF & UT & MC -->|configures| PB1 & PB2 & PB3

    CE -->|compiles/libs| EXE

    %% Run & Data Flows
    EXE -->|reads| PARAM
    EXE -->|launches| MPI_RUN
    MPI_RUN -->|writes| H5D

    %% Analysis Flow
    H5D -->|input| AP1 & AP2 & AP3 & AM1 & AM2 & AH1 & AH2

    %% Testing Flow
    TT -->|invokes| PB1 & PB2 & PB3
    TT -->|runs| EXE
    TT -->|analyzes| AP1
    TT -->|compares| TDAT

    %% Class Definitions
    classDef cmod fill:#ADD8E6,stroke:#000;
    classDef python fill:#98FB98,stroke:#000;
    classDef io fill:#FFA500,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;
    classDef test fill:#DDA0DD,stroke:#000;

    %% Click Events - Core Simulation Engine
    click CE "https://github.com/afd-illinois/ebhlight/tree/master/core/"
    click MTR "https://github.com/afd-illinois/ebhlight/blob/master/core/metric.c"
    click FLD1 "https://github.com/afd-illinois/ebhlight/blob/master/core/step.c"
    click FLD2 "https://github.com/afd-illinois/ebhlight/blob/master/core/reconstruction.c"
    click FLD3 "https://github.com/afd-illinois/ebhlight/blob/master/core/phys.c"
    click RAD1 "https://github.com/afd-illinois/ebhlight/blob/master/core/radiation.c"
    click RAD2 "https://github.com/afd-illinois/ebhlight/blob/master/core/make_superphotons.c"
    click RAD3 "https://github.com/afd-illinois/ebhlight/blob/master/core/push_superphotons.c"
    click INT1 "https://github.com/afd-illinois/ebhlight/blob/master/core/interact.c"
    click INT2 "https://github.com/afd-illinois/ebhlight/blob/master/core/emissivity.c"
    click INT3 "https://github.com/afd-illinois/ebhlight/blob/master/core/scattering.c"
    click EOS "https://github.com/afd-illinois/ebhlight/blob/master/core/electrons.c"
    click RNG "https://github.com/afd-illinois/ebhlight/blob/master/core/random.c"
    click MPI "https://github.com/afd-illinois/ebhlight/blob/master/core/mpi.c"
    click IO1 "https://github.com/afd-illinois/ebhlight/blob/master/core/io.c"
    click IO2 "https://github.com/afd-illinois/ebhlight/blob/master/core/io.h"
    click IO3 "https://github.com/afd-illinois/ebhlight/blob/master/core/xdmf_output.c"
    click TMG "https://github.com/afd-illinois/ebhlight/blob/master/core/timing.c"
    click UTL "https://github.com/afd-illinois/ebhlight/blob/master/core/utils.c"
    click MAIN "https://github.com/afd-illinois/ebhlight/blob/master/core/main.c"

    %% Click Events - Problem Examples
    click PB1 "https://github.com/afd-illinois/ebhlight/blob/master/prob/bondi/build.py"
    click PP1 "https://github.com/afd-illinois/ebhlight/blob/master/prob/bondi/problem.c"
    click PB2 "https://github.com/afd-illinois/ebhlight/blob/master/prob/sod/build.py"
    click PP2 "https://github.com/afd-illinois/ebhlight/blob/master/prob/sod/problem.c"
    click PB3 "https://github.com/afd-illinois/ebhlight/blob/master/prob/thermalization/build.py"
    click PP3 "https://github.com/afd-illinois/ebhlight/blob/master/prob/thermalization/problem.c"

    %% Click Events - Python Layer
    click BW "https://github.com/afd-illinois/ebhlight/blob/master/script/bhlight.py"
    click CF "https://github.com/afd-illinois/ebhlight/blob/master/script/config.py"
    click UT "https://github.com/afd-illinois/ebhlight/blob/master/script/util.py"
    click MC "https://github.com/afd-illinois/ebhlight/tree/master/script/machine/"

    %% Click Events - Analysis Scripts
    click AP1 "https://github.com/afd-illinois/ebhlight/blob/master/script/analysis/plot.py"
    click AP2 "https://github.com/afd-illinois/ebhlight/blob/master/script/analysis/diag.py"
    click AP3 "https://github.com/afd-illinois/ebhlight/blob/master/script/analysis/spec.py"
    click AM1 "https://github.com/afd-illinois/ebhlight/blob/master/script/analysis/movie.py"
    click AM2 "https://github.com/afd-illinois/ebhlight/blob/master/script/analysis/snap.py"
    click AH1 "https://github.com/afd-illinois/ebhlight/blob/master/script/analysis/hdf5_to_dict.py"
    click AH2 "https://github.com/afd-illinois/ebhlight/blob/master/script/analysis/hdr.py"

    %% Click Events - Test Harness
    click TT "https://github.com/afd-illinois/ebhlight/blob/master/test/test_auto.py"
    click TB1 "https://github.com/afd-illinois/ebhlight/blob/master/test/bondi.py"
    click TB2 "https://github.com/afd-illinois/ebhlight/blob/master/test/sod.py"
    click TB3 "https://github.com/afd-illinois/ebhlight/blob/master/test/mhdmodes1d.py"
    click TM1 "https://github.com/afd-illinois/ebhlight/blob/master/test/sod_mpi.py"
    click TM2 "https://github.com/afd-illinois/ebhlight/blob/master/test/mhdmodes2d_mpi.py"
    click TM3 "https://github.com/afd-illinois/ebhlight/blob/master/test/thermalization_mpi.py"
    click TDAT "https://github.com/afd-illinois/ebhlight/blob/master/test/data/kshocks.txt"
```
