Cantera mechanism I/O and reactor simulation (#65)

.github/workflows/ci.yml

@@ -170,6 +170,7 @@ jobs:
           --extra dev --extra rl --extra mpc --extra symmetry
           --extra distributed --extra equivariance
           --extra baselines-ode --extra msm
+          --extra reaction --extra cantera
 
       - name: Run tests
         if: matrix.coverage != 'true'
@@ -231,6 +232,7 @@ jobs:
           --extra dev --extra rl --extra mpc --extra symmetry
           --extra lightning --extra equivariance
           --extra baselines-ode --extra msm
+          --extra reaction --extra cantera
 
       - name: Run macOS core smoke tests
         env:

.github/workflows/release.yml

@@ -24,6 +24,7 @@ jobs:
           --extra dev --extra rl --extra mpc --extra symmetry --extra docs
           --extra distributed --extra equivariance
           --extra baselines-ode --extra msm
+          --extra reaction --extra cantera
 
       - name: Lint with Ruff
         run: |

CHANGELOG.md

@@ -65,10 +65,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   SSA (`gillespie_ssa`, `SSATrajectory`) with mass-action propensities
   (falling factorials, volume scaling) that match the ODE rates, plus
   last-value-hold binning onto a grid (`bin_to_grid`).
+- `koopman_graph.datasets.reaction.cantera_io` (lazy `[cantera]` boundary):
+  - `load_cantera_mechanism` converts a Cantera gas mechanism (default the
+    bundled `h2o2.yaml`, read from the installed package) to a mass-action
+    `ReactionSystem` at a reference `(T, P, X)`. Reversible reactions are
+    split into forward and reverse. Elementary and mass-action three-body
+    reactions convert exactly: `[M]` is expanded into one reaction per
+    collider with rate `k ε_s`.
+  - Falloff and other state-dependent rates are frozen at the reference
+    state, skipped, or rejected (`state_dependent=`); frozen rates with a
+    mass-action third body keep the per-collider `[M]` expansion.
+    Reactions with non-mass-action `orders` are skipped or rejected
+    (orders equal to the stoichiometry convert normally). Rate constants
+    are read with Cantera's legacy rate-constant mode off, whatever the
+    process setting. Duplicate reactions get unique names. Every frozen or
+    skipped reaction is listed in `CanteraProvenance`, which also records
+    the Cantera version, mechanism path and SHA-256, the reference state,
+    the "illustration only" caveat, and the Cantera citation DOI.
+  - `simulate_cantera_reactor` runs constant-pressure or constant-volume
+    ideal-gas reactors, adiabatic or isothermal.
+  - Also: `require_cantera`, `resolve_mechanism_path` (bare names prefer
+    Cantera's bundled data over the working directory), and
+    `mechanism_sha256`.
 - `[reaction]` extra (`scipy>=1.11.0`) for stiff reaction-network solvers
   and `[cantera]` extra (`cantera>=3.2,<3.3`) for Cantera mechanisms.
 - `cantera` pytest marker; marked tests are skipped automatically when the
   `[cantera]` extra is not installed.
+- CI test jobs and the release verify job install `[reaction]` and
+  `[cantera]`, so `cantera`-marked tests run there.
 - `tests/test_import_hygiene.py`: `import koopman_graph` must not load
   SciPy, Cantera, or torchdiffeq.
 

src/koopman_graph/datasets/reaction/__init__.py

@@ -38,6 +38,20 @@
 replacement for a production kinetics solver.
 """
 
+from koopman_graph.datasets.reaction.cantera_io import (
+    CANTERA_CITATION_DOI,
+    CANTERA_ILLUSTRATION_NOTE,
+    DEFAULT_MECHANISM,
+    CanteraMechanism,
+    CanteraProvenance,
+    CanteraReactorTrajectory,
+    StateDependentPolicy,
+    load_cantera_mechanism,
+    mechanism_sha256,
+    require_cantera,
+    resolve_mechanism_path,
+    simulate_cantera_reactor,
+)
 from koopman_graph.datasets.reaction.catalog import (
     DEFAULT_BRUSSELATOR_PARAMS,
     DEFAULT_CHAIN_RATE,
@@ -111,13 +125,16 @@
 )
 
 __all__ = [
+    "CANTERA_CITATION_DOI",
+    "CANTERA_ILLUSTRATION_NOTE",
     "DEFAULT_BRUSSELATOR_PARAMS",
     "DEFAULT_CHAIN_RATE",
     "DEFAULT_CHAIN_RATIO",
     "DEFAULT_DIMERIZATION_RATES",
     "DEFAULT_LOG_FLOOR",
     "DEFAULT_LOTKA_VOLTERRA_RATES",
     "DEFAULT_MAX_EVENTS",
+    "DEFAULT_MECHANISM",
     "DEFAULT_MICHAELIS_MENTEN_RATES",
     "GAS_CONSTANT_J_PER_MOL_K",
     "PRODUCT_RELATION",
@@ -128,13 +145,17 @@
     "VAN_DE_VUSSE_NOMINAL_DILUTION",
     "VAN_DE_VUSSE_NOMINAL_TEMPERATURE_K",
     "ArrheniusParams",
+    "CanteraMechanism",
+    "CanteraProvenance",
+    "CanteraReactorTrajectory",
     "ElementBalanceReport",
     "IntegrationMethod",
     "LogConcentrationTransform",
     "OracleSpectrum",
     "ReactionSystem",
     "SSATrajectory",
     "SampledReactionNetwork",
+    "StateDependentPolicy",
     "VanDeVusseCSTR",
     "bin_to_grid",
     "brusselator",
@@ -149,17 +170,22 @@
     "integrate_rk4",
     "integrate_stiff",
     "linear_rate_equations",
+    "load_cantera_mechanism",
     "lotka_volterra",
     "mass_action_jacobian",
+    "mechanism_sha256",
     "michaelis_menten",
     "oracle_spectrum",
     "oracle_timescales",
     "propensities",
     "reaction_directed_hyperedges",
     "reaction_hyperedge_index",
+    "require_cantera",
     "require_scipy",
+    "resolve_mechanism_path",
     "reversible_dimerization",
     "sample_random_network",
+    "simulate_cantera_reactor",
     "species_influence_graph",
     "species_reaction_bipartite",
     "stoichiometric_rank",