Developer notes

Developer notes

Repository conventions

• The module layout is uniform. The active module follows the structure py_utils/, cpp_utils/, codes/, input/, output/, build/.
• Physics lives in the workbook. Parameters carry a Symbol key, a unit and a source citation. The code reads them. It does not hard-code them.
• Outputs are immutable and stamped. Runs never overwrite one another.
• New physics is Python-first. See the order of work below.

Order of work for new physics

1. Develop the physics in the Python graph walker.
2. Pass the conservation gate (see Verification).
3. Mirror the physics in the C++ kernels.
4. Calibrate.

Adding a host material

Adding a host material is a declaration, not a change of the solver.

1. Add a folder materials/<name>/ in both py_utils/ and cpp_utils/.
2. Declare the populations of the material.
3. Add its edge families. Each one belongs to one of the ten edge classes (see Methodology).
4. Register a size-resolved rate kernel for every edge, as a precomputed array.

The solver, the preconditioner and the reductions are inherited unchanged. The EUROFER-97 declaration, py_utils/materials/eurofer97/declaration.py, is the worked example.

Contributing

Issues and pull requests are welcome. A change that touches reaction kernels or stoichiometry should come with the relevant conservation check from codes/Python_Testing/, and with a note of the resulting $\delta_{\rm FP}$ and $\delta_{\rm He}$.

Building the API reference

The API reference is generated with Doxygen from the folder docs/doxygen/ of the repository. It is not hosted online: build it locally as described below and in the Documentation section of the README. The workflow .github/workflows/documentation.yml also builds it on each push to main and keeps the HTML as a workflow artifact.

To build it locally (Doxygen 1.9 or later and Python 3 are required), run from the repository root:

doxygen docs/doxygen/Doxyfile

The pages are written to docs/doxygen/build/html/. Open docs/doxygen/build/html/index.html in a browser.

Path	Content
docs/doxygen/Doxyfile	the Doxygen configuration
docs/doxygen/mainpage.md	the main page
docs/doxygen/markdown_math_filter.py	converts the equations of radcluster_code/CLAUDE.md into Doxygen formulas during the build
docs/doxygen/README.md	what the reference covers and how it is published

Releases

A release and its container image are published by the workflow .github/workflows/release.yml when a tag v* is pushed.