# c-kj/athena architecture

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

- Interactive diagram: https://gitdiagram.com/c-kj/athena
- Repository: https://github.com/c-kj/athena

## Overview

##### Project Type and Purpose
- Athena++ is a high-performance, command-line astrophysical simulation framework written in C++.
- It implements adaptive mesh refinement (AMR), general-relativistic magnetohydrodynamics (GRMHD), radiation transport, cosmic rays, chemistry, gravity solvers, and more.
- It ships as a CLI-driven executable (`main.cpp`) plus a suite of post-processing Python/Visit scripts under `vis/`.

##### High-Level Architectural Overview
- At its core is the “Athena” library (all code under `src/`), organized into physics plugins, mesh and AMR managers, I/O layers, and a task scheduler.
- The top-level executable (`main.cpp`) reads inputs, initializes global state, constructs the mesh and blocks, schedules per-block tasks, advances the solution in time, and writes outputs.
- A separate “pgen” tool under `src/pgen/` generates initial conditions (Athena input files).
- Regression tests (`tst/`) drive containerized builds and sample problem runs.
- Visualization scripts (`vis/`) in Python or Visit format consume output files.

##### Key Components
A. Entry Point & Configuration
- main.exe (main.cpp)
- Parameter reader (`parameter_input.cpp`)
- Build system / configure / Makefile
B. Mesh & AMR
- Mesh manager (`src/mesh/`)
- MeshBlock tree & load balancing
- Multigrid driver (`src/multigrid/`)
C. Physics Modules (each compiled into the core library)
- Hydrodynamics (`src/hydro/`)
- Magnetohydrodynamics (`src/mhd/`)
- General relativity support (`src/hydro_gr/`, `src/mhd_gr/`)
- Radiation transport (NR, IM) (`src/nr_radiation/`, `src/chem_rad/`)
- Cosmic rays (`src/cr/`, `src/crdiffusion/`)
- Chemistry (`src/chemistry/`)
- Equation of state (`src/eos/`)
- Gravity (`src/gravity/`)
- Orbital advection (`src/orbital_advection/`)
D. Task Scheduler & Integrators
- Task list & time integrator (`src/task_list/`)
- Flux solvers & Riemann solvers (`src/hydro/rsolvers/`, `src/hydro/srcterms/`)
E. I/O & Output
- HDF5 / VTK wrappers (`src/inputs/`, `src/outputs/`)
- ASCII / table reader
- Restart & history outputs
F. External Dependencies
- MPI (parallel decomposition)
- HDF5 (binary output)
- FFTW / MPI-FFT (`src/fft/`)
- CVODE (chemistry integrators)
- Python (visualization)
G. Auxiliary Tools
- pgen initial-condition generator (`src/pgen/`)
- Regression test harness (`tst/`)
- Style and CI scripts (`.github/`, `tst/style/`, container scripts)

##### Relationships & Data Flow
- main.exe reads parameters → constructs Mesh & MeshBlocks → invokes Task Scheduler
- Task Scheduler dispatches physics modules on each MeshBlock in time-stepping loops
- Physics modules compute fluxes, source terms, boundary conditions (via `src/bvals/`)
- Mesh & AMR modules refine/coarsen blocks as needed
- Multigrid is invoked for Poisson solves (self-gravity)
- I/O modules serialize block state at output times to HDF5/VTK
- pgen generates Athena input files consumed by main.exe
- vis/python scripts ingest HDF5/VTK for post-processing

##### Architectural Patterns & Design Principles
- Modular plugin-style organization: each physics component lives in its own directory and adheres to a common interface (e.g., `Init`, `ComputeFlux`, `ApplySource`).
- Hierarchical AMR: a tree of MeshBlocks supporting dynamic refinement; use of load balancer.
- Task graph / scheduler pattern: tasks are registered in `task_list` and executed in a deterministic sequence.
- MPI-parallel, domain-decomposed grid.
- Separation of concerns: physics, mesh, I/O, utilities.

##### Essential Elements
- Clear component labels (e.g., “Hydro Module”, “MeshRefine”)
- Notes on external libraries and file formats

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry Point & Configuration
    subgraph "Entry & Configuration"
        direction TB
        MainExe["main.exe"]:::core
        ParamReader["Parameter Reader"]:::core
        Makefile["Makefile.in"]:::core
        Configure["configure.py"]:::core
    end

    %% Mesh & AMR
    subgraph "Mesh & AMR" 
        direction TB
        MeshMgr["Mesh Manager"]:::core
        AMRRefine["AMR Refinement"]:::core
        MeshBlockTree["MeshBlock Tree & Load Balancing"]:::core
        MultiGrid["Multigrid Driver"]:::core
    end

    %% Physics Modules
    subgraph "Physics Plugins"
        direction TB
        Hydro["Hydrodynamics Module"]:::core
        MHD["Magnetohydrodynamics Module"]:::core
        GRHydroEOS["GR Hydro EOS Hooks"]:::core
        RadiationNR["Radiation Transport (NR)"]:::core
        RadiationIM["Radiation Transport (IM)"]:::core
        CosmicRays["Cosmic Rays"]:::core
        Chemistry["Chemistry Module"]:::core
        EOS["Equation of State"]:::core
        GravitySolvers["Gravity Solvers"]:::core
        OrbitalAdv["Orbital Advection"]:::core
    end

    %% Task Scheduler & Integrators
    subgraph "Task Scheduler & Integrators"
        direction TB
        TaskList["Task List & Scheduler"]:::core
        TimeIntegrator["Time Integrator"]:::core
    end

    %% I/O & Output
    subgraph "I/O & Output"
        direction TB
        InputReaders["Input Readers (ASCII/HDF5)"]:::core
        OutputWriters["Output Writers (HDF5/VTK/Restart/History)"]:::core
    end

    %% External Dependencies & Utilities
    subgraph "External Dependencies & Utilities"
        direction TB
        MPI["MPI"]:::ext
        HDF5["HDF5"]:::ext
        FFTW["FFTW"]:::ext
        CVODE["CVODE"]:::ext
        Utils["Utilities"]:::core
    end

    %% Auxiliary Tools
    subgraph "Auxiliary Tools & Scripts"
        direction TB
        PGen["pgen (IC Generator)"]:::tools
        Regression["Regression Test Harness"]:::tools
        CI["Style & CI Scripts"]:::tools
        VisScripts["Visualization Scripts"]:::tools
    end

    %% Connections
    MainExe -->|"reads parameters"| ParamReader
    MainExe -->|"initializes mesh"| MeshMgr
    MainExe -->|"invokes scheduler"| TaskList
    TaskList -->|"dispatches tasks"| Hydro
    TaskList --> MHD
    TaskList --> RadiationNR
    TaskList --> RadiationIM
    TaskList --> CosmicRays
    TaskList --> Chemistry
    Hydro -->|"uses EOS"| EOS
    Hydro -->|"uses Riemann solvers"| MHD
    MeshMgr --> AMRRefine
    MeshMgr --> MeshBlockTree
    MeshBlockTree --> MPI
    MultiGrid -->|"Poisson solves"| GravitySolvers
    GravitySolvers --> FFTW
    PhysicsPluginsIncomplete{skip} 
    RadiationNR --> CVODE
    InputReaders --> MainExe
    MainExe --> OutputWriters
    OutputWriters --> VisScripts
    PGen -->|"generates inputs"| MainExe
    Regression --> MainExe

    %% Click Events
    click MainExe "https://github.com/c-kj/athena/blob/master/src/main.cpp"
    click ParamReader "https://github.com/c-kj/athena/blob/master/src/parameter_input.cpp"
    click Makefile "https://github.com/c-kj/athena/blob/master/Makefile.in"
    click Configure "https://github.com/c-kj/athena/blob/master/configure.py"
    click MeshMgr "https://github.com/c-kj/athena/blob/master/src/mesh/mesh.cpp"
    click AMRRefine "https://github.com/c-kj/athena/blob/master/src/mesh/mesh_refinement.cpp"
    click MeshBlockTree "https://github.com/c-kj/athena/blob/master/src/mesh/meshblock_tree.cpp"
    click MultiGrid "https://github.com/c-kj/athena/blob/master/src/multigrid/multigrid_driver.cpp"
    click Hydro "https://github.com/c-kj/athena/blob/master/src/hydro/hydro.cpp"
    click RadiationNR "https://github.com/c-kj/athena/blob/master/src/nr_radiation/radiation.cpp"
    click RadiationIM "https://github.com/c-kj/athena/blob/master/src/chem_rad/chem_rad.cpp"
    click CosmicRays "https://github.com/c-kj/athena/blob/master/src/cr/cr.cpp"
    click Chemistry "https://github.com/c-kj/athena/blob/master/src/chemistry/cvode.cpp"
    click EOS "https://github.com/c-kj/athena/blob/master/src/eos/adiabatic_hydro_gr.cpp"
    click GravitySolvers "https://github.com/c-kj/athena/blob/master/src/gravity/gravity.cpp"
    click TaskList "https://github.com/c-kj/athena/blob/master/src/task_list/task_list.cpp"
    click TimeIntegrator "https://github.com/c-kj/athena/blob/master/src/task_list/time_integrator.cpp"
    click InputReaders "https://github.com/c-kj/athena/blob/master/src/inputs/ascii_table_reader.cpp"
    click OutputWriters "https://github.com/c-kj/athena/blob/master/src/outputs/athena_hdf5.cpp"
    click PGen "https://github.com/c-kj/athena/tree/master/src/pgen/"
    click Regression "https://github.com/c-kj/athena/tree/master/tst/regression/"
    click CI "https://github.com/c-kj/athena/tree/master/.github/"
    click VisScripts "https://github.com/c-kj/athena/blob/master/vis/python/athena_read.py"

    %% Styles
    classDef core fill:#B3CDE3,stroke:#03496F,color:#03496F
    classDef ext fill:#FBB4AE,stroke:#B10026,color:#B10026
    classDef tools fill:#C7E9C0,stroke:#006D2C,color:#006D2C
```
