tipbox 0.1.0__tar.gz

tipbox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juan Nathaniel
+
+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.

tipbox-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: tipbox
+Version: 0.1.0
+Summary: Stochastic tipping models, empirical observations, and early-warning benchmarks
+Author-email: Juan Nathaniel <jn2808@columbia.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/juannat7/tipbox
+Project-URL: Documentation, https://juannat7.github.io/tipbox/
+Project-URL: Issues, https://github.com/juannat7/tipbox/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jax
+Requires-Dist: jaxlib
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Provides-Extra: docs
+Requires-Dist: sphinx<9,>=7; extra == "docs"
+Requires-Dist: furo>=2024.8.6; extra == "docs"
+Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
+Dynamic: license-file
+
+# <img src="https://raw.githubusercontent.com/juannat7/tipbox/main/docs/tipbox-icon-300ppi.png" alt="" width="48" height="48" align="absmiddle"> TipBox
+
+TipBox is a collection of tipping models and empirical observations. It covers bifurcation- and rate-induced tipping in stochastic systems, with early-warning indicators such as lag-1 autocorrelation and variance.
+
+<div align="center">
+
+[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![PyPI version](https://img.shields.io/pypi/v/tipbox)](https://pypi.org/project/tipbox/)
+[![PyPI downloads](https://static.pepy.tech/personalized-badge/tipbox?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=Downloads)](https://pepy.tech/projects/tipbox)
+[![Documentation](https://img.shields.io/badge/docs-Documentation-b31b1b)](https://juannat7.github.io/tipbox/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/juannat7/tipbox/blob/main/LICENSE)
+
+</div>
+
+## Contents
+
+- [Installation](#installation)
+- [Generate or load a time series](#generate-or-load-a-time-series)
+- [Early-warning indicators](#compute-early-warning-indicators)
+- [Benchmarking](#benchmarking)
+- [Systems](#systems)
+- [Notebook examples](#notebook-examples)
+- [Used in research](#used-in-research)
+- [Citation](#citation)
+
+## Installation
+
+```bash
+pip install tipbox
+```
+
+For development, clone this repository and run `pip install -e .`.
+
+## Generate or load a time series
+
+TipBox provides a common interface to simulate tipping systems and load observations. See the [system collection](#systems) for available models and their documentation.
+
+```python
+from tipbox.models import MayHarvesting, SaddleNode
+from tipbox.datasets import Microcosm
+
+# Bifurcation-induced tipping
+harvesting = MayHarvesting()
+bifurcation = harvesting.make_trajectory(num_samples=1200, noise=1.0, seed=43)
+bifurcation_control = harvesting.make_trajectory(num_samples=1200, noise=1.0, seed=43, null_simulation=True)
+
+# Rate-induced tipping
+rate_model = SaddleNode(epsilon=1.4)
+rate = rate_model.make_trajectory(num_samples=2401, noise=0.01, seed=43)
+rate_control = rate_model.make_trajectory(num_samples=2401, noise=0.01, seed=43, null_simulation=True)
+
+# Empirical observations: Veraart et al. (2012), chemostats M1 and M2.
+observed = Microcosm().load()
+```
+
+Simulation results contain `time` and `trajectory` arrays; loaded observations contain `time` and `observations`. Equations, parameters, and simulation controls are in the [documentation](https://juannat7.github.io/tipbox/usage.html).
+
+![Bifurcation-induced tipping, rate-induced tipping, and empirical observations](https://raw.githubusercontent.com/juannat7/tipbox/main/docs/_static/figures/trajectories.png)
+
+Empirical panels: [CC BY-NC 4.0](https://github.com/juannat7/tipbox/blob/main/docs/_static/figures/LICENSE.md).
+
+## Compute early-warning indicators
+
+Choose an observable and apply a trailing-window statistic before the fold:
+
+```python
+from tipbox.indicators import rolling_ar1, rolling_variance
+
+before_fold = bifurcation.param_values < harvesting.critical_parameter
+signal = bifurcation.trajectory[before_fold, 0]
+
+# Get early warning signals
+ar1 = rolling_ar1(signal, window=200, detrend="linear")
+variance = rolling_variance(signal, window=200, detrend="linear")
+```
+
+The [indicator reference](https://juannat7.github.io/tipbox/indicators.html) also covers autocorrelation, skewness, and kurtosis.
+
+![AR1 and variance for the same three time series](https://raw.githubusercontent.com/juannat7/tipbox/main/docs/_static/figures/indicators.png)
+
+## Benchmarking
+
+Evaluate indicator trends on tipping and control trajectories with the area under the ROC curve (AUROC). Each trajectory contributes one score.
+
+### Generate a batch
+
+Batches support repeated experiments and indicator comparisons:
+
+```python
+from tipbox.models import MayHarvesting
+from tipbox.datasets import generate_dataset
+from tipbox.indicators import rolling_ar1, rolling_variance
+from tipbox.metrics import ensemble_roc, plot_roc
+
+# 50 tipping trajectories + 50 controls; retain 300 samples before each tipping threshold.
+batch = generate_dataset(
+    MayHarvesting(), num_tipping=50, num_controls=50, num_samples=1000,
+    context_samples=300, noise=1.0, seed=43,
+)
+signals = batch.observations[:, :, 0]  # First observed variable in each trajectory.
+indicators = {
+    "AR1": [rolling_ar1(x, window=100, detrend="linear") for x in signals],
+    "Variance": [rolling_variance(x, window=100, detrend="linear") for x in signals],
+}
+```
+
+Score the indicator trend in each trajectory and plot the ROC curves:
+
+```python
+report = ensemble_roc(batch.labels, indicators)  # Labels: 0 control, 1 tipping.
+ax = plot_roc(report)
+```
+
+![AR1 and variance ROC curves for the May harvesting batch](https://raw.githubusercontent.com/juannat7/tipbox/main/docs/_static/figures/roc.png)
+
+See the [benchmark guide](https://juannat7.github.io/tipbox/benchmarks.html) for labels, trend scores, and evaluation conventions.
+
+## Systems
+
+Import model classes from `tipbox.models` and observation classes from `tipbox.datasets`.
+Model links include equations and defaults; observation links describe `.load()`.
+
+| System | Class / call | Mechanism / observable |
+|---|---|---|
+| **Models** | | |
+| [May harvesting](https://juannat7.github.io/tipbox/models/harvesting.html) | `MayHarvesting` | Fold |
+| [Rosenzweig–MacArthur](https://juannat7.github.io/tipbox/models/consumer_resource.html) | `RosenzweigMacArthur` | Transcritical / Hopf |
+| [Disease and vaccination](https://juannat7.github.io/tipbox/models/seirx.html) | `SEIRx` | Transcritical |
+| [Ocean overturning](https://juannat7.github.io/tipbox/models/amoc.html#amoc-fold) | `AMOCFold` | Fold |
+| [Moving saddle-node](https://juannat7.github.io/tipbox/models/saddle_node.html) | `SaddleNode` | Rate-induced |
+| [Moving Bautin](https://juannat7.github.io/tipbox/models/bautin.html) | `Bautin` | Rate-induced |
+| [Compost bomb](https://juannat7.github.io/tipbox/models/compost.html) | `CompostBomb` | Rate-induced |
+| [Ocean overturning](https://juannat7.github.io/tipbox/models/amoc.html#amoc-rate) | `AMOCRate` | Rate-induced |
+| [Ricker population map](https://juannat7.github.io/tipbox/models/ricker.html) | `Ricker` | Population decline |
+| [Combustion oscillator](https://juannat7.github.io/tipbox/models/thermoacoustic.html) | `Thermoacoustic` | Subcritical Hopf |
+| **Empirical observations** | | |
+| [Microcosm · M1 and M2](https://juannat7.github.io/tipbox/api.html#tipbox.datasets.Microcosm) | `Microcosm().load()` | Light attenuation |
+| [Voice onset](https://juannat7.github.io/tipbox/api.html#tipbox.datasets.VoiceOnset) | `VoiceOnset().load()` | Subglottal pressure |
+| [Cellular ATP](https://juannat7.github.io/tipbox/api.html#tipbox.datasets.CellularATP) | `CellularATP().load()` | Fluorescence ratio |
+| [Paleoclimate](https://juannat7.github.io/tipbox/api.html#tipbox.datasets.Paleoclimate) | `Paleoclimate().load()` | CaCO₃ |
+| [Electrical blackout](https://juannat7.github.io/tipbox/api.html#tipbox.datasets.ElectricalBlackout) | `ElectricalBlackout().load()` | Frequency |
+
+Full reference: [system catalog](https://juannat7.github.io/tipbox/models/index.html).
+
+![Phase portraits and simulated trajectories, with start and end markers](https://raw.githubusercontent.com/juannat7/tipbox/main/docs/_static/figures/overview.png)
+
+## Notebook examples
+
+- [Generation and evaluation](https://github.com/juannat7/tipbox/blob/main/notebook/01_generate_batch.ipynb)
+- [Parameter sensitivity](https://github.com/juannat7/tipbox/blob/main/notebook/02_sensitivity_analysis.ipynb)
+
+## Used in research
+
+- **[In revision]** Nathaniel et al. (2026), [Koopman early warning signals for bifurcation and rate-induced tipping](https://arxiv.org/abs/2608.14716). Code: [KEWS](https://github.com/juannat7/kews).
+- **[NeurIPS 2026]** Sevinchan, Nathaniel, et al. (2026), [In-context learning to predict critical transitions in dynamical systems](https://arxiv.org/abs/2605.12308).
+
+## Citation
+
+If you use TipBox's code or datasets, we would appreciate citations to these works:
+
+```bibtex
+@article{nathaniel2026koopman,
+  title={Koopman early warning signals for bifurcation and rate-induced tipping},
+  author={Nathaniel, Juan and Roesch, Carla and DeSantis, Derek and Kooloth, Parvathi and Fan, Hang and Lucarini, Valerio and Romanou, Anastasia and Gentine, Pierre},
+  journal={arXiv preprint arXiv:2608.14716},
+  year={2026}
+}
+
+@article{sevinchan2026context,
+  title={In-context learning to predict critical transitions in dynamical systems},
+  author={Sevinchan, Yunus and Nathaniel, Juan and Ueltzh{\"o}ffer, Kai and Roesch, Carla and Weber, Tobias and Laschos, Vaios and Fan, Hang and Ramien, Gregor and Haux, Johannes and Gentine, Pierre and others},
+  journal={arXiv preprint arXiv:2605.12308},
+  year={2026}
+}
+```

tipbox-0.1.0/README.md

@@ -0,0 +1,175 @@
+# <img src="https://raw.githubusercontent.com/juannat7/tipbox/main/docs/tipbox-icon-300ppi.png" alt="" width="48" height="48" align="absmiddle"> TipBox
+
+TipBox is a collection of tipping models and empirical observations. It covers bifurcation- and rate-induced tipping in stochastic systems, with early-warning indicators such as lag-1 autocorrelation and variance.
+
+<div align="center">
+
+[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![PyPI version](https://img.shields.io/pypi/v/tipbox)](https://pypi.org/project/tipbox/)
+[![PyPI downloads](https://static.pepy.tech/personalized-badge/tipbox?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=Downloads)](https://pepy.tech/projects/tipbox)
+[![Documentation](https://img.shields.io/badge/docs-Documentation-b31b1b)](https://juannat7.github.io/tipbox/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/juannat7/tipbox/blob/main/LICENSE)
+
+</div>
+
+## Contents
+
+- [Installation](#installation)
+- [Generate or load a time series](#generate-or-load-a-time-series)
+- [Early-warning indicators](#compute-early-warning-indicators)
+- [Benchmarking](#benchmarking)
+- [Systems](#systems)
+- [Notebook examples](#notebook-examples)
+- [Used in research](#used-in-research)
+- [Citation](#citation)
+
+## Installation
+
+```bash
+pip install tipbox
+```
+
+For development, clone this repository and run `pip install -e .`.
+
+## Generate or load a time series
+
+TipBox provides a common interface to simulate tipping systems and load observations. See the [system collection](#systems) for available models and their documentation.
+
+```python
+from tipbox.models import MayHarvesting, SaddleNode
+from tipbox.datasets import Microcosm
+
+# Bifurcation-induced tipping
+harvesting = MayHarvesting()
+bifurcation = harvesting.make_trajectory(num_samples=1200, noise=1.0, seed=43)
+bifurcation_control = harvesting.make_trajectory(num_samples=1200, noise=1.0, seed=43, null_simulation=True)
+
+# Rate-induced tipping
+rate_model = SaddleNode(epsilon=1.4)
+rate = rate_model.make_trajectory(num_samples=2401, noise=0.01, seed=43)
+rate_control = rate_model.make_trajectory(num_samples=2401, noise=0.01, seed=43, null_simulation=True)
+
+# Empirical observations: Veraart et al. (2012), chemostats M1 and M2.
+observed = Microcosm().load()
+```
+
+Simulation results contain `time` and `trajectory` arrays; loaded observations contain `time` and `observations`. Equations, parameters, and simulation controls are in the [documentation](https://juannat7.github.io/tipbox/usage.html).
+
+![Bifurcation-induced tipping, rate-induced tipping, and empirical observations](https://raw.githubusercontent.com/juannat7/tipbox/main/docs/_static/figures/trajectories.png)
+
+Empirical panels: [CC BY-NC 4.0](https://github.com/juannat7/tipbox/blob/main/docs/_static/figures/LICENSE.md).
+
+## Compute early-warning indicators
+
+Choose an observable and apply a trailing-window statistic before the fold:
+
+```python
+from tipbox.indicators import rolling_ar1, rolling_variance
+
+before_fold = bifurcation.param_values < harvesting.critical_parameter
+signal = bifurcation.trajectory[before_fold, 0]
+
+# Get early warning signals
+ar1 = rolling_ar1(signal, window=200, detrend="linear")
+variance = rolling_variance(signal, window=200, detrend="linear")
+```
+
+The [indicator reference](https://juannat7.github.io/tipbox/indicators.html) also covers autocorrelation, skewness, and kurtosis.
+
+![AR1 and variance for the same three time series](https://raw.githubusercontent.com/juannat7/tipbox/main/docs/_static/figures/indicators.png)
+
+## Benchmarking
+
+Evaluate indicator trends on tipping and control trajectories with the area under the ROC curve (AUROC). Each trajectory contributes one score.
+
+### Generate a batch
+
+Batches support repeated experiments and indicator comparisons:
+
+```python
+from tipbox.models import MayHarvesting
+from tipbox.datasets import generate_dataset
+from tipbox.indicators import rolling_ar1, rolling_variance
+from tipbox.metrics import ensemble_roc, plot_roc
+
+# 50 tipping trajectories + 50 controls; retain 300 samples before each tipping threshold.
+batch = generate_dataset(
+    MayHarvesting(), num_tipping=50, num_controls=50, num_samples=1000,
+    context_samples=300, noise=1.0, seed=43,
+)
+signals = batch.observations[:, :, 0]  # First observed variable in each trajectory.
+indicators = {
+    "AR1": [rolling_ar1(x, window=100, detrend="linear") for x in signals],
+    "Variance": [rolling_variance(x, window=100, detrend="linear") for x in signals],
+}
+```
+
+Score the indicator trend in each trajectory and plot the ROC curves:
+
+```python
+report = ensemble_roc(batch.labels, indicators)  # Labels: 0 control, 1 tipping.
+ax = plot_roc(report)
+```
+
+![AR1 and variance ROC curves for the May harvesting batch](https://raw.githubusercontent.com/juannat7/tipbox/main/docs/_static/figures/roc.png)
+
+See the [benchmark guide](https://juannat7.github.io/tipbox/benchmarks.html) for labels, trend scores, and evaluation conventions.
+
+## Systems
+
+Import model classes from `tipbox.models` and observation classes from `tipbox.datasets`.
+Model links include equations and defaults; observation links describe `.load()`.
+
+| System | Class / call | Mechanism / observable |
+|---|---|---|
+| **Models** | | |
+| [May harvesting](https://juannat7.github.io/tipbox/models/harvesting.html) | `MayHarvesting` | Fold |
+| [Rosenzweig–MacArthur](https://juannat7.github.io/tipbox/models/consumer_resource.html) | `RosenzweigMacArthur` | Transcritical / Hopf |
+| [Disease and vaccination](https://juannat7.github.io/tipbox/models/seirx.html) | `SEIRx` | Transcritical |
+| [Ocean overturning](https://juannat7.github.io/tipbox/models/amoc.html#amoc-fold) | `AMOCFold` | Fold |
+| [Moving saddle-node](https://juannat7.github.io/tipbox/models/saddle_node.html) | `SaddleNode` | Rate-induced |
+| [Moving Bautin](https://juannat7.github.io/tipbox/models/bautin.html) | `Bautin` | Rate-induced |
+| [Compost bomb](https://juannat7.github.io/tipbox/models/compost.html) | `CompostBomb` | Rate-induced |
+| [Ocean overturning](https://juannat7.github.io/tipbox/models/amoc.html#amoc-rate) | `AMOCRate` | Rate-induced |
+| [Ricker population map](https://juannat7.github.io/tipbox/models/ricker.html) | `Ricker` | Population decline |
+| [Combustion oscillator](https://juannat7.github.io/tipbox/models/thermoacoustic.html) | `Thermoacoustic` | Subcritical Hopf |
+| **Empirical observations** | | |
+| [Microcosm · M1 and M2](https://juannat7.github.io/tipbox/api.html#tipbox.datasets.Microcosm) | `Microcosm().load()` | Light attenuation |
+| [Voice onset](https://juannat7.github.io/tipbox/api.html#tipbox.datasets.VoiceOnset) | `VoiceOnset().load()` | Subglottal pressure |
+| [Cellular ATP](https://juannat7.github.io/tipbox/api.html#tipbox.datasets.CellularATP) | `CellularATP().load()` | Fluorescence ratio |
+| [Paleoclimate](https://juannat7.github.io/tipbox/api.html#tipbox.datasets.Paleoclimate) | `Paleoclimate().load()` | CaCO₃ |
+| [Electrical blackout](https://juannat7.github.io/tipbox/api.html#tipbox.datasets.ElectricalBlackout) | `ElectricalBlackout().load()` | Frequency |
+
+Full reference: [system catalog](https://juannat7.github.io/tipbox/models/index.html).
+
+![Phase portraits and simulated trajectories, with start and end markers](https://raw.githubusercontent.com/juannat7/tipbox/main/docs/_static/figures/overview.png)
+
+## Notebook examples
+
+- [Generation and evaluation](https://github.com/juannat7/tipbox/blob/main/notebook/01_generate_batch.ipynb)
+- [Parameter sensitivity](https://github.com/juannat7/tipbox/blob/main/notebook/02_sensitivity_analysis.ipynb)
+
+## Used in research
+
+- **[In revision]** Nathaniel et al. (2026), [Koopman early warning signals for bifurcation and rate-induced tipping](https://arxiv.org/abs/2608.14716). Code: [KEWS](https://github.com/juannat7/kews).
+- **[NeurIPS 2026]** Sevinchan, Nathaniel, et al. (2026), [In-context learning to predict critical transitions in dynamical systems](https://arxiv.org/abs/2605.12308).
+
+## Citation
+
+If you use TipBox's code or datasets, we would appreciate citations to these works:
+
+```bibtex
+@article{nathaniel2026koopman,
+  title={Koopman early warning signals for bifurcation and rate-induced tipping},
+  author={Nathaniel, Juan and Roesch, Carla and DeSantis, Derek and Kooloth, Parvathi and Fan, Hang and Lucarini, Valerio and Romanou, Anastasia and Gentine, Pierre},
+  journal={arXiv preprint arXiv:2608.14716},
+  year={2026}
+}
+
+@article{sevinchan2026context,
+  title={In-context learning to predict critical transitions in dynamical systems},
+  author={Sevinchan, Yunus and Nathaniel, Juan and Ueltzh{\"o}ffer, Kai and Roesch, Carla and Weber, Tobias and Laschos, Vaios and Fan, Hang and Ramien, Gregor and Haux, Johannes and Gentine, Pierre and others},
+  journal={arXiv preprint arXiv:2605.12308},
+  year={2026}
+}
+```

tipbox-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tipbox"
+version = "0.1.0"
+description = "Stochastic tipping models, empirical observations, and early-warning benchmarks"
+authors = [
+    {name = "Juan Nathaniel", email = "jn2808@columbia.edu"},
+]
+dependencies = [
+    "jax",
+    "jaxlib",
+    "numpy",
+    "scipy",
+    "matplotlib",
+]
+
+requires-python = ">=3.10"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+docs = ["sphinx>=7,<9", "furo>=2024.8.6", "sphinx-copybutton>=0.5"]
+
+[tool.setuptools.packages.find]
+include = ["tipbox*"]
+
+[project.urls]
+Homepage = "https://github.com/juannat7/tipbox"
+Documentation = "https://juannat7.github.io/tipbox/"
+Issues = "https://github.com/juannat7/tipbox/issues"

tipbox-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tipbox-0.1.0/tipbox/__init__.py

@@ -0,0 +1,13 @@
+"""Box models and reproducible tipping-point benchmarks."""
+
+from . import generate
+from .registry import get_system_info, list_systems
+from .types import BoxModel, TrajectoryResult
+
+__all__ = [
+    "BoxModel",
+    "TrajectoryResult",
+    "generate",
+    "get_system_info",
+    "list_systems",
+]

tipbox-0.1.0/tipbox/_amoc.py

@@ -0,0 +1,126 @@
+"""Shared physical parameters and numerical kernels for the two-state AMOC model."""
+
+from dataclasses import dataclass
+
+import jax.numpy as jnp
+
+from .utils import parameter, register_dataclass_pytree
+
+
+@register_dataclass_pytree
+@dataclass(frozen=True)
+class AMOCPhysics:
+    """Calibrated 2×CO₂ box-model parameters; salinities are mass fractions.
+
+    The states are 100 times salinity anomalies. Their drift therefore includes
+    100 times the seconds-per-year conversion. Model time is years; box volumes
+    use m³ and transports use m³/s.
+    """
+
+    S0: float = parameter(0.035, "Reference salinity mass fraction.", "mass fraction")
+    alpha: float = parameter(0.12, "Thermal-density coefficient.", "kg / m^3 / K")
+    beta: float = parameter(
+        790.0, "Haline-density coefficient per salinity mass fraction.", "kg / m^3"
+    )
+    seconds_per_year: float = parameter(
+        31500000.0,
+        "Seconds per model year; the separate factor100 converts salinity fractions to anomaly coordinates.",
+        "s / year",
+    )
+    V_N: float = parameter(3.683e16, "North Atlantic box volume.", "m^3")
+    V_T: float = parameter(5.418e16, "Tropical Atlantic box volume.", "m^3")
+    V_S: float = parameter(6.097e16, "Southern Ocean box volume.", "m^3")
+    V_IP: float = parameter(1.486e17, "Indo-Pacific box volume.", "m^3")
+    V_B: float = parameter(9.925e17, "Bottom-water box volume.", "m^3")
+    T_S: float = parameter(
+        7.919, "Southern reference temperature in the transport closure.", "degC"
+    )
+    T_0: float = parameter(
+        3.87, "North Atlantic reference temperature in the transport closure.", "degC"
+    )
+    total_salt: float = parameter(
+        4.4735e16, "Conserved salinity-volume integral.", "m^3"
+    )
+    lambda_q: float = parameter(
+        16200000.0, "Density-to-volume-transport coefficient.", "m^6 / kg / s"
+    )
+    gamma: float = parameter(
+        0.36, "Southern contribution to northward advective inflow.", "dimensionless"
+    )
+    mu: float = parameter(
+        2.2e-07,
+        "Temperature-transport coupling in the transport denominator.",
+        "K s / m^3",
+    )
+    K_N: float = parameter(1762000.0, "Northern gyre exchange transport.", "m^3 / s")
+    K_S: float = parameter(1872000.0, "Southern gyre exchange transport.", "m^3 / s")
+    S_S: float = parameter(0.034427, "Fixed Southern Ocean salinity.", "mass fraction")
+    S_B: float = parameter(0.034538, "Fixed bottom-water salinity.", "mass fraction")
+    F_N0: float = parameter(0.486, "Northern freshwater flux at zero hosing.", "Sv")
+    F_NH: float = parameter(
+        0.1311, "Northern freshwater-flux response to hosing.", "dimensionless"
+    )
+    F_T0: float = parameter(-0.997, "Tropical freshwater flux at zero hosing.", "Sv")
+    F_TH: float = parameter(
+        0.6961, "Tropical freshwater-flux response to hosing.", "dimensionless"
+    )
+
+
+def strength_sv(SN, p: AMOCPhysics):
+    """AMOC transport in Sverdrups from North Atlantic salinity anomaly."""
+    south = p.S_S - p.S0
+    return (
+        p.lambda_q
+        * (p.alpha * (p.T_S - p.T_0) + p.beta * (SN / 100 - south))
+        / (1 + p.lambda_q * p.alpha * p.mu)
+        * 1e-6
+    )
+
+
+def drift(state, H, p: AMOCPhysics):
+    """Salinity-anomaly drift, preserving the calibrated sign-dependent transport."""
+    SN, ST = state
+    SS, SB = (p.S_S - p.S0) * 100, (p.S_B - p.S0) * 100
+    SIP = (
+        100
+        * (
+            p.total_salt
+            - (p.V_N * SN + p.V_T * ST + p.V_S * SS + p.V_B * SB) / 100
+            - p.S0 * (p.V_B + p.V_N + p.V_T + p.V_IP + p.V_S)
+        )
+        / p.V_IP
+    )
+    q = strength_sv(SN, p) * 1e6
+    aq = jnp.abs(q)
+    FN, FT = (p.F_N0 + p.F_NH * H) * 1e6, (p.F_T0 + p.F_TH * H) * 1e6
+    north_exchange = p.K_N * (ST - SN) / 100
+    tropical_exchange = p.K_S * (SS - ST) / 100 + p.K_N * (SN - ST) / 100
+    north_adv = jnp.where(q >= 0, q * (ST - SN) / 100, aq * (SB - SN) / 100)
+    tropical_adv = jnp.where(
+        q >= 0,
+        q * (p.gamma * SS + (1 - p.gamma) * SIP - ST) / 100,
+        aq * (SN - ST) / 100,
+    )
+    return jnp.array(
+        [
+            100 * p.seconds_per_year / p.V_N * (north_adv + north_exchange - FN * p.S0),
+            100
+            * p.seconds_per_year
+            / p.V_T
+            * (tropical_adv + tropical_exchange - FT * p.S0),
+        ]
+    )
+
+
+def rk4_step(state, h_cur, h_mid, h_next, dt, physics):
+    """RK4 drift update; diffusion is applied separately by the caller."""
+    k1 = drift(state, h_cur, physics)
+    k2 = drift(state + 0.5 * dt * k1, h_mid, physics)
+    k3 = drift(state + 0.5 * dt * k2, h_mid, physics)
+    k4 = drift(state + dt * k3, h_next, physics)
+    return state + dt / 6 * (k1 + 2 * k2 + 2 * k3 + k4)
+
+
+def observe(path, physics):
+    """Observed transport followed by the two physical salinity-anomaly states."""
+    return jnp.column_stack([strength_sv(path[:, 0], physics), path])