# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""The reference's Runge-Kutta engines over its workspace (SEP 52 section 5.2).
Two :class:`~solprop.backends.engines.RungeKuttaEngine` implementations, the
counterparts of native's resident engines. :class:`NumpyRungeKutta` forms an
interaction-picture embedded Runge-Kutta trial from the workspace's committed state
and keeps its stages and end state until :meth:`~NumpyRungeKutta.accept` finishes and
commits it; a rejected trial leaves the committed state as it was.
:class:`NumpyLowStorage` is the low-storage RK4 step of SEP 24
(:mod:`solprop.backends.low_storage`), whose trial overwrites the state in place and
is in flight until it is accepted. The Adams engine is
:class:`solprop.backends.numpy_ref.multistep.HostHistory`.
"""
import math
from typing import TYPE_CHECKING
import numpy as np
from jaxtyping import Complex
from solprop.backends.engines import AcceptRecord, BoundaryReading
from solprop.backends.low_storage import schedule_key, table_steps
from solprop.backends.numpy_ref.passes.stepping import (
accept_step,
accumulate,
stage_input,
)
from solprop.exceptions import BackendError
from solprop.stepper.low_storage import LowStorageRungeKutta
from solprop.stepper.schedule import FixedSchedule
from solprop.stepper.tableau import Tableau, extension_coefficients
if TYPE_CHECKING:
from solprop.backends.numpy_ref.workspace import NumpyWorkspace
__all__ = ["NumpyLowStorage", "NumpyRungeKutta"]
_State = Complex[np.ndarray, "n_modes n_pol n_omega"]
_Extension = tuple[float, float, list[np.ndarray]]
"""A continuous extension: its step's start and length, m, and its coefficients."""
[docs]
class NumpyRungeKutta:
"""The interaction-picture embedded Runge-Kutta trial over a workspace.
Every stage is evaluated. The tableau's first-same-as-last property would let the
last stage of one step serve as the first of the next, after rebasing it by
``exp(dPhi)`` because the interaction picture is re-anchored every step; the
reference does not take that saving, so that no stage it uses depends on the
bookkeeping of the step before (``docs/dev/stepper.md`` section 10, trap 10).
Parameters
----------
workspace : solprop.backends.numpy_ref.workspace.NumpyWorkspace
The workspace whose state is stepped.
tableau : solprop.stepper.tableau.Tableau
The embedded pair.
Attributes
----------
evaluations : int
Physical source evaluations of the trials since the engine was built, for one
run, rejected trials included (SEP 30 records work rather than estimating it
from steps).
"""
def __init__(self, workspace: "NumpyWorkspace", tableau: Tableau) -> None:
"""Hold the workspace; no trial is held yet."""
self._workspace = workspace
self._tableau = tableau
self._trial: tuple[_State, list[_State]] | None = None
self._extension: tuple[float, float, list[np.ndarray]] | None = None
self.evaluations = 0
[docs]
@property
def in_flight(self) -> bool: # numpydoc ignore=RT01
"""Whether a trial overwrote the committed state; never, on this engine."""
return False
[docs]
@property
def trial_state(self) -> _State: # numpydoc ignore=RT01
"""The held trial's raw end state, before the accepted step's finish."""
if self._trial is None:
raise BackendError("take a trial before reading its state")
return self._trial[0]
[docs]
@property
def stages(self) -> list[_State]: # numpydoc ignore=RT01
"""The held trial's stage derivatives, in its anchor's frame."""
if self._trial is None:
raise BackendError("take a trial before reading its stages")
return list(self._trial[1])
[docs]
def trial(self, z: float, dz: float) -> float:
"""Form a trial from the committed state at `z` over `dz`; return its norm.
A problem carrying ``linear.coupled_flow`` multiplies each stage's scalar
propagator by the section's Schur matrix-function action; the two factors
commute, so their product is the flow of the sum. A ``"frozen_residual"`` flow
adds the explicit residual to each stage's lab-frame source, before the
interaction picture's own factors carry it back, so it is integrated by the
embedded pair exactly as the material response is.
Parameters
----------
z : float
Where the trial starts, m.
dz : float
The step, m, positive.
Returns
-------
float
The scaled error norm of the step's embedded difference.
"""
workspace = self._workspace
state = workspace.committed()
workspace.hoist(z)
tableau = self._tableau
# The whole step and every stage, read together: each table once.
workspace.stage_bundles(
z, [z + dz, *(z + float(node) * dz for node in tableau.nodes)]
)
exponents = workspace.exponents()
step = workspace.stage_scalars(z, z + dz)
actions = workspace.flow_actions(step.flow_section, dz)
stages: list[_State] = []
solution = np.zeros_like(state)
error = np.zeros_like(state)
for index, node in enumerate(tableau.nodes):
fraction = float(node)
combination = np.zeros_like(state)
for previous in range(index):
combination = accumulate(
combination,
stages[previous],
float(tableau.matrix[index, previous]),
)
bundle = workspace.stage_scalars(z, z + fraction * dz)
exponent = exponents(fraction, bundle)
forward, inverse = actions(fraction)
lab = stage_input(
workspace.channels(state, forward),
workspace.channels(combination, forward),
dz,
np.exp(exponent),
workspace.noise_at(bundle),
)
back = np.exp(-exponent)
self.evaluations += 1
drive = workspace.nonlinear(lab, bundle, back)
residual = workspace.residual(lab, step.flow_section, bundle)
if residual is not None:
drive = drive + back * residual
stage = workspace.channels(drive, inverse)
stages.append(stage)
solution = accumulate(
solution, stage, float(tableau.solution_weights[index])
)
error = accumulate(error, stage, float(tableau.error_weights[index]))
propagator = np.exp(exponents(1.0, step))
whole = actions(1.0)[0]
advanced = accept_step(
workspace.channels(state, whole),
propagator,
dz,
workspace.channels(solution, whole),
)
# The embedded difference is carried to the end of the step by the same
# exponential as the solution, so the norm scales the local error of the
# propagated state rather than of the interaction variable.
norm = workspace.error_norm(
propagator * (dz * workspace.channels(error, whole)), state, advanced
)
# Kept for the accept, and for the continuous extension of an accepted step
# (SEP 14 phase 3).
self._trial = (advanced, stages)
return norm
[docs]
def accept(self, dz: float) -> AcceptRecord:
"""Finish the held trial and commit it as the workspace's state.
Parameters
----------
dz : float
The accepted step, m.
Returns
-------
solprop.backends.engines.AcceptRecord
The finish's split collar's sums.
"""
finished, record = self._workspace.finish(self.trial_state, dz)
self._workspace.install(finished)
return record
[docs]
def extend(self, z: float, dz: float) -> None:
"""Hold the held trial's continuous extension, before it is accepted.
With ``v0`` the state at the step's anchor, ``k_i`` its stage derivatives in
the anchor's frame and ``v1 = v0 + h sum_i b_i k_i``, the coefficients are
DOPRI5's (Hairer, Noersett and Wanner, II.6): ``v0``, ``v1 - v0``, ``h k1 - (v1
- v0)``, ``(v1 - v0) - h k7 - (h k1 - (v1 - v0))`` and ``h sum_i d_i k_i``.
Parameters
----------
z : float
Where the trial started, m.
dz : float
The step, m.
"""
workspace = self._workspace
start = workspace.committed().reshape(workspace.problem.shape)
coefficients = extension_coefficients(self._tableau, start, self.stages, dz)
self._extension = (z, dz, coefficients)
[docs]
@property
def extension(self) -> "_Extension | None": # numpydoc ignore=RT01
"""The held extension: its step's start and length, m, and its coefficients."""
return self._extension
[docs]
def reading(self) -> BoundaryReading:
"""Return the committed state's boundary reading.
Returns
-------
solprop.backends.engines.BoundaryReading
The workspace's reading.
"""
return self._workspace.reading()
[docs]
class NumpyLowStorage:
"""The host engine: the four register passes over host arrays (SEP 24 6.5).
The workspace's state is the register ``A`` and is updated in place by the
trial; ``B`` and ``C`` are this engine's host arrays, allocated at the first step.
Each pass makes one source evaluation through the workspace's ``lab_source`` (the
complete source, the noise draw advanced to the pass's position and the in-stage
absorbers included) and takes ``P`` and ``Q`` from its ``propagator`` or the
table, allocating transients as the reference does. The step's three positions
are known before its first pass, so their host scalars are read together
(``stage_bundles``) and the evaluations take the kept bundles.
**The commit contract** (SEP 52 section 5.2): :meth:`trial` overwrites the state,
and from its start until :meth:`accept` returns the engine is :attr:`in_flight`.
An exception or a non-finite result in that interval leaves no committed state at
that position; only :meth:`reset`, at a load, clears the flag.
**The flows.** ``"tabulate"`` on a constant operator holds one volume,
``exp(h_t D / 2)``, built at the first step after a load and reused while the steps
keep the same key ``h_t``, their run's mean step
(:func:`~solprop.backends.low_storage.table_steps`, SEP 24 Q10): a uniform
schedule's steps are differences of rounded positions and differ in their last bits.
The table is built from the key alone, from the operator's origin to ``h_t / 2`` --
a constant operator's increment is the distance itself -- so its exponent carries
one rounding of ``D h_t / 2`` and none of the step's position (``fl(z + h/2) - z``
would be off by up to half an ulp of ``z``, an error that accumulates). Each reused
flow's exponent is then off by ``|D| |h - h_t| / 2``, a few ulps of the position
times ``|D|``, which does not accumulate over the run. A varying operator's ``P``
and ``Q`` change every step, and ``"tabulate"`` forms the pair once per step;
``"recompute"`` forms each flow in the finish that applies it, from the positions,
whose differences telescope. The treatments agree to rounding, not bit for bit.
**The stiffness indicator** (SEP 24 section 6.3, Q1): ``h rho = 2 ||F3 - F2|| /
||F2 - g1||`` over the norm mask estimates ``|h lambda|`` of the linearised source
on the content the step integrates (for ``u' = lambda u`` it is exactly
``|h lambda|``), the quantity the stability interval of section 4.6 bounds. It is
kept in ``stiffness`` and never enters the norm column. It reads the content's
margin, not the worst case: measured on an ionising capillary it passed 2.785 on
the step before the replay diverged, and beside an in-stage collar it read 0.17 to
0.65 of ``h alpha_max / 2`` as the collar held less or more of the field.
Parameters
----------
workspace : solprop.backends.numpy_ref.workspace.NumpyWorkspace
The reference's workspace, whose state, evaluations and finish are used. The
native session keeps its registers resident and never takes this engine.
method : solprop.stepper.low_storage.LowStorageRungeKutta
The march.
schedule : solprop.stepper.schedule.FixedSchedule or None
The replayed schedule, whose runs key the flow table; ``None`` only for an
engine that never tabulates.
propagator_mode : {'tabulate', 'recompute'}
Whether the step's flows are held for it.
Attributes
----------
stiffness : float
``h rho`` of the last completed trial, dimensionless; NaN before one, or when
``F2 - g1`` vanished on the norm mask.
Notes
-----
What the engine holds between steps is the registers ``B`` and ``C`` and, on a
constant operator tabulating, the table: :meth:`held` names them for the backend's
memory ledger, and :meth:`close` releases them.
"""
def __init__(
self,
workspace: "NumpyWorkspace",
method: LowStorageRungeKutta,
schedule: FixedSchedule | None,
propagator_mode: str,
) -> None:
"""Hold the workspace with no registers yet."""
self._workspace = workspace
self._method = method
self._schedule = schedule
self._propagator_mode = propagator_mode
self._accumulator: _State | None = None
self._stage: _State | None = None
self._table: _State | None = None
self._table_step = math.nan
self._keys: tuple[np.ndarray, np.ndarray] | None = None
self._in_flight = False
self.stiffness = math.nan
[docs]
@property
def in_flight(self) -> bool: # numpydoc ignore=RT01
"""Whether a trial overwrote the state and its accept has not returned."""
return self._in_flight
[docs]
def reset(self) -> None:
"""Drop the flow table and a step left in flight: a state was loaded.
A resume builds the table again from its own first step.
"""
self._table = None
self._table_step = math.nan
self.stiffness = math.nan
self._in_flight = False
[docs]
def close(self) -> None:
"""Release the registers and the flow table."""
self.reset()
self._accumulator = None
self._stage = None
[docs]
def held(self) -> dict[str, int]:
"""Return the bytes of every array the engine holds between steps, by name.
Returns
-------
dict
``register_accumulator``, ``register_stage`` and ``propagators`` (the
table), each zero while it is not allocated.
"""
return {
"register_accumulator": _bytes(self._accumulator),
"register_stage": _bytes(self._stage),
"propagators": _bytes(self._table),
}
[docs]
def trial(self, z: float, dz: float) -> float:
"""Take one RK4IP step in place, in the four passes of the register form.
The engine is in flight from here until :meth:`accept` returns.
Parameters
----------
z : float
Where the step starts, m.
dz : float
The step, m, positive.
Returns
-------
float
0.0, "not estimated"; or, when the field has diverged, the accepted
state's non-finite squared norm over the norm mask.
"""
workspace = self._workspace
state = workspace.committed()
self._in_flight = True
squared = self._step(state, z, dz)
return squared if not math.isfinite(squared) else 0.0
[docs]
def accept(self, dz: float) -> AcceptRecord:
"""Finish the state the trial left and commit it; the step leaves flight.
Parameters
----------
dz : float
The step, m, which the split collar's rate needs.
Returns
-------
solprop.backends.engines.AcceptRecord
The stiffness indicator and the finish's split collar's sums.
"""
workspace = self._workspace
finished, record = workspace.finish(workspace.committed(), dz)
workspace.install(finished)
self._in_flight = False
return AcceptRecord(
stiffness=self.stiffness, removed=record.removed, found=record.found
)
[docs]
def extend(self, z: float, dz: float) -> None:
"""Refuse: the low-storage march replays and observes no plane densely.
Parameters
----------
z : float
Where the step started, m.
dz : float
The step, m.
Raises
------
BackendError
Always.
"""
del z, dz
raise BackendError("the low-storage engine holds no dense extension")
[docs]
def reading(self) -> BoundaryReading:
"""Return the committed state's boundary reading.
Returns
-------
solprop.backends.engines.BoundaryReading
The workspace's reading.
"""
return self._workspace.reading()
def _step(self, state: _State, z: float, dz: float) -> float:
"""Take the step's four passes on `state`; return its squared norm."""
workspace = self._workspace
midpoint, end = z + 0.5 * dz, z + dz
first, second = self._flows(z, dz)
mask = workspace.problem.grids.norm_mask
# Pass 1: F1 at z_n; A <- P A, g <- P S, B <- A + h/6 g, C <- A + h/2 g.
source = workspace.lab_source(state, z)
flow = workspace.propagator(z, midpoint) if first is None else first
if state.flags.writeable:
np.multiply(state, flow, out=state)
else:
# An observation holds the accepted state read-only; it keeps its own.
state = flow * state
workspace.install(state)
slope = flow * source
accumulator, stage = self._registers(state)
np.add(state, (dz / 6.0) * slope, out=accumulator)
np.add(state, (0.5 * dz) * slope, out=stage)
# Pass 2: F2 at z_m; B <- B + h/3 S, C <- A + h/2 S.
source = workspace.lab_source(stage, midpoint)
lower = _masked_norm(source - slope, mask)
accumulator += (dz / 3.0) * source
np.add(state, (0.5 * dz) * source, out=stage)
previous = source
# Pass 3: F3 at z_m; B <- B + h/3 S, C <- Q (A + h S).
source = workspace.lab_source(stage, midpoint)
upper = _masked_norm(source - previous, mask)
accumulator += (dz / 3.0) * source
flow = workspace.propagator(midpoint, end) if second is None else second
np.multiply(flow, state + dz * source, out=stage)
# Pass 4: F4 at z_n + h; A <- Q B + h/6 S.
source = workspace.lab_source(stage, end)
flow = workspace.propagator(midpoint, end) if second is None else second
np.multiply(flow, accumulator, out=state)
state += (dz / 6.0) * source
self.stiffness = 2.0 * upper / lower if lower > 0.0 else math.nan
accepted = state[..., mask]
return float(np.vdot(accepted, accepted).real)
def _flows(self, z: float, dz: float) -> tuple[_State | None, _State | None]:
"""Read the step's bundles and return the flows held for it, ``P`` and ``Q``.
- ``z``: where the step starts, m.
- ``dz``: the step, m, positive.
- Returns: ``P`` and ``Q`` when they are held for the step -- the table on a
constant operator, the pair on a varying one -- or ``None`` each when
recomputed in the finishes that apply them.
"""
workspace = self._workspace
midpoint, end = z + 0.5 * dz, z + dz
tabulating = self._propagator_mode == "tabulate"
table = tabulating and workspace.problem.flags.constant_linop
workspace.hoist(z)
# Each evaluation reads its position as its own anchor and each flow its
# interval, so the anchors' bundles are read here, once each.
workspace.stage_bundles(z, [z] if table else [z, midpoint])
workspace.stage_bundles(midpoint, [midpoint] if table else [midpoint, end])
workspace.stage_bundles(end, [end])
if table:
if self._keys is None:
schedule = self._schedule
assert schedule is not None # the translation refused it without one
self._keys = (table_steps(schedule), schedule.edges)
key = schedule_key(*self._keys, z, dz)
if self._table is None or key != self._table_step:
# From the operator's origin, where a constant operator's increment is
# the half step itself, not fl(z + h/2) - z (class docstring).
origin = workspace.problem.linear.z_span[0]
half = origin + 0.5 * key
workspace.stage_bundles(origin, [half])
self._table = workspace.propagator(origin, half)
self._table_step = key
return self._table, self._table
if tabulating:
return (
workspace.propagator(z, midpoint),
workspace.propagator(midpoint, end),
)
return None, None
def _registers(self, state: _State) -> tuple[_State, _State]:
"""Return ``B`` and ``C``, allocated like the state at the first step.
- ``state``: the state, whose shape and type the registers take.
- Returns: the accumulator and the stage register.
"""
if self._accumulator is None or self._stage is None:
self._accumulator = np.empty_like(state)
self._stage = np.empty_like(state)
return self._accumulator, self._stage
def _bytes(values: np.ndarray | None) -> int:
"""Return an optional array's bytes, zero for ``None``."""
return 0 if values is None else int(values.nbytes)
def _masked_norm(values: _State, mask: np.ndarray) -> float:
"""Return the 2-norm of an array over the norm mask's bins.
- ``values``: an array of the state's layout.
- ``mask``: the norm mask, boolean of shape ``(n_omega,)``.
"""
return float(np.linalg.norm(values[..., mask]))