luna-hydro 0.1.0__tar.gz

luna_hydro-0.1.0/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to LUNA. Versions follow [Semantic Versioning](https://semver.org); while
+the version is 0.x, minor releases may change the configuration and the Python API.
+
+## 0.1.0 (2026-11-02)
+
+The first public release. Status words as in the README: validated (asserted by a test
+against an independent reference), shown (runs and figures, no asserting test), experimental
+(under development). Details and tests: docs/CLAIMS.md.
+
+### Hydrodynamics
+- Euler equations in 1D, 2D and 3D: unsplit MUSCL-Hancock, PLM reconstruction (minmod, MC,
+  van Leer), HLLC and HLL Riemann solvers; FP32 by default, FP64 with `enable_x64=True`. Validated.
+- Non-physical Hancock face states are refused with the face named; a first-order face
+  fallback exists only as an opt-in (`allow_first_order_faces=True`) and is counted and reported.
+- XLA kernel (default, differentiable reference) and an opt-in Pallas GPU kernel
+  (`hydro_kernel="pallas"`), bitwise equal to the XLA kernel on an A100.
+- Known open bug: HLLC carbuncle at grid-aligned strong shocks (strict xfail tests); HLL is
+  the user's choice there, never switched automatically.
+
+### Parallel runs
+- Domain decomposition over many devices and processes (`MESH_SHAPE`); a sharded run
+  reproduces the single-device run (bitwise in the Sedov and Kelvin-Helmholtz tests). Validated.
+- Weak scaling measured to 4096 NVIDIA GH200 GPUs on JUPITER (FP32); runs on A100, GH200 and
+  MI300A. Shown (measurements, not tests).
+
+### Physics modules
+- Self-gravity with periodic and isolated boundaries, energy-conserving coupling. Validated.
+- Comoving cosmological integration (adiabatic expansion, top-hat collapse validated); dark
+  matter particles with particle-mesh gravity (power spectrum compared with Arepo: shown).
+- Radiative cooling from tables (tables validated against published equilibria; cooling in the
+  step shown).
+- Chemistry networks (chemcool networks 5 and 17 ported to JAX), radiation transport (M1 and
+  M2 closures), sink particles and star formation coupled to Torch/AMUSE, block AMR, Helmholtz
+  EOS and aprox13 nuclear network (standalone). Experimental.
+- Starburst-driven wind (M82 disk, CC85 injection) and driven turbulence setups. Shown.
+
+### Differentiation
+- Reverse-mode gradients through the solver, checked against finite differences; known gaps
+  listed in docs/AUTODIFF.md. Shown.
+
+### Running and packaging
+- One command line for every run: `luna run_file.py field=value ...` (or `python main.py` in a
+  clone); every setting is a field of one `Config` (docs/CONFIG.md); unknown fields are errors.
+- `pip install` extras `cuda12`, `rocm`, `plot`, `test`, `notebooks`; `luna.__version__`; run
+  provenance (settings, command line, code revision or installed version) in `run.json`.
+- Snapshots as HDF5 directories, checkpoints and restarts, `history.csv`.
+
+### Tests
+- Fast tier on every push, the full CPU suite (12 shards, 8 virtual devices), the 2-device
+  files and the Torch/AMUSE coupling tests (AMUSE v2026.3.0 built from source) in public CI; GPU and multi-node tiers on the
+  author's clusters. Reference solutions (AthenaK, Arepo, RAMSES, Pencil Code digitisations,
+  AMReX Microphysics, spectral runs, LUNA's own regression outputs) in the separate,
+  checksummed luna-reference-solutions repository; a missing or altered file fails, never skips.
+
+### Known issues in 0.1.0
+- Some full-suite CI tests fail at this release; fixes are under review for 0.1.1: AMR
+  sharded vs single-device ghost cells, the MC-limiter accretion shocks in the coupled cosmology
+  test, round-off differences between CPUs in the sink field and the stellar golden, the
+  isolated-gravity multipole sum order, and outdated test stubs.
+- The chemistry tests need the chemcool references, which move into luna-reference-solutions
+  for 0.1.1; until then they run only where `$LUNA_DATA` holds them.
+

luna_hydro-0.1.0/CITATION.cff

@@ -0,0 +1,36 @@
+cff-version: 1.2.0
+message: "If you use this software in your research, please cite it as below."
+title: "LUNA: A Differentiable Astrophysical Hydrodynamics Code"
+abstract: >-
+  LUNA is a differentiable astrophysical hydrodynamics code written in JAX, with hand-written
+  Pallas kernels as a fast path on GPUs. It solves the Euler equations in one, two and three
+  dimensions with an unsplit, second-order MUSCL-Hancock scheme and HLLC or HLL Riemann solvers,
+  and runs on CPUs and on many NVIDIA or AMD GPUs, with the domain split over devices.
+  Self-gravity is solved with periodic or isolated boundaries and couples to the gas conserving
+  energy; comoving cosmology evolves gas together with dark-matter particles; radiative cooling,
+  driven turbulence and starburst energy and mass injection are built in. Examples of what it
+  does: shock tubes, blast waves and Kelvin-Helmholtz, Rayleigh-Taylor and Richtmyer-Meshkov
+  instabilities; Jeans collapse and collapsing self-gravitating clouds; the cosmic web of gas and
+  dark matter from cosmological initial conditions; driven supersonic turbulence; galactic winds
+  blown out of a starburst disk; and inverse problems, such as optimising initial conditions with
+  gradients taken through the solver. Non-equilibrium chemistry and cooling networks, radiation
+  transport, sink particles and star formation with stellar dynamics and feedback through
+  Torch/AMUSE, and block-based adaptive mesh refinement are included as experimental modules.
+  Validated capabilities are tested against exact solutions or other codes (AthenaK, Arepo,
+  RAMSES), whose reference solutions are published with the code.
+type: software
+authors:
+  - family-names: Steinwandel
+    given-names: Ulrich Philipp
+version: 0.1.0
+date-released: 2026-11-02
+license: BSD-3-Clause
+repository-code: "https://github.com/Ulli1991/LUNA"
+url: "https://github.com/Ulli1991/LUNA"
+keywords:
+  - hydrodynamics
+  - JAX
+  - GPU
+  - astrophysics
+  - ISM
+  - differentiable programming

luna_hydro-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Ulrich Philipp Steinwandel, Max Planck Institute for Astrophysics
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

luna_hydro-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+# The sdist is the library and its metadata; tests, tools and scripts need the full clone
+# (conftest.py, tools/run_tests.py, luna-reference-solutions), so they are not in it.
+include LICENSE README.md CITATION.cff CHANGELOG.md THIRD_PARTY.md
+include src/luna/amr/LICENSE-JAX-AMR src/luna/radiation/*.npz
+prune tests
+global-exclude CLAUDE.md DESIGN.md __pycache__ *.py[cod]

luna_hydro-0.1.0/PKG-INFO

@@ -0,0 +1,355 @@
+Metadata-Version: 2.4
+Name: luna-hydro
+Version: 0.1.0
+Summary: Differentiable astrophysical hydrodynamics in JAX, from one CPU to many GPUs
+Author: Ulrich Philipp Steinwandel
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/Ulli1991/LUNA
+Project-URL: Source, https://github.com/Ulli1991/LUNA
+Project-URL: Documentation, https://github.com/Ulli1991/LUNA/tree/main/docs
+Project-URL: Issues, https://github.com/Ulli1991/LUNA/issues
+Project-URL: Changelog, https://github.com/Ulli1991/LUNA/blob/main/CHANGELOG.md
+Project-URL: Reference data, https://github.com/Ulli1991/luna-reference-solutions
+Keywords: hydrodynamics,JAX,GPU,astrophysics,cosmology,differentiable,Euler equations
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Environment :: GPU :: NVIDIA CUDA :: 12
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: src/luna/amr/LICENSE-JAX-AMR
+Requires-Dist: jax<0.11,>=0.10.0
+Requires-Dist: jaxlib<0.11,>=0.10.0
+Requires-Dist: h5py>=3.0
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.9
+Provides-Extra: cuda12
+Requires-Dist: jax[cuda12]<0.11,>=0.10.0; extra == "cuda12"
+Provides-Extra: rocm
+Requires-Dist: jax[rocm7-local]<0.11,>=0.10.0; extra == "rocm"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.5; extra == "plot"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: notebooks
+Requires-Dist: jupyter; extra == "notebooks"
+Requires-Dist: matplotlib>=3.5; extra == "notebooks"
+Requires-Dist: scipy>=1.9; extra == "notebooks"
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: ruff>=0.16; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# LUNA
+
+LUNA is a differentiable astrophysical hydrodynamics code written in
+[JAX](https://docs.jax.dev), with hand-written
+[Pallas](https://docs.jax.dev/en/latest/pallas/index.html) kernels as a fast path on
+GPUs. It solves the Euler equations in one, two and three dimensions with an unsplit,
+second-order MUSCL-Hancock scheme and HLLC or HLL Riemann solvers, and runs on CPUs and
+on many NVIDIA or AMD GPUs, with the domain split over devices. Self-gravity is solved
+with periodic or isolated boundaries and couples to the gas conserving energy; comoving
+cosmology evolves gas together with dark-matter particles; radiative cooling, driven
+turbulence and starburst energy and mass injection are built in. Examples of what it
+does: shock tubes, blast waves and Kelvin-Helmholtz, Rayleigh-Taylor and
+Richtmyer-Meshkov instabilities; Jeans collapse and collapsing self-gravitating clouds;
+the cosmic web of gas and dark matter from cosmological initial conditions; driven
+supersonic turbulence; galactic winds blown out of a starburst disk; and inverse
+problems, such as optimising initial conditions with gradients taken through the solver.
+Non-equilibrium chemistry and cooling networks, radiation transport, sink particles and
+star formation with stellar dynamics and feedback through Torch/AMUSE, and block-based
+adaptive mesh refinement are included as experimental modules. Validated capabilities
+are tested against exact solutions or other codes (AthenaK, Arepo, RAMSES), whose
+reference solutions are published with the code.
+
+Defaults on `main`: FP32
+(`enable_x64=False`), minmod limiter, HLLC, CFL 0.8, and the XLA kernel
+(`hydro_kernel="xla"`), which is the reference path. A Pallas kernel is an opt-in path
+for GPUs (`hydro_kernel="pallas"`); it refuses configurations it cannot run.
+
+The reference solutions the tests compare against (AthenaK, Arepo, RAMSES, the Pencil
+Code, AMReX Microphysics and others, with their sources) are public in
+[luna-reference-solutions](https://github.com/Ulli1991/luna-reference-solutions).
+
+## What LUNA can do
+
+Status: **validated** = asserted by a test against an independent reference;
+**shown** = real runs, shown in figures, not yet asserted by a test; **experimental** =
+under development, not finalised. Each row's tests and details are in
+[docs/CLAIMS.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/docs/CLAIMS.md).
+
+| capability | status |
+|---|---|
+| Euler hydrodynamics in 1D, 2D, 3D: unsplit MUSCL-Hancock, PLM (minmod, MC, van Leer), HLLC | validated |
+| `riemann_solver="hll"`: the robust fallback where HLLC carbuncles at grid-aligned strong shocks; chosen by the user, never switched automatically | validated |
+| Multi-GPU domain decomposition; a sharded run reproduces the single-device run | validated |
+| Weak scaling to 4096 NVIDIA GH200 GPUs on JUPITER (FP32, 88.9 % efficiency) | shown (measurement) |
+| NVIDIA and AMD GPUs (runs on A100, GH200, MI300A; public CI is CPU only) | shown |
+| Pallas GPU kernels (`hydro_kernel="pallas"`, opt-in), bitwise equal to the XLA kernel on A100 | validated |
+| Self-gravity, periodic and isolated boundaries; energy-conserving coupling | validated |
+| Comoving cosmology: adiabatic expansion, top-hat collapse | validated |
+| Cosmic web with dark-matter particles and gas; DM power spectrum compared with Arepo | shown |
+| Radiative cooling (tables validated against published equilibria; cooling in the step not yet asserted) | shown |
+| Chemistry networks | experimental |
+| Radiation transport, M1 and M2 closures | experimental |
+| Sink particles and star formation coupled to Torch/AMUSE | experimental |
+| Block AMR | experimental |
+| Starburst-driven wind (M82 disk, CC85 injection) | shown |
+| Driven turbulence | shown |
+| Differentiation through the solver (gradients checked against finite differences; known gaps in [docs/AUTODIFF.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/docs/AUTODIFF.md)) | shown |
+
+<table>
+<tr>
+<td width="50%"><img src="https://raw.githubusercontent.com/Ulli1991/LUNA/v0.1.0/code_paper_figs/kh_8192_luna_vs_athenak.png" alt="Kelvin-Helmholtz at 8192², LUNA and AthenaK"><br>
+<sub><b>Kelvin-Helmholtz at 8192²</b>, density at t = 0 to 5: LUNA (top, second order) and AthenaK (bottom, fourth-order WENOZ) as the reference. Shown: an accuracy comparison by eye, not an asserted test.</sub></td>
+<td width="50%"><img src="https://raw.githubusercontent.com/Ulli1991/LUNA/v0.1.0/code_paper_figs/sedov3d_Nx1024.png" alt="3D Sedov-Taylor blast wave"><br>
+<sub><b>3D Sedov-Taylor blast</b> in an ISM-like medium: shock radius against the self-similar solution, and column density. The Sedov solution is asserted in the 2D off-axis tests (validated); this 3D run is shown.</sub></td>
+</tr>
+<tr>
+<td><img src="https://raw.githubusercontent.com/Ulli1991/LUNA/v0.1.0/code_paper_figs/cosmic_web_512_z0.png" alt="Cosmic web at z=0, dark matter and gas"><br>
+<sub><b>Cosmic web at z = 0</b>: 512³ gas cells and 512³ dark-matter particles, 25 Mpc/h box; dark matter (left), gas (right). Shown.</sub></td>
+<td><img src="https://raw.githubusercontent.com/Ulli1991/LUNA/v0.1.0/code_paper_figs/fig33_dm_powerspec_arepo_vs_luna.png" alt="Dark-matter power spectrum, LUNA PM and Arepo TreePM"><br>
+<sub><b>Dark-matter power spectrum</b>, LUNA (particle-mesh) and Arepo (TreePM) from identical 512³ initial conditions: equal on large scales, LUNA lower above k ≈ 5 h/Mpc where the grid softens the force. Shown: compared in a figure; no test gates it yet.</sub></td>
+</tr>
+<tr>
+<td><img src="https://raw.githubusercontent.com/Ulli1991/LUNA/v0.1.0/code_paper_figs/coupled_collapse_512.png" alt="Molecular cloud collapse with sinks and stars"><br>
+<sub><b>Collapsing molecular cloud</b> (2000 M⊙, 512³) to one free-fall time, with sink particles; stars and their N-body dynamics through Torch/AMUSE. Experimental.</sub></td>
+<td><img src="https://raw.githubusercontent.com/Ulli1991/LUNA/v0.1.0/code_paper_figs/m82_wind_density.png" alt="M82-like starburst wind"><br>
+<sub><b>M82-like starburst wind</b> leaving a rotating disk (CC85 injection, Schneider et al. 2018 setup), log n_H at 60 Myr. Shown.</sub></td>
+</tr>
+<tr>
+<td><img src="https://raw.githubusercontent.com/Ulli1991/LUNA/v0.1.0/code_paper_figs/amr_sedov3d_evolution.png" alt="3D Sedov with block AMR"><br>
+<sub><b>Block AMR</b>: 3D Sedov on a fixed 64³ grid and with block refinement, refinement mesh overlaid. Experimental.</sub></td>
+<td><img src="https://raw.githubusercontent.com/Ulli1991/LUNA/v0.1.0/code_paper_figs/autodiff_LUNA_emergence_Nx256.png" alt="Initial conditions optimised so that the word LUNA emerges"><br>
+<sub><b>Differentiating through the solver</b>: initial conditions optimised with reverse-mode gradients so that the word LUNA emerges from an explosion (top) and from turbulence (bottom). A demonstration, shown.</sub></td>
+</tr>
+</table>
+
+More figures: [docs/GALLERY.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/docs/GALLERY.md).
+
+## What is validated
+
+Only results that a test asserts against an independent reference (exact or analytic
+solution, published data, or another code's output) with a stated bound; the test for
+each is in [docs/CLAIMS.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/docs/CLAIMS.md), and the other codes' outputs are in
+[luna-reference-solutions](https://github.com/Ulli1991/luna-reference-solutions).
+
+- Second-order convergence on smooth flows and linear waves; HLLC and HLL fluxes against
+  Toro's tests; shock tubes against the exact Riemann solution.
+- Sedov-Taylor, Noh and Guderley against exact solutions; linear growth of
+  Kelvin-Helmholtz, Rayleigh-Taylor and Richtmyer-Meshkov against linear theory;
+  nonlinear Kelvin-Helmholtz against McNally et al. (2012).
+- HLL keeps grid-aligned strong shocks planar where HLLC carbuncles (the HLLC case is a
+  known open bug, kept as a strict xfail test).
+- A run split over several devices reproduces the single-device run (bitwise in the
+  Sedov and Kelvin-Helmholtz tests, to 1e-12 in the shard-seam test); the Pallas hydro
+  kernel equals the XLA kernel bitwise on an A100.
+- Self-gravity with periodic and isolated boundaries (Jeans waves, direct sums, energy
+  conservation in the Evrard collapse); comoving expansion and the spherical top-hat
+  collapse against exact solutions; cooling tables against published equilibria.
+
+White-dwarf detonations are in development and not on `main`.
+
+## Install
+
+Python 3.11, 3.12 or 3.13. The package is `luna-hydro`; it installs the library `luna`
+and the command `luna` (the same as `python main.py` in a clone), and pins
+`jax>=0.10.0,<0.11`. Until LUNA is on PyPI, install from a clone; the commands in
+brackets are the PyPI form for once it is published.
+
+**CPU** (laptop, workstation, login node):
+
+```bash
+git clone https://github.com/Ulli1991/LUNA.git
+pip install "./LUNA[plot]"              # (once published: pip install "luna-hydro[plot]")
+```
+
+**NVIDIA GPUs**: the `[cuda12]` extra installs JAX's CUDA 12 build of the same version,
+with the CUDA libraries as pip wheels; the machine needs only an NVIDIA driver, no CUDA
+module.
+
+```bash
+pip install "./LUNA[cuda12,plot]"       # (once published: pip install "luna-hydro[cuda12,plot]")
+python -c "import jax; print(jax.devices())"     # [CudaDevice(id=0), ...]
+```
+
+**AMD GPUs**: `pip install "./LUNA[rocm,plot]"` installs JAX's ROCm 7 plugin of the
+same version (`jax[rocm7-local]`), which needs ROCm 7 installed on the machine (module
+or system). This route is not tested by LUNA's CI.
+
+**No JAX 0.10 wheel for your platform** (for example an Intel Mac): use the CPU image in
+[tools/docker/Dockerfile](https://github.com/Ulli1991/LUNA/blob/v0.1.0/tools/docker/Dockerfile); its header has the build and run
+commands.
+
+For development, install the clone editable with the test tools:
+
+```bash
+cd LUNA
+pip install -e ".[plot,test]"
+```
+
+Extras: `plot` (matplotlib; the default run plots its result at the end,
+`PLOT_AFTER_SIM=True`, and fails there without it, so set `PLOT_AFTER_SIM=False` if you
+leave it out), `test` (pytest), `notebooks` (Jupyter and matplotlib), `cuda12`, `rocm`.
+The installed package is the library and the `luna` command. The run scripts in
+`scripts/`, the autodiff example tasks (`scripts/examples/autodiff/`), the tests and
+`tools/`, the SLURM templates in `submit/` and the Torch/AMUSE coupling (`src/amuse_luna`)
+need the clone.
+
+## Quick start
+
+A run is a config file (a copy of the template, which holds every setting) plus
+`field=value` overrides on the command line:
+
+```bash
+cp LUNA/src/luna/template_config.py my_run.py     # every setting; docs/CONFIG.md explains them
+luna my_run.py Nx=256                             # Sod shock tube, 1D (the template's problem)
+luna my_run.py test_problem=Kelvin-Helmholtz SPATIAL_DIMENSION=2 BOUNDARY=0 \
+    Nx=128 Ny=128 Lx=2 Ly=2 t_end=1.0 output_dir=snapshots/kh128
+luna my_run.py test_problem=Sedov-Blast-3D SPATIAL_DIMENSION=3 \
+    Nx=32 Ny=32 Nz=32 output_dir=snapshots/sedov32
+```
+
+Without a clone, copy the template from the installed package:
+`python -c "import luna.template_config as t, shutil; shutil.copy(t.__file__, 'my_run.py')"`.
+In a clone, `python main.py` is the same command as `luna`.
+
+On four cores of a shared login node (`JAX_PLATFORMS=cpu`) each took under three
+minutes. The first one ends with
+
+```
+[gas] done: 195 steps, t=2.45000e-01, 14.5s
+
+============================================================
+SIMULATION COMPLETED
+============================================================
+✓ Total runtime: 14.50 seconds
+✓ Total steps: 195
+✓ Final time: 0.24500
+```
+
+Snapshots are written to `output_dir` (default `snapshots/`) as `snapdir_NNN/` HDF5
+directories, together with `history.csv` and `run.json` (the settings, the command line
+and the code revision). An unknown field name is an error, not a warning. Problem
+parameters are set as `problem.<name>=value`. [docs/TUTORIAL.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/docs/TUTORIAL.md) walks
+through a first run, and [docs/RUNNING.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/docs/RUNNING.md) covers production runs.
+
+## Clusters and GPUs
+
+Start one process per GPU with `srun`; JAX's distributed runtime picks up the SLURM
+environment, and `MESH_SHAPE` chooses how the grid is split across the processes:
+
+```bash
+srun luna my_run.py test_problem=Sedov-Blast-3D SPATIAL_DIMENSION=3 \
+    Nx=1024 Ny=1024 Nz=1024 MESH_SHAPE=2,4,4
+```
+
+SLURM templates for NVIDIA and AMD nodes are in [submit/examples/](https://github.com/Ulli1991/LUNA/tree/v0.1.0/submit/examples/).
+
+Measured weak scaling (not a test; method, job ids and the strong-scaling data are in
+[docs/GALLERY.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/docs/GALLERY.md)): 3D Sedov blast, 512³ cells per GPU, FP32, on
+JUPITER's NVIDIA GH200 nodes, from 2.19 Gcell-updates/s on one GPU to 7.99 Tcell-updates/s
+on 4096 GPUs (8192³ cells), 88.9 % weak-scaling efficiency. No FP64 run was made at 4096 GPUs.
+
+<img src="https://raw.githubusercontent.com/Ulli1991/LUNA/v0.1.0/code_paper_figs/scaling_jupiter.png" alt="LUNA weak and strong scaling on JUPITER GH200">
+
+## Interactive use (Jupyter)
+
+[examples/notebooks/](https://github.com/Ulli1991/LUNA/tree/v0.1.0/examples/notebooks/) has small CPU notebooks that go through the same
+path as `main.py` (`luna.launch(Config)`, which starts JAX and calls `luna.main.run`). Each runs
+in a few minutes on four CPU cores, FP64, on grids far smaller than the tests' (the test file is
+named in each), and compares with an exact or published solution:
+
+| notebook | what it compares | status (docs/CLAIMS.md) |
+|---|---|---|
+| 01_sod_shock_tube | Sod tube against the exact Riemann solution | validated |
+| 02_kelvin_helmholtz | 2D KH run (a demonstration, no reference) | - |
+| 03_shock_tubes | Toro tests 1-5, HLLC and HLL, against the exact Riemann solution | validated |
+| 04_sedov_taylor | 2D off-axis and 3D Sedov-Taylor against the exact solution | 2D validated, 3D shown |
+| 05_noh | planar and cylindrical Noh against Noh (1987) | validated |
+| 06_linear_waves | sound, entropy and shear waves: convergence order | validated |
+| 07_gresho_vortex | Gresho vortex: velocity error and kinetic-energy loss vs resolution | validated |
+| 08_kelvin_helmholtz_validation | KH linear growth vs linear theory; McNally et al. (2012) vs the Pencil Code | validated |
+| 09_jeans_waves | Jeans waves against the linear dispersion relation | validated |
+| 10_cosmology_tophat | comoving top-hat collapse against the closed-FRW solution | validated |
+| 11_autodiff_gradients | gradients of a Sedov run: forward-mode AD vs finite differences and Sedov scaling | validated (AD vs FD), shown (whole runs) |
+| 12_custom_problem | your own initial state through `launch(cfg, ic=...)` (a demonstration) | - |
+
+They need `pip install -e ".[plot,notebooks]"`; 08 also needs the reference solutions
+(below). How to add a problem of your own, from a run file to a registered, tested problem:
+[docs/ADDING_A_PROBLEM.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/docs/ADDING_A_PROBLEM.md). From Python:
+
+```python
+from dataclasses import replace
+from luna import Config, launch
+
+res = launch(replace(Config(), test_problem="Sedov-Blast-3D", SPATIAL_DIMENSION=3,
+                     Nx=32, Ny=32, Nz=32, output_dir="snapshots/sedov32"))
+print(res.t, res.n_steps)    # final state in res.extra["U"]
+```
+
+## Tests and reference data
+
+```bash
+pip install -e ".[plot,test]"  # in the clone
+python tools/run_tests.py      # the fast tier on CPU, as CI runs it
+```
+
+The tests need the clone and the reference solutions below; how to run them and the
+rules for new tests are in [CONTRIBUTING.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/CONTRIBUTING.md).
+
+Reference solutions (outputs of AthenaK, Arepo, RAMSES, the Pencil Code and AMReX
+Microphysics, spectral solutions, and LUNA's own high-resolution runs for the
+regression-only tests) live in a separate repository,
+[luna-reference-solutions](https://github.com/Ulli1991/luna-reference-solutions). Tests
+look for it in `$LUNA_REFERENCE_SOLUTIONS`, then next to the LUNA checkout
+(`../luna-reference-solutions`), then in `~/luna-reference-solutions`, and check every
+file's sha256 against its `MANIFEST.json`; a missing or altered file is an error, not a
+skip. Other codes are used only as accuracy references.
+
+```bash
+git clone https://github.com/Ulli1991/luna-reference-solutions.git ../luna-reference-solutions
+```
+
+Public CI runs the fast tier on CPU, once on one device and once on two virtual devices
+(`--devices 2`, which exercises the halo exchange), plus `ruff check`. The GPU and
+multi-node tiers run on the author's clusters ([docs/TESTING.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/docs/TESTING.md)).
+
+## Documentation
+
+| | |
+|---|---|
+| [docs/CLAIMS.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/docs/CLAIMS.md) | every claim, the test that asserts it, its status |
+| [docs/TUTORIAL.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/docs/TUTORIAL.md) | a first run, step by step |
+| [docs/RUNNING.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/docs/RUNNING.md) | configuration, multi-GPU and production runs |
+| [docs/CONFIG.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/docs/CONFIG.md) | every field of `Config` |
+| [docs/ARCHITECTURE.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/docs/ARCHITECTURE.md) | how the code fits together |
+| [docs/TESTING.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/docs/TESTING.md) | the test suite and its tiers |
+| [docs/GALLERY.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/docs/GALLERY.md) | figures and the scaling measurements |
+
+## Citation
+
+Please cite LUNA through [`CITATION.cff`](https://github.com/Ulli1991/LUNA/blob/v0.1.0/CITATION.cff) (GitHub shows it under "Cite this
+repository").
+
+## License
+
+BSD 3-Clause; see [LICENSE](https://github.com/Ulli1991/LUNA/blob/v0.1.0/LICENSE). The AMR layer derives from JAX-AMR (MIT;
+[src/luna/amr/LICENSE-JAX-AMR](https://github.com/Ulli1991/LUNA/blob/v0.1.0/src/luna/amr/LICENSE-JAX-AMR)).
+
+## Contributing
+
+Bug reports and questions: GitHub issues. Pull requests are welcome; see
+[CONTRIBUTING.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/CONTRIBUTING.md) and the [Code of Conduct](https://github.com/Ulli1991/LUNA/blob/v0.1.0/CODE_OF_CONDUCT.md).
+Changes are listed in [CHANGELOG.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/CHANGELOG.md); third-party code and data, with
+their licences, in [THIRD_PARTY.md](https://github.com/Ulli1991/LUNA/blob/v0.1.0/THIRD_PARTY.md).