Contributing to MomentRT#
MomentRT combines numerical transport models with explicit physical inputs. Contributions should make behavior reproducible and document its scientific meaning. Follow the repository’s AGENTS.md for module ownership, units, Python style, and model conventions.
Development environment#
Use Python 3.11 or newer. From a checkout, reuse .venv if it already exists;
otherwise create it with python3 -m venv .venv. Install the declared extras
with that environment’s interpreter:
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e ".[testing,documentation,dev,release]"
testing, dev, and release use the shared
martinpdes-maintenance tooling; documentation supplies the Sphinx
configuration. Plotly is a runtime dependency, so no viz extra is needed.
On Debian or Ubuntu, the Gmsh wheel also needs the system runtime library
libglu1-mesa, installed with sudo apt-get install libglu1-mesa.
On Windows, use py -m venv .venv when creating the environment, then replace
.venv/bin/python with .venv\Scripts\python.exe in these commands.
GNU Make is optional: the module commands below can be run directly.
Checks before submitting a change#
make check typecheck docstring-check PYTHON=.venv/bin/python
git diff --check
make check runs Ruff linting, formatting checks, and pytest. The separate
typecheck and docstring-check targets run mypy and public API
annotation/docstring validation. Their direct equivalents are:
.venv/bin/python -m ruff check MomentRT tests docs/examples tools
.venv/bin/python -m ruff format --check MomentRT tests docs/examples tools
.venv/bin/python -m pytest
.venv/bin/python -m mypy MomentRT
.venv/bin/python tools/check_docstrings.py
Tests under tests/analytical compare against mathematical or independent
references. tests/numerical covers discretization, geometry, and workflow
behavior; tests/packaging checks metadata. Select focused checks during
development, then run the appropriate broader checks before submitting.
Numerical changes need independent evidence for the affected observable. For photon transport, cover layer crossings and collision/absorption conventions as well as energy accounting. A repeatable seeded answer or a small energy-balance residual alone does not establish correctness. Preserve units, unresolved levels, negative outputs, and uncertainty diagnostics.
Documentation and reference data#
make docs PYTHON=.venv/bin/python
The documentation build executes changed Sphinx-Gallery scripts and treats
Sphinx warnings as errors. Examples belong in docs/examples and start
with an RST title and introduction. Use # %% cells to explain meaningful
steps and show=False for figures; examples must not open browsers or write
HTML as side effects. Inspect changed figures, including interactive behavior.
For a changed 3D gallery preview, install Playwright and Chromium if needed, build the docs, run the preview generator, and rebuild:
.venv/bin/python -m pip install playwright
.venv/bin/python -m playwright install chromium
make docs PYTHON=.venv/bin/python
.venv/bin/python tools/generate_gallery_thumbnails.py
make docs PYTHON=.venv/bin/python
Include the generated preview with the change. Ordinary documentation builds then use that image without requiring a browser.
The full sensor reference study is an explicit maintenance operation:
.venv/bin/python tools/validate_sensor_models.py
It regenerates the committed JSON and plots under
docs/source/_static/images/sensor_validation. Review changed reference
results and uncertainties, rerun their independent checks, and explain any
algorithm correction in the changelog and validation guide. Documentation
examples read the committed report rather than rerunning Monte Carlo.
API and compatibility policy#
This policy applies to future releases; it does not relabel existing tags.
Patch releases preserve documented public import paths and calling conventions. They contain fixes and documentation updates. Correcting numerical results or rejecting previously accepted invalid input can be a patch fix, but must be described in the changelog with its scientific impact.
Minor releases add capabilities. During the 0.x series, an incompatible change requires a minor release and migration instructions describing the previous and replacement APIs, units, and result meaning.
A deprecation must identify a replacement and a target minor release for removal. Keep the old API through at least one subsequent minor release; do not remove it in a patch release. Existing compatibility aliases remain supported until a deprecation is explicitly announced.
Physical units, source/boundary signs, normalization, array locations, and result provenance are part of the public contract. Document changes to them as carefully as renamed parameters. Keep unsupported physical cases explicit.
Numerical comparisons use justified tolerances and statistical uncertainty. Bit-for-bit equality across meshes, dependency versions, platforms, or Monte Carlo generator revisions is not guaranteed.
Add a concise entry under Unreleased in
CHANGELOG.md
for user-visible changes. For scientific corrections, identify the affected
results and whether published data must be regenerated. Keep existing aliases
such as convergence_study and full_hemisphere_on_face working unless a
documented deprecation is part of the change.
Packaging and releases#
make package-check release-check PYTHON=.venv/bin/python
package-check builds the source archive and wheel. For package changes,
also run tools/check_wheel.py with the newly built wheel’s exact path;
it installs and imports the wheel in a temporary environment outside the
checkout. release-check validates version metadata and the changelog’s
section for the current version.
Maintainers create releases from a clean, checked commit. To inspect the next version without writing files, run:
.venv/bin/python -m martinpdes_maintenance.cli next patch
The CLI’s tag vX.Y.Z --dry-run command previews metadata and changelog
changes for a chosen tag, also requiring a clean tree. Use the release tools
to align pyproject.toml, _version.py, the conda recipe, citation, and
Zenodo metadata. The configured changelog rolls Unreleased into the new
version and records the actual release date.
make tag VERSION=vX.Y.Z creates a local release commit and annotated tag.
make release patch, make release minor, and make release major
also push the commit and tag and trigger publication. Run those publishing
commands only when a release is explicitly intended, then check the publishing
workflow and package artifacts.