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

{op_engine-0.2.0 → op_engine-0.3.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.3.0/CHANGELOG.md

@@ -0,0 +1,140 @@
+# Changelog
+
+Notable user-facing changes are recorded here. Versions follow semantic
+versioning while the project remains pre-1.0.
+
+## [Unreleased]
+
+## [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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: op_engine
-Version: 0.2.0
+Version: 0.3.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
@@ -124,9 +127,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.

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

@@ -75,9 +75,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.

op_engine-0.3.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.3.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.3.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

op_engine-0.3.0/docs/guides/chemostat-pde.md

@@ -0,0 +1,97 @@
+# Trait-structured chemostat PDE
+
+The
+[`chemostat_pde.py`](https://github.com/ACCIDDA/op_engine/blob/main/examples/chemostat_pde.py)
+example couples a population density over a continuous trait coordinate to one
+well-mixed resource. It demonstrates non-uniform finite-volume geometry,
+implicit diffusion, nonlinear explicit coupling, and structured observables in
+one reproducible comparison.
+
+![Chemostat operator split](../assets/chemostat-split.svg)
+
+## Model and split
+
+For population density `n(theta, t)` and resource `S(t)`, the example solves
+
+```text
+dn/dt = n g(theta, S) - D n + d d2n/dtheta2
+dS/dt = D (S_in - S) - integral[n g(theta, S) w(theta) dtheta].
+```
+
+Growth combines Monod resource limitation with a Gaussian trait optimum. The
+positive uptake weight varies exponentially with trait and is scaled by the
+yield coefficient.
+
+The split supplied to `CoreSolver` is:
+
+| Partition | Terms |
+| --- | --- |
+| implicit linear | no-flux trait diffusion |
+| explicit nonlinear | growth, dilution, resource inflow, and consumption |
+
+`imex-heun-tr` treats the two partitions to second order. The implicit stage is
+assembled additively as `L y = R y_n + explicit_increment`; the right
+trapezoidal operator does not multiply the explicit increment.
+
+The example does not clip stage states or project the result onto the positive
+orthant. Positivity in the canonical run is an observed numerical diagnostic,
+not an extra model operation.
+
+## Non-uniform finite volumes
+
+`build_trait_grid()` calls `generate_adaptive_grid()` on the curvature of the
+initial Gaussian trait profile. More centers are placed where the initial
+profile bends rapidly, while the domain endpoints remain fixed.
+
+For adjacent center spacings `h_i`, the integration weights are
+
+```text
+q_0     = h_0
+q_i     = (h_(i-1) + h_i) / 2
+q_(N-1) = h_(N-2).
+```
+
+These are the same control-volume widths used by the non-uniform diffusion
+operator. With reflecting boundaries, `q^T A = 0`, so diffusion alone
+conserves total biomass.
+
+## Structured observables
+
+At every output time the example records resource and five summaries of the
+trait distribution:
+
+| Observable | Discrete definition |
+| --- | --- |
+| biomass | `I = sum_i q_i n_i` |
+| mean trait | `rho = sum_i q_i n_i theta_i / I` |
+| variance | `Sigma = sum_i q_i n_i (theta_i-rho)^2 / I` |
+| skewness | third central moment divided by `Sigma^(3/2)` |
+| kurtosis | fourth central moment divided by `Sigma^2` |
+
+Kurtosis is the raw standardized fourth moment, not excess kurtosis.
+
+## Run and interpret the comparison
+
+From a development checkout:
+
+```bash
+uv sync --dev
+uv run python examples/chemostat_pde.py
+```
+
+The command writes
+`examples/output/chemostat_pde/chemostat_summary.png` and reports maximum state
+and biomass differences. The committed reference figure below uses the default
+41-cell grid and 0.02-day time step.
+
+![Default chemostat comparison](../assets/chemostat-summary.png)
+
+The panels compare initial and final trait densities, resource and total
+biomass, and the evolving mean trait with one standard deviation. Dashed lines
+come from SciPy RK45 applied to the same semi-discrete system with tight
+tolerances. This comparison isolates time integration: RK45 uses the identical
+grid, quadrature, reaction functions, diffusion matrix, and initial state.
+
+The RK45 trajectory is a high-accuracy reference for this finite-dimensional
+discretization, not an exact solution of the continuous PDE. Grid convergence
+and time-step convergence remain separate checks.

{op_engine-0.2.0 → op_engine-0.3.0}/docs/guides/getting-started.md

@@ -21,22 +21,28 @@ CoreSolver(core).run(decay)
 solution = core.state_array
 ```
 
-## NumPy and JAX solves
+## Array-backend solves
 
-NumPy 2 and JAX arrays implement `__array_namespace__()`. Passing either one to
+`array-api-compat` discovers the numerical namespace from NumPy, JAX, CuPy,
+PyTorch, and other supported native arrays. Passing an array to
 `set_initial_state` selects the namespace for state storage, history, solver
-stages, and adaptive error control. No backend argument is needed. An RHS should
-derive operations from its state when it needs namespace functions:
+stages, and adaptive error control. No backend argument is needed. An RHS
+should derive operations from its state when it needs namespace functions:
 
 ```python
+from op_engine import array_namespace
+
+
 def portable_decay(_time, state):
-    xp = state.__array_namespace__()
+    xp = array_namespace(state)
     return xp.multiply(state, -0.25)
 ```
 
 Dense implicit and IMEX operators are converted into the state's namespace and
 solved with its Array-API `linalg.solve` implementation. This provides the
-portable correctness path for NumPy, JAX, and other conforming backends.
+portable correctness path for NumPy, JAX, PyTorch, and other supported
+backends. Array portability alone does not promise backend compilation,
+automatic differentiation, sparse support, or random-number semantics.
 
 Sparse acceleration is an optional second tier. SciPy sparse operators retain
 cached factorization for NumPy state. Installing `op-engine[cupy]` registers the

{op_engine-0.2.0 → op_engine-0.3.0}/docs/guides/solver-methods.md

@@ -236,8 +236,22 @@ CoreSolver(core).run(rhs, config=config)
 ```
 
 With `adaptive=False`, every adjacent pair of output times defines one solver
-step. With `adaptive=True`, the controller may take multiple internal steps but
-still stores only the requested output times.
+step by default. Set `fixed_max_step` to bound explicit Euler, Heun, RK4, or
+Dormand--Prince integration steps independently of the output grid:
+
+```python
+config = RunConfig(method="rk4", fixed_max_step=0.25)
+```
+
+Each output interval then uses as many full `fixed_max_step` steps as fit plus
+a final remainder step that lands exactly on the next output time. Only the
+requested output states are stored. Output grids aligned with the fixed-step
+mesh can therefore be made more or less frequent without changing states at
+shared times. `fixed_max_step` is incompatible with `adaptive=True`; adaptive
+methods use their controller configuration instead.
+
+With `adaptive=True`, the controller may take multiple internal steps but still
+stores only the requested output times.
 
 Heun, RK4, and Dormand--Prince share one validated explicit Runge--Kutta
 tableau kernel. `rk4` takes four RHS stages per fixed step. Under adaptivity it
@@ -310,6 +324,46 @@ config = RunConfig(
 CoreSolver(core, operator_axis="state").run(reaction, config=config)
 ```
 
+For a non-uniform axis, pass strictly increasing cell-center coordinates and
+set `dx=None`:
+
+```python
+centers = np.asarray([0.0, 0.08, 0.21, 0.5, 1.0])
+operator = build_diffusion_matrix(
+    centers.size,
+    None,
+    diffusivity,
+    grid=centers,
+    bc="neumann",
+)
+```
+
+The no-flux operator is conservative and self-adjoint under the inferred
+cell-volume weights. It is generally not symmetric in the unweighted Euclidean
+inner product. Periodic non-uniform grids need an explicit wrap spacing, which
+cannot be inferred from center coordinates alone, and are rejected.
+
+Use `generate_adaptive_grid` to create a curvature-weighted point grid from a
+vectorized profile callable:
+
+```python
+from op_engine import generate_adaptive_grid
+
+centers = generate_adaptive_grid(
+    lambda x: np.exp(-10.0 * x * x),
+    (-1.0, 1.0),
+    65,
+    smoothing_window=5,
+    minimum_spacing=1e-3,
+)
+```
+
+The generator returns exactly the requested number of NumPy coordinates,
+including both interval endpoints. It is eager preprocessing rather than part
+of the differentiable solve; the resulting static geometry can drive NumPy,
+JAX, Torch, or another supported Array-API backend. The sampled-data companion
+is `generate_adaptive_grid_from_data`.
+
 For `imex-trbdf2`, provide both stage schemes:
 
 ```python
@@ -348,10 +402,11 @@ across Array-API namespaces.
 
 `imex-ars443` and `ars443` are aliases for `imex-ark3`.
 
-The flepimop2 provider can compile typed `op_system` `axis_kernel`, `advection`,
-and `diffusion` descriptors into these same factories. Descriptor parsing and
-axis-label resolution belong to the provider; the numerical builders and
-stepping methods remain in `op_engine`.
+The flepimop2 provider can compile typed `op_system` `axis_kernel`,
+`jump_integral`, `advection`, and `diffusion` descriptors into these same
+factories. Descriptor parsing, axis-type/coordinate resolution, and layout
+lifting belong to the provider; portable jump assembly follows op_system's
+public reference semantics, while stepping methods remain in `op_engine`.
 
 ## Linearly implicit methods
 
@@ -360,8 +415,11 @@ well as the Rosenbrock method, take a Jacobian callable. The callable returns an
 operator acting along `operator_axis`:
 
 ```python
+from op_engine import array_namespace
+
+
 def jacobian(_time, state):
-    xp = state.__array_namespace__()
+    xp = array_namespace(state)
     return xp.multiply(xp.eye(state.shape[0], dtype=state.dtype), -0.5)
 
 

{op_engine-0.2.0 → op_engine-0.3.0}/docs/index.md

@@ -7,6 +7,9 @@ Start with [Getting Started](guides/getting-started.md), then use
 explicit, IMEX, or linearly implicit method. The
 [biogeochemical network tutorial](guides/biogeochemical-network.md) shows
 stage-dependent operator splitting in a complete example.
+The [trait-structured chemostat tutorial](guides/chemostat-pde.md) combines a
+non-uniform finite-volume grid, implicit diffusion, nonlinear resource
+coupling, and structured trait observables.
 
 `op_engine` numerical methods use the array namespace supplied by model state.
 The [backend guide](guides/backends.md) explains portability, JAX