Reaction-network oracles example notebook (#65)

.github/workflows/ci.yml

@@ -286,6 +286,7 @@ jobs:
                               "examples/52_cochain_hodge_modes.ipynb",
                               "examples/53_latent_rank_selection.ipynb",
                               "examples/54_criticality_monitor.ipynb",
+                              "examples/55_reaction_network_oracles.ipynb",
                           ]
                       ),
                   }
@@ -307,12 +308,12 @@ jobs:
                       ),
                   },
                   {
-                      "shard": "27-54",
+                      "shard": "27-55",
                       "pattern": (
                           "examples/2[7-9]_*.ipynb "
                           "examples/3[0-9]_*.ipynb "
                           "examples/4[0-9]_*.ipynb "
-                          "examples/5[0-4]_*.ipynb"
+                          "examples/5[0-5]_*.ipynb"
                       ),
                   },
               ]

CHANGELOG.md

@@ -115,11 +115,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `compute_card_oracle` and `scripts/build_reaction_cards.py` (with
     `--check`) regenerate the oracle sections; tests recompute them to catch
     drift.
-- `eigenvalue_timescales`: `-1/Re(λ)` with real parts below eigensolver
-  round-off (`100 · eps · max|λ|`) mapped to `inf`;
-  `OracleSpectrum.timescales` uses it. `ReactionNetworkBenchmark.generate`
-  refuses a Cantera card whose recorded mechanism SHA-256 differs from the
-  installed file.
+- Example `55_reaction_network_oracles.ipynb` compares estimators against the
+  `ReactionNetworkBenchmark` oracles:
+  - exact DMD recovers the chain's `exp(λ Δt)` (errors ~1e-7) and conserves
+    mass in rollouts;
+  - DMD on the card's log features misses by up to ~0.13;
+  - a short `koopman="graph"` fit is approximate, and
+    `element_balance_violation` flags its rollout drift;
+  - a late-window DMD recovers the Michaelis-Menten slow mode against each
+    trajectory's own equilibrium linearization.
+
+  Registered in the PR notebook smoke set and the full `27-55` shard.
+- `ReactionDataset.sequence(..., graph_encoding=)` overrides the card's
+  encoding (e.g. drop `hyperedge_index` for `DMDBaseline`).
+- `eigenvalue_timescales`: `-1/Re(λ)` with numerical zeros mapped to `inf`
+  (an optional absolute `zero_tolerance`, else eigensolver round-off
+  `100 · eps · max|λ|`); `OracleSpectrum.timescales` uses it with its own
+  `zero_tolerance`. `ReactionNetworkBenchmark.generate` refuses a Cantera
+  card whose recorded mechanism SHA-256 differs from the installed file.
 
 ### Changed
 

docs/source/tutorials.rst

@@ -115,6 +115,12 @@ Analysis and stability
    * - `54_criticality_monitor.ipynb <https://github.com/tjkessler/KoopmanGraph/blob/main/examples/54_criticality_monitor.ipynb>`_
      - Closing-gap diagonal toy: ``monitor_critical_transition`` score
        rises versus a constant-gap control (not a Ghosh certificate)
+   * - `55_reaction_network_oracles.ipynb <https://github.com/tjkessler/KoopmanGraph/blob/main/examples/55_reaction_network_oracles.ipynb>`_
+     - ``ReactionNetworkBenchmark`` card oracles: exact DMD recovers the
+       chain's :math:`e^{\lambda \Delta t}`, log features and a short
+       ``koopman="graph"`` fit do not, ``element_balance_violation`` flags
+       rollout drift, and a late-window DMD recovers the Michaelis-Menten
+       slow mode (linearization, not a production kinetics benchmark)
    * - `40_resdmd_pseudospectra.ipynb <https://github.com/tjkessler/KoopmanGraph/blob/main/examples/40_resdmd_pseudospectra.ipynb>`_
      - Finite-dictionary ResDMD MVP + resolvent-norm grid (≠ ``spectral_residuals``; not infinite-dim certificates)
    * - `46_representation_explain.ipynb <https://github.com/tjkessler/KoopmanGraph/blob/main/examples/46_representation_explain.ipynb>`_