Metadata-Version: 2.4
Name: otter-hed
Version: 0.3.0
Summary: Average-atom, pseudoatom, and ionic-structure calculations for dense plasmas.
Author: Chongbing Qu, Dominik Kraus
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/otter-hed/otter
Project-URL: Documentation, https://otter-hed.github.io/otter/
Project-URL: Repository, https://github.com/otter-hed/otter
Project-URL: Issues, https://github.com/otter-hed/otter/issues
Keywords: average atom,dense plasma,ionic structure,pseudoatom,warm dense matter
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: numpy<3,>=2.0
Requires-Dist: scipy<2,>=1.13
Requires-Dist: numba<1,>=0.60
Requires-Dist: matplotlib>=3.8
Provides-Extra: libxc
Requires-Dist: pylibxc7==7.0.0; extra == "libxc"
Dynamic: license-file

# 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)](https://doi.org/10.1016/j.hedp.2013.12.001).

## Capabilities

- finite-temperature quantum (KS-DFT, QM) and Thomas–Fermi (TF) electronic structure; the
  QM model provides orbital levels, occupations, and density components;
- 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:

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

Windows PowerShell:

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

Verify the installation:

```console
poetry --version
```

Clone and install:

```bash
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:

```bash
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](https://otter-hed.github.io/otter/user_guide/xc_functionals.html#installation).

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

## Quick start

Run an introductory calculation in Google Colab:

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/otter-hed/otter/blob/main/notebooks/00-otter_intro.ipynb)

Run the complete [single-species workflow](examples/single_species_workflow.py)
from the repository root:

```bash
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](examples/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](docs/source/user_guide/state_exports.rst) 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](https://otter-hed.github.io/otter/),
[example gallery](https://otter-hed.github.io/otter/gen_examples/index.html), and
[scientific benchmarks](https://otter-hed.github.io/otter/benchmarks/index.html).

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

```bash
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](https://otter-hed.github.io/otter/user_guide/reproducing_galleries.html)
for each page's commands, optional dependencies, and download formats.

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

```bash
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](docs/source/index.rst);
- [capability example gallery](docs/examples/README.rst);
- [scientific benchmark gallery](docs/source/benchmarks/index.rst);
- [validation policy](docs/source/benchmarks/validation_policy.rst);
- [portable state schema](docs/source/user_guide/state_exports.rst);
- [development roadmap](docs/source/development/roadmap.rst).

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](benchmarks/reference_data/README.md) 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

```bash
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](CONTRIBUTING.md) for numerical and benchmark review
requirements and [CHANGELOG.md](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.0, computer software (2026),
> [https://github.com/otter-hed/otter](https://github.com/otter-hed/otter).

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

The same metadata are available in [CITATION.cff](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`](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](LICENSE).
