[tjkessler]

Refs #65. Sixth PR for the reaction-network datasets. Stacked on #72 (→ #71 → #70 → #69). Merge in order #69 → #70 → #71 → #72 → this one. Each PR retargets to main when the one below it merges, and CI starts then.

Changes

koopman_graph.datasets.reaction.cantera_io is the lazy [cantera] boundary. Importing it doesn't import Cantera.

load_cantera_mechanism(name_or_path="h2o2.yaml", *, temperature_k, pressure_pa, mole_fractions, state_dependent="freeze") converts a gas mechanism into a mass-action ReactionSystem at a reference state (T, P, X):

• Reversible reactions become a forward row and a reverse row, using Cantera's forward_rate_constants / reverse_rate_constants at T. Reverse constants come from thermochemistry and aren't Arrhenius, so arrhenius=None.
• Elementary reactions convert exactly.
• Mass-action three-body reactions also convert exactly. In Cantera 3.2 the rate constants leave out [M], and [M] = Σ ε_s c_s, so each +M reaction expands into one reaction per collider s (A + B + s → … + s, k ε_s). Explicit colliders (+ O2) are just the case with a single collider.
• State-dependent rates (falloff, PLOG, Chebyshev, …) aren't mass action. state_dependent="freeze" uses the effective constant at the reference state, which is exact there and approximate elsewhere. "skip" drops them and "error" raises.
• Non-mass-action orders are always skipped (or raise under "error").
• Nothing is dropped silently. CanteraProvenance lists every frozen and skipped equation, and records the Cantera version, resolved path, mechanism SHA-256, reference state, Cantera's "bundled inputs are for illustration only" caveat, and the Cantera 3.2.0 citation DOI. It also has a JSON-safe to_dict.
• Units: kmol/m³ equals mol/L, so concentrations, rate constants and time carry over unchanged.

Other functions:

• simulate_cantera_reactor(...) runs an IdealGasConstPressureReactor or IdealGasReactor, adiabatic or isothermal (energy="off"), and returns concentrations, T, and P at the output times plus provenance. It passes clone=True explicitly, which becomes Cantera's default after 3.2.
• require_cantera() raises ImportError naming [cantera]. resolve_mechanism_path takes an explicit path, which needs no Cantera, or searches Cantera's data directories. mechanism_sha256 hashes the file.

CI: the Ubuntu and macOS test jobs and the release verify job now install --extra reaction --extra cantera. #66 deferred this until cantera-marked tests existed. Without it, cantera_io.py would be mostly uncovered in CI and fail the 90% Codecov patch target. Cantera 3.2.0 has wheels for the whole matrix (CPython 3.10–3.14, manylinux x86_64, macOS arm64), and uv sync --frozen with the combined extras resolves from the existing lock.

Tests

• The bundled h2o2.yaml SHA-256 equals the value in [Feature]: Mass-action reaction-network datasets (koopman_graph.datasets.reaction) #65 (0efc6c52…c8d4).
• At the reference state (1200 K, radical-rich mix), system.time_derivative equals Cantera's net_production_rates to 1e-12 relative. The system is element-balanced, has 1 frozen reaction (the Troe falloff) and 0 skipped.
• With the falloff removed, the conversion stays exact (≤1e-12) at a different composition and pressure, which shows the three-body expansion is exact. With the falloff frozen, the error away from the reference state is nonzero but under 5%.
• skip / error policies work. A custom mechanism with orders: {H2: 0.5} has that reaction skipped (or rejected under error).
• An isothermal constant-volume reactor agrees with integrate_stiff on the converted system to 1e-3 of the concentration scale. The adiabatic run heats past 1500 K at constant pressure.
• Without Cantera, simulated via sys.modules, every entry point raises the [cantera] hint. Hashing and explicit-path resolution work without it.
• Locally the 9 Cantera tests skip cleanly when Cantera is hidden, and the 2 missing-extra tests pass.

Verification (macOS arm64, Python 3.13, Cantera 3.2.0)

• 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: 3480 passed, 26 skipped, 97.27%. cantera_io.py is at 98%.
• sphinx-build -W --keep-going passes.
• Not checked: the Linux CI install with [cantera]. It will run for the first time when this PR retargets to main.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 98.55769% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/koopman_graph/datasets/reaction/cantera_io.py	98.55%	2 Missing and 1 partial ⚠️

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

🚀 New features to boost your workflow:

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