Source code for solprop.backends.numpy_ref.engines

# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later

"""The reference's Runge-Kutta engine over its workspace (SEP 52 section 5.2).

:class:`NumpyRungeKutta` is the reference's
:class:`~solprop.backends.engines.RungeKuttaEngine`, the counterpart of native's
``engines::ResidentRungeKutta``: it forms an interaction-picture embedded Runge-Kutta
trial from the workspace's committed state and keeps the trial's stages and end state
until :meth:`~NumpyRungeKutta.accept` finishes and commits it. A rejected trial leaves
the committed state as it was. The reference's other engines are the low-storage step
(:class:`solprop.backends.low_storage.HostLowStorage`) and the Adams history
(:class:`solprop.backends.numpy_ref.multistep.HostHistory`).
"""

import numpy as np
from jaxtyping import Complex

from solprop.backends.engines import AcceptRecord, BoundaryReading
from solprop.backends.numpy_ref import passes
from solprop.backends.numpy_ref.workspace import NumpyWorkspace
from solprop.exceptions import BackendError
from solprop.stepper.tableau import Tableau, extension_coefficients

__all__ = ["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(z, dz) 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 = passes.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 = passes.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 = passes.accumulate( solution, stage, float(tableau.solution_weights[index]) ) error = passes.accumulate(error, stage, float(tableau.error_weights[index])) propagator = np.exp(exponents(1.0, step)) whole = actions(1.0)[0] advanced = passes.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()