op-engine 0.3.0__tar.gz → 0.5.0__tar.gz

{op_engine-0.3.0 → op_engine-0.5.0}/CHANGELOG.md

@@ -5,6 +5,109 @@ versioning while the project remains pre-1.0.
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-06
+
+### Added
+
+- `op_engine.from_compiled_rhs(compiled, params)` and
+  `op_engine.compile_reaction_network(reactions, template_shapes=...,
+  axis_sizes=..., params=...)` build the flat stochastic reaction network from
+  op_system reaction artifacts in the core package, with no flepimop2
+  dependency. `from_compiled_rhs` refuses a RHS with reaction gaps unless
+  `allow_gaps=True` or a `reaction_names` partition is given. The new guide
+  covers the `mean_drift` consistency check against the deterministic RHS
+  (#191).
+- `op_engine.steady_state(rhs, y0, ...)` finds equilibria by pseudo-transient
+  continuation, without a long burn-in. `fixed` holds absorbing states
+  (cumulative counters) at their starting values; `invariants` enforces
+  conserved totals exactly through a bordered step, so `dt` can grow without
+  the total drifting; and convergence requires a small Newton correction as
+  well as a small residual, which catches slowly decaying modes.
+  `conserved_quantities`, `linear_invariants` (including rate-balanced totals
+  such as births `mu * N`), and `sink_states` find what to pass.
+  Diagnostics stay arrays, and `loop=jax.lax.fori_loop` runs the solve under
+  `jax.jit` and `jax.vmap`. See the new steady-states guide (#192).
+- `AdaptiveTauLeapingSolver` accepts `dependency_incidence` and
+  `propensity_orders` for reactions that are not mass action, such as
+  frequency-dependent infection. Each species a reaction reads gets a
+  Cao-Gillespie-Petzold scaling of at least the reaction's elasticity order,
+  so its propensity's relative change stays within the leap tolerance; orders
+  above three are allowed. `CompiledReactionNetwork` builds both arrays from
+  the `dependencies`, `propensity_order`, and `dependencies_complete` fields
+  op_system 0.7.0 publishes for `reactants: auto`, counts such reactions as
+  complete, and the provider passes them to the solver, so adaptive
+  tau-leaping runs frequency-dependent op_system models (#193).
+
+### Changed
+
+- The flepimop2 provider's `compile_reaction_network(system, params, ...)` is
+  now a thin adapter over the core function, with unchanged behavior and
+  error messages. `CompiledReactionNetwork` moved to `op_engine.reactions`
+  (still re-exported by the provider) (#191).
+- The provider requires op_system 0.7.0. With it, a reaction whose rate reads
+  no state is complete without declarations, so constant-rate flows no longer
+  block adaptive tau-leaping, and the incomplete-reactants message suggests
+  `reactants: auto` / `catalysts: auto` (#191).
+
+## [0.4.0] - 2026-10-02
+
+### Added
+
+- Prepared Flepimop2 execution plans now support explicit PyTree and JAX block
+  layouts for fixed steps and frozen adaptive replay, including structured typed
+  operators, while preserving dynamic-value cache contracts (#168).
+- Direct SSA accepts explicit forcing breakpoints for exact piecewise-constant
+  rates, including dormant zero-rate intervals, while retaining pending events
+  across observation times. The provider exposes this for pure direct SSA (#171).
+- Fixed and adaptive tau-leaping stop at declared forcing changes, so each
+  leap segment uses its own starting rate; forcing boundaries take precedence
+  over tied critical or exact-fallback events (#174).
+- Pure stochastic runs consume the producer's declared `forcing_breakpoints`
+  (op_system `time_interpolation: previous`), combined with explicit engine
+  boundaries. Hybrid mode reports producer forcing as unsupported (#175).
+- `stochastic_method: thinning-ssa` gives exact bounded thinning for smoothly
+  time-varying rates. Supply a total-rate bound as `thinning_rate_bound` or a
+  `RateBoundFunction` through `run(..., rate_bound=...)`; `ThinningSSASolver`
+  is available in the core package (#173, #176, #177).
+- Stochastic execution consumes axis-wide `coord_shift` reactions from
+  op_system: each source bin of an `offsets` axis becomes a channel that moves
+  one unit by the published step, and off-axis destinations only deplete the
+  donor. Direct SSA reproduces Poisson bin occupancy and Erlang exit times for
+  pure aging chains (#180).
+- Pure stochastic validation and execution reject models with dynamics that
+  have no reaction artifact: transitions listed in the producer's
+  `reaction_gaps` coverage records, and typed operators. Each uncovered
+  transition is named by origin, selectors, and reason. Hybrid mode and
+  producers without coverage records are unchanged (#182).
+- Stochastic execution supports reactions between templates with different
+  axes, including axis-less states: scalar S→I→R models, axis-less donors
+  depositing into a pinned cell, and templated sources collapsing into an
+  axis-less state. Targets are indexed with op_system's `to_full_axes`,
+  falling back to `full_axes` for older producers (#184).
+- Stochastic execution runs routing and target-only fan-out reactions: each
+  source cell and routed target coordinate (op_system's `routed_axes`) is one
+  channel, so routing generators move discrete units between bins (#186).
+- Adaptive tau-leaping validation reports incomplete reactant metadata before
+  running, and both validation and run name each incomplete reaction and the
+  remedy: `reactants` on ordinary op_system transitions, or `catalysts` on
+  `chain:` and `coord_shift` entries (#188).
+
+### Changed
+
+- The provider's optional `op_system` integration requires
+  `flepimop2-op-system>=0.6.0` and `op-system>=0.6.0`.
+- Pure stochastic runs that previously dropped uncovered transitions or typed
+  operators silently now fail validation; use `mode: hybrid` or give each
+  transition a reaction artifact (#182).
+
+### Fixed
+
+- `PreparedExecution` can be passed directly to JAX transformations, including
+  mixed NumPy/JAX samples whose effective namespaces and dtypes are canonicalized
+  by JAX during tracing (#168).
+- Pinned source-only renewal births are accepted: donor-axis coverage is
+  validated only for reactions with a donor (#178, #179).
+
 ## [0.3.0] - 2026-09-27
 
 ### Added

{op_engine-0.3.0 → op_engine-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: op_engine
-Version: 0.3.0
+Version: 0.5.0
 Summary: Multiphysics integration engine for ODEs and PDEs using implicit-explicit operator splitting
 Project-URL: Repository, https://github.com/ACCIDDA/op_engine
 Project-URL: Documentation, https://accidda.github.io/op_engine/
@@ -67,13 +67,17 @@ Operator-Partitioned Engine (OP Engine) is a lightweight multiphysics solver cor
 - `ModelCore`: state/time manager; configure axes, dtype, and optional history.
 - `CoreSolver`: portable explicit methods through Dormand--Prince 5(4), plus dense IMEX and linearly implicit methods; accepts `RunConfig` with `AdaptiveConfig`, `DtControllerConfig`, and `OperatorSpecs`.
 - `DirectSSASolver`: exact Gillespie direct-method trajectories with injected, backend-specific exponential and categorical sampling.
-- `AdaptiveTauLeapingSolver`: bounded adaptive tau-leaping with leap-condition control, exact critical events, and explicit post-leap rejection.
+- `AdaptiveTauLeapingSolver`: bounded adaptive tau-leaping with leap-condition control, exact critical events, and explicit post-leap rejection. Non-mass-action propensities (frequency-dependent infection) are supported through per-reaction dependency incidence and elasticity orders.
 - `TauLeapingSolver`: fixed-step stochastic reaction-network integration with injected, backend-specific Poisson sampling.
+- `from_compiled_rhs` / `compile_reaction_network`: build the flat stochastic network (stoichiometry, reactant orders, propensity) from an op_system spec's reaction artifacts, with no flepimop2 dependency.
+- `steady_state`: equilibria by pseudo-transient continuation, with absorbing states held fixed, conserved totals enforced exactly, and a Newton-correction convergence test; runs under `jax.jit`/`vmap`.
 - `matrix_ops`: portable dense advection/diffusion, sparse Laplacian/Crank–Nicolson, implicit Euler/trapezoidal builders, predictor–corrector, implicit solve cache, Kronecker helpers, and grouped aggregations.
 - Extras: `OperatorSpecs`, `RunConfig`, `AdaptiveConfig`, `DtControllerConfig`, `Operator`, `GridGeometry`, `DiffusionConfig`.
 
 See the documentation guides for [solver selection](docs/guides/solver-methods.md),
 [the biogeochemical splitting tutorial](docs/guides/biogeochemical-network.md),
+[stochastic simulation from an op_system spec](docs/guides/op-system-reactions.md),
+[steady states](docs/guides/steady-states.md),
 and [backend boundaries](docs/guides/backends.md).
 
 ## Installation
@@ -88,6 +92,18 @@ With JAX as the array namespace:
 pip install "op_engine[jax]"
 ```
 
+For the other packaged Array-API backends:
+
+```bash
+pip install "op_engine[torch]"
+pip install "op_engine[cupy]"
+```
+
+NumPy is installed with the core package. Backend support is method-specific;
+consult the [backend guide](docs/guides/backends.md) before assuming that JIT,
+automatic differentiation, adaptivity, or stochastic sampling have identical
+semantics across namespaces.
+
 With flepimop2 adapter:
 
 ```bash
@@ -139,7 +155,8 @@ adaptive controller is eager Python control flow. See the
 
 ```python
 import numpy as np
-from op_engine import CoreSolver, ModelCore, OperatorSpecs
+from op_engine import CoreSolver, ModelCore
+from op_engine.core_solver import OperatorSpecs, RunConfig
 
 n = 4
 times = np.linspace(0.0, 1.0, 11)
@@ -156,21 +173,31 @@ def rhs(t, y):
     return -0.1 * y
 
 
-solver = CoreSolver(core, operators=ops.default, operator_axis="state")
-solver.run(rhs, config=None)  # defaults: method="heun" (explicit)
-
-# For IMEX methods set method and operators via RunConfig:
-# from op_engine.core_solver import RunConfig, AdaptiveConfig, DtControllerConfig
+solver = CoreSolver(core, operator_axis="state")
+solver.run(
+    rhs,
+    config=RunConfig(
+        method="imex-heun-tr",
+        operators=ops,
+    ),
+)
 ```
 
+This compact example uses identity left/right operators to show the API. For a
+nontrivial implicit term, construct timestep-aware operator factories as in the
+[solver guide](docs/guides/solver-methods.md#imex-methods-and-operator-factories).
+
 ## Public API
 - `ModelCore`: state tensor + time grid manager; supports extra axes and optional history.
 - `CoreSolver`: portable explicit and dense IMEX/implicit stepping selected by the state array namespace.
 - `DirectSSASolver`: exact event-by-event stochastic reaction trajectories with NumPy, JAX, or another Array-API namespace supplying random draws.
 - `AdaptiveTauLeapingSolver`: adaptive non-negative stochastic leaps using explicit reactant stoichiometry and injected Poisson plus exact-event sampling.
 - `TauLeapingSolver`: portable stoichiometric updates with NumPy, JAX, or another Array-API namespace supplying Poisson samples.
+- `op_engine.reactions`: `from_compiled_rhs(compiled, params)` and `compile_reaction_network(reactions, template_shapes=..., axis_sizes=..., params=...)` return a `CompiledReactionNetwork` whose `stoichiometry`, `reactant_stoichiometry`, and `propensity` feed the stochastic solvers; `mean_drift` checks the network against the deterministic RHS.
 - Operator utilities (`matrix_ops`): portable upwind advection, Laplacian, Crank–Nicolson/implicit Euler/trapezoidal operators, predictor-corrector builders, implicit solve cache, Kronecker helpers, and grouped aggregation utilities.
-- Configuration helpers: `RunConfig`, `OperatorSpecs`, `AdaptiveConfig`, `DtControllerConfig` for method/IMEX/adaptive control.
+- Configuration helpers: `RunConfig`, `OperatorSpecs`, `AdaptiveConfig`, and
+  `DtControllerConfig` from `op_engine.core_solver` for method, IMEX, and
+  adaptive control.
 - Adapters: optional flepimop2 integration (extra dependency) via entrypoints in the adapter package. The adapter merges any `mixing_kernels` already computed by op_system (no automatic generation) and consumes config-supplied IMEX operator specs (dict or `OperatorSpecs`), forwarding the chosen `operator_axis` to `CoreSolver`.
 
 ## Development

{op_engine-0.3.0 → op_engine-0.5.0}/README.md

@@ -15,13 +15,17 @@ Operator-Partitioned Engine (OP Engine) is a lightweight multiphysics solver cor
 - `ModelCore`: state/time manager; configure axes, dtype, and optional history.
 - `CoreSolver`: portable explicit methods through Dormand--Prince 5(4), plus dense IMEX and linearly implicit methods; accepts `RunConfig` with `AdaptiveConfig`, `DtControllerConfig`, and `OperatorSpecs`.
 - `DirectSSASolver`: exact Gillespie direct-method trajectories with injected, backend-specific exponential and categorical sampling.
-- `AdaptiveTauLeapingSolver`: bounded adaptive tau-leaping with leap-condition control, exact critical events, and explicit post-leap rejection.
+- `AdaptiveTauLeapingSolver`: bounded adaptive tau-leaping with leap-condition control, exact critical events, and explicit post-leap rejection. Non-mass-action propensities (frequency-dependent infection) are supported through per-reaction dependency incidence and elasticity orders.
 - `TauLeapingSolver`: fixed-step stochastic reaction-network integration with injected, backend-specific Poisson sampling.
+- `from_compiled_rhs` / `compile_reaction_network`: build the flat stochastic network (stoichiometry, reactant orders, propensity) from an op_system spec's reaction artifacts, with no flepimop2 dependency.
+- `steady_state`: equilibria by pseudo-transient continuation, with absorbing states held fixed, conserved totals enforced exactly, and a Newton-correction convergence test; runs under `jax.jit`/`vmap`.
 - `matrix_ops`: portable dense advection/diffusion, sparse Laplacian/Crank–Nicolson, implicit Euler/trapezoidal builders, predictor–corrector, implicit solve cache, Kronecker helpers, and grouped aggregations.
 - Extras: `OperatorSpecs`, `RunConfig`, `AdaptiveConfig`, `DtControllerConfig`, `Operator`, `GridGeometry`, `DiffusionConfig`.
 
 See the documentation guides for [solver selection](docs/guides/solver-methods.md),
 [the biogeochemical splitting tutorial](docs/guides/biogeochemical-network.md),
+[stochastic simulation from an op_system spec](docs/guides/op-system-reactions.md),
+[steady states](docs/guides/steady-states.md),
 and [backend boundaries](docs/guides/backends.md).
 
 ## Installation
@@ -36,6 +40,18 @@ With JAX as the array namespace:
 pip install "op_engine[jax]"
 ```
 
+For the other packaged Array-API backends:
+
+```bash
+pip install "op_engine[torch]"
+pip install "op_engine[cupy]"
+```
+
+NumPy is installed with the core package. Backend support is method-specific;
+consult the [backend guide](docs/guides/backends.md) before assuming that JIT,
+automatic differentiation, adaptivity, or stochastic sampling have identical
+semantics across namespaces.
+
 With flepimop2 adapter:
 
 ```bash
@@ -87,7 +103,8 @@ adaptive controller is eager Python control flow. See the
 
 ```python
 import numpy as np
-from op_engine import CoreSolver, ModelCore, OperatorSpecs
+from op_engine import CoreSolver, ModelCore
+from op_engine.core_solver import OperatorSpecs, RunConfig
 
 n = 4
 times = np.linspace(0.0, 1.0, 11)
@@ -104,21 +121,31 @@ def rhs(t, y):
     return -0.1 * y
 
 
-solver = CoreSolver(core, operators=ops.default, operator_axis="state")
-solver.run(rhs, config=None)  # defaults: method="heun" (explicit)
-
-# For IMEX methods set method and operators via RunConfig:
-# from op_engine.core_solver import RunConfig, AdaptiveConfig, DtControllerConfig
+solver = CoreSolver(core, operator_axis="state")
+solver.run(
+    rhs,
+    config=RunConfig(
+        method="imex-heun-tr",
+        operators=ops,
+    ),
+)
 ```
 
+This compact example uses identity left/right operators to show the API. For a
+nontrivial implicit term, construct timestep-aware operator factories as in the
+[solver guide](docs/guides/solver-methods.md#imex-methods-and-operator-factories).
+
 ## Public API
 - `ModelCore`: state tensor + time grid manager; supports extra axes and optional history.
 - `CoreSolver`: portable explicit and dense IMEX/implicit stepping selected by the state array namespace.
 - `DirectSSASolver`: exact event-by-event stochastic reaction trajectories with NumPy, JAX, or another Array-API namespace supplying random draws.
 - `AdaptiveTauLeapingSolver`: adaptive non-negative stochastic leaps using explicit reactant stoichiometry and injected Poisson plus exact-event sampling.
 - `TauLeapingSolver`: portable stoichiometric updates with NumPy, JAX, or another Array-API namespace supplying Poisson samples.
+- `op_engine.reactions`: `from_compiled_rhs(compiled, params)` and `compile_reaction_network(reactions, template_shapes=..., axis_sizes=..., params=...)` return a `CompiledReactionNetwork` whose `stoichiometry`, `reactant_stoichiometry`, and `propensity` feed the stochastic solvers; `mean_drift` checks the network against the deterministic RHS.
 - Operator utilities (`matrix_ops`): portable upwind advection, Laplacian, Crank–Nicolson/implicit Euler/trapezoidal operators, predictor-corrector builders, implicit solve cache, Kronecker helpers, and grouped aggregation utilities.
-- Configuration helpers: `RunConfig`, `OperatorSpecs`, `AdaptiveConfig`, `DtControllerConfig` for method/IMEX/adaptive control.
+- Configuration helpers: `RunConfig`, `OperatorSpecs`, `AdaptiveConfig`, and
+  `DtControllerConfig` from `op_engine.core_solver` for method, IMEX, and
+  adaptive control.
 - Adapters: optional flepimop2 integration (extra dependency) via entrypoints in the adapter package. The adapter merges any `mixing_kernels` already computed by op_system (no automatic generation) and consumes config-supplied IMEX operator specs (dict or `OperatorSpecs`), forwarding the chosen `operator_axis` to `CoreSolver`.
 
 ## Development

{op_engine-0.3.0 → op_engine-0.5.0}/docs/guides/backends.md

@@ -82,6 +82,9 @@ semantics.
 `NumpySSASampler` and `NumpyPoissonSampler` are provided as conveniences.
 JAX users can construct fresh keys from the stable direct-SSA `draw_index` or
 tau-leaping `step_index`.
+Direct SSA's optional forcing schedule is static Python configuration. It
+preserves the state namespace and uses fresh draw indices when a forcing
+boundary invalidates a pending event; observation times retain that event.
 
 The current safety checks and stochastic event loops are eager, so these
 stochastic solvers are not JIT-compatible paths. Adaptive selection also reads

op_engine-0.5.0/docs/guides/bounded-thinning.md

@@ -0,0 +1,112 @@
+# Bounded thinning SSA
+
+`ThinningSSASolver` provides an exact waiting-time method for smoothly varying
+propensities with user-certified bounds. This design addresses
+[#173](https://github.com/ACCIDDA/op_engine/issues/173), including the flepimop2
+provider's explicit `thinning-ssa` method.
+
+## Bound contract
+
+`ThinningSSASolver.run(propensity_func, thinning_sampler, *, rate_bound, config=None)`
+uses the same stoichiometry, reaction axis, and batched propensity contract as
+direct SSA. It permits arbitrary time dependence between events when a valid
+upper bound is supplied.
+
+`rate_bound` is either a finite non-negative real constant, or a
+`RateBoundFunction(t, state, limit)` returning `TotalRateBound(rate, valid_until)`.
+The bound covers the sum of **all** reaction and batch-cell propensities with
+the supplied state held fixed, over `[t, valid_until)`. The callback chooses a
+finite endpoint satisfying `t < valid_until <= limit`. `limit` is the earlier
+of the next declared forcing change and the solve's final time; observations
+do not shorten it. A constant bound applies to every state reached during the
+solve, until the next forcing change or final time.
+
+After an accepted event, the state changes and the callback is queried again.
+A rejected candidate leaves the state and current bound unchanged. At expiry,
+the solver discards a tied or later candidate, advances without firing, and
+requests a new bound. The same rule applies at forcing changes, with
+right-continuous propensities. No candidate fires exactly at an interval's
+right endpoint, including the solve's final endpoint.
+
+A zero bound declares the entire interval inactive. The solver checks rates
+at the interval's start, advances to its endpoint without sampling, and can
+resume with a positive bound. Zero instantaneous propensity with a positive
+bound still produces candidates, allowing smooth rates to become active.
+The caller must prove the bound over the whole interval. Checks at interval
+starts and candidate times detect encountered violations but cannot certify
+unsampled times. A violation fails visibly rather than clipping acceptance.
+Bounds and cumulative rates use the state's floating dtype. Bounds that
+overflow or become zero on conversion fail; tight bounds should allow for
+floating-point rounding when summing many channels. Callback inputs must be
+treated as read-only, and callbacks must not depend on observation storage.
+
+## Sampling contract
+
+`ThinningSampler(bound_rate, draw_index)` returns
+`ThinningSample(waiting_time, uniform)`, both scalar arrays in the state array
+namespace. The wait is finite and strictly positive, sampled exponentially at
+`bound_rate`. The independent uniform lies in `[0, 1)`. Draw indices start at
+zero and increase globally, including rejected and expired candidates.
+`NumpyThinningSampler(seed)` supplies the NumPy implementation; other backends
+inject their own sampler.
+
+At a candidate time, the solver evaluates the actual channel rates. If
+`uniform * bound_rate` is at least the actual total rate, it rejects the
+candidate. Otherwise it selects the flattened channel/batch event whose
+cumulative propensity contains that threshold. This uses one uniform for
+acceptance and channel selection: each channel has probability
+`channel_rate / bound_rate`, and the remaining probability rejects.
+
+Candidates beyond an observation are retained with their sampled uniform;
+their propensities are evaluated only when the solver reaches them. Inserting
+observations with the same solve endpoints therefore preserves the seeded path
+and callback/sampler history. `ThinningSSAConfig.max_candidates` bounds all
+candidate draws during one run, including rejection and expiry. Invalid
+sampler values, non-advancing clocks, invalid bounds, and impossible population
+updates fail explicitly.
+
+The construction follows
+[Lewis and Shedler's thinning method](https://doi.org/10.1002/nav.3800260304).
+The bound and expiry contract extends it to state-dependent reaction networks;
+exactness remains conditional on the caller's bound and random sampling laws.
+Existing direct SSA and tau-leaping behavior and samplers are unchanged.
+
+## Example
+
+For an independent birth channel in each batch cell with rate `2 * time`, the
+integrated intensity over `[0, 1]` is one per cell. The total upper bound must
+include every batch cell:
+
+```python
+import numpy as np
+
+from op_engine import ModelCore, NumpyThinningSampler, ThinningSSASolver
+
+core = ModelCore(1, 100, np.linspace(0, 1, 11))
+core.set_initial_state(np.zeros((1, 100)))
+
+
+def smooth_birth(time, state):
+    return np.full(state.shape, 2 * time, dtype=state.dtype)
+
+
+ThinningSSASolver(core, np.asarray([[1]])).run(
+    smooth_birth, NumpyThinningSampler(seed=173), rate_bound=200,
+)
+```
+
+A callback can instead return `TotalRateBound(2 * limit * state.shape[1], limit)`
+for this example. For consuming reactions, a bound that depends on the current
+state can be refreshed after each accepted event. A loose bound remains valid
+but generates more rejected candidates.
+
+The flepimop2 provider selects this method through
+`mode: stochastic` and `stochastic_method: thinning-ssa`. Supply a constant
+`thinning_rate_bound` in configuration, or leave it unset and pass a scalar or
+`RateBoundFunction` through `run(..., rate_bound=...)`. Both interfaces cannot
+be supplied together. `thinning_max_candidates` sets the per-run candidate
+guard. NumPy has seeded sampling through `random_seed`; other backends inject
+`thinning_sampler=`. Hybrid thinning is unsupported. See the
+[provider examples](https://github.com/ACCIDDA/op_engine/tree/main/flepimop2-op_engine#bounded-thinning-ssa)
+for configuration and callback usage. Existing direct SSA and tau-leaping
+defaults remain unchanged.

op_engine-0.5.0/docs/guides/op-system-reactions.md

@@ -0,0 +1,146 @@
+# Stochastic Simulation From An op_system Spec
+
+An [op_system](https://github.com/ACCIDDA/op_system) spec compiles to typed
+reaction artifacts, one per named transition (`CompiledRhs.reactions`).
+`op_engine.from_compiled_rhs` turns them into the flat network that
+`DirectSSASolver`, `TauLeapingSolver`, and `AdaptiveTauLeapingSolver`
+consume. No flepimop2 installation is needed.
+
+```shell
+pip install op_engine op-system
+```
+
+## Build the network
+
+```python
+import numpy as np
+from op_system import compile_spec
+
+from op_engine import from_compiled_rhs
+
+spec = {
+    "kind": "transitions",
+    "axes": [{"name": "age", "coords": ["child", "adult"]}],
+    "state": ["S[age]", "I[age]", "R[age]"],
+    "transitions": [
+        {
+            "name": "infect",
+            "from": "S[age]",
+            "to": "I[age]",
+            "rate": "b * I[age]",
+            "reactants": "auto",
+        },
+        {"name": "recover", "from": "I[age]", "to": "R[age]", "rate": "g"},
+    ],
+}
+params = {"b": 0.002, "g": 0.1}
+
+compiled = compile_spec(spec)
+network = from_compiled_rhs(compiled, params)
+```
+
+Each reaction becomes one channel per source cell: `network.stoichiometry` is
+`(n_state, n_channels)`, and `network.channel_names` labels the columns
+(`infect[age=0]`, ...). The flat state follows `compiled.template_shapes`:
+each template's cells in C order, templates in declaration order.
+
+## Check the network against the RHS
+
+The network's mean drift, `stoichiometry @ propensity`, must equal the
+deterministic right-hand side. Check it once for each new model:
+
+```python
+rng = np.random.default_rng(0)
+y = rng.uniform(1.0, 100.0, network.n_state)
+np.testing.assert_allclose(
+    network.mean_drift(0.0, y),
+    compiled.eval_fn(0.0, y, **params),
+    rtol=1e-12,
+)
+```
+
+A mismatch means some dynamics have no reaction. `from_compiled_rhs` already
+refuses a RHS whose `reaction_gaps` lists transitions without a reaction
+artifact (an unnamed transition, for example). Pass `allow_gaps=True` only
+when you intend to simulate the reactions alone.
+
+## Simulate
+
+```python
+from op_engine import DirectSSASolver, ModelCore, NumpySSASampler
+
+times = np.linspace(0.0, 30.0, 7)
+core = ModelCore(network.n_state, 1, times)
+core.set_initial_state(np.asarray([[95.0], [90.0], [5.0], [10.0], [0.0], [0.0]]))
+DirectSSASolver(core, network.stoichiometry).run(
+    network.propensity, NumpySSASampler(seed=1)
+)
+trajectory = core.state_array[:, :, 0]  # (time, state)
+```
+
+`TauLeapingSolver(core, network.stoichiometry)` runs the same network with a
+`NumpyPoissonSampler`.
+
+## Adaptive tau-leaping
+
+`AdaptiveTauLeapingSolver` chooses each leap so that no propensity changes
+by more than `leap_tolerance` relative to itself. It therefore needs to know
+which states each propensity depends on, and how strongly. The network must
+describe every reaction: `network.reactants_complete` is false, and
+`network.incomplete_reactions` names the culprits, when a reaction might read
+a state op_system has not declared. In op_system 0.7.0 and later:
+
+- a reaction whose rate reads no state (`recover` above) is complete as is;
+- `reactants: auto` infers the molecular reactants of a rate that is a single
+  product of states (`infect` above: `S` consumed, `I` catalytic);
+- for any other `reactants: auto` rate, such as a frequency-dependent force
+  of infection `beta * S * sum(I) / N`, op_system publishes the states the
+  propensity reads and a bound `E` on its elasticity
+  `sum_i |d log a / d log x_i|` (3 for that example). The network turns them
+  into `dependency_incidence` and `propensity_orders`;
+- an explicit `reactants:` list is always authoritative.
+
+Pass all four arrays; the dependency arrays are `None` when every reaction is
+mass action:
+
+```python
+from op_engine import AdaptiveTauLeapingSolver, NumpyPoissonSampler
+
+assert network.reactants_complete
+core = ModelCore(network.n_state, 1, times)
+core.set_initial_state(np.asarray([[95.0], [90.0], [5.0], [10.0], [0.0], [0.0]]))
+AdaptiveTauLeapingSolver(
+    core,
+    network.stoichiometry,
+    network.reactant_stoichiometry,
+    dependency_incidence=network.dependency_incidence,
+    propensity_orders=network.propensity_orders,
+).run(network.propensity, NumpyPoissonSampler(seed=2), NumpySSASampler(seed=3))
+```
+
+For a reaction described by dependencies, every species it reads gets a
+Cao-Gillespie-Petzold scaling of at least `E`, so its propensity's relative
+change stays within the tolerance. Orders above three are allowed. Its
+`reactant_stoichiometry` column lists only the consumed source, which is what
+can be exhausted for the critical-reaction check.
+
+## Partitions and lower-level use
+
+`from_compiled_rhs(compiled, params, reaction_names=[...])` compiles only the
+named reactions, for a hybrid jump partition. `compile_reaction_network`
+takes the artifacts and layout directly, for producers other than a
+`CompiledRhs`:
+
+```python
+from op_engine import compile_reaction_network
+
+network = compile_reaction_network(
+    compiled.reactions,
+    template_shapes=compiled.template_shapes,
+    axis_sizes={"age": 2},
+    params=params,
+)
+```
+
+The flepimop2 provider (`flepimop2-op-engine`) builds its stochastic runs
+through the same function.