Developer onboarding notes

What Quokka is built to do

  • Radiation hydrodynamics on AMReX. Quokka targets multi-physics astrophysical simulations using the AMReX adaptive mesh refinement framework, providing two-moment radiation transport, hydrodynamics, and optional MHD capabilities in a single-source C++17 codebase (README.md).
  • Modular simulation core. The AMRSimulation base class orchestrates time stepping, refinement, and I/O, while QuokkaSimulation adds domain-specific toggles for radiation, cooling, chemistry, and MHD support that downstream problems can enable selectively (simulation.hpp, QuokkaSimulation.hpp).

Repository tour

  • src/
    • Framework layer. simulation.hpp defines AMRSimulation, the central driver that manages AMReX state, time stepping, outputs, and particle infrastructure (simulation.hpp).
    • Physics modules. Hydrodynamics, radiation, MHD, chemistry, and cooling each live in subdirectories such as hydro/, radiation/, and cooling/, which are wired into QuokkaSimulation via the Physics_Traits mechanism (QuokkaSimulation.hpp).
    • Problem drivers. Each scenario in src/problems/ defines a problem_t type, customises traits, sets initial conditions, and then instantiates QuokkaSimulation to run; see src/problems/OrszagTang/test_orszag_tang.cpp for a representative setup.
  • inputs/
    • Runtime parameter files that pair with problem drivers; regression entries reference them directly when defining automated tests (regression/quokka-tests.ini).
  • regression/
    • The regression harness (quokka-tests.ini) enumerates long-running GPU test suites, including MPI launch commands, linked data files, and which executables to build (regression/quokka-tests.ini).
  • docs/
    • Source for the published documentation site (MkDocs). The landing page summarises Quokka’s goals and AMReX integration, and additional pages cover workflow diagrams, testing, debugging, and performance topics (site overview, simulation flowchart, test catalog).

Execution flow in practice

  • Start-up: main.cpp initialises AMReX, then calls problem_main() declared in main.hpp and implemented by each problem driver (main.cpp, main.hpp).
  • Simulation lifecycle: the flowchart documentation page mirrors the control flow of AMRSimulation::setInitialConditions, evolve, and computeTimestep, showing the nested loops for hydrodynamics stages and radiation subcycling (flowchart overview).
  • Custom physics: problem-specific traits determine which subsystems QuokkaSimulation activates (e.g., MHD, radiation groups, chemistry), and each problem supplies initial conditions (cells and face-centered fields) before calling sim.evolve() (QuokkaSimulation.hpp, test_orszag_tang.cpp).

Build, test, and quality checks

  • Build locally. Follow the installation guide to clone with submodules, configure with CMake (Ninja or Make), and choose the desired dimensionality and accelerator backend (installation guide).
  • Automated tests. ninja test or ctest exercises the bundled problem suite; for full GPU coverage, rely on the regression harness described earlier (installation guide, quokka-tests.ini).
  • Static analysis. Run clang-tidy manually or via scripts/tidy.sh to match the repository’s CI checks, as documented in the How to Use clang-tidy guide (clang-tidy how-to).

Where to dive deeper next

  1. Physics modules. Explore src/hydro/ and src/radiation/ alongside the corresponding documentation pages (hydro_integrator.md, radiation topics) to understand scheme implementations (QuokkaSimulation.hpp, overview page).
  2. Problem setups. Study more drivers in src/problems/ and the matching documentation in the Tests section to see how diagnostic comparisons are scripted (test_orszag_tang.cpp, test index).
  3. Performance & HPC workflows. The GPU section in the installation guide plus the Running on HPC Clusters page outline how to scale to accelerators and clusters (installation guide, HPC guide).
  4. Contribution process. Pair the coding standards baked into clang-tidy with the community guidance in the Contributing guide when preparing patches (and review CONTRIBUTING.md at the repo root) (clang-tidy how-to, contribution guide).

Armed with the overview above, a newcomer can pick a problem driver, follow the build instructions, and iterate confidently while leaning on the documentation site for deeper dives.