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 oftrialuntilacceptreturns,in_flightis 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 itsAcceptRecord(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_attemptandend_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
|
What an accepted step's finish reports (SEP 52 §5.2). |
|
What an Adams march asks of its engine ( |
|
How an attempt ended, for a host source's reservation ( |
|
The boundary monitor's reading of the committed state ( |
|
One entry of an Adams march's history ( |
|
What a Runge-Kutta march asks of its engine ( |
- class solprop.backends.engines.AcceptRecord(stiffness=nan, removed=0.0, found=None)[source]#
Bases:
objectWhat 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;Noneunder the in-stage scheme or without a collar.
- class solprop.backends.engines.AdamsEngine(*args, **kwargs)[source]#
Bases:
ProtocolWhat 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:
IntEnumHow 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:
objectThe 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’sAcceptRecord). 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;
Nonewithout one.
- regions: Float[ndarray, '4']#
- class solprop.backends.engines.HistoryEntry(z, identity, row)[source]#
Bases:
objectOne 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.
- class solprop.backends.engines.RungeKuttaEngine(*args, **kwargs)[source]#
Bases:
ProtocolWhat 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.