# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""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 (:mod:`~solprop.backends.numpy_ref.adams_tables`).
:class:`AdamsKernels` is the interaction formulation's: the predictor, the corrector
with every scored defect, and the history's transport to the new anchor.
:class:`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: :class:`CoupledBlock` is a step's
frozen block and :func:`coupled_moments` its augmented-exponential moments
(:class:`MatrixMoments`). :func:`weighted_sum` is the accumulation every pass shares.
"""
import math
from collections.abc import Callable
from dataclasses import dataclass, field
import numpy as np
from jaxtyping import Complex
from scipy.linalg import expm
from solprop.backends.exponential import phi_functions
from solprop.backends.numpy_ref.passes.stepping import accumulate
__all__ = [
"AdamsKernels",
"CoupledBlock",
"ExponentialKernels",
"MatrixMoments",
"coupled_moments",
"weighted_sum",
]
_State = Complex[np.ndarray, "n_modes n_pol n_omega"]
_StoreRows = Complex[np.ndarray, "n_slots n_modes n_pol n_omega"]
_Shift = Complex[np.ndarray, "1 1 #n_omega"]
"""A carrier frame's shift (SEP 35), shape ``(1, 1, 1)``."""
_Factors = Complex[np.ndarray, "n_used 1 1 #n_omega"]
"""A carrier frame's rotation of each history row a trial reads, in its slots' order."""
_MomentRows = Complex[np.ndarray, "n_k n_modes n_pol n_omega"]
"""A trial's moments ``M_k`` per element, along a leading axis."""
[docs]
def weighted_sum(weights: np.ndarray, values: list[_State]) -> _State:
"""Return ``sum_j w_j X_j``, accumulated in the order of the rows.
Parameters
----------
weights : numpy.ndarray
One real weight per row.
values : list of numpy.ndarray
The rows, each in the state's layout.
Returns
-------
numpy.ndarray
The weighted sum, a new array.
"""
total = np.zeros_like(values[0])
for weight, value in zip(weights, values, strict=True):
total = accumulate(total, value, float(weight))
return total
[docs]
class AdamsKernels:
"""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
:mod:`~solprop.backends.numpy_ref.adams_tables`'.
"""
[docs]
def predict( # noqa: PLR0917 - called positionally
self,
state: _State,
propagator: _State,
store: Complex[np.ndarray, "n_slots n_modes n_pol n_omega"],
slots: np.ndarray,
weights: np.ndarray,
dz: float,
) -> _State:
"""Return the predictor's lab-frame field ``U (a_n + dz sum_t w_t g_t)``.
Parameters
----------
state : numpy.ndarray
The accepted state at the anchor.
propagator : numpy.ndarray
``U(z_n + dz, z_n)``.
store : numpy.ndarray
The history rows.
slots : numpy.ndarray
The rows the predictor combines, newest first, ``int64``.
weights : numpy.ndarray
One integrated weight per row.
dz : float
The step, m.
Returns
-------
numpy.ndarray
The predicted field at the end of the step.
"""
total = weighted_sum(weights, [store[slot] for slot in slots])
return propagator * (state + dz * total)
[docs]
def correct( # noqa: PLR0917 - buffers are a kernel's parameters
self,
state: _State,
propagator: _State,
source: _State,
store: Complex[np.ndarray, "n_slots n_modes n_pol n_omega"],
slots: np.ndarray,
corrector: np.ndarray,
rows: np.ndarray,
dz: float,
mask: np.ndarray,
divisor: np.ndarray,
) -> tuple[_State, np.ndarray]:
"""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, propagator : numpy.ndarray
As for :meth:`predict`.
source : numpy.ndarray
The source at the predicted field, in the anchor's frame.
store : numpy.ndarray
The history rows.
slots : numpy.ndarray
The rows after the source, newest first, ``int64``.
corrector : numpy.ndarray
The corrector's weights over ``X``, zero past its own nodes.
rows : numpy.ndarray
One defect's weights over ``X`` per row, shape ``(n_rows, 1 + n_slots)``.
dz : float
The step, m.
mask : numpy.ndarray
The in-band bins, Boolean.
divisor : numpy.ndarray
The norm's scale per bin.
Returns
-------
tuple
The corrected field and one norm per row.
"""
values = [source, *(store[slot] for slot in slots)]
total = weighted_sum(corrector, values)
norms = np.empty(rows.shape[0])
for index, row in enumerate(rows):
defect = weighted_sum(row, values)
scaled = (propagator * (dz * defect))[..., mask] / divisor[mask]
norms[index] = float(np.linalg.norm(scaled))
return propagator * (state + dz * total), norms
[docs]
def transport(
self,
store: Complex[np.ndarray, "n_slots n_modes n_pol n_omega"],
slots: np.ndarray,
propagator: _State,
new_slot: int,
source: _State,
) -> None:
"""Re-anchor the history at the step's end and store the new derivative.
Parameters
----------
store : numpy.ndarray
The history rows, updated in place.
slots : numpy.ndarray
The rows of the kept history, ``int64``.
propagator : numpy.ndarray
``U(z_n + dz, z_n)``.
new_slot : int
The free row the new derivative goes to.
source : numpy.ndarray
The new derivative in the step's anchor frame.
"""
for slot in slots:
store[slot] *= propagator
np.multiply(propagator, source, out=store[new_slot])
[docs]
@dataclass(frozen=True)
class CoupledBlock:
"""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
----------
active : numpy.ndarray
Which bins carry a block, bool, shape ``(n_omega,)``.
vectors, triangular : numpy.ndarray
``Z`` and ``T`` of the section's block, 1/m for ``T``, shape
``(n_active, n_modes, n_modes)``.
section : int
The section the step is anchored in.
end_weights : numpy.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.
residual : callable 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: np.ndarray
vectors: np.ndarray
triangular: np.ndarray
section: int
end_weights: np.ndarray | None = None
residual: Callable[[np.ndarray, np.ndarray], np.ndarray] | None = None
[docs]
@dataclass(frozen=True)
class MatrixMoments:
"""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_scalar : numpy.ndarray
The diagonal moments and flow, per element.
matrices, flow_matrix : numpy.ndarray
The block's moments and flow on its bins.
active : numpy.ndarray
Which bins carry the block, bool.
"""
scalar: np.ndarray
flow_scalar: np.ndarray
matrices: np.ndarray
flow_matrix: np.ndarray
active: np.ndarray
_columns: np.ndarray = field(init=False, repr=False, compare=False)
_flow_columns: np.ndarray = field(init=False, repr=False, compare=False)
def __post_init__(self) -> None:
"""Hold the matrices with the bin axis last, for the products."""
object.__setattr__(
self, "_columns", np.ascontiguousarray(np.moveaxis(self.matrices, -3, -1))
)
object.__setattr__(
self,
"_flow_columns",
np.ascontiguousarray(np.moveaxis(self.flow_matrix, -3, -1)),
)
def _product(
self, columns: np.ndarray, scalar: np.ndarray, values: _State
) -> _State:
"""Return the scalar product off the block and the matrix product on it.
- ``scalar``: the diagonal factor, in the state's layout.
- ``values``: the array, in the state's layout.
"""
out = scalar * values
selected = values[..., self.active]
block = columns[:, 0][:, np.newaxis] * selected[np.newaxis, 0]
for column in range(1, columns.shape[1]):
block += columns[:, column][:, np.newaxis] * selected[np.newaxis, column]
out[..., self.active] = block
return out
[docs]
def apply(self, k: int, values: _State) -> _State:
"""Return ``M_k`` applied to a state-shaped array.
Parameters
----------
k : int
The moment.
values : numpy.ndarray
The array, in the state's layout.
Returns
-------
numpy.ndarray
``M_k values``.
"""
columns = self._columns
return self._product(columns[k], self.scalar[k], values)
[docs]
def flow(self, values: _State) -> _State:
"""Return the step's flow ``exp(h B)`` applied to a state-shaped array.
Parameters
----------
values : numpy.ndarray
The array, in the state's layout.
Returns
-------
numpy.ndarray
``exp(h B) values``.
"""
columns = self._flow_columns
return self._product(columns, self.flow_scalar, values)
[docs]
def coupled_moments(
exponent: _State,
count: int,
block: CoupledBlock,
dz: float,
*,
carrier: _Shift | None = None,
) -> MatrixMoments:
"""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 :meth:`ExponentialKernels.moments`.
Parameters
----------
exponent : numpy.ndarray
``Delta Phi`` over the step, the same in every channel.
count : int
The moments formed.
block : CoupledBlock
The step's frozen block.
dz : float
The step, m.
carrier : numpy.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.
"""
unshifted = exponent
if carrier is not None:
exponent = np.ascontiguousarray(exponent - carrier)
active = block.active
# The block's bins take matrix moments below: the scalar ones are formed off it.
scalar = np.zeros((count, *exponent.shape), dtype=np.complex128)
if count and not np.all(active):
scalar[..., ~active] = ExponentialKernels().moments(
np.ascontiguousarray(exponent[..., ~active]), count
)
flow_scalar = np.exp(unshifted)
n_modes = block.triangular.shape[-1]
shift = exponent[0, 0, active]
matrices = np.empty((count, *block.triangular.shape), dtype=np.complex128)
flow_matrix = np.empty(block.triangular.shape, dtype=np.complex128)
size = n_modes * (count + 1)
identity = np.eye(n_modes)
for index in range(block.triangular.shape[0]):
augmented = np.zeros((size, size), dtype=np.complex128)
augmented[:n_modes, :n_modes] = (
shift[index] * identity + dz * block.triangular[index]
)
for row in range(count):
start = (row + 1) * n_modes
augmented[row * n_modes : start, start : start + n_modes] = identity
functions = expm(augmented)[:n_modes]
vectors = block.vectors[index]
adjoint = np.conj(vectors.T)
flow_matrix[index] = vectors @ functions[:, :n_modes] @ adjoint
for k in range(count):
column = (k + 1) * n_modes
matrices[k, index] = (
math.factorial(k)
* vectors
[docs]
@ functions[:, column : column + n_modes]
@ adjoint
)
if carrier is not None:
factor = np.exp(np.broadcast_to(carrier, unshifted.shape)[0, 0, active])
flow_matrix = factor[:, np.newaxis, np.newaxis] * flow_matrix
return MatrixMoments(scalar, flow_scalar, matrices, flow_matrix, active)
class ExponentialKernels:
"""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
:class:`MatrixMoments` (:func:`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
(:class:`~solprop.backends.numpy_ref.multistep.ExponentialHistory`), so the passes
themselves do not change.
"""
[docs]
def moments(
self, exponent: _State, count: int, *, shift: _Shift | None = None
) -> Complex[np.ndarray, "n_k n_modes n_pol n_omega"]:
"""Return ``k! phi_{k+1}(x)`` for ``k < count`` along a new leading axis.
Parameters
----------
exponent : numpy.ndarray
``x = Phi(z + h) - Phi(z)``, in the canonical layout.
count : int
The most interpolation nodes any formula of the trial has.
shift : numpy.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)`` (:meth:`flow`).
Returns
-------
numpy.ndarray
Shape ``(count, *x.shape)``.
"""
if shift is not None:
exponent = exponent - shift
phi = phi_functions(exponent, count)
factors = np.array([math.factorial(k) for k in range(count)], dtype=np.float64)
return phi[1:] * factors.reshape((count, *([1] * exponent.ndim)))
[docs]
def flow(self, exponent: _State) -> _State:
"""Return the step's exact linear flow ``exp(x)``.
Parameters
----------
exponent : numpy.ndarray
``x = Phi(z + h) - Phi(z)``.
Returns
-------
numpy.ndarray
``exp(x)``, the propagator the interaction formulation would apply.
"""
return np.exp(exponent)
[docs]
def carry( # noqa: PLR0917 - called positionally
self,
exponent: _State,
dz: float,
rates: Complex[np.ndarray, "n_slots n_modes n_pol n_omega"],
states: Complex[np.ndarray, "n_slots n_modes n_pol n_omega"],
slots: np.ndarray,
spans: np.ndarray,
) -> Complex[np.ndarray, "n_used n_modes n_pol n_omega"]:
"""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
----------
exponent : numpy.ndarray
``x = Phi(z + h) - Phi(z)``.
dz : float
The step, m.
rates, states : numpy.ndarray
The history's rates and states, by slot.
slots : numpy.ndarray
The samples carried, newest first, ``int64``.
spans : numpy.ndarray
``1 - theta_j`` per sample: the flow's length in steps.
Returns
-------
numpy.ndarray
One carried row per sample.
"""
reference = exponent / dz
return np.stack(
[
np.exp(span * exponent) * ((rates[slot] - reference) * states[slot])
for slot, span in zip(slots, spans, strict=True)
]
)
[docs]
def carry_coupled( # noqa: PLR0917 - called positionally
self,
exponent: _State,
dz: float,
rows: tuple[_StoreRows, _StoreRows, list[np.ndarray | None]],
slots: np.ndarray,
spans: np.ndarray,
block: CoupledBlock,
) -> Complex[np.ndarray, "n_used n_modes n_pol n_omega"]:
"""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
----------
exponent : numpy.ndarray
``x = Delta Phi`` over the step.
dz : float
The step, m.
rows : tuple
The history's rates and states, by slot, and each slot's flow weights.
slots : numpy.ndarray
The samples carried, newest first.
spans : numpy.ndarray
``1 - theta_j`` per sample.
block : CoupledBlock
The step's frozen block.
Returns
-------
numpy.ndarray
One carried row per sample.
"""
rates, states, weights = rows
reference = exponent / dz
carried = []
for slot, span in zip(slots, spans, strict=True):
term = (rates[slot] - reference) * states[slot]
sample_weights = weights[slot]
if block.residual is not None and sample_weights is not None:
term = term + block.residual(states[slot], sample_weights)
if span != 0.0:
flow = coupled_moments(span * exponent, 0, block, span * dz)
term = flow.flow(term)
carried.append(term)
return np.stack(carried)
[docs]
def apply(
self,
moments: _MomentRows | MatrixMoments,
coefficients: np.ndarray,
values: list[_State],
dz: float,
) -> _State:
"""Return ``dz sum_k M_k (sum_j c_jk X_j)`` over the given rows.
Parameters
----------
moments : numpy.ndarray or MatrixMoments
``M_k`` from :meth:`moments` or :func:`coupled_moments`.
coefficients : numpy.ndarray
``c_jk``, shape ``(len(values), n_k)`` with ``n_k <= len(moments)``.
values : list of numpy.ndarray
The samples ``X_j``.
dz : float
The step, m.
Returns
-------
numpy.ndarray
The increment.
"""
total = np.zeros_like(values[0])
for k in range(coefficients.shape[1]):
combined = np.zeros_like(values[0])
for weight, value in zip(coefficients[:, k], values, strict=True):
if weight != 0.0:
combined = accumulate(combined, value, float(weight))
total += self._times_moment(moments, k, combined)
return dz * total
[docs]
def predict( # noqa: PLR0917 - buffers are a kernel's parameters
self,
state: _State,
flow: _State | MatrixMoments,
moments: _MomentRows | MatrixMoments,
store: Complex[np.ndarray, "n_slots n_modes n_pol n_omega"],
slots: np.ndarray,
coefficients: np.ndarray,
dz: float,
*,
factors: _Factors | None = None,
) -> _State:
"""Return the predicted field ``exp(x) u_n + dz sum_k M_k sum_j c_jk F_j``.
Parameters
----------
state : numpy.ndarray
The accepted state at the anchor.
flow : numpy.ndarray or MatrixMoments
``exp(x)``, the step's exact linear flow, or a coupled trial's.
moments : numpy.ndarray or MatrixMoments
``M_k`` from :meth:`moments` or :func:`coupled_moments`.
store : numpy.ndarray
The history rows.
slots : numpy.ndarray
The rows the predictor combines, newest first, ``int64``.
coefficients : numpy.ndarray
The predictor's Lagrange coefficients, shape ``(len(slots), len(slots))``.
dz : float
The step, m.
factors : numpy.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.
"""
values = _rows_read(store, slots, factors)
return self._times_flow(flow, state) + self.apply(
moments, coefficients, values, dz
)
[docs]
def correct( # noqa: PLR0917 - buffers are a kernel's parameters
self,
state: _State,
flow: _State | MatrixMoments,
moments: _MomentRows | MatrixMoments,
source: _State,
store: Complex[np.ndarray, "n_slots n_modes n_pol n_omega"],
slots: np.ndarray,
corrector: np.ndarray,
rows: np.ndarray,
dz: float,
mask: np.ndarray,
divisor: np.ndarray,
extra: tuple[_State, list[_State]] | None = None,
*,
factors: _Factors | None = None,
) -> tuple[_State, np.ndarray]:
"""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, moments : numpy.ndarray
As for :meth:`predict`.
source : numpy.ndarray
The untransported source at the predicted field.
store : numpy.ndarray
The history rows.
slots : numpy.ndarray
The rows after the source, newest first, ``int64``.
corrector : numpy.ndarray
The corrector's coefficients over ``X``, shape ``(width, n_k)``, zero past
its own nodes.
rows : numpy.ndarray
One defect's coefficients over ``X`` per row, shape ``(n_rows, width,
n_k)``.
dz : float
The step, m.
mask : numpy.ndarray
The in-band bins, Boolean.
divisor : numpy.ndarray
The norm's scale per bin.
extra : tuple or None, optional
The compensation's corrector term and its term in each defect, or
``None`` for a constant operator.
factors : numpy.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.
"""
values = [source, *_rows_read(store, slots, factors)]
advanced = self._times_flow(flow, state) + self.apply(
moments, corrector, values, dz
)
if extra is not None:
advanced = advanced + extra[0]
norms = np.empty(rows.shape[0])
for index, row in enumerate(rows):
defect = self.apply(moments, row, values, dz)
if extra is not None:
defect = defect + extra[1][index]
norms[index] = float(np.linalg.norm(defect[..., mask] / divisor[mask]))
return advanced, norms
@staticmethod
def _times_moment(
moments: _MomentRows | MatrixMoments, k: int, values: _State
) -> _State:
"""Return ``M_k values``: elementwise, or through a coupled trial's block.
- ``values``: the array, in the state's layout.
"""
if isinstance(moments, MatrixMoments):
return moments.apply(k, values)
return moments[k] * values
@staticmethod
def _times_flow(flow: _State | MatrixMoments, values: _State) -> _State:
"""Return the step's flow applied to an array: elementwise, or through a block.
- ``values``: the array, in the state's layout.
"""
if isinstance(flow, MatrixMoments):
return flow.flow(values)
return flow * values
def _rows_read(
store: Complex[np.ndarray, "n_slots n_modes n_pol n_omega"],
slots: np.ndarray,
factors: _Factors | None,
) -> list[_State]:
"""Return the history rows a pass combines, rotated when a carrier frame asks.
- ``factors``: their rotations, in the slots' order; ``None`` for the rows
themselves.
"""
if factors is None:
return [store[slot] for slot in slots]
return [factor * store[slot] for factor, slot in zip(factors, slots, strict=True)]