# achael/koral_lite architecture

> Architecture diagram of the GitHub repository achael/koral_lite, 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/achael/koral_lite
- Repository: https://github.com/achael/koral_lite

## Overview

##### Project type and purpose
- Koral_lite is a high-performance scientific simulation code for two-temperature, radiative general relativistic magnetohydrodynamics (GRMHD).
- Written in C, it uses MPI for parallelization, HDF5/SILO for I/O, and reads precomputed opacity tables.

##### File structure
- Top-level C sources implement core functionality:
- problem.c/h – problem definitions & dispatch
- finite.c, metric.c, physics.c, nonthermal.c, opacities.c – numerical & physics modules
- mpi.c – parallel decomposition & communication
- fileop.c, silo.c, dumps2hdf5.c, hdf52dumps.c – output drivers
- postproc.c, avg.c, outavg.c, frames.c, regrid.c – postprocessing & grid management
- utility scripts mpar.sh, mser.sh – job submission wrappers
- OPACITIES directory holds data tables (CHIANTI, Sutherland_Dopita_1993) consumed by the opacity module.
- PROBLEMS directory contains legacy problem setups (initial condition codelets), most removed or deprecated.
- Makefile orchestrates the build; LICENSE & .gitignore are ancillary.

##### README for additional insights
- “Lighter” version of KORAL, older problem definitions not tested.
- Core code focuses on a time-stepping loop for GRMHD with radiation, two fluid temperatures.

##### Elements
- Clear labels for each component block (Input, Physics, Solver, I/O, Postproc, Data).
- Config → Init → Solver Core
- Solver Core ↔ MPI Communication
- Solver Core → I/O Subsystem → Filesystem
- External Tables → Opacity Module
- I/O Files → Postprocessing Tools
- Blue rectangles for compute modules (Solver, Physics),
- Green for I/O (HDF5/SILO),
- Orange for data (OPACITIES),
- Diamond for control flow start/end,

##### Detailed flow chart of koral_lite
- Start (parameter & script invocation)
↓
- Read parameters & select problem (problem.c)
↓
- Load external tables (opacities.c reads OPACITIES/*)
↓
- Initialize grid & metric (regrid.c, metric.c)
↓
- Initialize physical fields (problem-specific init.c)
↓
- Enter time-stepping loop:
- Compute fluxes (finite.c, phiavg.c, phisli.c)
- Apply source terms (physics.c, nonthermal.c)
- MPI halo exchange (mpi.c)
- Update conserved variables (u2p.c, p2u.c, u2prad.c)
- Every N steps: invoke I/O
– dumps2hdf5.c → HDF5 file
– silo.c → SILO file
– fileop.c → ASCII dumps
- Check for end time or stopping criteria
↓
- Exit loop, finalize (close files, MPI_Finalize)
↓
- Optionally run postprocessing (postproc.c, avg.c, frames.c)
↓
- End

## Diagram (Mermaid)

```mermaid
flowchart TD
    Start(("Start")):::control
    Start --> InputConfig

    subgraph "Input & Configuration"
        InputConfig["Input & Configuration"]:::config
        mpar["mpar.sh"]:::script
        mser["mser.sh"]:::script
        problemC["problem.c"]:::code
        problemH["problem.h"]:::code
        choices["choices.h"]:::code
    end
    InputConfig --> ExtData

    subgraph "External Data Tables"
        ExtData["External Data Tables"]:::data
        chianti[(CHIANTI)]:::data
        sd93[(Sutherland_Dopita_1993)]:::data
    end
    ExtData --> GridInit

    subgraph "Grid & Metric Initialization"
        GridInit["Grid & Metric Init"]:::compute
        regrid["regrid.c"]:::code
        metric["metric.c"]:::code
    end
    GridInit --> ProblemInit

    subgraph "Problem-specific Initialization"
        ProblemInit["Problem Init"]:::compute
        problems["PROBLEMS/*"]:::code
    end
    ProblemInit --> SolverCore

    subgraph "Solver Core"
        SolverCore["Solver Core"]:::compute
        ko["ko.c"]:::code
        ana["ana.c"]:::code
    end
    SolverCore --> TimeLoopStart(("Enter Time-stepping Loop")):::loop

    subgraph "Time-stepping Loop"
        direction TB
        finite["finite.c"]:::code
        phiavg["phiavg.c"]:::code
        phisli["phisli.c"]:::code
        physics["physics.c"]:::code
        nonthermal["nonthermal.c"]:::code
        opacities["opacities.c"]:::code
        rad["rad.c"]:::code
        u2prad["u2prad.c"]:::code
        p2u["p2u.c"]:::code
        u2p_ff["u2p_ff.c"]:::code
        mpiComm["mpi.c"]:::code

        finite --> phiavg --> phisli
        phisli --> physics --> nonthermal --> opacities --> rad
        rad --> u2prad --> p2u --> u2p_ff
        u2p_ff --> mpiComm --> finite
    end

    TimeLoopStart --> Time-stepping_Loop
    Time-stepping_Loop --> IO

    subgraph "I/O Subsystem"
        IO["I/O Subsystem"]:::io
        silo["silo.c"]:::code
        dumps2hdf5["dumps2hdf5.c"]:::code
        hdf52dumps["hdf52dumps.c"]:::code
        fileop["fileop.c"]:::code
        outavg["outavg.c"]:::code
    end
    IO --> Time-stepping_Loop
    Time-stepping_Loop --> LoopExit(("Exit Loop")):::loop

    LoopExit --> Finalize["Finalize & MPI_Finalize"]:::control
    Finalize --> Postprocessing

    subgraph "Postprocessing & Visualization"
        Postprocessing["Postprocessing"]:::post
        postproc["postproc.c"]:::code
        avg["avg.c"]:::code
        frames["frames.c"]:::code
    end
    Postprocessing --> End(("End")):::control

    %% Click Events
    click mpar "https://github.com/achael/koral_lite/blob/master/mpar.sh"
    click mser "https://github.com/achael/koral_lite/blob/master/mser.sh"
    click problemC "https://github.com/achael/koral_lite/blob/master/problem.c"
    click problemH "https://github.com/achael/koral_lite/blob/master/problem.h"
    click choices "https://github.com/achael/koral_lite/blob/master/choices.h"
    click regrid "https://github.com/achael/koral_lite/blob/master/regrid.c"
    click metric "https://github.com/achael/koral_lite/blob/master/metric.c"
    click problems "https://github.com/achael/koral_lite/tree/master/PROBLEMS/"
    click ko "https://github.com/achael/koral_lite/blob/master/ko.c"
    click ana "https://github.com/achael/koral_lite/blob/master/ana.c"
    click finite "https://github.com/achael/koral_lite/blob/master/finite.c"
    click phiavg "https://github.com/achael/koral_lite/blob/master/phiavg.c"
    click phisli "https://github.com/achael/koral_lite/blob/master/phisli.c"
    click physics "https://github.com/achael/koral_lite/blob/master/physics.c"
    click nonthermal "https://github.com/achael/koral_lite/blob/master/nonthermal.c"
    click opacities "https://github.com/achael/koral_lite/blob/master/opacities.c"
    click rad "https://github.com/achael/koral_lite/blob/master/rad.c"
    click u2prad "https://github.com/achael/koral_lite/blob/master/u2prad.c"
    click p2u "https://github.com/achael/koral_lite/blob/master/p2u.c"
    click u2p_ff "https://github.com/achael/koral_lite/blob/master/u2p_ff.c"
    click mpiComm "https://github.com/achael/koral_lite/blob/master/mpi.c"
    click silo "https://github.com/achael/koral_lite/blob/master/silo.c"
    click dumps2hdf5 "https://github.com/achael/koral_lite/blob/master/dumps2hdf5.c"
    click hdf52dumps "https://github.com/achael/koral_lite/blob/master/hdf52dumps.c"
    click fileop "https://github.com/achael/koral_lite/blob/master/fileop.c"
    click outavg "https://github.com/achael/koral_lite/blob/master/outavg.c"
    click postproc "https://github.com/achael/koral_lite/blob/master/postproc.c"
    click avg "https://github.com/achael/koral_lite/blob/master/avg.c"
    click frames "https://github.com/achael/koral_lite/blob/master/frames.c"
    click chianti "https://github.com/achael/koral_lite/tree/master/OPACITIES/CHIANTI"
    click sd93 "https://github.com/achael/koral_lite/tree/master/OPACITIES/Sutherland_Dopita_1993"

    %% Styles
    classDef compute fill:#E3F2FD,stroke:#0288D1;
    classDef io fill:#C8E6C9,stroke:#2E7D32;
    classDef data fill:#FFE0B2,stroke:#EF6C00;
    classDef control fill:#FFF9C4,stroke:#F9A825;
    classDef script fill:#E1BEE7,stroke:#8E24AA;
    classDef code fill:#BBDEFB,stroke:#1976D2;
    classDef post fill:#FCE4EC,stroke:#C2185B;
    classDef loop fill:#FFCDD2,stroke:#D32F2F;
    classDef config fill:#E8F5E9,stroke:#43A047;
```
