# About

<p style="text-align: center;">
  <img
    src="media/quokka-favicon.svg"
    alt="Quokka riding a rocket"
    style="width: min(18rem, 45%); height: auto;"
  >
</p>

<p style="text-align: center;"><em>Quokka riding a rocket</em></p>

Quokka is a high-resolution shock capturing AMR radiation hydrodynamics code using the AMReX library [@AMReX_JOSS] to provide patch-based adaptive mesh functionality. We take advantage of the C++ loop abstractions in AMReX in order to run with high performance on either CPUs, NVIDIA GPUs, or AMD GPUs.

## Physics module status

Per the documentation policy in the maintainer guide, physics features that have not yet been exercised in a published science application are marked as **beta**.

| Module | Status | Notes |
| ------ | :----: | ----- |
| Radiation | beta | Two-moment radiation transport and matter-radiation coupling |
| MHD | beta | Ideal MHD with constrained transport |
| Dust | beta | Dedicated dust dynamics, drag, and charged-dust Lorentz source terms |
| Particles | beta | Particle-mesh gravity, sink particles, star formation, and feedback |
| Chemistry | beta | Primordial chemistry source terms |
| Self-gravity | beta | Poisson solve for gas and particle mass |

Hydrodynamics and optically-thin cooling are not currently marked as beta.

See [Known Issues and Errata](known_issues.md) for the current caveats and unsupported combinations.

## Development methodology

The code is written in modern C++20, using MPI for distributed-memory parallelism, with the AMReX GPU abstraction compiling as either native CUDA code or native HIP code when GPU support is enabled.

We use a modern C++ development methodology, using CMake, CTest, and Doxygen. We use `clang-format` for automated code formatting, and `clang-tidy` and SonarCloud for static analysis, in order to audit code adherence to the ISO C++ Core Guidelines and the MISRA C/C++ guidelines. We additionally ensure the code is free of memory corruption bugs using Clang's `AddressSanitizer`.

There is an automated suite of test problems that can be run using CTest. Each test problem has a validated solution against which it is compared (usually in L1 norm) in order to pass.

Code development is managed using pull requests (PRs) on GitHub. In an effort to ensure long-term code maintainability, all code must be written in C++20 following the Coding Guidelines, it must compile using Clang without warnings, all tests must pass, and the static analyzers must show zero new bugs before a pull request is merged with the main branch.

User assistance and bug reports are managed via Discussions and Issues in the GitHub repository.

## Numerical methods

### Hydrodynamics

The hydrodynamics solver is an unsplit method, using the piecewise parabolic method[@CW84] for reconstruction in the primitive variables, the HLLC Riemann solver [@Toro2013] for flux computations, and a method-of-lines formulation for the time integration.

We use the method of [@Miller_2002] to reduce the order of reconstruction in zones where shocks are detected in order to suppress spurious oscillations in strong shocks.

### Radiation

The radiation hydrodynamics formulation is based on the mixed-frame moment equations (e.g., [@MihalasMihalas]). The radiation subsystem is coupled to the hydrodynamic subsystem via operator splitting, with the hydrodynamic update computed first, followed by the radiation update, with the latter update including the source terms corresponding to the radiation four-force applied to both the radiation and hydrodynamic variables. A method-of-lines formulation is also used for the time integration, with the time integration done by the same integrator chosen for the hydrodynamic subsystem.

The hyperbolic radiation subsystem is solved using an unsplit method, using PPM for reconstruction of the moment variables, with fluxes computed via the HLL Riemann solver, with the wavespeeds computed using the 'frozen Eddington factor' approximation [@Balsara_1999], which is more robust than using the eigenvalues of the M1 system [@Skinner_2013] itself.

We reconstruct the energy density and the *reduced flux* \\(f = F/cE\\), in order to maintain the flux-limiting condition \\(F \le cE\\) in discontinuous and near-discontinuous radiation flows.

To ensure the correct behavior of the advection terms in the asymptotic diffusion limit [@Lowrie_2001], we modify the Riemann solver according to [@Skinner_2019]. We use the Lorentz-factor local closure of [@Levermore_1984] to compute the variable Eddington tensor.

The source terms corresponding to matter-radiation energy exchange are solved implicitly with the method of [@Howell_2003] following the hyperbolic subsystem update. The matter-radiation momentum update is likewise computed implicitly in order to maintain the correct behavior in the asymptotic diffusion limit [@Skinner_2019].
