solprop.backends.engines#

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: RungeKuttaEngine is rk::Engine (native/include/solprop_native/march/rk_march.hpp), which the low-storage step implements too, and AdamsEngine is march::Engine (native/include/solprop_native/march/adams_march.hpp). The reference’s engines are NumpyRungeKutta, the low-storage step HostLowStorage and the Adams history 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 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 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.

Classes

AcceptRecord([stiffness, removed, found])

What an accepted step's finish reports (SEP 52 §5.2).

AdamsEngine(*args, **kwargs)

What an Adams march asks of its engine (march::Engine).

AttemptOutcome(*values)

How an attempt ended, for a host source's reservation (HostOutcome, SEP 49).

BoundaryReading(total, regions[, occupancy])

The boundary monitor's reading of the committed state (monitor_reading).

HistoryEntry(z, identity, row)

One entry of an Adams march's history (march::Entry).

RungeKuttaEngine(*args, **kwargs)

What a Runge-Kutta march asks of its engine (rk::Engine).

class solprop.backends.engines.AcceptRecord(stiffness=nan, removed=0.0, found=None)[source]#

Bases: object

What an accepted step’s finish reports (SEP 52 §5.2).

Equality is by identity (eq=False) because it holds an array.

Attributes:
stiffnessfloat

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.

removedfloat

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.

foundnumpy.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.

found: Float[ndarray, '4'] | None = None#
removed: float = 0.0#
stiffness: float = nan#
class solprop.backends.engines.AdamsEngine(*args, **kwargs)[source]#

Bases: 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 (HistoryEntry) and passes them in.

accept(dz, free, stencil, kept)[source]#

Adopt the held trial; the new sample takes row free.

Parameters:
dzfloat

The accepted step, m.

freeint

The history row the new sample takes.

stencilsolprop.backends.adams_core.Stencil

The trial’s stencil.

keptcollections.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.

begin_attempt(cost)[source]#

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:
costint

The attempt’s logical response calls.

chord_phase(z1, z2)[source]#

Return the carrier chord’s largest phase over [z1, z2].

Parameters:
z1, z2float

The interval, m.

Returns:
float

The phase, rad.

end_attempt(outcome)[source]#

End an attempt: a host source’s outcome.

Parameters:
outcomeAttemptOutcome

How it ended.

reading()[source]#

Return the committed state’s boundary reading.

Returns:
BoundaryReading

The reading.

start(z)[source]#

Evaluate the history’s first sample at the accepted state at z into row 0.

Parameters:
zfloat

The accepted position, m.

step_carrier(order)[source]#

Return the last trial’s carrier rotations over its order newest rows.

Parameters:
orderint

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.

trial(z, dz, stencil)[source]#

Form a trial from z over dz; return its scored orders’ norms.

Parameters:
zfloat

Where the trial starts, m.

dzfloat

The step, m.

stencilsolprop.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.

class solprop.backends.engines.AttemptOutcome(*values)[source]#

Bases: IntEnum

How an attempt ended, for a host source’s reservation (HostOutcome, SEP 49).

Attributes:
REJECTEDint

The trial was rejected.

ACCEPTEDint

The trial was accepted and committed.

ABANDONEDint

The attempt ended without a decision: a failure or a stop.

ABANDONED = 2#
ACCEPTED = 1#
REJECTED = 0#
class solprop.backends.engines.BoundaryReading(total, regions, occupancy=None)[source]#

Bases: object

The boundary monitor’s reading of the committed state (monitor_reading).

The state’s own sums (solprop.monitor.BoundaryEnergies, less the split collar’s sums, which travel in each step’s AcceptRecord). Equality is by identity (eq=False) because it holds arrays.

Attributes:
totalfloat

The state’s energy, sum_t P(t), in the proxy’s units of energy.

regionsnumpy.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.

occupancynumpy.ndarray or None

The state’s energy per walk-off bucket of the split collar’s crossing limit; None without one.

occupancy: Float[ndarray, 'n_buckets'] | None = None#
regions: Float[ndarray, '4']#
total: float#
class solprop.backends.engines.HistoryEntry(z, identity, row)[source]#

Bases: object

One entry of an Adams march’s history (march::Entry).

Attributes:
zfloat

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.

rowint

The engine’s history row that holds it.

identity: Literal['accepted', 'predicted']#
row: int#
z: float#
class solprop.backends.engines.RungeKuttaEngine(*args, **kwargs)[source]#

Bases: 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.

accept(dz)[source]#

Adopt the trial: promote its recycled stage, then finish and commit it.

Parameters:
dzfloat

The accepted step, m.

Returns:
AcceptRecord

The finish’s stiffness diagnostic and split collar’s sums.

extend(z, dz)[source]#

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:
zfloat

Where the trial started, m.

dzfloat

The step, m.

property in_flight: bool[source]#

Whether a step that overwrites the state in place was left partway.

reading()[source]#

Return the committed state’s boundary reading.

Returns:
BoundaryReading

The reading.

trial(z, dz)[source]#

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:
zfloat

Where the trial starts, m.

dzfloat

The step, m, positive.

Returns:
float

The scaled error norm.