Reaction catalog and oracle equilibria, spectra, timescales (#65)

CHANGELOG.md

@@ -37,6 +37,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   Jacobian behind a lazy `require_scipy()` guard (`integrate_stiff`;
   `[reaction]` extra), the `integrate_reaction_system` dispatcher
   (`method="auto"`), and `mass_action_jacobian`.
+- `koopman_graph.datasets.reaction.catalog`: reference systems with frozen
+  default parameters (`first_order_chain`, `reversible_dimerization`,
+  `michaelis_menten`, `brusselator`, `lotka_volterra`). Closed systems carry
+  an element matrix.
+- `koopman_graph.datasets.reaction.oracles`: `conservation_laws` (orthonormal
+  left nullspace of `N`), `stoichiometric_rank`, `equilibrium` (exact for
+  linear systems, damped non-negative Newton within the compatibility
+  class otherwise), and `oracle_spectrum` / `oracle_timescales` /
+  `OracleSpectrum`. These give the Jacobian, dynamic eigenvalues with the
+  conservation zero modes removed, timescales `-1/Re(λ)`, and flow-map
+  eigenvalues `exp(λ Δt)` to compare with a learned discrete operator.
 - `[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

src/koopman_graph/datasets/reaction/__init__.py

@@ -38,6 +38,19 @@
 replacement for a production kinetics solver.
 """
 
+from koopman_graph.datasets.reaction.catalog import (
+    DEFAULT_BRUSSELATOR_PARAMS,
+    DEFAULT_CHAIN_RATE,
+    DEFAULT_CHAIN_RATIO,
+    DEFAULT_DIMERIZATION_RATES,
+    DEFAULT_LOTKA_VOLTERRA_RATES,
+    DEFAULT_MICHAELIS_MENTEN_RATES,
+    brusselator,
+    first_order_chain,
+    lotka_volterra,
+    michaelis_menten,
+    reversible_dimerization,
+)
 from koopman_graph.datasets.reaction.graphs import (
     PRODUCT_RELATION,
     REACTANT_RELATION,
@@ -58,6 +71,14 @@
     mass_action_jacobian,
     require_scipy,
 )
+from koopman_graph.datasets.reaction.oracles import (
+    OracleSpectrum,
+    conservation_laws,
+    equilibrium,
+    oracle_spectrum,
+    oracle_timescales,
+    stoichiometric_rank,
+)
 from koopman_graph.datasets.reaction.system import (
     GAS_CONSTANT_J_PER_MOL_K,
     ArrheniusParams,
@@ -72,7 +93,13 @@
 )
 
 __all__ = [
+    "DEFAULT_BRUSSELATOR_PARAMS",
+    "DEFAULT_CHAIN_RATE",
+    "DEFAULT_CHAIN_RATIO",
+    "DEFAULT_DIMERIZATION_RATES",
     "DEFAULT_LOG_FLOOR",
+    "DEFAULT_LOTKA_VOLTERRA_RATES",
+    "DEFAULT_MICHAELIS_MENTEN_RATES",
     "GAS_CONSTANT_J_PER_MOL_K",
     "PRODUCT_RELATION",
     "REACTANT_RELATION",
@@ -82,18 +109,29 @@
     "ElementBalanceReport",
     "IntegrationMethod",
     "LogConcentrationTransform",
+    "OracleSpectrum",
     "ReactionSystem",
+    "brusselator",
     "check_element_balance",
+    "conservation_laws",
     "element_balance_violation",
+    "equilibrium",
+    "first_order_chain",
     "integrate_expm",
     "integrate_reaction_system",
     "integrate_rk4",
     "integrate_stiff",
     "linear_rate_equations",
+    "lotka_volterra",
     "mass_action_jacobian",
+    "michaelis_menten",
+    "oracle_spectrum",
+    "oracle_timescales",
     "reaction_directed_hyperedges",
     "reaction_hyperedge_index",
     "require_scipy",
+    "reversible_dimerization",
     "species_influence_graph",
     "species_reaction_bipartite",
+    "stoichiometric_rank",
 ]