xeos 0.1.0__tar.gz

xeos-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,134 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+# Modern replacement for styfle/cancel-workflow-action: cancel superseded runs
+# of this workflow on the same ref (e.g. rapid pushes to a PR branch).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ---------------------------------------------------------------------------
+  # Full cross-validation suite across the supported Python range, using the
+  # pinned conda environment (numpy/xarray + the optional gsw + dask extras) so
+  # the TEOS-10 backend and the dask-parallelized path are actually exercised.
+  # ---------------------------------------------------------------------------
+  test-conda:
+    name: test (conda, py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13', '3.14']
+
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v4
+
+      - name: Set up conda (miniforge)
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          miniforge-version: latest
+          channels: conda-forge
+          channel-priority: strict
+          python-version: ${{ matrix.python-version }}
+          activate-environment: test_env_xeos
+          auto-activate-base: false
+
+      - name: Update environment from ci/environment.yml
+        run: conda env update -f ci/environment.yml
+
+      - name: Editable install
+        run: python -m pip install -e .
+
+      - name: Environment info
+        run: |
+          conda env list
+          conda list
+
+      - name: Test with pytest
+        run: pytest -ra
+
+  # ---------------------------------------------------------------------------
+  # Guard the "core install stays lightweight" invariant: install ONLY the
+  # core package (numpy + xarray) via pip, confirm no heavy optional deps leaked
+  # in, and run the suite. The gsw/dask-dependent cases skip themselves cleanly
+  # (pytest.importorskip / ImportError -> pytest.skip), so this also serves as a
+  # non-conda cross-check that the vendored numpy kernels stand on their own.
+  # ---------------------------------------------------------------------------
+  test-pip-core:
+    name: test (pip, core-only)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install core package only (numpy + xarray)
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .
+
+      - name: Assert the core install did not pull heavy optional deps
+        run: |
+          python -c "import xeos; print('xeos import OK,', len(xeos.list_eos()), 'backends registered')"
+          python - <<'PY'
+          import importlib.util
+          for mod in ("gsw", "dask", "numba"):
+              assert importlib.util.find_spec(mod) is None, \
+                  f"{mod} unexpectedly installed by the core `pip install -e .` (invariant broken)"
+          print("lightweight-core invariant holds: gsw/dask/numba absent")
+          PY
+
+      - name: Run tests (pytest added separately so it is not a core dep)
+        run: |
+          python -m pip install pytest
+          pytest -ra
+
+  # ---------------------------------------------------------------------------
+  # Style / static-analysis. Advisory (non-blocking): the vendored numeric
+  # kernels deliberately use compact, hand-aligned coefficient tables and
+  # oceanographic single-letter names (R100, A0, SA, CT, ...), which black would
+  # explode line-per-value and pylint flags as naming/format violations. The
+  # job still runs so reviewers see the output, but does not gate the workflow.
+  # Flip `continue-on-error` to false once the team adopts a [tool.black] /
+  # pylint config that codifies those exceptions.
+  # ---------------------------------------------------------------------------
+  lint:
+    name: lint / format (advisory)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install lint tools + package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e . black pylint
+
+      - name: black --check
+        continue-on-error: true
+        run: black --check --diff xeos
+
+      - name: pylint
+        continue-on-error: true
+        run: pylint xeos

xeos-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Allow the GITHUB_TOKEN to deploy to GitHub Pages.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; cancel in-progress runs for the same ref.
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -r docs/requirements.txt
+
+      - name: Build HTML docs
+        run: sphinx-build -W --keep-going -b html docs docs/_build/html
+
+      - uses: actions/configure-pages@v5
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

xeos-0.1.0/.github/workflows/python-publish.yml

@@ -0,0 +1,99 @@
+# Build and publish xeos to PyPI using PyPI Trusted Publishing (OIDC).
+#
+# No API token / password secret is used: the `publish` job authenticates to
+# PyPI over OpenID Connect via `pypa/gh-action-pypi-publish`, gated by the
+# GitHub `pypi` environment. See conda/README.md and PyPI's "Trusted Publishers"
+# settings for the one-time configuration the maintainer must do on PyPI before
+# the first publish succeeds.
+#
+# Triggers:
+#   * release: published  -> build + publish to PyPI
+#   * workflow_dispatch   -> build (+ optional TestPyPI publish) on demand
+
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      testpypi:
+        description: "Also publish the build to TestPyPI"
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: twine check --strict dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    # Only publish to PyPI on an actual GitHub Release.
+    if: github.event_name == 'release'
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/xeos
+    permissions:
+      id-token: write  # OIDC token for Trusted Publishing
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    # Opt-in dry-run path: trigger via "Run workflow" and tick the `testpypi`
+    # box. Requires a separate Trusted Publisher configured on
+    # https://test.pypi.org and a GitHub environment named `testpypi`.
+    if: github.event_name == 'workflow_dispatch' && inputs.testpypi
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/xeos
+    permissions:
+      id-token: write  # OIDC token for Trusted Publishing
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

xeos-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# OS / editor
+.DS_Store
+
+# Sphinx docs build output
+docs/_build/
+
+# Claude Code transient worktrees
+.claude/worktrees/

xeos-0.1.0/CLAUDE.md

@@ -0,0 +1,122 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+`xeos` provides lightweight, xarray/dask-aware wrappers over many seawater
+Equations of State (EOS), so analysts can apply the *same* EOS their ocean-model
+run used (MOM6, Oceananigans, MITgcm) — selected by the model's own selector
+string. The polynomial/rational EOS are vendored as numpy kernels; core runtime
+deps are **numpy + xarray only**. TEOS-10 is delegated to the optional `gsw` extra
+(`pip install xeos[teos10]`) — note `gsw.rho` is itself the Roquet 75-term
+polynomial, not the exact Gibbs function (which is `gsw.rho_t_exact`).
+
+## Commands
+
+```bash
+pip install -e .[test]                              # editable install + gsw + pytest
+pytest                                              # full suite
+pytest xeos/tests/test_backends.py                  # cross-validation vs frozen truth
+pytest xeos/tests/test_models.py::test_selector_resolves   # a single test
+pylint xeos && black xeos                           # lint / format (declared in ci/environment.yml)
+```
+
+CI (`.github/workflows/ci.yml`) builds a conda env from `ci/environment.yml`,
+does an editable install, and runs `pytest` across Python 3.11–3.14.
+
+## Architecture
+
+The package is a small registry-and-facade design. Data flows:
+`from_model(model, selector)` → canonical EOS id → registered `EOSBackend`
+→ wrapped in an `EquationOfState` facade → kernels dispatched through xarray.
+
+- **`registry.py`** — `EOSBackend` dataclass (a `density` kernel + optional
+  analytic `drho_dt`/`drho_ds` + convention metadata) and a global registry.
+  Backends self-register at import time.
+- **`backends/`** — one module per EOS; importing `backends/__init__.py`
+  registers them all. Vendored kernels: `_linear`, `_wright` (full + reduced
+  coefficient sets, native pressure **Pa**), `_jmd95` and `_unesco` (native
+  **dbar**; `_unesco` reuses `_jmd95._rho_surface`), `_mdjwf` (rational fit,
+  **dbar**), `_roquet` (55-term TEOS-10 density polynomial, **dbar**≈depth),
+  `_roquet_spv` (55-term specific-volume form, MOM6 `ROQUET_SPV`), and
+  `_roquet_idealized` (6 second-order Roquet forms via one factory, conservative
+  temp / absolute salinity, Z = −p), and `_mpas` (MPAS-Ocean: `mpas-linear` plus
+  `mpas-jm`/`mpas-wright`, which **reuse** the `_jmd95`/`_wright`-reduced kernels —
+  byte-identical EOS). `_teos10` is a thin lazy-`gsw` wrapper.
+- **`eos.py`** — `EquationOfState` facade. Converts user pressure (default dbar)
+  to each backend's native unit, dispatches via `xarray_utils.apply_eos`, and
+  computes `alpha = -drho_dt/rho`, `beta = drho_ds/rho` from analytic derivatives,
+  falling back to centred finite differences when a backend supplies none.
+- **`models.py`** — `MODEL_SELECTORS` alias table mapping each model's selector
+  strings (MOM6 `EQN_OF_STATE`, MITgcm `eosType`, Oceananigans EOS types, MPAS-O
+  `config_eos_type`) to canonical ids; `from_model()` and `equation_of_state()`
+  (the latter handles parameterised schemes like `linear`).
+- **`conventions.py`** — `TemperatureKind`/`SalinityKind`/`PressureUnit` enums
+  and optional gsw-backed conversion helpers. **xeos never silently converts
+  inputs**; backends declare the kinds they expect. TEOS-10 + Roquet take
+  conservative temperature / absolute salinity; everything else potential
+  temperature / practical salinity.
+- **`xarray_utils.py`** — `apply_eos` wraps kernels with
+  `xr.apply_ufunc(dask="parallelized")` when any input is a DataArray (preserving
+  labels/dask, attaching CF attrs); otherwise calls the kernel on numpy arrays.
+
+### Adding an EOS
+Drop a `backends/_name.py` that builds an `EOSBackend` and calls `register(...)`,
+import it in `backends/__init__.py`, and add its model selector strings to
+`MODEL_SELECTORS`. Tests iterating the registry / truth fixtures pick it up.
+
+### Critical gotchas
+- **Pressure units differ per backend** (Wright = Pa, JMD95/Roquet/gsw = dbar);
+  the facade converts, so a kernel always receives its declared native unit.
+- **Wright variants share one formula, differ only in coefficients.** Both
+  `wright97-reduced` (MOM6 `WRIGHT`/`WRIGHT_RED`) and `wright97-full`
+  (`WRIGHT_FULL`) are validated against MOM6 Fortran (`MOM_EOS_Wright_{red,full}.F90`).
+- **MOM6 `UNESCO`/`JACKETT_MCD` is the JMD95 fit, NOT EOS-80.** Despite the name,
+  `MOM_EOS_UNESCO.F90` is the Jackett & McDougall (1995) potential-temp fit —
+  byte-for-byte xeos's `jmd95` (verified to machine precision), differing from the
+  original Fofonoff & Millard EOS-80 (xeos's `unesco`, = MITgcm `UNESCO`) by up to
+  ~0.4 kg/m³. So those MOM6 selectors resolve to `jmd95` in `models.py`; the
+  `jmd95@mom6` truth case pins the equivalence.
+- **`ROQUET_SPV` uses `deltaS=24`, NOT 32.** The widely-used `polyTEOS10.py`
+  reference has a typo in its `polyTEOS10_55t` routine (`deltaS=32`, copied from the
+  density form), making its specific-volume output disagree with its own published
+  check values. `_roquet_spv.py` uses the correct `24` and is validated against
+  MOM6's authoritative Fortran (`MOM_EOS_Roquet_SpV.F90`), not the buggy Python —
+  see `xeos/tests/reference/_build_roquet_spv_fortran.py`. (Bug reported upstream.)
+- **MPAS-O `jm`/`wright` are the same EOS as `jmd95`/`wright97-reduced`.** MPAS-O's
+  `config_eos_type` offers `linear`, `jm` (Jackett-McDougall 1995) and `wright`
+  (Wright 1997, reduced coefficients); the `jm`/`wright` coefficients are
+  byte-for-byte identical to xeos's existing kernels, so `_mpas.py` reuses those
+  kernel functions rather than re-vendoring them, and the `mpas-jm`/`mpas-wright`
+  truth (from MPAS-O's own Fortran, `_build_mpas_eos_fortran.py`) confirms the reuse
+  is exact. MPAS-O's T/S clamping and depth→pressure parameterisations are
+  documented in `_mpas.py` but **not** applied (the facade takes pressure as input).
+- **Not yet implemented:** MOM6 `JACKETT_06`, MOM6 `WRIGHT` legacy-buggy, MITgcm
+  `POLY3` (per-level runtime coefficients), MITgcm `IDEALGAS`. Add as new
+  `backends/_*.py` + selector entries when a trustworthy reference is available.
+
+## Testing & reference truth
+
+`test_backends.py` validates each vendored kernel against frozen values in
+`xeos/tests/reference/truth.json`. **Preferred truth source is the model's own
+source code**, not a third-party Python port: MITgcm Fortran (`jmd95`, `unesco`,
+`mdjwf` — coefficients parsed from `ini_eos.F`, formulas from `find_rho.F`), MOM6
+Fortran (`wright97-*`, `jmd95@mom6`, `roquet-spv`) and MPAS-Ocean Fortran
+(`mpas-linear`/`-jm`/`-wright`, from E3SM) all compiled with gfortran, plus
+Oceananigans' `SeawaterPolynomials.jl` run via Julia (the six idealized `roquet-*`
+forms); `gsw` is the accepted exception for `teos10`. The `_build_*.py` generators
+download/compile/run those sources on demand (each self-checks a value first) and
+emit only numbers, so the committed `truth.json` stays toolchain-free to consume.
+A truth case may set a `"backend"` field to validate one kernel against multiple
+model sources (e.g. `jmd95@mom6` → the `jmd95` backend, which is *also* validated
+against MITgcm's own Fortran; `mpas-jm`/`mpas-wright` reuse the `jmd95`/
+`wright97-reduced` kernels and confirm MPAS-O's `jm`/`wright` are the same EOS).
+Only `polyTEOS10.py` (→ `teos10-poly55`) remains a Python-port reference; `gsw` is
+canonical. All run in a **separate pinned env** (`xeos/tests/reference/environment.yml`:
+gfortran + julia + gsw); the regular suite reads only `truth.json`. Regenerate via
+`xeos/tests/reference/README.md` and commit the updated JSON.
+
+## Versioning
+
+Single-sourced in `xeos/version.py`, read by hatchling (`[tool.hatch.version]`).

xeos-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henri F. Drake
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xeos-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: xeos
+Version: 0.1.0
+Summary: xarray-enabled wrappers for various Equations of State of seawater
+Project-URL: Homepage, https://github.com/hdrake/xeos
+Project-URL: Bugs/Issues/Features, https://github.com/hdrake/xeos/issues
+Author-email: "Henri F. Drake" <hfdrake@uci.edu>
+License-File: LICENSE
+Keywords: ocean modeling,oceanography,water mass transformation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: numpy
+Requires-Dist: xarray
+Provides-Extra: complete
+Requires-Dist: gsw; extra == 'complete'
+Requires-Dist: numba; extra == 'complete'
+Provides-Extra: teos10
+Requires-Dist: gsw; extra == 'teos10'
+Provides-Extra: test
+Requires-Dist: dask; extra == 'test'
+Requires-Dist: gsw; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+# xeos
+
+**Lightweight, xarray-enabled wrappers for seawater equations of state.**
+
+Ocean models (MOM6, MITgcm, MPAS-Ocean, Oceananigans) differ in the equation of
+state (EOS) they use, and many let you change it at run time. Python post-processing then
+often applies a *different* EOS than the simulation did, silently corrupting
+derived quantities like density, thermal expansion, and water-mass transformation
+diagnostics. `xeos` lets you pick the EOS that matches your run — **by the model's
+own selector string** — and apply it to xarray/dask data through one uniform API.
+
+It stays lightweight on purpose: the polynomial/rational equations of state are
+vendored as small numpy kernels, so the core install needs only **numpy + xarray**.
+TEOS-10 (via `gsw`) is an optional extra.
+
+## Install
+
+```bash
+pip install xeos              # core (numpy + xarray): all vendored EOS
+pip install xeos[teos10]      # adds TEOS-10 via gsw
+pip install xeos[complete]    # gsw + numba acceleration
+```
+
+## Usage
+
+Match your model run by its selector string:
+
+```python
+import xeos
+
+# MOM6 run with EQN_OF_STATE = "WRIGHT_FULL"
+eos = xeos.from_model("MOM6", "WRIGHT_FULL")
+rho = eos.rho(theta, salt, pressure)     # xarray DataArrays in, labeled DataArray out
+a   = eos.alpha(theta, salt, pressure)   # thermal expansion
+b   = eos.beta(theta, salt, pressure)    # haline contraction
+
+# MITgcm eosType = 'JMD95Z'
+xeos.from_model("MITgcm", "JMD95Z").rho(theta, salt, p)
+
+# MPAS-Ocean config_eos_type = 'jm'
+xeos.from_model("MPAS-Ocean", "jm").rho(theta, salt, p)
+
+# Oceananigans TEOS10EquationOfState
+xeos.from_model("Oceananigans", "TEOS10EquationOfState").rho(CT, SA, p)
+```
+
+Or address an EOS directly:
+
+```python
+xeos.equation_of_state("jmd95").rho(t, s, p)
+xeos.rho(t, s, p, eos="wright97-full")          # one-off functional form
+xeos.list_eos()                                  # what's available
+```
+
+Inputs may be scalars, numpy arrays, or xarray `DataArray`s (dask-backed arrays
+stay lazy). Pressure is sea pressure in **dbar** by default.
+
+## Conventions
+
+`xeos` does **not** silently convert inputs. Each EOS declares the temperature and
+salinity it expects: TEOS-10 and the Roquet polynomials use **conservative
+temperature** + **absolute salinity**; the others use **potential temperature** +
+**practical salinity** (see `eos.temperature` / `eos.salinity`). Explicit
+conversion helpers live in `xeos.conventions` (these need the `gsw` extra).
+
+## Supported equations of state
+
+`xeos.list_eos()` returns the current set. As of now:
+
+- **linear** — configurable (MOM6/MITgcm/Oceananigans `LINEAR`)
+- **wright97-full**, **wright97-reduced** — Wright 1997 (MOM6 `WRIGHT_FULL`, `WRIGHT`/`WRIGHT_RED`)
+- **jmd95** — Jackett & McDougall 1995 (MITgcm `JMD95Z`/`JMD95P`; **also** MOM6
+  `UNESCO`/`JACKETT_MCD`, which are this fit — *not* EOS-80)
+- **unesco** — UNESCO/EOS-80, Fofonoff & Millard 1983 (MITgcm `UNESCO`)
+- **mdjwf** — McDougall et al. 2003 (MITgcm `MDJWF`)
+- **teos10-poly55** — Roquet 55-term polynomial / TEOS-10 density form
+  (Oceananigans `TEOS10EquationOfState`, MOM6 `ROQUET_RHO`/`NEMO`)
+- **roquet-spv** — Roquet 55-term specific-volume form (MOM6 `ROQUET_SPV`)
+- **roquet-{linear,cabbeling,cabbeling-thermobaricity,freezing,second-order,simplest-realistic}**
+  — idealized second-order Roquet forms (Oceananigans `RoquetSeawaterPolynomial(:…)`)
+- **mpas-linear**, **mpas-jm**, **mpas-wright** — MPAS-Ocean / E3SM
+  `config_eos_type` = `linear`/`jm`/`wright`; `mpas-jm` and `mpas-wright` reuse the
+  `jmd95` and `wright97-reduced` kernels (MPAS-O's `jm`/`wright` are the same EOS)
+- **teos10** — TEOS-10 via `gsw` (its 75-term Roquet polynomial, not the exact
+  Gibbs function; MOM6/MITgcm `TEOS10`)
+
+Not yet implemented (planned, slot into the same registry): MOM6 `JACKETT_06` and
+`WRIGHT` legacy-buggy, and MITgcm `POLY3` (per-level runtime coefficients).
+
+Full literature references with DOIs are in the
+[usage docs](docs/usage.md#references).
+
+## Development
+
+```bash
+pip install -e .[test]
+pytest                       # validates vendored kernels against frozen fixtures
+```
+
+Test "truth" values are generated from authoritative reference packages in a
+pinned, separate environment and frozen into `xeos/tests/reference/truth.json`;
+the test suite reads that file and stays lightweight. See
+[`xeos/tests/reference/README.md`](xeos/tests/reference/README.md) to regenerate.