op-engine 0.2.0__tar.gz → 0.4.0__tar.gz

{op_engine-0.2.0 → op_engine-0.4.0}/.gitignore

@@ -174,6 +174,8 @@ __marimo__/
 *.png
 *.pdf
 *.svg
+!docs/assets/*.png
+!docs/assets/*.svg
 
 # Numpy saved arrays
 *.npy
@@ -184,4 +186,3 @@ __marimo__/
 
 # Optional example output directory convention
 examples/output/
-

op_engine-0.4.0/CHANGELOG.md

@@ -0,0 +1,199 @@
+# Changelog
+
+Notable user-facing changes are recorded here. Versions follow semantic
+versioning while the project remains pre-1.0.
+
+## [Unreleased]
+
+## [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
+
+- A trait-structured chemostat PDE example combines a curvature-adapted
+  non-uniform finite-volume grid, no-flux implicit diffusion, nonlinear
+  resource coupling, structured trait moments, an RK45 reference, and a
+  documented three-panel diagnostic (#47).
+- The Flepimop provider compiles typed `jump_integral` descriptors into
+  conservative Array-API operators for implicit/IMEX and structured explicit
+  execution. It preserves dynamic rates and kernel matrices under JAX,
+  applies declared direction and continuous target quadrature, and reuses
+  selector/multi-axis lifting with real op_system integration coverage (#94).
+- A finite-element boundary design note and tested 1D P1 diffusion proof of
+  concept show how externally assembled mass/stiffness systems use the existing
+  stage-operator contract, without adding mesh or element abstractions to core
+  (#107).
+- Curvature-weighted 1D spatial-grid generators accept vectorized profile
+  callables or sampled data, with optional curvature smoothing and a feasible
+  minimum-spacing constraint. They return explicit NumPy geometry for use by
+  any runtime array backend (#46).
+- Dense Array-API and sparse SciPy diffusion builders now accept monotone
+  non-uniform cell-center grids with conservative no-flux boundaries. The
+  flepimop2 provider uses the same geometry for flat, PyTree, and block
+  explicit or IMEX execution while retaining JAX differentiation (#45).
+- Explicit adaptive JAX discovery now keeps attempted-step acceptance and
+  controller state in a bounded device loop, including conservative shared-mesh
+  discovery for block layouts. Compact frozen-mesh replay reports array-valued
+  local-error freshness diagnostics and can reject materially stale schedules
+  at an outer orchestration boundary without compromising JIT or gradients;
+  the solver matrix now benchmarks discovery in each row's actual backend
+  (#148).
+- Fixed flat-state JAX DOPRI5 now computes only its high-order solution, keeps
+  FSAL reuse, and carries a requested-output buffer instead of materializing
+  every hidden internal state. Optional `fixed_checkpoint: step` and `chunk`
+  policies control reverse-mode rematerialization; RK4 retains its smaller
+  compile-sensitive scan. The solver matrix records the resulting forward and
+  gradient IR, compile, memory, runtime, and accuracy changes (#147).
+- The flepimop2 provider can prepare and cache stable flat explicit execution
+  plans for fixed stepping and frozen adaptive replay. Prepared callables keep
+  array values dynamic for NumPy or caller-owned JAX transforms while reusing
+  system binding, packing contracts, step grids, and execution structure;
+  explicit cache invalidation and matched staging benchmarks are included (#146).
+- A machine-readable solver benchmark now separates provider construction,
+  adaptive discovery, JAX trace/lower/compile, first and warm execution, and
+  value-and-gradient phases while reporting analytic accuracy, work counts,
+  memory, revision, and environment metadata. SciPy and optional Diffrax
+  references use explicit solver, controller, and adjoint settings (#145).
+- Numerical namespace discovery now uses `array-api-compat`, including native
+  PyTorch tensors that do not implement `__array_namespace__`. A public
+  `array_namespace` helper and optional Torch contract test preserve JAX
+  JIT/grad behavior while extending eager fixed-step autograd support (#144).
+- Explicit fixed-step runs can bound their internal integration step with
+  `fixed_max_step` independently of requested output times, including compact
+  differentiable JAX provider trajectories (#130).
+- The flepimop2 provider exposes SDIRK2 with explicit full-RHS Jacobian and
+  nonlinear-solver options, plus adaptive initial-step and safety limits. A
+  method-surface parity test now requires explicit provider decisions for new
+  core methods, and frozen schedules tolerate representational rounding when
+  replayed on a lower-precision backend (#131).
+- Compact JAX fixed-step provider trajectories use a single `jax.lax.scan`
+  while the core retains backend-neutral functional step kernels (#123).
+- The flepimop2 provider exposes eager adaptive-schedule discovery and
+  validated frozen-mesh replay for conditional JAX JIT and differentiation
+  workflows (#127).
+
+### Fixed
+
+- Sparse implicit-solver cache entries retain and verify their exact operator
+  objects, preventing stale factorizations when Python recycles an object ID
+  for a different same-shape matrix (#164).
+- IMEX Heun--trapezoidal now assembles its endpoint predictor and corrector as
+  additive solves, so nonlinear and non-commuting explicit/implicit splits
+  retain second-order convergence across NumPy and Array-API execution (#162).
+- The public `Array` protocol now matches `array-api-compat` namespace
+  discovery and accepts native tensors such as `torch.Tensor` without requiring
+  a direct `__array_namespace__` method (#155).
+- `flepimop2-op-engine` now types public trajectories with Flepimop2's
+  backend-neutral `Array` protocol and returns the native NumPy or JAX result
+  without a NumPy-only cast (#154).
+- Explicit flepimop2 provider methods now add typed op_system axis-kernel,
+  advection, and diffusion drift at every Runge--Kutta stage. Flat, PyTree,
+  and block layouts share the same namespace-preserving operator path instead
+  of silently omitting operators outside IMEX execution (#140).
+- Typed advection and transport descriptors now honor op_system's explicit
+  `increasing`/`decreasing` direction contract in both IMEX and explicit
+  provider paths while preserving JAX differentiation through dynamic
+  coefficients (#142).
+
+## [0.2.0] - 2026-09-26
+
+### Added
+
+- Array-API-native state, explicit Runge--Kutta, dense implicit, and IMEX
+  paths preserve the namespace selected by the initial state. Portable
+  fixed-step methods support JAX tracing and differentiation without adding a
+  backend-specific solver to the core method surface (#75, #76, #85, #87,
+  #89, #90).
+- Reusable explicit Runge--Kutta tableaus through Dormand--Prince 5(4),
+  adaptive step control with differentiable accepted-schedule replay, and
+  validated public run configuration (#95, #100, #108).
+- A portable nonlinear-solver contract plus corrected ROS2, reusable
+  multistep BDF2, SDIRK2 diagnostics, and higher-order paired IMEX
+  Runge--Kutta integration (#113, #114, #115, #117, #118, #119).
+- Backend-neutral fixed tau-leaping, exact direct SSA, and bounded adaptive
+  tau-leaping with injected random samplers (#102, #120, #121).
+- Portable advection and typed diffusion/advection operator compilation for
+  flepimop2, including dynamic Array-API parameters (#81, #91, #92, #93).
+- The flepimop2 provider consumes typed op_system reaction artifacts and can
+  execute deterministic, stochastic, or hybrid reaction networks without
+  parsing raw model configuration (#122).
+
+### Changed
+
+- Provider development and integration coverage now targets the op_system
+  0.4 typed operator/reaction contract.
+- `flepimop2-op-engine` declares its actual `flepimop2>=0.3.0` compatibility
+  floor. Clean-wheel release validation installs the lowest published direct
+  dependencies instead of installing flepimop2 from its development branch.
+- The documented flepimop2 installation uses the separately distributed
+  `flepimop2-op-engine` package. Its `op-system` extra installs the matching
+  system provider integration.
+
+### Fixed
+
+- Explicit Euler once again performs one Euler update per requested output
+  interval (#79).
+- Solver-method documentation now matches the implemented biogeochemical
+  splitting order and backend boundaries (#98).
+
+## [0.1.1] - 2026-04-27
+
+- Initial PyPI release of `op-engine` and `flepimop2-op-engine`.

{op_engine-0.2.0 → op_engine-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: op_engine
-Version: 0.2.0
+Version: 0.4.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/
@@ -39,12 +39,15 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Requires-Python: <3.15,>=3.11
+Requires-Dist: array-api-compat>=1.12
 Requires-Dist: numpy>=2.0
 Requires-Dist: scipy>=1.11
 Provides-Extra: cupy
 Requires-Dist: cupy>=13; extra == 'cupy'
 Provides-Extra: jax
 Requires-Dist: jax>=0.4.38; extra == 'jax'
+Provides-Extra: torch
+Requires-Dist: torch>=2.6; extra == 'torch'
 Description-Content-Type: text/markdown
 
 # op_engine
@@ -85,6 +88,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
@@ -124,9 +139,10 @@ solution = core.state_array  # shape (n_timesteps, state, subgroup)
 ### Array namespaces
 
 `ModelCore` infers its numerical namespace from the initial state through
-`initial_state.__array_namespace__()`. The state, stored history, solver stages,
+`array_api_compat.array_namespace()`. The state, stored history, solver stages,
 and dense solver operations stay in that namespace. There is no `xp=` or
-backend option. Fixed-step methods can be differentiated by JAX; the built-in
+backend option. This supports standard Array-API objects and native arrays such
+as `torch.Tensor`. Fixed-step methods can be differentiated by JAX; the built-in
 adaptive controller is eager Python control flow. See the
 [backend guide](docs/guides/backends.md) for the precise contract and the
 [solver guide](docs/guides/solver-methods.md) for method-specific examples.
@@ -135,7 +151,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)
@@ -152,13 +169,20 @@ 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.
@@ -166,7 +190,9 @@ solver.run(rhs, config=None)  # defaults: method="heun" (explicit)
 - `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.
 - 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.2.0 → op_engine-0.4.0}/README.md

@@ -36,6 +36,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
@@ -75,9 +87,10 @@ solution = core.state_array  # shape (n_timesteps, state, subgroup)
 ### Array namespaces
 
 `ModelCore` infers its numerical namespace from the initial state through
-`initial_state.__array_namespace__()`. The state, stored history, solver stages,
+`array_api_compat.array_namespace()`. The state, stored history, solver stages,
 and dense solver operations stay in that namespace. There is no `xp=` or
-backend option. Fixed-step methods can be differentiated by JAX; the built-in
+backend option. This supports standard Array-API objects and native arrays such
+as `torch.Tensor`. Fixed-step methods can be differentiated by JAX; the built-in
 adaptive controller is eager Python control flow. See the
 [backend guide](docs/guides/backends.md) for the precise contract and the
 [solver guide](docs/guides/solver-methods.md) for method-specific examples.
@@ -86,7 +99,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)
@@ -103,13 +117,20 @@ 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.
@@ -117,7 +138,9 @@ solver.run(rhs, config=None)  # defaults: method="heun" (explicit)
 - `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.
 - 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.4.0/docs/assets/chemostat-split.svg

@@ -0,0 +1,41 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="900" height="280" viewBox="0 0 900 280" role="img" aria-labelledby="title desc">
+  <title id="title">Chemostat PDE operator split</title>
+  <desc id="desc">Population density and resource enter explicit reaction and implicit diffusion partitions, which are combined by the IMEX solver into observables.</desc>
+  <defs>
+    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto" markerUnits="strokeWidth">
+      <path d="M0,0 L0,6 L9,3 z" fill="#4051b5"/>
+    </marker>
+    <style>
+      .box { fill: #f7f8fc; stroke: #4051b5; stroke-width: 2; rx: 10; }
+      .accent { fill: #eef7f3; stroke: #16866b; stroke-width: 2; rx: 10; }
+      .text { font: 16px sans-serif; fill: #202124; text-anchor: middle; }
+      .small { font: 13px sans-serif; fill: #4b4d52; text-anchor: middle; }
+      .arrow { stroke: #4051b5; stroke-width: 2.5; fill: none; marker-end: url(#arrow); }
+    </style>
+  </defs>
+  <rect class="box" x="25" y="75" width="190" height="120"/>
+  <text class="text" x="120" y="110">State</text>
+  <text class="small" x="120" y="140">trait density n(theta)</text>
+  <text class="small" x="120" y="165">resource S</text>
+
+  <path class="arrow" d="M215 115 H295"/>
+  <path class="arrow" d="M215 165 H295"/>
+
+  <rect class="accent" x="300" y="25" width="245" height="95"/>
+  <text class="text" x="422" y="58">Explicit partition</text>
+  <text class="small" x="422" y="83">growth + dilution</text>
+  <text class="small" x="422" y="103">resource coupling</text>
+
+  <rect class="accent" x="300" y="155" width="245" height="95"/>
+  <text class="text" x="422" y="188">Implicit partition</text>
+  <text class="small" x="422" y="213">non-uniform no-flux</text>
+  <text class="small" x="422" y="233">trait diffusion</text>
+
+  <path class="arrow" d="M545 73 C600 73 600 112 640 125"/>
+  <path class="arrow" d="M545 203 C600 203 600 164 640 151"/>
+
+  <rect class="box" x="645" y="75" width="225" height="120"/>
+  <text class="text" x="757" y="110">IMEX trajectory</text>
+  <text class="small" x="757" y="140">biomass + resource</text>
+  <text class="small" x="757" y="165">mean + central moments</text>
+</svg>

op_engine-0.4.0/docs/development/fem-assembly-boundary.md

@@ -0,0 +1,102 @@
+# Finite-element assembly boundary
+
+Finite elements are a spatial discretization and assembly system, not a new
+`CoreSolver` time-method name. The current decision is **not to add a mesh,
+element, or quadrature framework to `op_engine` core and not to create an
+`op_engine-fem` provider yet**. Externally assembled linear finite-element
+systems can already use the stage-operator interface.
+
+## Supported semi-discrete form
+
+Consider the linear system
+
+\[
+  M \dot y = K y + g(t, y).
+\]
+
+An operator factory can map its implicit linear part into the existing solve
+
+\[
+  L y_{n+1} = R x.
+\]
+
+For example, the factory for a trapezoidal stage of size \(h\) returns
+
+\[
+  L = M - \tfrac{h}{2}K,
+  \qquad
+  R = M + \tfrac{h}{2}K.
+\]
+
+An implicit-Euler stage instead returns \(L=M-hK\) and \(R=M\). This supports
+fixed or variable stage sizes and permits the existing IMEX Euler,
+Heun--trapezoidal, and TR-BDF2 control flow to advance an externally assembled
+mass/stiffness pair.
+
+The explicit callable still has derivative units. A finite-element load vector
+`g` must therefore be supplied as `solve(M, g)`; the current API does not inject
+an unscaled weak-form load directly. Likewise, `imex-ark3` currently consumes
+only the left implicit solve at each additive stage, so a non-identity mass
+matrix must be resolved to an operator such as `solve(M, K)` before using that
+method. Changing either contract should be motivated and designed separately,
+not hidden in an FEM adapter.
+
+## Ownership
+
+The assembly package or application owns:
+
+- mesh topology and geometry;
+- basis functions, quadrature, and element integration;
+- degree-of-freedom maps and constraint elimination;
+- essential and natural boundary-condition assembly;
+- mass, stiffness, load, and nonlinear residual assembly;
+- any matrix reassembly or preconditioner lifecycle.
+
+`op_engine` owns time integration, stage context, operator-axis application,
+accepted-step control, and the `L @ y_next = R @ x` solve boundary. This keeps
+optional SciPy, PETSc, FEniCSx, and JAX FEM ecosystems from becoming core
+dependencies.
+
+## Sparse operators and differentiation
+
+SciPy CSR pairs use the registered sparse adapter. A provider should reuse
+operator objects when their values do not change so the factorization cache is
+effective. Other array backends can supply dense native arrays and use the
+Array-API linear solve. A JAX-native dense assembly remains differentiable
+through matrix construction and solve; eager NumPy/SciPy assembly and
+factorization do not. An external PETSc or FEniCSx provider would own any
+custom differentiation rule for its solver.
+
+Nonlinear forms such as \(M(y,t)\dot y=r(t,y)\), differential-algebraic
+constraints, and external Krylov/preconditioner callbacks are outside the
+current stage-operator contract. They require a concrete use case before a new
+portable solver interface is added.
+
+## Proof of concept
+
+[`examples/fem_diffusion.py`](https://github.com/ACCIDDA/op_engine/blob/main/examples/fem_diffusion.py)
+assembles a consistent P1 mass matrix and diffusion stiffness matrix on a 1D
+mesh, eliminates homogeneous Dirichlet boundary degrees of freedom, and runs
+the result with fixed-step `imex-heun-tr`. Assembly uses SciPy only because the
+example is demonstrating the external sparse boundary; it is not a required
+FEM representation.
+
+The example intentionally uses fixed steps. For pure implicit diffusion,
+Heun--trapezoidal's embedded low/high pair differs only in its explicit term
+and therefore cannot estimate the implicit truncation error. Adaptive FEM runs
+should currently use a method with a suitable estimator, such as TR-BDF2 step
+doubling, or supply and validate a fixed/replayed mesh at a higher layer.
+
+## When to reconsider a provider
+
+Reconsider a separate provider, rather than extending core, when at least one
+real unstructured-domain model identifies all of the following:
+
+1. a specific external assembly and linear-solver ecosystem;
+2. required boundary-condition and constraint semantics;
+3. sparse/device and differentiation expectations;
+4. nonlinear and reassembly requirements;
+5. a benchmark showing that the existing `(L, R)` boundary is insufficient.
+
+Until then, the proof of concept is the supported design pattern and a general
+FEM abstraction would add dependencies and policy without a validated user.

{op_engine-0.2.0 → op_engine-0.4.0}/docs/guides/backends.md

@@ -1,6 +1,9 @@
 # Backend and solve-strategy boundaries
 
-`op_engine` selects the numerical namespace from the state array. Explicit,
+`op_engine` selects the numerical namespace from the state array with
+`array_api_compat.array_namespace()`. This supports arrays with the standard
+`__array_namespace__` protocol and native arrays such as `torch.Tensor`
+through compatibility namespaces. Explicit,
 dense linearly implicit, and IMEX methods use that namespace's Array-API
 operations, including `linalg.solve`. The numerical method does not change when
 the array namespace changes.
@@ -9,6 +12,10 @@ Namespace portability and automatic differentiation are related but distinct.
 The Array API does not define `grad`, `jit`, or traced control flow. A namespace
 such as JAX can nevertheless differentiate the ordinary `op_engine` methods
 because their fixed-step numerical operations remain in that namespace.
+The optional `torch` dependency group qualifies representative eager
+fixed-step kernels with PyTorch autograd. Compiler integration and complete
+method qualification remain provider/backend capabilities rather than
+consequences of namespace selection.
 
 ## Portable fixed-step methods
 
@@ -47,15 +54,17 @@ parameters move, and always refresh it after a material model or tolerance
 change. A schedule is validated against the output grid, while matching the
 method and other configuration is the caller's responsibility.
 
-Schedule replay statically unrolls the accepted steps when JAX traces it. For
-very long meshes, a provider may instead implement bounded, masked compiled
-control flow around the same portable kernels.
+Direct `CoreSolver` schedule replay statically unrolls accepted steps when JAX
+traces it. The optional flepimop2 provider consumes the same functional kernels
+but defaults explicit JAX replay to one compact `lax.scan`. Its forced compact
+mode can also checkpoint/rematerialize each step for long reverse-mode solves;
+non-JAX and nonlinear-diagnostic paths retain portable core replay.
 
-Projects that require a compiled adaptive controller, checkpointed adjoints, or
-other solver-specific capabilities can provide those at an external plugin or
-provider boundary. A specialized integration may return a complete trajectory
-and adopt it through `ModelCore.apply_trajectory`; it does not need to add a
-backend-specific method to `CoreSolver`.
+Projects that require a compiled adaptive controller or other solver-specific
+capabilities can provide those at an external plugin or provider boundary. A
+specialized integration may return a complete trajectory and adopt it through
+`ModelCore.apply_trajectory`; it does not need to add a backend-specific method
+to `CoreSolver`.
 
 This keeps optional packages such as Diffrax out of the core dependency and
 method surfaces. The portable fixed-step methods and their differentiation
@@ -73,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