solprop.backends.numpy_ref.adams_kernels#

The field arithmetic of the reference’s Adams steps (SEP 13, SEP 14, SEP 16).

The state-sized passes an Adams trial and its acceptance take, given the history’s rows and the trial’s coefficients (adams_tables). AdamsKernels is the interaction formulation’s: the predictor, the corrector with every scored defect, and the history’s transport to the new anchor. ExponentialKernels is the exponential formulation’s: the moments k! phi_{k+1}(x) and the flow exp(x), the passes in the monomial basis of the interpolant, and a varying operator’s carried compensation. Beside a coupled flow the flow and moments are matrices on the block’s bins: CoupledBlock is a step’s frozen block and coupled_moments() its augmented-exponential moments (MatrixMoments). weighted_sum() is the accumulation every pass shares.

Functions

coupled_moments(exponent, count, block, dz, *)

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

weighted_sum(weights, values)

Return sum_j w_j X_j, accumulated in the order of the rows.

Classes

AdamsKernels()

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

ExponentialKernels()

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

MatrixMoments(scalar, flow_scalar, matrices, ...)

A coupled trial's flow and moments: scalar per element, matrices on a block.

class solprop.backends.numpy_ref.adams_kernels.AdamsKernels[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; the weights are adams_tables’.

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.

class solprop.backends.numpy_ref.adams_kernels.CoupledBlock(active, vectors, triangular, section, end_weights=None, residual=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.

active: ndarray#
end_weights: ndarray | None = None#
residual: Callable[[ndarray, ndarray], ndarray] | None = None#
section: int#
triangular: ndarray#
vectors: ndarray#
class solprop.backends.numpy_ref.adams_kernels.ExponentialKernels[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.

Beside a coupled flow (SEP 16 phase 5) a trial’s flow and moments are MatrixMoments (coupled_moments()): matrices in the channel axis on the bins that carry a block, elementwise elsewhere; the same passes apply them. Under a carrier frame (SEP 35) the passes take the moments at x - sigma and rows rotated by exp(sigma (1 - theta_j)); the caller forms both (ExponentialHistory), so the passes themselves do not change.

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 or MatrixMoments

M_k from moments() or coupled_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.

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

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 or MatrixMoments

exp(x), the step’s exact linear flow, or a coupled trial’s.

momentsnumpy.ndarray or MatrixMoments

M_k from moments() or coupled_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.adams_kernels.MatrixMoments(scalar, flow_scalar, matrices, flow_matrix, active)[source]#

Bases: object

A coupled trial’s flow and moments: scalar per element, matrices on a block.

Off the block’s bins the step’s flow and moments are the diagonal ones, per element; on them each is a matrix in the channel axis, applied to the channel vector of every polarisation. matrices and flow_matrix are laid out by bin, (..., n_bins, n_modes, n_modes); the products read the same matrices with the bin axis last, as the state holds it.

Attributes:
scalar, flow_scalarnumpy.ndarray

The diagonal moments and flow, per element.

matrices, flow_matrixnumpy.ndarray

The block’s moments and flow on its bins.

activenumpy.ndarray

Which bins carry the block, bool.

active: ndarray#
apply(k, values)[source]#

Return M_k applied to a state-shaped array.

Parameters:
kint

The moment.

valuesnumpy.ndarray

The array, in the state’s layout.

Returns:
numpy.ndarray

M_k values.

flow(values)[source]#

Return the step’s flow exp(h B) applied to a state-shaped array.

Parameters:
valuesnumpy.ndarray

The array, in the state’s layout.

Returns:
numpy.ndarray

exp(h B) values.

flow_matrix: ndarray#
flow_scalar: ndarray#
matrices: ndarray#
scalar: ndarray#
solprop.backends.numpy_ref.adams_kernels.coupled_moments(exponent, count, block, dz, *, 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.moments().

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.

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. None for the unshifted step.

Returns:
MatrixMoments

The flow exp(h B) and the moments.

solprop.backends.numpy_ref.adams_kernels.weighted_sum(weights, values)[source]#

Return sum_j w_j X_j, accumulated in the order of the rows.

Parameters:
weightsnumpy.ndarray

One real weight per row.

valueslist of numpy.ndarray

The rows, each in the state’s layout.

Returns:
numpy.ndarray

The weighted sum, a new array.