Otter

Otter calculates electronic and ionic structure in warm and hot dense matter. From composition, mass density, and temperature it can solve a quantum average-atom or Thomas–Fermi model, construct neutral pseudoatoms, build effective ion–ion potentials, and solve one- or multicomponent QOZ/HNC equations.

Otter is based primarily on the pseudoatom model of Starrett and Saumon (2014).

Capabilities

• finite-temperature quantum (KS-DFT, QM) and Thomas–Fermi (TF) electronic structure; the QM model provides orbital levels, occupations, and density components;
• per-level ionic densities and form factors, raw KS radial wavefunctions, and direct access to partition mean ionization and background ionization;
• pseudoatom densities n_pa(r) and screening densities n_scr(r), with form factors f(k)=n_ion(k) and q(k)=n_scr(k);
• effective ion–ion potentials V_ij(r) and V_ij(k);
• one- and multicomponent QOZ/HNC results g_ij(r) and S_ij(k).

Install

Otter uses a reproducible editable installation from source. It requires CPython 3.12 or newer, Git, and Poetry 2.1.3.

macOS, Linux, or WSL:

curl -sSL https://install.python-poetry.org | python3 - --version 2.1.3

Windows PowerShell:

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py - --version 2.1.3

Verify the installation:

poetry --version

Clone and install:

git clone https://github.com/otter-hed/otter.git
cd otter
poetry install

Dependencies are locked by poetry.lock; Otter is installed in editable mode.

Otter's built-in local-density Dirac exchange is the dependency-free default used by the validated warm- and hot-dense-matter workflows. Libxc is optional and is needed only for additional LDA correlation or GGA functionals such as lda_pw, lda_pz, lda_vwn, and pbe.

To enable these additional functionals:

poetry install --extras libxc

PyPI distributes the Libxc Python bindings as source, so this optional step requires CMake and a C compiler. See the XC installation guide.

poetry run python -c "import otter; print(otter.__version__)"

Quick start

Run an introductory calculation in Google Colab:

Run the complete single-species workflow from the repository root:

poetry run python examples/single_species_workflow.py

The default state is Al at rho=8.1 g/cm^3 and Te=Ti=15 eV. Edit the input block to change the state or output controls. The script plots the electronic density, effective potential, g_ii(r), and S_ii(k), and saves PNG, PDF, and NPZ files.

For mixtures, run mixture_workflow.py.

Saved workflow state

The versioned NPZ schema stores units and convergence metadata together with the selected scientific quantities. The default complete profile retains native electronic profiles and levels, q/f, electron response and LFC, interaction channels, and g_ij/S_ij. The smaller electronic_summary profile includes compact bound levels; ion_structure retains f/q/g/S. Optional groups add quantities such as chi_ee_k without requiring a complete export. Existing state schemas remain readable. In a complete archive:

• q_k == n_scr_k and f_k == n_ion_k;
• G_ee_k, chi0_k, chi_ee_k, v_ie_k, c_ie_k, v_ee_k, and c_ee_k;
• gij_r, sij_k, vij_r, and vij_k.

gee_k and g_ee_k are temporary compatibility aliases for G_ee_k.

The default windows are r < 20 Bohr and k < 20 Bohr^-1. Archives load with allow_pickle=False and are written atomically. See the state-export guide for in-memory and NPZ access.

Quantum continuum calculations can be slow near pressure ionization. continue_plasma_workflow_from_electronic_result reuses a validated electronic result for subsequent QOZ/HNC calculations.

Validation and documentation

Browse the documentation, example gallery, and scientific benchmarks.

Examples and benchmarks calculate from their input parameters. From the repository root, for example:

poetry run python docs/examples/plot_al_full_workflow.py
poetry run python benchmarks/examples/plot_doppner_2023_be_ionization.py

The current source tree does not include precomputed Otter NPZ files. Scripts write new results locally; literature reference data and recorded website figures, tables, and terminal output remain included. MD comparisons require LAMMPS/MPI and first calculate the Otter pair potentials. See the reproduction guide for each page's commands, optional dependencies, and download formats.

Build the documentation, including its recorded example and benchmark results:

poetry install
poetry run make -C docs strict

This build does not run AA or MD calculations. Open docs/build/html/index.html after the build. Start with:

• documentation source;
• capability example gallery;
• scientific benchmark gallery;
• validation policy;
• portable state schema;
• development roadmap.

Digitized publication curves and author-provided numerical data have separate provenance and rights manifests; they are not covered by Otter's BSD software license unless a dataset explicitly says otherwise. The current bundled reference sets are published by maintainer decision with source attribution and license status NOASSERTION. Read the reference-data notice before reuse. The executable gate poetry run python tools/check_public_release.py rejects any future manifest that reintroduces an unresolved public-release action.

Development

poetry install
poetry run pytest -q
poetry run make -C docs strict
poetry run python -m build
poetry run python -m twine check dist/*

Anyone interested in Otter is welcome to contribute. See CONTRIBUTING.md for numerical and benchmark review requirements and CHANGELOG.md for user-visible changes.

Citation

If you use Otter in a scientific publication, please cite:

Chongbing Qu and Dominik Kraus, Otter, version 0.3.1, computer software (2026), https://github.com/otter-hed/otter.

@misc{QuKraus2026Otter,
  author  = {Qu, Chongbing and Kraus, Dominik},
  title   = {Otter},
  year    = {2026},
  note    = {Computer software, version 0.3.1},
  url     = {https://github.com/otter-hed/otter}
}

The same metadata are available in CITATION.cff. Otter is also available through GitHub's Cite this repository menu. Runtime configuration objects provide config.citation(style="plain"|"bibtex"|"cite") and expose their canonical citation_keys as scientific provenance for selected physical models; these are not additional software-citation requirements. See CITATIONS.md.

Acknowledgements

The authors thank Zachary A. Johnson and C. E. Starrett for helpful discussions.

Chongbing Qu gratefully acknowledges financial support from HEDI and the China Scholarship Council (CSC).

Otter is distributed under the BSD 3-Clause License.