Source code for solprop.backends.host.adams

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

"""The reference's Adams march (SEP 13, SEP 14, SEP 39, SEP 52).

The controller, history, ledger and lifecycle of :class:`HostAdamsMarch`, over the
engine protocol (:class:`solprop.backends.engines.AdamsEngine`) that native's
``march::Engine`` mirrors: the reference's engine is
:class:`solprop.backends.numpy_ref.multistep.HostHistory`. The march holds its own
state -- position, proposal, replay cursor and accepted norms
(:class:`~solprop.backends.host.marches.MarchState`), the history's entries, the order,
the rejections and the call ledger -- and asks its session only through
:class:`~solprop.backends.host.marches.MarchHost`. The decisions are
:mod:`solprop.backends.adams_core`'s functions of one policy record.

The method, its lifecycle and its numbers are those of
:mod:`solprop.backends.numpy_ref.multistep`'s module documentation.
"""

import math
from collections import deque
from collections.abc import Callable, Iterator, Mapping
from contextlib import contextmanager
from dataclasses import dataclass
from typing import Any, cast

import numpy as np

from solprop._interrupts import committing
from solprop.backends import adams_core
from solprop.backends.engines import AdamsEngine, AttemptOutcome, HistoryEntry
from solprop.backends.host.marches import MarchHost, MarchState
from solprop.backends.ledger import CallLedger
from solprop.exceptions import BackendError, ConvergenceError, ResponseBudgetError
from solprop.output.records import MarchSnapshot
from solprop.stepper.controller import limit_step
from solprop.stepper.multistep import MarchPolicy, Multistep
from solprop.stepper.schedule import FixedSchedule, landing, reached, replay_tolerance

__all__ = ["AcceptedStep", "HostAdamsMarch"]


[docs] @dataclass(frozen=True, eq=False) class AcceptedStep: """The last accepted step, as the session's dense observation reads it. The counterpart of a native march call's ``step_z``, ``step_dz``, ``step_order``, ``step_nodes`` and ``step_carrier``. Equality is by identity (``eq=False``) because it holds an array. Attributes ---------- z : float Where the step started, m. dz : float Its length, m. order : int Its order. nodes : tuple of float The history's normalised positions it read, newest first, ``order`` of them. carrier : numpy.ndarray Its trial's carrier rotations (:meth:`~solprop.backends.engines.AdamsEngine.step_carrier`); empty without a carrier frame. """ z: float dz: float order: int nodes: tuple[float, ...] carrier: np.ndarray
[docs] class HostAdamsMarch: """March a state with an Adams method over an engine. Parameters ---------- engine : solprop.backends.engines.AdamsEngine The engine that holds the history's rows. method : solprop.stepper.multistep.Multistep The method. host : solprop.backends.host.marches.MarchHost The session the march reports to. policy : solprop.stepper.multistep.MarchPolicy Every number the controller and the landings read (SEP 39 section 4.2). field : callable Returns the committed state, for a budget's error. schedule : solprop.stepper.schedule.FixedSchedule or None, optional The schedule to replay, or ``None`` to step adaptively. interpolate : bool, optional Whether the run interpolates its planes (ADR-036, ADR-039): each accepted step's record is then kept for the session's dense observation (:attr:`last_step`). shape : tuple of int, optional The state's shape, which a snapshot's is checked against. proposal : float, optional The first proposal, m. lag : int, optional The lag of the controller whose norms a 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. ledger : solprop.backends.ledger.CallLedger The run's call counts. last_step : AcceptedStep or None The last accepted step of an interpolated run; ``None`` before one, and always without interpolation. Raises ------ solprop.exceptions.BackendError If `engine` lacks a member the march calls. """ def __init__( self, engine: object, method: Multistep, host: object, *, policy: MarchPolicy, field: Callable[[], np.ndarray], schedule: FixedSchedule | None = None, interpolate: bool = False, shape: tuple[int, ...] = (), proposal: float = 0.0, lag: int = 1, name: str = "numpy_ref", ) -> None: """Hold the engine and start with no history.""" _check_engine(engine) self._engine: AdamsEngine = cast("AdamsEngine", engine) self._method = method self._host = cast("MarchHost", host) self._policy = policy self._field = field self._schedule = schedule self._interpolate = interpolate self._shape = shape self._name = name self.state = MarchState(z=0.0, proposal=proposal, norms=deque(maxlen=lag + 2)) self._history: list[HistoryEntry] = [] self._rejections = 0 self._last_rejected = False self._order = 1 if method.variable_order else method.order # The engine's history rows: the method's order and two more. self._n_slots = method.order + 2 self.last_step: AcceptedStep | None = None self.ledger = CallLedger() # Whether the stages left a quiet collar out at the last attempt: the step # after it returns is held to the collar's stable step (`_collar_reentry`). self._collar_was_quiet = False # A floor an attempt's next proposal fell below, raised once the attempt is # recorded (`_propose`, `_reject`, `_raise_floor`). self._floor: ConvergenceError | None = None
[docs] def load(self, z: float, proposal: float, cursor: int) -> None: """Start a run afresh at a loaded position. The history and the held trial are forgotten, and the run's accounting starts afresh -- the ledger, the last rejection and the collar's flag -- so that a backend loaded for another run counts that run's calls alone and chooses its first order and step as a fresh backend would (SEP 22 section 4.7, SEP 39 R9). A resume restores its persisted ledger and flags afterwards. Parameters ---------- z : float The position, m. proposal : float The first proposal, m. cursor : int The replay cursor at `z`. """ self.state.load(z, proposal, cursor) self.ledger = CallLedger() self._last_rejected = False self._collar_was_quiet = False self._floor = None self._history = [] self._rejections = 0 self.last_step = None
[docs] def restore_ledger(self, logical: Mapping[str, object]) -> None: """Continue a resumed run's cumulative call counts. Parameters ---------- logical : collections.abc.Mapping The persisted logical counts (:meth:`solprop.backends.ledger.CallLedger.to_record`). """ self.ledger = CallLedger.from_record(logical)
[docs] def snapshot_fields(self) -> dict[str, Any] | None: """Return the march's part of a snapshot at its accepted position. The session adds the state and the engine's rows (:class:`~solprop.output.records.MarchSnapshot`'s ``state`` and ``rows``). Returns ------- dict or None The snapshot's other fields, or ``None`` with no history to continue. """ if not self._history: return None state = self.state return { "z": float(state.z), "proposal": float(state.proposal), "method": repr(self._method), "order": int(self._order), "rejections": int(self._rejections), "last_rejected": bool(self._last_rejected), "positions": np.array( [entry.z for entry in self._history], dtype=np.float64 ), "identities": tuple(entry.identity for entry in self._history), "slots": np.array([entry.row for entry in self._history], dtype=np.int64), "collar_was_quiet": self._collar_was_quiet, "history_key": self._method.history_key, }
[docs] @property def in_flight(self) -> None: # numpydoc ignore=RT01 """No step in flight: an Adams trial never overwrites the committed state.""" return
[docs] @property def has_history(self) -> bool: # numpydoc ignore=RT01 """Whether the march holds a history a snapshot could continue.""" return bool(self._history)
[docs] def refusal(self, snapshot: MarchSnapshot) -> str | None: """Return why a snapshot cannot continue this march, or ``None``. Parameters ---------- snapshot : solprop.output.records.MarchSnapshot The snapshot, possibly read back from a file. Returns ------- str or None The reason, or ``None`` when it can. """ return self._refusal(snapshot)
[docs] def continue_from(self, snapshot: MarchSnapshot) -> None: """Continue from a snapshot taken where the march now stands. Installs the history, the order, the rejection count, the flags and the proposed step, so that the march goes on as the uninterrupted one would have; the session installs the state and the engine's rows, once :meth:`refusal` found nothing. Parameters ---------- snapshot : solprop.output.records.MarchSnapshot The snapshot. """ self.state.z = snapshot.z self._history = [ HistoryEntry(float(z), cast("Any", identity), int(slot)) for z, identity, slot in zip( snapshot.positions, snapshot.identities, snapshot.slots, strict=True ) ] self._order = snapshot.order self._rejections = snapshot.rejections self._last_rejected = snapshot.last_rejected self._collar_was_quiet = snapshot.collar_was_quiet self.state.proposal = snapshot.proposal
def _refusal(self, snapshot: MarchSnapshot) -> str | None: """Return why a snapshot cannot continue this march, or ``None``.""" z = self.state.z n_slots = self._n_slots checks = ( ( snapshot.history_key != self._method.history_key, f"the snapshot's history was kept by {snapshot.history_key}, and " f"this run steps with {self._method.history_key}", ), ( snapshot.z != z, f"the snapshot is at z = {snapshot.z!r} m and the run resumes at " f"z = {z!r} m", ), ( snapshot.state.shape != tuple(self._shape), f"the snapshot's state has shape {snapshot.state.shape}", ), ( # A landing snaps to its plane, a rounding from the step's z + dz. not math.isclose( float(snapshot.positions[-1]), snapshot.z, rel_tol=1e-12 ), "the snapshot's newest sample is not at its position", ), ( bool(np.any((snapshot.slots < 0) | (snapshot.slots >= n_slots))), "the snapshot's history names no row of this engine", ), ) return next((reason for failed, reason in checks if failed), None) # --- the march --------------------------------------------------------------------
[docs] def advance(self, target: float) -> None: """Step towards `target`: the schedule's replay, or adaptively. Parameters ---------- target : float The position to reach, m. """ self.march_to(target)
[docs] def march_to(self, target: float) -> None: """Step adaptively to `target`, landing on it exactly, or replay towards it. Parameters ---------- target : float Position to reach, m. Raises ------ ConvergenceError If the proposal falls below the contract's ``dz_min``. """ host, state = self._host, self.state if self._schedule is not None: self._replay_to(self._schedule, target) return targets = adams_core.targets(self._policy, target) while not reached(state.z, target): host.poll_stop() with self._attempt_scope() as attempt: if not self._history: self._start() proposal = self._collar_reentry( host.cap(self._capped(state.proposal), state.z) ) stop = landing(state.z, proposal, targets) dz, end, kink = adams_core.approach( self._policy, state.z, stop, targets, target ) # The accepted step moves the position with the state, and restarts # the history at a kink, in one commit (`_land`). accepted, norm = self._attempt(dz, landing=(end, kink)) host.record(end, dz, norm, accepted) self._end(attempt, accepted=accepted) if accepted: host.stepped() if host.natural_stop(target): return
def _replay_to(self, schedule: FixedSchedule, target: float) -> None: """Replay a prescribed schedule's steps to `target` (SEP 16 section 5). The schedule fixes the accepted positions: every step is taken as given and accepted, as the Runge-Kutta replay does (``docs/dev/stepper.md`` section 8), while the predictor-corrector estimate is still computed and recorded, so a schedule too coarse for its tolerance is reported rather than silent. The order is chosen by the same rule as an adaptive run's, from the same estimates. A hard kink, an edge of the schedule, restarts the history as it does in an adaptive run. - ``target``: position to reach, m. """ host, state = self._host, self.state edges = schedule.edges slack = replay_tolerance(schedule, target) 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]) with self._attempt_scope() as attempt: norm = self.replay_step(dz, end, slack) state.cursor += 1 host.record(end, dz, norm, accepted=True) attempt.end(AttemptOutcome.ACCEPTED) state.norms.append(norm) self._raise_floor() 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: the startup of an empty history, the step and, when `end` is a hard kink, the restart. Called inside an attempt, whose reservation the caller opened. 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 kink it lands on, m. Returns ------- float The step's scaled error norm, recorded and not acted on. Raises ------ ConvergenceError If the norm is not finite: the field has diverged, and a replay cannot reject the step. """ if not self._history: self._start() kink = adams_core.replay_kink(self._policy, end, slack) _, norm = self._attempt(dz, fixed=True, landing=(end, kink)) if not math.isfinite(norm): msg = ( f"{self._name}: a replayed {self._method.name} step of " f"{dz:.4g} m ending at z = {end:.6g} m has a non-finite error norm " f"({norm!r}): 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 temporal collar's or a " "coupled flow's advisory step -- grows until it overflows; the " "translation refuses a declared step past the collar's limit and " "warns on one past the flow's. Take shorter steps, or let the " "controller choose them" ) raise ConvergenceError(msg) return norm
def _end(self, attempt: "_Attempt", *, accepted: bool) -> None: """End a recorded attempt with its decision, then raise a floor it fell below. As native's march does (``adams_march.cpp``): an accepted attempt ends first, and a failure there is the run's error, its step committed; a rejected attempt's floor is the run's error, and a failure of its end rides on it as a note (SEP 49 section 6.3, issue #651). """ if accepted: attempt.end(AttemptOutcome.ACCEPTED) self._raise_floor() return error, self._floor = self._floor, None if error is None: attempt.end(AttemptOutcome.REJECTED) return try: attempt.end(AttemptOutcome.REJECTED) except Exception as cleanup: error.add_note(f"releasing the source reservation failed: {cleanup}") raise error @contextmanager def _attempt_scope(self) -> Iterator["_Attempt"]: """Open an attempt with its host-source reservation; end it on every exit. The budget is checked and the reservation made before the attempt's first evaluation (SEP 49 section 6.2). An attempt the body does not end -- a failure, a floor, a diverged replay -- ends abandoned, which only releases what it reserved; that release's own failure is attached to the error as a note, never raised in its place (SEP 49 section 6.3). """ attempt = _Attempt(self._engine) self._afford(attempt) try: yield attempt except BaseException as error: if attempt.open: try: attempt.end(AttemptOutcome.ABANDONED) except Exception as cleanup: error.add_note( f"releasing the source reservation failed: {cleanup}" ) raise def _afford(self, attempt: "_Attempt") -> None: """Refuse a trial the call budget cannot pay for, before any call is made.""" self._raise_floor() budget = self._policy.max_calls cost = (0 if self._history else 1) + 1 spent = self.ledger.total z = self.state.z if budget is not None and spent + cost > budget: msg = ( f"the source-call budget of {budget} is spent ({spent} charged) at " f"z = {z:.6g} m: the next trial needs {cost}; the run stops at its " "last accepted step, unfinished" ) raise ResponseBudgetError(msg, z=z, field=self._field().copy(), calls=spent) try: attempt.begin(cost) except ResponseBudgetError as error: raise ResponseBudgetError( "the TDSE atomic-call budget cannot reserve the next trial " f"at z = {z:.6g} m ({error.calls} charged); " "the run stops at its last accepted step, unfinished", z=z, field=self._field().copy(), calls=error.calls, ) from None def _start(self) -> None: """Evaluate the source at the accepted field to (re)start the history.""" z = self.state.z self.ledger.startup += 1 self._engine.start(z) self._history = [HistoryEntry(z, "accepted", 0)] self._order = 1 if self._policy.variable_order else self._policy.order def _capped(self, proposal: float) -> float: """Return the proposal shortened to the carrier frame's phase cap. Under a carrier frame no step covers more than :data:`~solprop.stepper.multistep.CARRIER_PHASE_CAP` of carrier phase (SEP 35 section 6.4), measured by one chord of the reference element's operator over the proposal (:func:`~solprop.backends.adams_core.carrier_capped`). Applied before the landing rule, so a shortened step is not a landing; a fixed schedule's replay is not capped. - ``proposal``: the controller's proposal, m. """ if not self._policy.carrier: return proposal return adams_core.carrier_capped( self._policy, self.state.z, proposal, self._engine.chord_phase ) def _attempt( self, dz: float, *, fixed: bool = False, landing: tuple[float, bool] | None = None, ) -> tuple[bool, float]: """Try one step of length `dz` and commit it if accepted. - ``fixed``: whether the step is a prescribed schedule's, accepted whatever its norm. - ``landing``: where an accepted step ends, m, and whether that is a hard kink, which restarts the history; ``None`` ends it at ``z + dz`` and restarts nothing. - Returns: whether the step was accepted, and its scaled error norm. """ stencil = adams_core.stencil( self._policy, self.state.z, dz, [entry.z for entry in self._history], [entry.row for entry in self._history], self._order, last_rejected=self._last_rejected, ) self.ledger.predictor += 1 norms = self._engine.trial(self.state.z, dz, stencil) return self._decide(dz, stencil, norms, fixed=fixed, landing=landing) def _decide( self, dz: float, stencil: adams_core.Stencil, norms: np.ndarray, *, fixed: bool, landing: tuple[float, bool] | None = None, ) -> tuple[bool, float]: """Reject a held trial, or accept it and choose the next order and step. The new sample takes the oldest row past the method's need. - ``landing``: where an accepted step ends and whether it is a hard kink (:meth:`_attempt`). - Returns: whether the step was accepted, and its scaled error norm. """ policy, engine, order = self._policy, self._engine, stencil.order norm = float(norms[0]) if not norm <= 1.0 and not (fixed and math.isfinite(norm)): self.ledger.rejected += 1 self._reject(dz, norm, order) if fixed: # A replay records no rejected attempt (`replay_step`): its floor is # raised at once. self._raise_floor() return False, norm z = self.state.z keep = self._history[-policy.order :] if policy.order else [] used = {entry.row for entry in keep} free = next(slot for slot in range(self._n_slots) if slot not in used) with committing(): record = engine.accept(dz, free, stencil, keep) self._host.absorb(record) self._history = [*keep, HistoryEntry(z + dz, "predicted", free)] self.ledger.accepted_steps += 1 self._rejections = 0 self.ledger.orders.append(order) next_order, control = self._choose_order( order, dict(zip(stencil.orders, norms.tolist(), strict=True)), dz ) self._last_rejected = False if self._interpolate: # The step's record for the session's dense observation, its trial's # carrier rotations among it (`adams_march.cpp`'s `step_carrier`). self.last_step = AcceptedStep( z=z, dz=dz, order=order, nodes=tuple(stencil.nodes[:order]), carrier=engine.step_carrier(order), ) self._land(z, dz, landing) self._propose( dz, adams_core.factor( policy, control, next_order, growth=policy.max_growth ), ) return True, norm def _propose(self, dz: float, factor: float) -> None: """Set an accepted step's next proposal, deferring a floor it falls below. Called inside an accepted step's commit, after the position, the history and the order have moved, so that a run stopped by the floor leaves the state of the step it accepted at that step's end (SEP 39 section 4.4). The floor is raised once the march has recorded the step (:meth:`_raise_floor`). """ policy = self._policy try: self.state.proposal = limit_step(dz, factor, policy.dz_min, policy.dz_max) except ConvergenceError as error: self._floor = error def _raise_floor(self) -> None: """Raise the floor an attempt's proposal fell below, once it is recorded. Every caller that records an attempt calls this straight after, and every attempt calls it before it starts (:meth:`_afford`), so a floor is never passed over. """ error, self._floor = self._floor, None if error is not None: raise error def _land(self, z: float, dz: float, landing: tuple[float, bool] | None) -> None: """Move to an accepted step's end, restarting at a kink. Called inside the commit that installed the step's state, so that the state and its position change together whatever interrupts the march afterwards. """ end, kink = (z + dz, False) if landing is None else landing self.state.z = end if kink: self._history = [] self.ledger.restarts += 1 def _collar_reentry(self, proposal: float) -> float: """Return the proposal held to the collar's stable step as its term returns. :func:`~solprop.backends.adams_core.collar_reentry`, recording the collar's flag at this attempt. """ quiet = self._host.collar_quiet capped = adams_core.collar_reentry( self._policy, proposal, self._order, was_quiet=self._collar_was_quiet, quiet=quiet, ) self._collar_was_quiet = quiet return capped def _choose_order( self, current: int, scores: dict[int, float], dz: float ) -> tuple[int, float]: """Store the next order; return the order and norm that set the next step. :func:`~solprop.backends.adams_core.choose_order`. In the exponential formulation each order is weighed by the step its defect allows capped at the step an in-stage collar leaves it stable at: near that limit the higher orders' defects carry the collar's growing mode, and a choice on them alone was decided by rounding -- runs a rounding apart settled in different orders, with calls 40 % apart. The cap weighs the choice only; the step is the chosen order's defect's, as before. """ stored, control, norm = adams_core.choose_order( self._policy, current, scores, dz, quiet=self._host.collar_quiet ) self._order = stored return control, norm def _reject(self, dz: float, norm: float, order: int) -> None: """Shrink the proposal after a rejected step; restart a failing history. :func:`~solprop.backends.adams_core.rejection`: a rejection leaves the accepted history untouched, and after :data:`~solprop.stepper.multistep.RESTART_AFTER` in a row the method restarts at order one from the accepted state, paying one startup call. A proposal below the floor is left as it was, and the floor is raised once the march has recorded the rejected attempt (:meth:`_raise_floor`; issue #651). """ policy = self._policy self.ledger.rejected_steps += 1 self._last_rejected = True outcome = adams_core.rejection( policy, norm, order, rejections=self._rejections, held=len(self._history) ) self._rejections = outcome.rejections if outcome.restart: self._history = [] self.ledger.failure_restarts += 1 try: self.state.proposal = limit_step( dz, outcome.factor, policy.dz_min, policy.dz_max ) except ConvergenceError as error: self._floor = error
class _Attempt: """An attempt's source reservation, ended exactly once (native ``Attempt``).""" def __init__(self, engine: object) -> None: self._engine = cast("AdamsEngine", engine) self.open = False def begin(self, cost: int) -> None: """Reserve the attempt's calls; the attempt is open from here.""" self._engine.begin_attempt(cost) self.open = True def end(self, outcome: AttemptOutcome) -> None: """End with the decision; closed first, so a failure here is not abandoned.""" self.open = False self._engine.end_attempt(outcome) _ENGINE_MEMBERS = ( "start", "trial", "accept", "chord_phase", "step_carrier", "begin_attempt", "end_attempt", "reading", ) """What the march asks of an engine: the protocol.""" def _check_engine(engine: object) -> None: """Refuse an engine that lacks a member the march calls.""" missing = [name for name in _ENGINE_MEMBERS if not hasattr(engine, name)] if missing: msg = f"an Adams engine lacks {', '.join(missing)}" raise BackendError(msg)