Skip to content

Development

LUCiD is under the Apache License 2.0 (LICENSE), and contributions are taken under the same licence. Open an issue or a pull request; sign off commits with a Developer Certificate of Origin (git commit -s).

Setup

pip install -e '.[dev]' -c tests/constraints.txt   # LUCiD with pytest, pre-commit, ruff
python scripts/download_data.py                    # data the examples and data tests need
pre-commit install                                 # run the hooks on every commit

Tests

pytest tests/ -q          # the fast set (tests marked slow are skipped)
pytest tests/ -q --slow   # everything

The markers (slow, golden, gpu, requires_data, requires_emitter), the layout and the switches for data and GPU tests are in tests/README.md. The one stored reference, tests/physics/test_forward_golden.py, is re-captured with LUCID_CAPTURE_GOLDEN=1 in a commit of its own that says why.

The gate

A change merges when the test suite passes, the paper figure scripts still re-plot their existing output (--plot-results), the production entry points still run at their smallest size, and a reviewer has read the diff. bash tools/gate.sh runs the first three; it exits 0 when all pass, or 1, 2 or 3 naming the first that failed. A change that moves a published number on purpose says what moved, and by how much, in its own commit.

Lint and hooks

pre-commit run --all-files runs ruff (configured in pyproject.toml), nbstripout, shellcheck --severity=warning and a shell-header check: every shell script sets set -euo pipefail in its first 30 lines and contains no personal or site-specific absolute paths (those come from user_paths.sh). CI's lint job runs the same hooks on every file and fails the build when one fails. The one-time reformat that brought the tree to this standard is listed in .git-blame-ignore-revs; git config blame.ignoreRevsFile .git-blame-ignore-revs makes git blame look past it (GitHub's blame view already does).

Docs

pip install -e '.[docs]' -c tests/constraints.txt
python .github/scripts/check_doc_links.py   # links, snippet includes and backtick repo paths resolve
mkdocs build --strict
  • A fact lives on one page; other pages link to it.
  • Code shown on a page is included from a file that runs, an examples/ script or a
  • A new page goes into the nav of mkdocs.yml in the same change.
  • Notebooks are committed with outputs stripped (notebooks/README.md).
  • Third-party files and CDN imports are listed in THIRD_PARTY.md.