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

AdamsKernels(*[, helpers])

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

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

The Adams history's rows, where the state lives (SEP 52 section 5.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(workspace, method, kernels, ...)

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

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.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.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(workspace, method, kernels, exponential, compensation, *, 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 and transport 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, exponential_dense; solprop.backends.numpy_ref.dense).

Parameters:
workspacesolprop.backends.numpy_ref.workspace.NumpyWorkspace

The workspace 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).

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 interaction formulation’s last accepted step, for dense observation; None before one.

exponential_denseobject

The exponential formulation’s, likewise.

compensatedbool

Whether a varying operator’s linear compensation is integrated.

carriersolprop.backends.exponential.CarrierReference or None

The exponential formulation’s carrier frame; None for the interaction 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 exponential: bool[source]#

Whether the exponential formulation’s arithmetic steps the history.

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.

Returns:
solprop.backends.engines.AcceptRecord

The finish’s split collar’s sums.

exponential_dense: Any#
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.

Returns:
solprop.backends.engines.AcceptRecord

The finish’s split collar’s sums.

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.

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 transported source in the interaction formulation, the untransported one in the exponential formulation.

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 method’s own formulation’s trial (fused_trial(), exponential_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.

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.