Random reaction networks, Van de Vusse CSTR, and Gillespie SSA (#65)

CHANGELOG.md

@@ -48,6 +48,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `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.
+- `koopman_graph.datasets.reaction.random_network`: `sample_random_network`
+  builds seeded, element-balanced mass-action networks. Species
+  compositions are sampled first, so every candidate reaction conserves
+  elements; reaction order is capped at 2 (`max_order=1` gives linear
+  dissociation networks); rates are log-uniform. The returned
+  `SampledReactionNetwork` records the seed and every sampler parameter.
+- `koopman_graph.datasets.reaction.cstr`: `van_de_vusse_cstr` /
+  `VanDeVusseCSTR`, a Van de Vusse CSTR with Klatt & Engell (1998)
+  Arrhenius kinetics. Reactor temperature and dilution rate are inputs,
+  either constant or piecewise-constant schedules. It provides the
+  controlled right-hand side, RK4 simulation, and a Newton steady state; the
+  nominal point (114.2 °C, `F/V = 14.19 1/h`) gives `c_A ≈ 2.14`,
+  `c_B ≈ 1.09`.
+- `koopman_graph.datasets.reaction.gillespie`: seeded Gillespie direct-method
+  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`).
 - `[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

@@ -51,6 +51,20 @@
     michaelis_menten,
     reversible_dimerization,
 )
+from koopman_graph.datasets.reaction.cstr import (
+    VAN_DE_VUSSE_FEED_A,
+    VAN_DE_VUSSE_NOMINAL_DILUTION,
+    VAN_DE_VUSSE_NOMINAL_TEMPERATURE_K,
+    VanDeVusseCSTR,
+    van_de_vusse_cstr,
+)
+from koopman_graph.datasets.reaction.gillespie import (
+    DEFAULT_MAX_EVENTS,
+    SSATrajectory,
+    bin_to_grid,
+    gillespie_ssa,
+    propensities,
+)
 from koopman_graph.datasets.reaction.graphs import (
     PRODUCT_RELATION,
     REACTANT_RELATION,
@@ -79,6 +93,10 @@
     oracle_timescales,
     stoichiometric_rank,
 )
+from koopman_graph.datasets.reaction.random_network import (
+    SampledReactionNetwork,
+    sample_random_network,
+)
 from koopman_graph.datasets.reaction.system import (
     GAS_CONSTANT_J_PER_MOL_K,
     ArrheniusParams,
@@ -99,24 +117,33 @@
     "DEFAULT_DIMERIZATION_RATES",
     "DEFAULT_LOG_FLOOR",
     "DEFAULT_LOTKA_VOLTERRA_RATES",
+    "DEFAULT_MAX_EVENTS",
     "DEFAULT_MICHAELIS_MENTEN_RATES",
     "GAS_CONSTANT_J_PER_MOL_K",
     "PRODUCT_RELATION",
     "REACTANT_RELATION",
     "REACTION_NODE",
     "SPECIES_NODE",
+    "VAN_DE_VUSSE_FEED_A",
+    "VAN_DE_VUSSE_NOMINAL_DILUTION",
+    "VAN_DE_VUSSE_NOMINAL_TEMPERATURE_K",
     "ArrheniusParams",
     "ElementBalanceReport",
     "IntegrationMethod",
     "LogConcentrationTransform",
     "OracleSpectrum",
     "ReactionSystem",
+    "SSATrajectory",
+    "SampledReactionNetwork",
+    "VanDeVusseCSTR",
+    "bin_to_grid",
     "brusselator",
     "check_element_balance",
     "conservation_laws",
     "element_balance_violation",
     "equilibrium",
     "first_order_chain",
+    "gillespie_ssa",
     "integrate_expm",
     "integrate_reaction_system",
     "integrate_rk4",
@@ -127,11 +154,14 @@
     "michaelis_menten",
     "oracle_spectrum",
     "oracle_timescales",
+    "propensities",
     "reaction_directed_hyperedges",
     "reaction_hyperedge_index",
     "require_scipy",
     "reversible_dimerization",
+    "sample_random_network",
     "species_influence_graph",
     "species_reaction_bipartite",
     "stoichiometric_rank",
+    "van_de_vusse_cstr",
 ]