Development

Otter is organized around explicit physical stages rather than around example scripts:

composition and thermodynamic state
    -> electronic full/external model
    -> pseudoatom screening density
    -> electron response and effective pair potentials
    -> QOZ/HNC ionic structure
    -> validated, serializable results

Contribution principles

  • Preserve the public otter namespace while internal modules evolve.

  • Add tests for physical invariants before moving a numerical implementation.

  • Keep physical model choices separate from convergence controls.

  • Cite primary literature next to equations and model implementations.

  • Add every new key to src/otter/literature.bib and expose selectable model keys through config.citation_keys; see Citing Otter.

  • Do not silently continue from an unconverged electronic or ionic solve.

  • Keep generated files, caches, and machine-specific paths out of Git.

Documentation workflow

The documentation is generated from hand-written reStructuredText, public docstrings, and Sphinx-Gallery examples:

$ poetry run make -C docs html
$ poetry run make -C docs strict
$ poetry run make -C docs serve

strict treats Sphinx warnings as errors. A successful build must not modify tracked files because autosummary and gallery products are ignored.

Third-party software provenance

The finite-temperature Geldart–Vosko and Gregori-2007 LFC routines were copied from JaXRTS and adapted to Otter’s NumPy/atomic-unit API. They retain the upstream BSD-3-Clause notice in THIRD_PARTY_NOTICES.md. The corresponding software paper is Lütgert et al. [2026]; primary physical-model references remain cited beside the implementation in otter.ionic.lfc.

Benchmark workflow

Heavy quantum calculations are opt-in. New scientific-gallery benchmark files must be complete, directly executable programs: an input switch chooses checksum-verified accepted arrays or calls Otter’s public workflow in that same file. Fresh calculations write review candidates under benchmarks/outputs and never overwrite accepted, non-pickled arrays. Every accepted package records model choices, convergence gates, controller hashes, and data provenance in a manifest.

All maintained scientific plots—not only the Sphinx galleries—must use otter.plotting for the shared serif/STIX typography, font sizes, inward major/minor ticks, line defaults, and semantic palettes. Every saved figure is exported as both a 300 dpi PNG and a vector PDF. The repository-wide test_plot_export_policy.py gate prevents examples, benchmark runners, and diagnostic plots from bypassing that style/export path.