# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""The reference's low-storage interaction-picture RK4 march (SEP 24, SEP 52).
:class:`HostLowStorageMarch` replays a prescribed schedule through a
:class:`~solprop.backends.engines.RungeKuttaEngine` with the documented destructive
trial: the reference's is :class:`solprop.backends.low_storage.HostLowStorage`, which
holds the registers and makes the step's four passes. The engine owns the in-flight
flag and the finish; the march owns the committed position, in its own
:class:`~solprop.backends.host.marches.MarchState`, and the count of committed source
evaluations. The method, the register form and the in-flight contract are those of
:mod:`solprop.backends.low_storage`'s module documentation.
"""
import logging
import math
from collections import deque
from typing import cast
from solprop._interrupts import committing
from solprop.backends.engines import RungeKuttaEngine
from solprop.backends.host.marches import MarchHost, MarchState, in_flight_refusal
from solprop.exceptions import BackendError, ConvergenceError
from solprop.stepper.low_storage import LowStorageRungeKutta
from solprop.stepper.schedule import FixedSchedule, replay_tolerance
__all__ = ["HostLowStorageMarch"]
logger = logging.getLogger(__name__)
[docs]
class HostLowStorageMarch:
"""Replay a schedule with the low-storage RK4IP march, accepting in place.
It replays a prescribed schedule, which is the only thing it does (SEP 24 section
6.2). Each step's trial overwrites the state; the accept finishes it (the hard band
mask, and the split-step collar where chosen) and the march moves its position in
the same commit, then records the step through its session.
Parameters
----------
engine : solprop.backends.engines.RungeKuttaEngine
The engine.
method : solprop.stepper.low_storage.LowStorageRungeKutta
The march.
host : solprop.backends.host.marches.MarchHost
The session the march reports to.
schedule : solprop.stepper.schedule.FixedSchedule
The schedule it replays.
proposal : float
The proposal it keeps, m, which a replay never updates.
lag : int, optional
The lag of the controller whose norms the replay keeps.
name : str, optional
The backend's name, for messages.
Attributes
----------
state : solprop.backends.host.marches.MarchState
The march's position, proposal, cursor and accepted norms.
source_evaluations : int
Source evaluations of the committed steps since the state was last loaded,
four a step: a physical count, never a logical response call (SEP 24 section
5). A step that did not commit -- abandoned in flight, or diverged -- adds none.
Notes
-----
The march has no error estimate to warn on. It logs a warning, once per call of
:meth:`replay_to`, when an accepted step's stiffness indicator
(:attr:`~solprop.backends.engines.AcceptRecord.stiffness`) passes RK4's
negative-real stability interval
(:data:`~solprop.stepper.low_storage.LOW_STORAGE_REAL_INTERVAL`): an explicitly
integrated damping term the translation cannot bound in advance -- plasma loss --
is then near the step's stability limit.
"""
def __init__(
self,
engine: object,
method: LowStorageRungeKutta,
host: object,
*,
schedule: FixedSchedule,
proposal: float,
lag: int = 1,
name: str = "numpy_ref",
) -> None:
"""Hold the engine; the march stands at the entrance."""
self._engine = cast("RungeKuttaEngine", engine)
self._method = method
self._host = cast("MarchHost", host)
self._schedule = schedule
self._name = name
self._warned = False
# The step whose trial the engine left in flight, while it is.
self._pending: tuple[float, float] | None = None
self.state = MarchState(z=0.0, proposal=proposal, norms=deque(maxlen=lag + 2))
self.source_evaluations = 0
[docs]
@property
def engine(self) -> object: # numpydoc ignore=RT01
"""Engine that holds the registers."""
return self._engine
[docs]
@property
def in_flight(self) -> tuple[float, float] | None: # numpydoc ignore=RT01
"""The step a failure left in flight, its start and length, m; or ``None``."""
return self._pending if self._engine.in_flight else None
[docs]
def load(self, z: float, proposal: float, cursor: int) -> None:
"""Start afresh at a loaded position; a step left in flight is cleared.
Parameters
----------
z : float
The position, m.
proposal : float
The proposal, m.
cursor : int
The replay cursor at `z`.
"""
self.state.load(z, proposal, cursor)
self._pending = None
# Its count is the loaded run's, as the Adams ledger is (SEP 22 4.7).
self.source_evaluations = 0
[docs]
def refusal(self) -> str | None:
"""Return why the state cannot be read or advanced, or ``None``.
Returns
-------
str or None
The message of a step left in flight, or ``None``.
"""
pending = self.in_flight
return None if pending is None else in_flight_refusal(self._name, *pending)
[docs]
def advance(self, target: float) -> None:
"""Replay the schedule towards `target`.
Parameters
----------
target : float
The position to reach, m.
"""
self.replay_to(self._schedule, target)
[docs]
def replay_to(self, schedule: FixedSchedule, target: float) -> None:
"""Replay the schedule's steps to `target`, mirroring the Adams replay.
Parameters
----------
schedule : solprop.stepper.schedule.FixedSchedule
The schedule to replay.
target : float
Position to reach, m.
Raises
------
BackendError
If the schedule runs out before the target is reached.
"""
host, state = self._host, self.state
edges = schedule.edges
slack = replay_tolerance(schedule, target)
self._warned = False
while state.cursor < schedule.n_steps and state.z < target - slack:
host.poll_stop()
dz = float(schedule.steps[state.cursor])
end = float(edges[state.cursor + 1])
norm = self.replay_step(dz, end, slack)
state.cursor += 1
host.record(end, dz, norm, accepted=True)
state.norms.append(norm)
host.stepped()
if host.natural_stop(target):
return
if state.z < target - slack:
msg = (
f"the replayed schedule ends at {float(schedule.z_end):.6g} m and "
f"cannot reach z = {target:.6g} m"
)
raise BackendError(msg)
[docs]
def replay_step(self, dz: float, end: float, slack: float) -> float:
"""Take one prescribed step from the march's position and accept it.
The unit a replay advances by, with
:meth:`solprop.backends.host.adams.HostAdamsMarch.replay_step`'s signature.
Parameters
----------
dz : float
The step, m.
end : float
The schedule's edge it ends on, m.
slack : float
How far an edge may sit from a target it lands on, m; unused, since the
march restarts nothing at a kink.
Returns
-------
float
The norm the history records: 0.0, "not estimated".
Raises
------
BackendError
If an earlier step was abandoned in flight.
ConvergenceError
If the accepted state is not finite: the field has diverged, and a replay
cannot reject the step. Raised in flight, so the state is lost with it.
"""
del slack
refusal = self.refusal()
if refusal is not None:
raise BackendError(refusal)
state = self.state
z = state.z
self._pending = (z, dz)
# The host passes are Python calls a signal may interrupt (the engine is not
# atomic): an interrupted step stays in flight, and only the move commits.
squared = self._engine.trial(z, dz)
if not math.isfinite(squared):
msg = (
f"{self._name}: a replayed {self._method.name} step of {dz:.4g} m "
f"from z = {z:.6g} m ended in a non-finite state: the field has "
"diverged. A replayed schedule takes its steps as given and cannot "
"reject one, so a step beyond an explicit stability limit -- the "
"in-stage collars' -- grows until it overflows; the translation "
"refuses a declared step past the collars' limit. The state was "
"accepted in place and is lost; take shorter steps"
)
raise ConvergenceError(msg)
with committing():
record = self._engine.accept(dz)
state.z = end
self._pending = None
self.source_evaluations += self._method.evaluations
self._host.absorb(record)
self._check_stiffness(z, dz, record.stiffness)
return 0.0
def _check_stiffness(self, z: float, dz: float, stiffness: float) -> None:
"""Warn, once per replay, when a step's stiffness passes RK4's interval.
- ``z``: where the step started, m.
- ``dz``: the step, m.
"""
interval = self._method.real_stability_interval
if self._warned or not stiffness > interval:
return
self._warned = True
logger.warning(
"%s: the %s march's stiffness indicator h rho = %.3g passed RK4's "
"stability interval %.4g on the step of %.4g m from z = %.6g m; an "
"explicitly integrated damping term (plasma loss, an in-stage collar) is "
"near the step's stability limit and may make the replay diverge. Take "
"shorter steps",
self._name,
self._method.name,
stiffness,
interval,
dz,
z,
)