Source code for solprop.backends.numpy_ref.dense

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

"""The reference's dense output: a plane interpolated inside the step that crossed it.

The counterparts of native's ``engines::RungeKuttaDense`` and ``engines::AdamsDense``
(``native/src/march/dense.cpp``), which implement the session's ``Dense``: the session
(:class:`~solprop.backends.host.session.HostSession`) decides when a plane is observed
inside the last accepted step, and asks one of these to hold the committed state aside,
make the state the interpolated field there, and restore the committed state before
the march goes on (SEP 14 phase 3, ADR-036, SEP 52 section 5.2). An observation
neither rewinds the controller nor advances the history, and evaluates no source.

- :class:`RungeKuttaDense` evaluates DOPRI5's continuous extension of Hairer, Norsett
  and Wanner II.6, which the engine held when the step was accepted
  (:meth:`~solprop.backends.numpy_ref.engines.NumpyRungeKutta.extend`), and carries
  it to the plane by the exact linear flow.
- :class:`AdamsDense` evaluates the Adams march's interpolant over its last accepted
  step: the weights at the plane's fraction from the march's record of the step
  (:class:`~solprop.backends.host.adams.AcceptedStep`), its carrier rotations applied
  to the samples the engine kept (SEP 35 section 4.1).
"""

import numpy as np
from jaxtyping import Complex

from solprop.backends.host.adams import AcceptedStep, HostAdamsMarch
from solprop.backends.numpy_ref.engines import NumpyRungeKutta
from solprop.backends.numpy_ref.multistep import (
    ExponentialKernels,
    HostHistory,
    _combine,
    _DenseStep,
    _ExponentialStep,
)
from solprop.backends.numpy_ref.workspace import NumpyWorkspace
from solprop.exceptions import BackendError
from solprop.stepper.multistep import integrated_weights, lagrange_coefficients
from solprop.stepper.schedule import reached
from solprop.stepper.tableau import extension_value

__all__ = ["AdamsDense", "RungeKuttaDense"]

_State = Complex[np.ndarray, "n_modes n_pol n_omega"]


class _Held:
    """The committed state a dense observation set aside, restored afterwards."""

    def __init__(self, workspace: NumpyWorkspace) -> None:
        self._workspace = workspace
        self._held: _State | None = None

    def hold(self, observed: _State) -> None:
        """Set the committed state aside and make `observed` the state."""
        workspace = self._workspace
        self._held = workspace.committed()
        workspace.install(observed)

    def restore(self) -> None:
        """Make the committed state current again."""
        held, self._held = self._held, None
        if held is None:
            raise BackendError("no dense observation holds the state")
        self._workspace.install(held)


[docs] class RungeKuttaDense: """DOPRI5's continuous extension of the last step that crossed a plane. Parameters ---------- workspace : solprop.backends.numpy_ref.workspace.NumpyWorkspace The workspace whose state is observed. engine : solprop.backends.numpy_ref.engines.NumpyRungeKutta The engine that held the extension. """ def __init__(self, workspace: NumpyWorkspace, engine: NumpyRungeKutta) -> None: """Hold the workspace and the engine; nothing is observed yet.""" self._workspace = workspace self._engine = engine self._held = _Held(workspace)
[docs] @staticmethod def crosses(position: float, target: float) -> bool: """Return whether a march that returned at `position` stepped across `target`. Parameters ---------- position : float The committed position, m. target : float The plane, m. Returns ------- bool True past the plane's landing tolerance (``not reached(target, z)``). """ return not reached(target, position)
[docs] def observe(self, position: float) -> None: """Hold the committed state aside; make the state the field at `position`. Interpolated by the continuous extension and carried to `position` by the exact linear flow; no source is evaluated. Parameters ---------- position : float The plane, m, inside the extended step. Raises ------ BackendError If no extension is held. """ extension = self._engine.extension if extension is None: raise BackendError("no accepted step is held for a dense observation") workspace = self._workspace z, dz, coefficients = extension start = coefficients[0] value = extension_value(coefficients, (position - z) / dz) # A bin the linear flow attenuates or amplifies by more than an e-fold over the # step -- the spectral collar's, outside the controlled band -- has an # interaction-picture derivative growing exponentially across it, which no # polynomial in theta follows: interpolated there it returns orders of # magnitude more than the field. Its source is negligible beside its own loss, # so the anchor's linear flow is its honest value. stiff = ( np.abs(np.real(workspace.delta_phi(workspace.stage_scalars(z, z + dz)))) > 1.0 ) value = np.where(stiff, start, value) self._held.hold(workspace.mask(workspace.propagator(z, position) * value))
[docs] def restore(self) -> None: """Make the committed state current again.""" self._held.restore()
[docs] class AdamsDense: """The Adams march's interpolant over its last accepted step. Parameters ---------- workspace : solprop.backends.numpy_ref.workspace.NumpyWorkspace The workspace whose state is observed. engine : solprop.backends.numpy_ref.multistep.HostHistory The engine that kept the step's samples. march : solprop.backends.host.adams.HostAdamsMarch The march whose record of the step (:attr:`~solprop.backends.host.adams.HostAdamsMarch.last_step`) gives the weights' nodes and the carrier rotations. """ def __init__( self, workspace: NumpyWorkspace, engine: HostHistory, march: HostAdamsMarch ) -> None: """Hold the workspace, the engine and the march; nothing is observed yet.""" self._workspace = workspace self._engine = engine self._march = march self._exponential = engine.exponential self._held = _Held(workspace)
[docs] @staticmethod def crosses(position: float, target: float) -> bool: """Return whether a march that returned at `position` stepped past `target`. Parameters ---------- position : float The committed position, m. target : float The plane, m. Returns ------- bool True when `position` is past it. """ return position > target
[docs] def observe(self, position: float) -> None: """Hold the committed state aside; make the state the field at `position`. Parameters ---------- position : float The plane, m, inside the last accepted step. Raises ------ BackendError If no accepted step is held. """ step = self._march.last_step if step is None: raise BackendError("no accepted Adams step is held for a dense observation") if self._exponential: held = self._engine.exponential_dense assert held is not None observed = self._observe_exponential(held, step, position) else: held = self._engine.dense assert isinstance(held, _DenseStep) observed = self._observe_fused(held, step, position) self._held.hold(observed)
[docs] def restore(self) -> None: """Make the committed state current again.""" self._held.restore()
def _observe_fused( self, held: _DenseStep, step: AcceptedStep, position: float ) -> _State: """Return the interaction formulation's field at `position`.""" workspace = self._workspace theta = (position - held.z) / held.dz weights = integrated_weights( np.array([1.0, *step.nodes]), theta, check=False, helpers=workspace.helpers, ) value = held.start + _combine(weights, held.slopes, held.dz) # A bin the linear flow changes by more than an e-fold over the step (the # spectral collar's) takes the anchor's linear flow: no polynomial follows its # exponentially growing derivative (as for the Runge-Kutta extension). exponent = workspace.delta_phi( workspace.stage_scalars(held.z, held.z + held.dz) ) value = np.where(np.abs(np.real(exponent)) > 1.0, held.start, value) return workspace.mask(workspace.propagator(held.z, position, hold=True) * value) def _observe_exponential( self, held: _ExponentialStep, step: AcceptedStep, position: float ) -> _State: """Return the exponential formulation's field at `position`. The accepted corrector's interpolant integrated exactly against the flow to the fraction ``xi`` of the step (SEP 16 section 4.3): ``exp(xi x) u_n + h sum_k k! xi**(k+1) phi_{k+1}(xi x) sum_j c_jk F_j``; under a carrier frame the samples rotated by the step's rotations, ``G_j``, the moments at ``xi (x - sigma)`` and the factor ``exp(-sigma (1 - xi))``, with the accepted step's ``sigma`` (SEP 35 section 4.1). Every factor is a forward flow, so a strongly damped bin needs no guard; no source is evaluated and nothing enters the history. """ # One evaluation per plane: the reference passes serve every backend. helpers = self._workspace.helpers kernels = ExponentialKernels(helpers=helpers) xi = (position - held.z) / held.dz # The accepted step's corrector, over (source, newest, ...), as its trial # formed it. coefficients = lagrange_coefficients( [1.0, *step.nodes], check=False, helpers=helpers ) count = coefficients.shape[1] shift, values = _rotated(step.carrier, held.values) # Under a carrier frame (SEP 35 section 4.1) the accepted step's rotated # samples, integrated against the moments at xi (x - sigma) and carried back # by exp(-sigma (1 - xi)); every factor is bounded for an imaginary sigma. moments = kernels.moments( xi * (held.exponent if shift is None else held.exponent - shift), count ) scaled = moments * np.array([xi ** (k + 1) for k in range(count)]).reshape( (count, *([1] * held.start.ndim)) ) increment = kernels.apply(scaled, coefficients, values, held.dz) if shift is not None: increment = np.exp(-shift * (1.0 - xi)) * increment value = np.exp(xi * held.exponent) * held.start + increment if held.compensation is not None: nodes, terms = held.compensation weights = integrated_weights( np.asarray(nodes), xi, check=False, helpers=helpers ) # e^{(xi - theta_j) x} is a forward flow for every history sample; for # the endpoint sample it is an inverse one, which a bin the step damps by # more than an e-fold would amplify: such a bin takes the anchor's flow, # as the interaction formulation's interpolant does (ADR-039). for weight, node, term in zip(weights, nodes, terms, strict=True): value = ( value + held.dz * weight * np.exp((xi - node) * held.exponent) * term ) damped = np.real(held.exponent) < -1.0 value = np.where(damped, np.exp(xi * held.exponent) * held.start, value) return self._workspace.mask(value)
def _rotated( carrier: np.ndarray, values: list[_State] ) -> tuple[np.ndarray | None, list[_State]]: """Return a step's carrier shift and its samples, rotated by its rotations. - ``carrier``: :meth:`~solprop.backends.engines.AdamsEngine.step_carrier`'s packing -- the shift's imaginary part, then each history row's rotation as its real and imaginary parts -- or empty without a carrier frame. - ``values``: the new sample, then the history rows the step read, newest first. - Returns: the shift, purely imaginary and shape ``(1, 1, 1)`` as the trial formed it, or ``None``; the new sample unrotated and each history row times its factor. """ if carrier.size == 0: return None, values # As `CarrierReference.shift` forms it, so that it is the trial's own bits. shift = 1j * np.array(carrier[0]).reshape((1, 1, 1)) factors = [ np.array(complex(carrier[1 + 2 * row], carrier[2 + 2 * row])).reshape((1, 1, 1)) for row in range(len(values) - 1) ] return shift, [ values[0], *(factor * value for factor, value in zip(factors, values[1:], strict=True)), ]