solprop.backends.numpy_ref.multistep#

The reference’s Adams engine: the history and its trials (SEP 13, SEP 14, SEP 16).

One accepted step of the PEC method costs one expensive source evaluation, against DOPRI5’s seven (six with first-same-as-last, which the reference does not take). The engine keeps a short history of source samples and decides each step on a local-defect estimate formed from that history without another evaluation (SEP 13 sections 4.1–4.3); a trial touches no row, so a rejection leaves the history as it was. HostHistory is the engine the march (solprop.backends.numpy_ref.marches.adams.HostAdamsMarch) drives, with its two formulations: InteractionHistory keeps transported sources, re-anchored at every accepted step by the step’s propagator, and ExponentialHistory keeps untransported ones and integrates them exactly against the step’s flow, with a coupled flow’s frozen block, a varying operator’s compensation and the carrier frame (SEP 35). AdamsRows is where the rows live, which the session exports and installs. The field arithmetic is adams_kernels’, the coefficients adams_tables’.

Classes

AdamsRows(n_slots, compensated, *[, name])

The Adams history's rows, where the state lives (SEP 52 section 5.2).

DenseStep(z, dz, start, slopes)

The last accepted step, in its anchor's frame, for dense observation.

ExponentialHistory(workspace, method, ...[, ...])

The exponential formulation's history (SEP 16, SEP 35).

ExponentialStep(z, dz, start, exponent, values)

The last accepted exponential step, for dense observation.

HostHistory(workspace, method, *, compensated)

The Adams history and its field arithmetic, on host arrays (SEP 16 phase 3b).

InteractionHistory(workspace, method, *[, ...])

The interaction formulation's history (SEP 13, SEP 14).

class solprop.backends.numpy_ref.multistep.AdamsRows(n_slots, compensated, *, name='numpy_ref')[source]#

Bases: object

The Adams history’s rows, where the state lives (SEP 52 section 5.2).

The samples a march’s entries name, and for a compensated history each sample’s state, rate and frozen-residual weights: what the engine (HostHistory) writes at a startup and an accepted step, and what the session exports into a snapshot and installs from one, as native’s session reads its resident rows.

Parameters:
n_slotsint

The rows: the method’s order and two more.

compensatedbool

Whether each sample’s state, rate and weights are kept too.

namestr, optional

The backend’s name, for messages.

Attributes:
n_slotsint

As given.

compensatedbool

As given.

namestr

As given.

storenumpy.ndarray or None

The samples, shape (n_slots, n_modes, n_pol, n_omega); None before the first startup.

states, ratesnumpy.ndarray or None

A compensated history’s per-sample states and rates, shaped as store.

weightslist

A frozen-residual flow’s weights per sample, None where a sample has none.

export()[source]#

Return copies of the rows a resume needs to continue the history.

Returns:
dict

"store", the samples; for a compensated march also "states" and "rates", and "weights_<row>" for each row a frozen-residual flow weights.

install(rows, shape)[source]#

Install rows export() returned, for a state of shape.

Parameters:
rowscollections.abc.Mapping

The rows, by name.

shapetuple of int

The state’s shape.

Raises:
BackendError

If a row is missing, does not have the store’s shape, or is one this history does not keep – the native engine’s applied frozen-residual generators ("applied") among them.

nbytes()[source]#

Return the bytes export() would copy, copying nothing.

Returns:
int

The size of every row.

class solprop.backends.numpy_ref.multistep.DenseStep(z, dz, start, slopes)[source]#

Bases: object

The last accepted step, in its anchor’s frame, for dense observation.

The observation’s weights are the session’s, from the march’s record of the step (solprop.backends.numpy_ref.marches.adams.AcceptedStep).

Attributes:
zfloat

The step’s start, m.

dzfloat

The step, m.

startnumpy.ndarray

The state at its start, (n_modes, n_pol, n_omega).

slopeslist of numpy.ndarray

Its slopes, the new source first, each of the state’s shape.

dz: float#
slopes: list[Complex[ndarray, 'n_modes n_pol n_omega']]#
start: Complex[ndarray, 'n_modes n_pol n_omega']#
z: float#
class solprop.backends.numpy_ref.multistep.ExponentialHistory(workspace, method, compensation, *, interpolate=False, rows=None)[source]#

Bases: HostHistory

The exponential formulation’s history (SEP 16, SEP 35).

The history keeps untransported sources; a trial integrates its interpolants exactly against the step’s flow exp(x), x = Phi(z + h) - Phi(z) (ExponentialKernels), steps a coupled flow’s section against its frozen block, adds a varying operator’s linear compensation of its samples, and under a carrier frame rotates the samples it reads.

Parameters:
workspacesolprop.backends.numpy_ref.workspace.NumpyWorkspace

The workspace whose state, source evaluation and propagators are used.

methodsolprop.stepper.multistep.Multistep

The method.

compensation{‘transported’, ‘untransported’}

A varying operator’s compensation treatment (SEP 16 Q8); the untransported one is a test witness.

interpolatebool, optional

Whether an accepted step keeps its interpolant for dense observation.

rowsAdamsRows or None, optional

The rows to write; new ones by default.

Attributes:
compensatedbool

Whether a varying operator’s linear compensation is integrated.

class solprop.backends.numpy_ref.multistep.ExponentialStep(z, dz, start, exponent, values, compensation=None)[source]#

Bases: object

The last accepted exponential step, for dense observation.

The observation’s coefficients and, under a carrier frame, its rotations are the session’s, from the march’s record of the step (solprop.backends.numpy_ref.marches.adams.AcceptedStep).

Attributes:
zfloat

The step’s start, m.

dzfloat

The step, m.

startnumpy.ndarray

The state at its start, (n_modes, n_pol, n_omega).

exponentnumpy.ndarray

The step’s chord exponent x = h B_n, of the state’s shape.

valueslist of numpy.ndarray

Its samples as stored, the new one first, each of the state’s shape.

compensationtuple or None

A varying operator’s corrector nodes (1, theta_0, ...) and matching untransported compensations; None without compensation.

compensation: tuple[list[float], list[Complex[ndarray, 'n_modes n_pol n_omega']]] | None = None#
dz: float#
exponent: Complex[ndarray, 'n_modes n_pol n_omega']#
start: Complex[ndarray, 'n_modes n_pol n_omega']#
values: list[Complex[ndarray, 'n_modes n_pol n_omega']]#
z: float#
class solprop.backends.numpy_ref.multistep.HostHistory(workspace, method, *, compensated, interpolate=False, rows=None)[source]#

Bases: object

The Adams history and its field arithmetic, on host arrays (SEP 16 phase 3b).

The reference’s AdamsEngine (native’s march::Engine, SEP 52 section 5.2). The march (HostAdamsMarch) keeps the controller – the orders, the entries, rejection, restarts, the budget and the ledger – and hands every state-sized operation to this engine over the workspace: the startup sample, a trial’s predictor, source, corrector and defect norms, and the adoption of an accepted step. The engine writes the history’s rows into AdamsRows, which the session exports and installs; between a trial and its acceptance it holds the trial, and an interpolated run’s accepted step keeps what its dense observation reads (dense; solprop.backends.numpy_ref.dense).

This base holds the lifecycle the two formulations share; each formulation is a subclass, InteractionHistory or ExponentialHistory, which forms the startup sample, the trial and the acceptance.

Parameters:
workspacesolprop.backends.numpy_ref.workspace.NumpyWorkspace

The workspace whose state, source evaluation and propagators are used.

methodsolprop.stepper.multistep.Multistep

The method.

compensatedbool

Whether the rows keep each sample’s state, rate and flow weights.

interpolatebool, optional

Whether an accepted step keeps its interpolant for dense observation.

rowsAdamsRows or None, optional

The rows to write; new ones by default.

Attributes:
rowsAdamsRows

The history’s rows.

denseobject

The last accepted step, for dense observation; None before one.

carriersolprop.backends.exponential.CarrierReference or None

The exponential formulation’s carrier frame; None without one.

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 solprop.backends.engines.HistoryEntry

The history the step keeps, oldest first, which the interaction formulation transports.

Returns:
solprop.backends.engines.AcceptRecord

The finish’s split collar’s sums.

begin_attempt(cost)[source]#

Reserve the attempt’s host-source calls (SEP 49 section 6.2).

Parameters:
costint

The attempt’s logical response calls.

carrier: CarrierReference | None#
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; 0.0 without a carrier frame.

dense: Any#
end_attempt(outcome)[source]#

Release the reservation’s rest and record a decided attempt’s outcome.

Parameters:
outcomesolprop.backends.engines.AttemptOutcome

How the attempt ended; an abandoned one only releases.

property n_slots: int[source]#

The history store’s rows: the method’s order and two more.

reading()[source]#

Return the committed state’s boundary reading.

Returns:
solprop.backends.engines.BoundaryReading

The workspace’s reading.

start(z)[source]#

Evaluate the source at the accepted state, the history’s first sample.

The sample goes to the store’s row zero (the subclass’s _startup).

Parameters:
zfloat

The accepted position, m.

step_carrier(order)[source]#

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

Packed as native’s are: the shift’s imaginary part, then each row’s rotation as its real and imaginary parts.

Parameters:
orderint

The rows the dense observation’s formula reads.

Returns:
numpy.ndarray

The rotations, empty without an active carrier frame.

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

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

The formulation’s own trial (the subclass’s _trial), held for accept().

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.numpy_ref.multistep.InteractionHistory(workspace, method, *, interpolate=False, rows=None)[source]#

Bases: HostHistory

The interaction formulation’s history (SEP 13, SEP 14).

The history keeps transported sources, re-anchored at every accepted step by the step’s own propagator; a trial’s predictor, source and corrector are AdamsKernels’ fused passes.

Parameters:
workspacesolprop.backends.numpy_ref.workspace.NumpyWorkspace

The workspace whose state, source evaluation and propagators are used.

methodsolprop.stepper.multistep.Multistep

The method.

interpolatebool, optional

Whether an accepted step keeps its interpolant for dense observation.

rowsAdamsRows or None, optional

The rows to write; new ones by default.