How c-kj/athena works
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