solprop.backends.numpy_ref.multistep#

The reference’s interaction-picture Adams march (SEP 13, SEP 14).

One accepted step of the PEC method costs one expensive source evaluation, against seven for the reference backend’s IP-DOPRI5. The march keeps a short history of transported derivatives, re-anchored at every accepted step, and decides each step on a local-defect estimate formed from that history without another evaluation (SEP 13 sections 4.1–4.3).

The interaction picture is anchored at the start of each step, z_n. With U(z_2, z_1) = exp(Phi(z_2) - Phi(z_1)), the variable v(z) = U(z_n, z) a(z) obeys v' = g(z) = U(z_n, z) N(U(z, z_n) v, z). A history derivative is stored in the current anchor’s frame; accepting a step re-anchors every one of them by the step’s own propagator, which is the multiplication the Runge-Kutta march already performs on its state, so no table is queried backwards. Every derivative keeps its position and the identity of the field it was evaluated at – the accepted field, or the predicted one PEC stores in its place.

The march is shared by its two copies: a backend supplies two hooks of the step driver, _adams_source (one source evaluation at a lab-frame field, returned in the step’s anchor frame) and _adams_propagator, and the driver’s own state, landing and recording do the rest. numpy_ref evaluates through its reference passes (SEP 14 phase 2).

Lifecycle, owned here and not by the shared driver’s Runge-Kutta march (SEP 13 section 6.1):

a trial computes its predictor, its single source call and its estimate without touching the history; only an accepted step commits, so a rejection leaves the accepted history exactly as it was;
a hard kink is landed on and the history restarted on its far side; a save plane is a pure observation and keeps the history;
a load or a resume starts afresh, at order one, and its startup calls are counted.

Who marches. The NumPy reference marches with solprop.backends.host.adams.HostAdamsMarch; the native backend’s session marches natively from one policy record (SEP 39, SEP 47). This module holds the reference’s kernels, its host engine HostHistory and the tables; the call ledger both backends keep is solprop.backends.ledger.

Functions

`compensation_tables`(nodes, order, orders, *, ...)	Return a trial's transported-compensation tables, for a resident engine.
`coupled_moments`(exponent, count, block, dz, *)	Return a coupled trial's flow and moments `k! phi_{k+1}(h B)`, `k < count`.
`exponential_tables`(nodes, order, orders, *, ...)	Return an exponential trial's coefficient tables, for a resident engine.
`factored_defect_rows`(nodes, orders, width)	Return each exponential defect factored: a divided difference and a polynomial.
`fused_tables`(nodes, order, orders, *, helpers)	Return a fused trial's coefficient tables, for an engine that applies them.
`trial_tables`(nodes, order, orders, *, ...)	Return all of an exponential trial's coefficient tables, for a resident engine.

Classes

`AdamsEngine`(args, *kwargs)	What an Adams march asks of the engine that holds its history (SEP 16).
`AdamsKernels`(*[, helpers])	The field arithmetic of a fused Adams step, in NumPy (SEP 14 phase 2).
`CoupledBlock`(active, vectors, triangular, ...)	A step's frozen coupled block on the bins that carry one (SEP 16 phase 5).
`CoupledExponentialKernels`(*[, helpers])	The reference passes beside a coupled flow (SEP 16 phase 5).
`ExponentialKernels`(*[, helpers])	The field arithmetic of an exponential Adams step, in NumPy (SEP 16 phase 2).
`HostHistory`(backend, method, kernels, ...)	The Adams history and its field arithmetic, on host arrays (SEP 16 phase 3b).

class solprop.backends.numpy_ref.multistep.AdamsEngine(*args, **kwargs)[source]#

Bases: Protocol

What an Adams march asks of the engine that holds its history (SEP 16).

The march keeps the controller; an engine keeps the history’s rows and does every state-sized operation, so that a backend can keep them where its state lives. HostHistory is the reference; docs/dev/stepper.md states the contract.

carrier: CarrierReference | None#: The run’s carrier frame (SEP 35), or None when off; an exponential trial removes its phase from the samples it reads.

compensated: bool#: Whether trials carry a varying operator’s linear compensation (SEP 16 4.2).

dense: Any#: The interaction formulation’s last accepted step (a _DenseStep or None), for observation.

exponential_accept(keep, free, *, interpolate)[source]#

Adopt the held exponential trial.

Parameters:

keepnumpy.ndarray: The history rows kept, int64.
freeint: The row the new sample takes.
interpolatebool: Whether the step’s interpolant is kept for dense observation.

exponential_trial(z, dz, nodes, slots, order, orders)[source]#

Form an exponential trial; return its scored norms.

Parameters:

z, dzfloat: The anchor and the step, m.
nodeslist of float: The history’s normalised positions, newest first.
slotsnumpy.ndarray: Their store rows, int64.
orderint: The step’s order.
orderslist of int: The orders scored, the step’s own first.

Returns:

numpy.ndarray: One scaled norm per scored order.

fused_accept(keep, free, *, interpolate)[source]#

Adopt the held interaction-formulation trial.

Parameters:

keepnumpy.ndarray: The history rows kept, int64.
freeint: The row the new sample takes.
interpolatebool: Whether the step’s interpolant is kept for dense observation.

fused_trial(z, dz, nodes, slots, order, orders)[source]#

Form an interaction-formulation trial; return its scored norms.

Parameters:

z, dzfloat: The anchor and the step, m.
nodeslist of float: The history’s normalised positions, newest first.
slotsnumpy.ndarray: Their store rows, int64.
orderint: The step’s order.
orderslist of int: The orders scored, the step’s own first.

Returns:

numpy.ndarray: One scaled norm per scored order.

hold()[source]#

Return the accepted state, to restore after a dense observation.

Returns:

object: A handle restore() takes.

load_rows(rows, shape)[source]#

Install rows snapshot_rows() returned, refusing rows it does not keep.

Parameters:

rowscollections.abc.Mapping: The rows, by name.
shapetuple of int: The state’s shape.

Raises:

BackendError: If the rows are another engine’s, missing, or of the wrong shape; nothing is installed then.

property n_slots: int[source]#: The history store’s rows.

observe(position)[source]#

Return the masked field at position inside the last accepted step.

Parameters:

positionfloat: The observation, m.

Returns:

object: The field, as the backend holds a state.

reset()[source]#

Forget the last accepted step and any trial in flight.

restore(z, held)[source]#

Make a held accepted state current again at z.

Parameters:

zfloat: Its position, m.
heldobject: What hold() returned.

snapshot_nbytes()[source]#

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

Returns:

int: The size of every row.

snapshot_rows()[source]#

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

Returns:

dict: The rows by name, each (n_slots, *shape), in the engine’s own names (HostHistory.snapshot_rows states the host engine’s).

start(z)[source]#

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

Parameters:

zfloat: The accepted position, m.

Returns:

numpy.ndarray or None: The sample on the host, or None when the rows are resident.

value(slot)[source]#

Return a store row on the host, or None when the rows are resident.

Parameters:

slotint: The row.

Returns:

numpy.ndarray or None: The row, or None.

class solprop.backends.numpy_ref.multistep.AdamsKernels(*, helpers=Helpers(name='plain'))[source]#

Bases: object

The field arithmetic of a fused Adams step, in NumPy (SEP 14 phase 2).

Three passes serve a step of the one-order-higher PEC family: the predictor’s lab-frame field, the corrected field with the defects of the current and the neighbouring orders, and the history’s transport to the new anchor. The history is a store of rows, newest first by slots. This is the reference a compiled form is checked against.

Parameters:

helperssolprop._helpers.Helpers, optional: The owning backend’s implementation of the Adams basis (SEP 29 section 6.6); the plain Python forms by default.

correct(state, propagator, source, store, slots, corrector, rows, dz, mask, divisor)[source]#

Return the corrected lab-frame field and the scaled norms of the defects.

With X = (source, store[slots[0]], ...), the field is U (a_n + dz sum_t c_t X_t) and each norm is the weak norm of U dz sum_t rows[r, t] X_t over the in-band bins.

Parameters:

state, propagatornumpy.ndarray: As for predict().
sourcenumpy.ndarray: The source at the predicted field, in the anchor’s frame.
storenumpy.ndarray: The history rows.
slotsnumpy.ndarray: The rows after the source, newest first, int64.
correctornumpy.ndarray: The corrector’s weights over X, zero past its own nodes.
rowsnumpy.ndarray: One defect’s weights over X per row, shape (n_rows, 1 + n_slots).
dzfloat: The step, m.
masknumpy.ndarray: The in-band bins, Boolean.
divisornumpy.ndarray: The norm’s scale per bin.

Returns:

tuple: The corrected field and one norm per row.

predict(state, propagator, store, slots, weights, dz)[source]#

Return the predictor’s lab-frame field U (a_n + dz sum_t w_t g_t).

Parameters:

statenumpy.ndarray: The accepted state at the anchor.
propagatornumpy.ndarray: U(z_n + dz, z_n).
storenumpy.ndarray: The history rows.
slotsnumpy.ndarray: The rows the predictor combines, newest first, int64.
weightsnumpy.ndarray: One integrated weight per row.
dzfloat: The step, m.

Returns:

numpy.ndarray: The predicted field at the end of the step.

transport(store, slots, propagator, new_slot, source)[source]#

Re-anchor the history at the step’s end and store the new derivative.

Parameters:

storenumpy.ndarray: The history rows, updated in place.
slotsnumpy.ndarray: The rows of the kept history, int64.
propagatornumpy.ndarray: U(z_n + dz, z_n).
new_slotint: The free row the new derivative goes to.
sourcenumpy.ndarray: The new derivative in the step’s anchor frame.

weights(nodes, upper=1.0)[source]#

Return the integrated weights of an interpolant on distinct nodes.

Parameters:

nodeslist of float or numpy.ndarray: The normalised nodes, accepted positions and so distinct.
upperfloat, optional: The integral’s upper limit.

Returns:

numpy.ndarray: One weight per node, as integrated_weights gives them.

class solprop.backends.numpy_ref.multistep.CoupledBlock(active, vectors, triangular, section, end_weights=None, residual=None, basis=None)[source]#

Bases: object

A step’s frozen coupled block on the bins that carry one (SEP 16 phase 5).

Beside a coupled flow the cumulative diagonal Phi is a multiple of the identity in the channel axis (docs/dev/kernel-contract.md, coupled_flow), so the step’s reference is B = (Delta Phi / h) I + G_s with G_s = Z T Z^H the frozen block of the section the step is anchored in, and the two parts commute.

Attributes:

activenumpy.ndarray: Which bins carry a block, bool, shape (n_omega,).
vectors, triangularnumpy.ndarray: Z and T of the section’s block, 1/m for T, shape (n_active, n_modes, n_modes).
sectionint: The section the step is anchored in.
end_weightsnumpy.ndarray or None: The flow’s term weights at the step’s end, read on the step’s side of a section edge (StageScalars.flow_weights); None without a residual.
residualcallable or None: (state, weights) -> R_s(z) state for a frozen-residual flow: the generator at the position the weights belong to less this section’s frozen block, on the active bins the error norm scores and zero elsewhere, as the Runge-Kutta stage applies it; None for a constant-Schur flow.
basistuple or None: The section’s eigenbasis (W, Y, lambda, route), as solprop.translate.coupled.schur_eigenbasis() returns it: the bins on the route take their matrix functions as W f(x + h lambda) Y, the compiled backends’ evaluation. None, the reference’s, takes every bin from the augmented exponential.

active: ndarray#

basis: tuple[ndarray, ndarray, ndarray, ndarray] | None = None#

end_weights: ndarray | None = None#

residual: Callable[[ndarray, ndarray], ndarray] | None = None#

section: int#

triangular: ndarray#

vectors: ndarray#

class solprop.backends.numpy_ref.multistep.CoupledExponentialKernels(*, helpers=Helpers(name='plain'))[source]#

Bases: ExponentialKernels

The reference passes beside a coupled flow (SEP 16 phase 5).

A coupled trial’s flow and moments are _MatrixMoments (coupled_moments()): matrices in the channel axis on the bins that carry a block, elementwise elsewhere. The passes are ExponentialKernels’ with those products.

carry_coupled(exponent, dz, rows, slots, spans, block)[source]#

Return each sample’s compensation carried to the step’s end (SEP 16 4.5).

C_j = (D(z_j) - x / h) u_j + R_s(z_j) u_j: the diagonal chord’s difference of rates and the frozen-residual’s residual relative to the step’s section, formed from the sample’s own flow weights – so that a step in a new section rebuilds the history’s residual against its block – and carried by the reference’s forward flow exp((1 - theta_j) h B).

Parameters:

exponentnumpy.ndarray: x = Delta Phi over the step.
dzfloat: The step, m.
rowstuple: The history’s rates and states, by slot, and each slot’s flow weights.
slotsnumpy.ndarray: The samples carried, newest first.
spansnumpy.ndarray: 1 - theta_j per sample.
blockCoupledBlock: The step’s frozen block.

Returns:

numpy.ndarray: One carried row per sample.

correct(state, flow, moments, source, store, slots, corrector, rows, dz, mask, divisor, extra=None, *, factors=None)[source]#

Return the corrected field and the defects’ norms through the block.

Parameters:

statenumpy.ndarray: The accepted state at the anchor.
flow, moments_MatrixMoments or numpy.ndarray: The coupled trial’s flow and moments.
sourcenumpy.ndarray: The untransported source at the predicted field.
storenumpy.ndarray: The history rows.
slotsnumpy.ndarray: The rows after the source, newest first, int64.
correctornumpy.ndarray: The corrector’s coefficients.
rowsnumpy.ndarray: One defect’s coefficients per row.
dzfloat: The step, m.
masknumpy.ndarray: The in-band bins, Boolean.
divisornumpy.ndarray: The norm’s scale per bin.
extratuple or None, optional: A varying operator’s compensation terms.
factorsnumpy.ndarray or None, optional: The history rows’ carrier-frame rotations, in the slots’ order.

Returns:

tuple: The corrected field and one norm per row.

coupled()[source]#

Return these passes.

Returns:

CoupledExponentialKernels: This object.

coupled_moments(exponent, count, block, dz, *, shift=None)[source]#

Return a coupled trial’s flow and moments (coupled_moments()).

Parameters:

exponentnumpy.ndarray: Delta Phi over the step.
countint: The moments formed.
blockCoupledBlock: The step’s frozen block.
dzfloat: The step, m.
shiftnumpy.ndarray or None, optional: A carrier frame’s sigma: the shifted block’s moments, the true flow.

Returns:

_MatrixMoments: The flow and the moments.

predict(state, flow, moments, store, slots, coefficients, dz, *, factors=None)[source]#

Return the predicted field through the trial’s block.

Parameters:

statenumpy.ndarray: The accepted state at the anchor.
flow, moments_MatrixMoments or numpy.ndarray: The coupled trial’s flow and moments.
storenumpy.ndarray: The history rows.
slotsnumpy.ndarray: The rows the predictor combines, newest first, int64.
coefficientsnumpy.ndarray: The predictor’s Lagrange coefficients.
dzfloat: The step, m.
factorsnumpy.ndarray or None, optional: The rows’ carrier-frame rotations, in the slots’ order.

Returns:

numpy.ndarray: The predicted lab-frame field at the end of the step.

class solprop.backends.numpy_ref.multistep.ExponentialKernels(*, helpers=Helpers(name='plain'))[source]#

Bases: object

The field arithmetic of an exponential Adams step, in NumPy (SEP 16 phase 2).

The history is a store of untransported source rows, newest first by slots. A trial forms M_k = k! phi_{k+1}(x), x = h D per element, once, and applies every formula it needs in the monomial basis of its interpolant, h sum_k M_k (sum_j c_jk F_j) (solprop.backends.exponential), so no per-node weight volume is formed. Accepting a step re-anchors nothing. The native backend’s kernels are checked against these passes.

Under a carrier frame (SEP 35) the same passes take the moments at x - sigma and rows rotated by exp(sigma (1 - theta_j)); the caller forms both (HostHistory), so the passes themselves do not change.

Parameters:

helperssolprop._helpers.Helpers, optional: The owning backend’s implementation of the Adams basis (SEP 29 section 6.6); the plain Python forms by default.

apply(moments, coefficients, values, dz)[source]#

Return dz sum_k M_k (sum_j c_jk X_j) over the given rows.

Parameters:

momentsnumpy.ndarray: M_k from moments().
coefficientsnumpy.ndarray: c_jk, shape (len(values), n_k) with n_k <= len(moments).
valueslist of numpy.ndarray: The samples X_j.
dzfloat: The step, m.

Returns:

numpy.ndarray: The increment.

carry(exponent, dz, rates, states, slots, spans)[source]#

Return each history sample’s compensation carried to the step’s end.

exp(s_j x) (D(z_j) - x / dz) u_j with s_j = 1 - theta_j, the difference of rates formed before the state multiplies it (SEP 16 4.2).

Parameters:

exponentnumpy.ndarray: x = Phi(z + h) - Phi(z).
dzfloat: The step, m.
rates, statesnumpy.ndarray: The history’s rates and states, by slot.
slotsnumpy.ndarray: The samples carried, newest first, int64.
spansnumpy.ndarray: 1 - theta_j per sample: the flow’s length in steps.

Returns:

numpy.ndarray: One carried row per sample.

correct(state, flow, moments, source, store, slots, corrector, rows, dz, mask, divisor, extra=None, *, factors=None)[source]#

Return the corrected field and the scaled norms of the defects.

With X = (source, store[slots[0]], ...), the field is exp(x) u_n + dz sum_k M_k sum_j corrector[j, k] X_j and each norm is the weak norm of dz sum_k M_k sum_j rows[r, j, k] X_j over the in-band bins; both are already at the end of the step. A varying operator’s compensation adds its own corrector term to the field and one term to each defect.

Parameters:

state, flow, momentsnumpy.ndarray: As for predict().
sourcenumpy.ndarray: The untransported source at the predicted field.
storenumpy.ndarray: The history rows.
slotsnumpy.ndarray: The rows after the source, newest first, int64.
correctornumpy.ndarray: The corrector’s coefficients over X, shape (width, n_k), zero past its own nodes.
rowsnumpy.ndarray: One defect’s coefficients over X per row, shape (n_rows, width, n_k).
dzfloat: The step, m.
masknumpy.ndarray: The in-band bins, Boolean.
divisornumpy.ndarray: The norm’s scale per bin.
extratuple or None, optional: The compensation’s corrector term and its term in each defect, or None for a constant operator.
factorsnumpy.ndarray or None, optional: A carrier frame’s rotation of each history row read, in the slots’ order; the new source’s is one.

Returns:

tuple: The corrected field and one norm per row.

coupled()[source]#

Return the passes this backend takes beside a coupled flow.

Returns:

CoupledExponentialKernels: The reference’s; a compiled backend returns its own.

defect_rows(nodes, orders, width)[source]#

Return the defects’ coefficients in the form correct() takes.

Parameters:

nodeslist of float: The history’s normalised positions, newest first.
orderslist of int: The orders scored, the step’s own first.
widthint: 1 + max(orders).

Returns:

numpy.ndarray: The monomial rows of _exponential_rows, shape (len(orders), width, width).

flow(exponent)[source]#

Return the step’s exact linear flow exp(x).

Parameters:

exponentnumpy.ndarray: x = Phi(z + h) - Phi(z).

Returns:

numpy.ndarray: exp(x), the propagator the interaction formulation would apply.

moments(exponent, count, *, shift=None)[source]#

Return k! phi_{k+1}(x) for k < count along a new leading axis.

Parameters:

exponentnumpy.ndarray: x = Phi(z + h) - Phi(z), in the canonical layout.
countint: The most interpolation nodes any formula of the trial has.
shiftnumpy.ndarray or None, optional: A carrier frame’s sigma (SEP 35): the moments are then those of x - sigma, and the step’s flow stays exp(x) (flow()).

Returns:

numpy.ndarray: Shape (count, *x.shape).

predict(state, flow, moments, store, slots, coefficients, dz, *, factors=None)[source]#

Return the predicted field exp(x) u_n + dz sum_k M_k sum_j c_jk F_j.

Parameters:

statenumpy.ndarray: The accepted state at the anchor.
flownumpy.ndarray: exp(x), the step’s exact linear flow.
momentsnumpy.ndarray: M_k from moments().
storenumpy.ndarray: The history rows.
slotsnumpy.ndarray: The rows the predictor combines, newest first, int64.
coefficientsnumpy.ndarray: The predictor’s Lagrange coefficients, shape (len(slots), len(slots)).
dzfloat: The step, m.
factorsnumpy.ndarray or None, optional: A carrier frame’s rotation of each row read, exp(sigma (1 - theta_j)) in the slots’ order (SEP 35 section 6.2); None for none.

Returns:

numpy.ndarray: The predicted lab-frame field at the end of the step.

class solprop.backends.numpy_ref.multistep.HostHistory(backend, method, kernels, exponential, compensation)[source]#

Bases: object

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

The march (HostAdamsMarch) keeps the controller – the orders, the slots, rejection, restarts, the budget and the ledger – and hands every state-sized operation to an engine: the startup sample, a trial’s predictor, source, corrector and defect norms, the adoption and transport of an accepted step, and dense observation. This engine holds the history in a NumPy store and applies the given kernels; a backend may supply its own, as the native backend keeps the history resident in its state (_ResidentAdams). Between a trial and its acceptance the engine holds the trial; nothing else is carried across calls but the store and the last accepted step for dense observation.

Parameters:

backendsolprop.backends.host.driver.HostDriver: The backend whose state, source evaluation and propagators are used.
methodsolprop.stepper.multistep.Multistep: The method.
kernelsAdamsKernels: The interaction formulation’s fused arithmetic.
exponentialExponentialKernels or None: The exponential formulation’s arithmetic, None for the interaction one.
compensation{‘transported’, ‘untransported’}: A varying operator’s compensation treatment (SEP 16 Q8).

carrier: CarrierReference | None#

dense: Any#

exponential_accept(keep, free, *, interpolate)[source]#

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

Parameters:

keepnumpy.ndarray: The history rows kept, int64; nothing moves in this formulation.
freeint: The row the new sample takes.
interpolatebool: Whether the step’s interpolant is kept for dense observation.

exponential_trial(z, dz, nodes, slots, order, orders)[source]#

Form one exponential trial and return the scaled norms of its defects.

The arithmetic of fused_trial() with untransported samples: the predictor and the corrector integrate their interpolants exactly against the step’s flow exp(x), x = Phi(z + h) - Phi(z); the defects of the neighbouring orders are scored from the same moments. A varying operator adds the compensation of its samples (SEP 16 section 4.2). Under a carrier frame the samples read are rotated and the moments shifted (SEP 35 section 4.1); the flow is unchanged. The trial is held for exponential_accept().

Parameters:

z, dzfloat: The anchor and the step, m.
nodeslist of float: The history’s normalised positions, newest first.
slotsnumpy.ndarray: Their store rows, int64.
orderint: The step’s order.
orderslist of int: The orders scored, the step’s own first.

Returns:

numpy.ndarray: One scaled norm per scored order.

fused_accept(keep, free, *, interpolate)[source]#

Adopt the held fused trial: the state, its interpolant, the new sample.

Parameters:

keepnumpy.ndarray: The history rows kept, int64; each is re-anchored at the step’s end.
freeint: The row the new sample takes.
interpolatebool: Whether the step’s interpolant is kept for dense observation.

fused_trial(z, dz, nodes, slots, order, orders)[source]#

Form one fused trial and return the scaled norms of its scored defects.

The predictor’s lab-frame field, the source there (one call, labelled a predictor), and in one pass the corrected field and each scored order’s defect: its k + 1-node corrector through the new source less its k-node predictor. The trial is held for fused_accept().

Parameters:

z, dzfloat: The anchor and the step, m.
nodeslist of float: The history’s normalised positions, newest first.
slotsnumpy.ndarray: Their store rows, int64.
orderint: The step’s order.
orderslist of int: The orders scored, the step’s own first.

Returns:

numpy.ndarray: One scaled norm per scored order.

hold()[source]#

Return the accepted state, to restore after a dense observation.

Returns:

object: The backend’s host copy of the accepted state.

load_rows(rows, shape)[source]#

Install rows snapshot_rows() 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.

property n_slots: int[source]#: The history store’s rows: the method’s order and two more.

observe(position)[source]#

Return the field at position inside the last accepted step.

Parameters:

positionfloat: The observation, m, inside the last accepted step.

Returns:

object: The masked lab-frame field at position, as the backend holds a state: a host array, or Kokkos’s native state loaded with it.

reset()[source]#

Forget the last accepted step and any trial in flight.

restore(z, held)[source]#

Make a held accepted state current again at z.

Parameters:

zfloat: Its position, m.
heldobject: What hold() returned.

snapshot_nbytes()[source]#

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

Returns:

int: The size of every row.

snapshot_rows()[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.

start(z)[source]#

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

The sample goes to the store’s row zero.

Parameters:

zfloat: The accepted position, m.

Returns:

numpy.ndarray: The sample: the transported source in the interaction formulation, the untransported one in the exponential formulation.

value(slot)[source]#

Return a store row, for the history entry that names it.

Parameters:

slotint: The row.

Returns:

numpy.ndarray: The row itself, not a copy.

solprop.backends.numpy_ref.multistep.compensation_tables(nodes, order, orders, *, helpers)[source]#

Return a trial’s transported-compensation tables, for a resident engine.

The weights _Compensation applies (SEP 16 section 4.2, ADR-042), over the carried rows exp((1 - theta_j) x) (D(z_j) - x / h) u_j of the history samples and the endpoint term (D(z + h) - x / h) u_pred, each sum still to be multiplied by the step.

Parameters:

nodeslist of float: The history’s normalised positions, newest first.
orderint: The step’s order.
orderslist of int: The orders scored, the step’s own first.
helperssolprop._helpers.Helpers: The engine’s backend’s implementation of the Adams basis.

Returns:

tuple: The spans 1 - theta_j of the width - 1 carried samples; the predictor’s weights over the order newest of them; the corrector’s over (endpoint, newest, ...); and each scored order’s defect weights over the same, shape (len(orders), width), with width = 1 + max(orders).

solprop.backends.numpy_ref.multistep.coupled_moments(exponent, count, block, dz, *, eigen=<function _eigen_functions>, diagonal=None, carrier=None)[source]#

Return a coupled trial’s flow and moments k! phi_{k+1}(h B), k < count.

The reference’s evaluation (SEP 16 section 4.5): on each bin of the block the functions of X = Delta Phi I + h T, upper triangular, are read off the first block row of the exponential of the augmented matrix [[X, I, 0, ...], [0, 0, I, ...], ..., [0, ..., 0]] – exp(X), phi_1(X), …, phi_count(X) – and carried back by Z; off the block the diagonal functions of ExponentialKernels. With the block’s eigenbasis (CoupledBlock.basis), the bins on its route instead take W f(Delta Phi + h lambda) Y, every bin in one pass: the route and its gate are the compiled flow actions’ (solprop.translate.coupled.eigenbasis_limit()), and the bins off it keep the augmented exponential.

Parameters:

exponentnumpy.ndarray: Delta Phi over the step, the same in every channel.
countint: The moments formed.
blockCoupledBlock: The step’s frozen block.
dzfloat: The step, m.
eigencallable, optional: Writes the eigenbasis route’s bins, (shift, dz, count, basis, matrices, flow_matrix): _eigen_functions, or a compiled backend’s kernel.
diagonalcallable or None, optional: (exponent, count) -> moments off the block; None for the reference’s ExponentialKernels.moments().
carriernumpy.ndarray or None, optional: A carrier frame’s sigma (SEP 35 section 4.5), broadcasting against exponent. The moments are then those of the shifted block h B - sigma I, and the flow is exp(sigma) times its phi_0: sigma I commutes with B, so exp(h B) = exp(sigma) exp(h B - sigma I) and one evaluation gives both, in the augmented and eigenbasis paths alike. None for the unshifted step.

Returns:

_MatrixMoments: The flow exp(h B) and the moments.

solprop.backends.numpy_ref.multistep.exponential_tables(nodes, order, orders, *, helpers)[source]#

Return an exponential trial’s coefficient tables, for a resident engine.

Parameters:

nodeslist of float: The history’s normalised positions, newest first.
orderint: The step’s order.
orderslist of int: The orders scored, the step’s own first.
helperssolprop._helpers.Helpers: The engine’s backend’s implementation of the Adams basis.

Returns:

tuple: The predictor’s Lagrange coefficients over the order newest rows, shape (order, order); the corrector’s over (source, newest, ...), shape (width, width) with width = 1 + max(orders); and the factored defect rows of factored_defect_rows().

solprop.backends.numpy_ref.multistep.factored_defect_rows(nodes, orders, width)[source]#

Return each exponential defect factored: a divided difference and a polynomial.

Order k’s defect, its k + 1-node corrector through the new sample less its k-node predictor, vanishes at the predictor’s nodes, so it is f[1, theta_0, ..., theta_{k-1}] prod_{j<k} (theta - theta_j): one divided difference of the samples times one polynomial, whose integral against the flow is one combination of the moments. That is 2 (k + 1) products an element instead of (k + 1) n_k, the monomial rows of _exponential_rows.

Parameters:

nodeslist of float: The history’s normalised positions, newest first.
orderslist of int: The orders scored, the step’s own first.
widthint: 1 + max(orders): the samples and the moments of the trial.

Returns:

numpy.ndarray: Shape (len(orders), 2 width): the divided-difference coefficients over (source, newest, ...), then the node polynomial’s ascending monomial coefficients.

solprop.backends.numpy_ref.multistep.fused_tables(nodes, order, orders, *, helpers)[source]#

Return a fused trial’s coefficient tables, for an engine that applies them.

The interaction formulation’s tables of HostHistory.fused_trial(), which a resident engine (ADR-043) receives instead of forming them.

Parameters:

nodeslist of float: The history’s normalised positions, newest first.
orderint: The step’s order.
orderslist of int: The orders scored, the step’s own first.
helperssolprop._helpers.Helpers: The engine’s backend’s implementation of the Adams basis.

Returns:

tuple: The predictor’s integrated weights over the order newest rows; the corrector’s weights over (source, newest, ...), zero past its nodes; and one defect row per scored order over the same samples.

solprop.backends.numpy_ref.multistep.trial_tables(nodes, order, orders, *, compensated, helpers)[source]#

Return all of an exponential trial’s coefficient tables, for a resident engine.

exponential_tables()’ three and, compensated, compensation_tables()’ four, composed over the record’s basis; a record that forms them in one call (Helpers.tables, the native backend’s) performs the same operations in the same order, so the tables are the same, read once a trial instead of from a dozen small calls.

Parameters:

nodeslist of float: The history’s normalised positions, newest first.
orderint: The step’s order.
orderslist of int: The orders scored, the step’s own first.
compensatedbool: Whether the trial carries a varying operator’s transported compensation.
helperssolprop._helpers.Helpers: The engine’s backend’s implementation of the Adams basis.

Returns:

tuple: The predictor, the corrector and the factored defect rows; then the compensation’s spans, predictor, corrector and defect rows, shapes (0,) and (0, 0) when not compensated.