[tjkessler]

Refs #65. Fourth PR for the reaction-network datasets. Stacked on #70, which is stacked on #69. Merge in order #69 → #70 → this one; each PR retargets to main when the one below it merges (branch auto-delete is on). CI runs only on PRs targeting main, so it starts once this PR retargets.

Changes

koopman_graph.datasets.reaction.catalog: reference systems with frozen defaults. The defaults are module constants, because changing them changes every dataset built from the catalog.

Constructor	Closed	Notes
first_order_chain(n, rate_constants=None)	yes	S0 → … → S(n-1); default rates 1, 0.5, 0.25, … keep the eigenvalues distinct
reversible_dimerization()	yes	2 A ⇌ A2 (3.0, 0.5); element X counts monomer units
michaelis_menten()	yes	E + S ⇌ ES → E + P (10, 1, 0.5); elements Enz, Sub; equilibrium on the boundary
brusselator(a, b)	no	(1, 3): unstable focus with a limit cycle (b > 1 + a²)
lotka_volterra(α, β, γ)	no	neutral centre with eigenvalues ±i√(αγ)

koopman_graph.datasets.reaction.oracles

• conservation_laws returns an orthonormal basis W of the left nullspace of N, so W N = 0. This covers element balance plus any extra stoichiometric conservation. stoichiometric_rank gives rank(N).
• equilibrium(system, initial, *, guess=None) finds a steady state with the same conserved totals as initial.
  • Linear systems: an exact solve of [A; W] c = [-b; W c0]. Raises ValueError when there is no steady state, e.g. a feed into a species with no outflow.
  • Nonlinear systems: damped Newton on the projected rate equations plus the conservation constraints, with backtracking and c ≥ 0. Raises RuntimeError if it doesn't converge.
• oracle_spectrum(system, state) returns an OracleSpectrum with:
  • the Jacobian (from mass_action_jacobian);
  • dynamic eigenvalues, slowest first, with the S − rank(N) conservation zero modes removed (J = N ∂r/∂c has rank ≤ rank(N));
  • timescales = −1/Re(λ): positive for decaying modes, inf for a centre, negative for growing modes;
  • is_stable, and discrete_eigenvalues(Δt) = exp(λ Δt) for comparison with a learned discrete Koopman operator.
• oracle_timescales is a shortcut for the timescales alone.

Tests (all against closed forms)

• The 4-species chain with rates (2, 1, 0.25) gives eigenvalues {−0.25, −1, −2} plus one removed zero, and timescales {4, 1, 0.5}.
• Dimerization reaches equilibrium at (1/4, 3/8) with λ = −(4k_f A* + k_r) = −3.5. A long RK4 run converges to that equilibrium within 1e-10.
• Michaelis-Menten reaches its boundary equilibrium (E0, 0, 0, S0). Its two dynamic eigenvalues match the free-substrate block, two conservation modes are removed, and RK4 converges to it.
• The Brusselator fixed point (a, b/a) has λ = 0.5 ± i√3/2, so it's unstable with timescales −2.
• Lotka-Volterra has λ = ±i, infinite timescales, and |exp(λΔt)| = 1. Its RK4 orbit conserves V = x − ln x + y − ln y.
• The open linear steady state is (feed/k1, k1A*/k_out). A missing steady state and Newton non-convergence both raise.
• W N = 0, W has orthonormal rows, and the element-matrix rows lie in the span of W.
• Every closed catalog system passes check_element_balance.

Verification (macOS arm64, Python 3.13)

• ruff check and ruff format --check on src/ tests/ pass.
• pytest -n auto -m "not slow and not distributed and not ray" --cov=koopman_graph --cov-fail-under=90: 3410 passed, 26 skipped, 97.25%. catalog.py is at 100% and oracles.py at 99%.
• sphinx-build -W --keep-going passes.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines	Coverage Δ
src/koopman_graph/datasets/reaction/__init__.py	100.00% <100.00%> (ø)
src/koopman_graph/datasets/reaction/catalog.py	100.00% <100.00%> (ø)
src/koopman_graph/datasets/reaction/oracles.py	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.