# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""The engine protocols: what a march asks of the state it advances (SEP 52 §5.2).
A march owns its controller, landing, history and call ledger; an engine does every
state-sized operation a march asks of the workspace that holds the state. The two
protocols here mirror the native marches' C++ interfaces one-to-one, every argument
included: :class:`RungeKuttaEngine` is ``rk::Engine``
(``native/include/solprop_native/march/rk_march.hpp``), which the low-storage step
implements too, and :class:`AdamsEngine` is ``march::Engine``
(``native/include/solprop_native/march/adams_march.hpp``). The reference's engines are
:class:`~solprop.backends.numpy_ref.engines.NumpyRungeKutta`, the low-storage step
:class:`~solprop.backends.low_storage.HostLowStorage` and the Adams history
:class:`~solprop.backends.numpy_ref.multistep.HostHistory`.
**The commit contract.**
- **The Runge-Kutta trial** keeps its stages and end state in the workspace. It commits
nothing until ``accept``, and a rejected trial leaves the committed state as it was.
- **The low-storage step is the same engine, with one documented difference.** Its
trial overwrites the state, the register ``A``. From the start of ``trial`` until
``accept`` returns, ``in_flight`` is true. An exception or a non-finite result in that
interval leaves no committed state at that position, so the session ends the run
failed with no checkpoint there. The engine owns the in-flight flag and the finish;
the march owns the committed position. The stiffness diagnostic is the engine's, a
field of its :class:`AcceptRecord` (NaN where the engine does not form it). The march
reads it from there, and the session reads the march's state, never a private field.
- **The Adams accept** receives the retained history entries, oldest first, which the
interaction formulation's transport uses.
- **step_carrier** returns the last trial's carrier rotations. The march stores them in
the accepted step's record, and the session's dense observation applies them to the
interpolation weights.
- **The dense hold, the dense observation and the snapshot rows** are the session's; no
engine holds, restores or observes.
- **The TDSE reservation and the trial's outcome** are the engine's, as
``begin_attempt`` and ``end_attempt``.
- **The split collar's sums.** An accepted step's finish computes them in the
workspace, from the masked field before the split, and returns them in its
:class:`AcceptRecord`; the session accumulates and drains them. The removal adds over
every accepted step since the previous check, and the next boundary reading drains
it; the found occupancies are those of the latest accepted step; a rejected trial, a
dense observation and a probe trial contribute nothing, because none of them finishes
a step; loading a state empties the accumulator, and attaching a monitor, at a launch
or a resume, starts it from zero.
A march holds its own state and touches no other object's fields.
"""
import enum
import math
from collections.abc import Sequence
from dataclasses import dataclass
from typing import Literal, Protocol
import numpy as np
from jaxtyping import Float
from solprop.backends.adams_core import Stencil
__all__ = [
"AcceptRecord",
"AdamsEngine",
"AttemptOutcome",
"BoundaryReading",
"HistoryEntry",
"RungeKuttaEngine",
]
[docs]
class AttemptOutcome(enum.IntEnum):
"""How an attempt ended, for a host source's reservation (``HostOutcome``, SEP 49).
Attributes
----------
REJECTED : int
The trial was rejected.
ACCEPTED : int
The trial was accepted and committed.
ABANDONED : int
The attempt ended without a decision: a failure or a stop.
"""
REJECTED = 0
ACCEPTED = 1
ABANDONED = 2
[docs]
@dataclass(frozen=True)
class HistoryEntry:
"""One entry of an Adams march's history (``march::Entry``).
Attributes
----------
z : float
Where its sample was evaluated, m.
identity : {"accepted", "predicted"}
Whether the sample is the accepted state's, or the predicted state's that PEC
stores in its place.
row : int
The engine's history row that holds it.
"""
z: float
identity: Literal["accepted", "predicted"]
row: int
[docs]
@dataclass(frozen=True, eq=False)
class BoundaryReading:
"""The boundary monitor's reading of the committed state (``monitor_reading``).
The state's own sums (:class:`solprop.monitor.BoundaryEnergies`, less the split
collar's sums, which travel in each step's :class:`AcceptRecord`). Equality is by
identity (``eq=False``) because it holds arrays.
Attributes
----------
total : float
The state's energy, ``sum_t P(t)``, in the proxy's units of energy.
regions : numpy.ndarray
Shape ``(4,)``: the low guard's, the high guard's and the collar's weighted
energies, and the collar's removal rate, energy per metre.
occupancy : numpy.ndarray or None
The state's energy per walk-off bucket of the split collar's crossing limit;
``None`` without one.
"""
total: float
regions: Float[np.ndarray, " 4"]
occupancy: Float[np.ndarray, " n_buckets"] | None = None
[docs]
@dataclass(frozen=True, eq=False)
class AcceptRecord:
"""What an accepted step's finish reports (SEP 52 §5.2).
Equality is by identity (``eq=False``) because it holds an array.
Attributes
----------
stiffness : float
The low-storage step's stiffness indicator ``h rho``, dimensionless (SEP 24
section 6.3); NaN where the engine does not form it, on every other engine and
on the native low-storage engine.
removed : float
What the split temporal collar took at this step, from the masked field before
the split, in the proxy's units of energy; 0.0 under the in-stage scheme or
without a collar.
found : numpy.ndarray or None
Shape ``(4,)``: the energy and the first three weighted energies of the power
the step's split found, taken halfway through its factor; ``None`` under the
in-stage scheme or without a collar.
"""
stiffness: float = math.nan
removed: float = 0.0
found: Float[np.ndarray, " 4"] | None = None
[docs]
class RungeKuttaEngine(Protocol):
"""What a Runge-Kutta march asks of its engine (``rk::Engine``).
The embedded Runge-Kutta trial and, with the documented difference of the module's
commit contract, the low-storage step.
"""
[docs]
def trial(self, z: float, dz: float) -> float:
"""Form a trial from `z` over `dz`; return its scaled error norm.
The low-storage step overwrites the state, and returns 0.0 ("not estimated"),
or a non-finite value when the field diverged.
Parameters
----------
z : float
Where the trial starts, m.
dz : float
The step, m, positive.
Returns
-------
float
The scaled error norm.
"""
...
[docs]
def accept(self, dz: float) -> AcceptRecord:
"""Adopt the trial: promote its recycled stage, then finish and commit it.
Parameters
----------
dz : float
The accepted step, m.
Returns
-------
AcceptRecord
The finish's stiffness diagnostic and split collar's sums.
"""
...
[docs]
def extend(self, z: float, dz: float) -> None:
"""Hold the accepted trial from `z` over `dz` as a dense extension.
Called before the trial is adopted, for the session's dense observation.
Parameters
----------
z : float
Where the trial started, m.
dz : float
The step, m.
"""
...
[docs]
def reading(self) -> BoundaryReading:
"""Return the committed state's boundary reading.
Returns
-------
BoundaryReading
The reading.
"""
...
[docs]
@property
def in_flight(self) -> bool: # numpydoc ignore=RT01
"""Whether a step that overwrites the state in place was left partway."""
...
[docs]
class AdamsEngine(Protocol):
"""What an Adams march asks of its engine (``march::Engine``).
The engine keeps the history's rows where the state lives; the march keeps the
entries (:class:`HistoryEntry`) and passes them in.
"""
[docs]
def start(self, z: float) -> None:
"""Evaluate the history's first sample at the accepted state at `z` into row 0.
Parameters
----------
z : float
The accepted position, m.
"""
...
[docs]
def trial(
self, z: float, dz: float, stencil: Stencil
) -> Float[np.ndarray, " n_orders"]:
"""Form a trial from `z` over `dz`; return its scored orders' norms.
Parameters
----------
z : float
Where the trial starts, m.
dz : float
The step, m.
stencil : solprop.backends.adams_core.Stencil
The history's nodes and rows, newest first, and the orders scored.
Returns
-------
numpy.ndarray
One scaled norm per scored order, the step's own first.
"""
...
[docs]
def accept(
self, dz: float, free: int, stencil: Stencil, kept: Sequence[HistoryEntry]
) -> AcceptRecord:
"""Adopt the held trial; the new sample takes row `free`.
Parameters
----------
dz : float
The accepted step, m.
free : int
The history row the new sample takes.
stencil : solprop.backends.adams_core.Stencil
The trial's stencil.
kept : collections.abc.Sequence of HistoryEntry
The history the step keeps, oldest first, which the interaction
formulation transports.
Returns
-------
AcceptRecord
The finish's split collar's sums.
"""
...
[docs]
def chord_phase(self, z1: float, z2: float) -> float:
"""Return the carrier chord's largest phase over ``[z1, z2]``.
Parameters
----------
z1, z2 : float
The interval, m.
Returns
-------
float
The phase, rad.
"""
...
[docs]
def step_carrier(self, order: int) -> Float[np.ndarray, " n_rotations"]:
"""Return the last trial's carrier rotations over its `order` newest rows.
Parameters
----------
order : int
The rows the dense observation's formula reads.
Returns
-------
numpy.ndarray
The shift's imaginary part, then each row's rotation as its real and
imaginary parts; empty without a carrier frame.
"""
...
[docs]
def begin_attempt(self, cost: int) -> None:
"""Start an attempt: a host source's reservation (SEP 49 section 6.2).
Called after the budget check and before the attempt's first evaluation.
Parameters
----------
cost : int
The attempt's logical response calls.
"""
...
[docs]
def end_attempt(self, outcome: AttemptOutcome) -> None:
"""End an attempt: a host source's outcome.
Parameters
----------
outcome : AttemptOutcome
How it ended.
"""
...
[docs]
def reading(self) -> BoundaryReading:
"""Return the committed state's boundary reading.
Returns
-------
BoundaryReading
The reading.
"""
...