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 doxygen/ of the repository. It is not hosted online: build it locally as described below and in the Documentation section of the README.

To build it locally (Doxygen and Graphviz are required):

cd doxygen
doxygen Doxyfile

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

Path	Content
doxygen/Doxyfile	the Doxygen configuration
doxygen/dox/mainPage.dox	the main page
doxygen/dox/Core/, Materials/, Solver/, IO/, Verification/	the pages of each module
doxygen/dox/external/	the pages on SUNDIALS, the container image and the Hoffman2 cluster

Releases

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