# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""The phi functions and exponential Adams weights, in NumPy (SEP 16 sections 4.2-4.3).
Exponential Adams integrates the polynomial through untransported source samples
exactly against the linear flow. For a constant operator ``D``, a step ``h`` and the
Lagrange basis ``ell_j(theta) = sum_k c_jk theta**k`` on the normalised nodes,
w_j(x) = int_0^1 exp((1 - theta) x) ell_j(theta) dtheta
= sum_k c_jk k! phi_{k+1}(x),
with ``x = h D`` per element and ``phi_r(x) = sum_m x**m / (m + r)!``. At a fraction
``xi`` of the step the same integral to ``xi`` is
``sum_k c_jk k! xi**(k+1) phi_{k+1}(xi x)``. At ``x = 0`` these are the ordinary
Adams weights (:func:`solprop.stepper.multistep.integrated_weights`).
The phi functions are evaluated by two algorithms, each where it is stable:
- **near zero** (``|x| <= 3``, ``PHI_JOIN``): scale to ``y = x / 2**s`` with
``|y| <= 1/2``, sum the Taylor series of the highest function to a fixed number of
terms, recur down with ``phi_k(y) = 1/k! + y phi_{k+1}(y)``, which contracts an error
by ``|y|`` and never divides by ``y``, and undo the scaling by the doubling identity
``phi_k(2y) = [exp(y) phi_k(y) + sum_{j=1}^k phi_j(y) / (k - j)!] / 2**k``, obtained
by splitting the defining integral at one half [1]_ [2]_;
- **away from zero** (``|x| > 3``): recur up from ``phi_0 = exp(x)``,
``phi_k(x) = (phi_{k-1}(x) - 1/(k-1)!) / x``, whose division by ``|x| > 3`` contracts
the error of every earlier function.
Both are checked against augmented matrix exponentials and independent quadrature in
``tests/backends/test_exponential_weights.py``, on both sides of the join. This module
is the reference the native backend's moment kernels are checked against.
A coupled flow's matrix exponentials -- its actions and, for the exponential Adams
formulation, the augmented exponentials of its moments -- are formed by scaling, a
Taylor series and squaring in both backends, with the one set of constants here
(:data:`FLOW_TAYLOR_ORDER`, :data:`FLOW_TAYLOR_SCALE`, :data:`FLOW_MAX_SQUARINGS`): the
reference reads them, and the native adapter hands the scale and the squaring cap to
its workspace's flow guard.
References
----------
.. [1] S. M. Cox and P. C. Matthews, "Exponential time differencing for stiff
systems", J. Comput. Phys. 176, 430 (2002). doi:10.1006/jcph.2002.6995
.. [2] M. Hochbruck and A. Ostermann, "Exponential integrators", Acta Numerica 19,
209 (2010), section 2. doi:10.1017/S0962492910000048
"""
import dataclasses
import math
from collections.abc import Sequence
from dataclasses import dataclass
import numpy as np
from jaxtyping import Complex, Float, Inexact
from solprop._helpers import PLAIN, Helpers
from solprop.exceptions import BackendError, StepperError
from solprop.stepper.multistep import (
MAX_ADAMS_ORDER,
CarrierFrame,
Multistep,
lagrange_coefficients,
)
from solprop.stepper.settings import StepperSettings
from solprop.translate.chebyshev import PiecewiseChebyshev
from solprop.translate.expansion import ParameterExpansion
from solprop.translate.linop import LinearOperator
from solprop.translate.problem import PropagationProblem
__all__ = [
"FLOW_MAX_SQUARINGS",
"FLOW_TAYLOR_ORDER",
"FLOW_TAYLOR_SCALE",
"MAX_PHI_ORDER",
"PHI_JOIN",
"CarrierChord",
"CarrierReference",
"carrier_chord",
"carrier_reference",
"exponential_weights",
"phi_functions",
"refuse_adams",
"refuse_carrier_frame",
]
MAX_PHI_ORDER = MAX_ADAMS_ORDER + 2
"""Highest phi function evaluated: the corrector's ``MAX_ADAMS_ORDER + 1`` nodes need
``phi_1`` to ``phi_{MAX_ADAMS_ORDER + 1}``, and one more serves a neighbouring order."""
PHI_JOIN = 3.0
"""``|x|`` above which the phi functions are recurred up from ``exp(x)``.
Below it the upward recurrence loses digits to the subtraction of ``1/(k-1)!``: at
order eight, 291 ulp of the natural scale at ``|x| = 2`` and 32 at 3, against
augmented exponentials. Above it the scaled series would need more than three
doublings. Three keeps both sides within the witnesses' 256 ulp with a margin and
bounds the doublings, the most expensive part of the near branch (SEP 16 phase 3;
eight, the SEP 15 study's join, cost up to four)."""
FLOW_TAYLOR_ORDER = 16
"""Degree of the Taylor series a coupled flow's scaled exponential is summed to.
Scaling brings the row-sum norm below :data:`FLOW_TAYLOR_SCALE`, so the truncated tail
is at most ``FLOW_TAYLOR_SCALE**(n+1)/(n+1)!``, which is 2.1e-20 at this degree --
below the rounding of the squarings that follow it and of the two unitary products
around it. The alternative, a Pade approximant, buys a lower degree at the cost of a
solve per frequency; the reference takes the series (``docs/dev/architecture.md``
section 3: physics and reference code carry no performance tricks)."""
FLOW_TAYLOR_SCALE = 0.5
"""Row-sum norm a coupled flow's exponent is scaled below before its series."""
FLOW_MAX_SQUARINGS = 30
"""Largest number of squarings a coupled flow's exponential may need before refusal.
``2**30`` times the scale is a step whose own generator spans 21 orders of magnitude in
the exponent; a problem that needs it has not been certified by anything the
translation layer measured."""
_SERIES_TERMS = 24
"""Taylor terms of the highest phi function at ``|y| <= 1/2``.
The tail after ``M`` terms is below ``|y|**M / (M + r)!`` times a geometric factor of at
most two: ``2**-24 / 24!`` is 1e-31, far under one ulp of ``phi_r(y) >= 1/(2 r!)``."""
_RECIPROCAL_FACTORIAL = tuple(1.0 / math.factorial(k) for k in range(MAX_PHI_ORDER + 2))
[docs]
def phi_functions(
x: Inexact[np.ndarray, "*shape"] | complex, order: int
) -> Complex[np.ndarray, " n_phi *shape"]:
"""Return ``phi_0(x)`` to ``phi_order(x)`` for each element of `x`.
``phi_0(x) = exp(x)`` and ``phi_r(x) = int_0^1 exp((1 - theta) x)
theta**(r-1) / (r-1)! dtheta``.
Parameters
----------
x : numpy.ndarray or complex
The arguments, dimensionless (a step times the linear operator). Their real
parts must not exceed 700, where ``exp`` overflows.
order : int
The highest function, in ``[1, MAX_PHI_ORDER]``.
Returns
-------
numpy.ndarray
``phi_r(x)`` along a new leading axis of length ``order + 1``.
Raises
------
StepperError
If an argument is not finite or overflows, or the order is out of range.
Examples
--------
>>> import numpy as np
>>> from solprop.backends.exponential import phi_functions
>>> values = phi_functions(np.array([0.0, 1.0]), 2)
>>> np.round(values.real, 12).tolist()
[[1.0, 2.718281828459], [1.0, 1.718281828459], [0.5, 0.718281828459]]
"""
if not 1 <= order <= MAX_PHI_ORDER:
msg = f"phi order must lie in [1, {MAX_PHI_ORDER}], got {order!r}"
raise StepperError(msg)
values = np.asarray(x, dtype=np.complex128)
if not np.all(np.isfinite(values)) or np.any(values.real > 700.0):
msg = "phi arguments must be finite with real parts at most 700"
raise StepperError(msg)
flat = values.reshape(-1)
out = np.empty((order + 1, flat.size), dtype=np.complex128)
far = np.abs(flat) > PHI_JOIN
if np.any(far):
out[:, far] = _phi_far(flat[far], order)
if not np.all(far):
out[:, ~far] = _phi_near(flat[~far], order)
return out.reshape((order + 1, *values.shape))
def _phi_far(
x: Complex[np.ndarray, " n_elements"], order: int
) -> Complex[np.ndarray, "n_phi n_elements"]:
"""Recur up from ``exp(x)``: stable where every ``|x|`` exceeds the join."""
out = np.empty((order + 1, x.size), dtype=np.complex128)
out[0] = np.exp(x)
for k in range(1, order + 1):
out[k] = (out[k - 1] - _RECIPROCAL_FACTORIAL[k - 1]) / x
return out
def _phi_near(
x: Complex[np.ndarray, " n_elements"], order: int
) -> Complex[np.ndarray, "n_phi n_elements"]:
"""Scale, sum the highest series, recur down and double back, near zero."""
magnitude = np.abs(x)
# The number of halvings bringing |x| to at most 1/2; zero at and below it.
squarings = np.where(
magnitude > 0.5, np.ceil(np.log2(np.maximum(magnitude, 0.5) / 0.5)), 0.0
).astype(np.int64)
y = x / np.exp2(squarings)
out = np.empty((order + 1, x.size), dtype=np.complex128)
term = np.full(x.size, _RECIPROCAL_FACTORIAL[order], dtype=np.complex128)
total = term.copy()
for m in range(1, _SERIES_TERMS):
term = term * y / (m + order)
total = total + term
out[order] = total
for k in range(order - 1, 0, -1):
out[k] = _RECIPROCAL_FACTORIAL[k] + y * out[k + 1]
out[0] = np.exp(y)
for level in range(int(squarings.max(initial=0))):
active = squarings > level
old = out[:, active]
doubled = np.empty_like(old)
doubled[0] = old[0] * old[0]
for k in range(1, order + 1):
total = old[0] * old[k]
for j in range(1, k + 1):
total = total + old[j] * _RECIPROCAL_FACTORIAL[k - j]
doubled[k] = total / 2.0**k
out[:, active] = doubled
return out
[docs]
def exponential_weights(
nodes: Float[np.ndarray, " n_nodes"] | Sequence[float],
x: Inexact[np.ndarray, "*shape"] | complex,
upper: float = 1.0,
*,
helpers: Helpers = PLAIN,
) -> Complex[np.ndarray, " n_nodes *shape"]:
"""Return the exponential Adams weights of distinct nodes at each argument.
``w_j = int_0^upper exp((upper - theta) x) ell_j(theta) dtheta``, so that
``exp(upper x) u_n + h sum_j w_j F_j`` advances ``u' = D u + F`` by ``upper h``
when ``F`` is the polynomial interpolating the samples ``F_j`` at the nodes and
``x = h D``.
Parameters
----------
nodes : numpy.ndarray or list of float
Distinct normalised positions ``(z_j - z_n) / h``.
x : numpy.ndarray or complex
``h D`` per element, dimensionless.
upper : float, optional
The fraction of the step integrated, in ``[0, 1]``.
helpers : solprop._helpers.Helpers, optional
The implementation of the Lagrange basis (SEP 29 section 6.6); the plain
Python forms by default.
Returns
-------
numpy.ndarray
One weight per node along a new leading axis, each of `x`'s shape.
Raises
------
StepperError
If the nodes are not distinct and finite, `upper` lies outside ``[0, 1]`` or an
argument overflows.
Examples
--------
At ``x = 0`` the weights are the ordinary Adams-Moulton ones:
>>> import numpy as np
>>> from solprop.backends.exponential import exponential_weights
>>> (24 * exponential_weights([1, 0, -1, -2], 0.0)).real.round(12).tolist()
[9.0, 19.0, -5.0, 1.0]
"""
if not 0.0 <= upper <= 1.0:
msg = f"the integrated fraction must lie in [0, 1], got {upper!r}"
raise StepperError(msg)
coefficients = lagrange_coefficients(nodes, helpers=helpers)
count = coefficients.shape[0]
arguments = np.asarray(x, dtype=np.complex128)
phi = phi_functions(upper * arguments, count)
# The moment of theta**k is k! upper**(k + 1) phi_{k+1}(upper x).
scaled = np.array(
[math.factorial(k) * upper ** (k + 1) for k in range(count)], dtype=np.float64
)
moments = phi[1 : count + 1] * scaled.reshape((count, *([1] * arguments.ndim)))
return np.tensordot(coefficients, moments, axes=(1, 0))
[docs]
@dataclass(frozen=True)
class CarrierChord:
"""The reference element's cumulative operator alone (SEP 35 sections 6.1, 6.4).
The operator's own representation restricted to column 0, polarisation 0 and the
reference bin: its chord over a step is the reference element's exponent, to
rounding the one the backend forms, at one scalar. The step cap reads it for every
proposal, and a backend that forms its exponent elsewhere (the native engine, on a
device too) takes its shift from it with nothing read back.
Attributes
----------
constant : numpy.ndarray or None
``D`` at the element, 1/m, shape ``()``, for a constant operator.
expansion : solprop.translate.expansion.ParameterExpansion or None
The expansion with its terms at the element, for an expansion.
table : solprop.translate.chebyshev.PiecewiseChebyshev or None
The z table at the element, for a table.
"""
constant: Complex[np.ndarray, ""] | None = None
expansion: ParameterExpansion | None = None
table: PiecewiseChebyshev | None = None
[docs]
def exponent(self, z1: float, z2: float) -> Complex[np.ndarray, ""]:
"""Return ``Phi(z2) - Phi(z1)`` at the element.
Parameters
----------
z1, z2 : float
Positions in m, inside the operator's span.
Returns
-------
numpy.ndarray
Dimensionless, shape ``()``.
"""
if self.constant is not None:
return np.asarray(self.constant * (z2 - z1))
if self.expansion is not None:
return np.asarray(self.expansion.delta(z1, z2), dtype=np.complex128)
assert self.table is not None
return np.asarray(self.table(z2) - self.table(z1), dtype=np.complex128)
[docs]
def carrier_chord(linear: LinearOperator, index: int) -> CarrierChord | None:
"""Return the reference element's operator alone, or ``None`` for a separable one.
Parameters
----------
linear : solprop.translate.linop.LinearOperator
The cumulative operator.
index : int
The reference bin.
Returns
-------
CarrierChord or None
``None`` for the separable (spatial) representation, which the carrier frame
refuses.
"""
def _element(values: np.ndarray) -> np.ndarray:
"""Return ``values[..., 0, 0, index]`` over its leading axes.
- ``values``: a representation's array, its last three axes the state's layout.
- Returns: column 0, polarisation 0 and the reference bin, every leading axis
kept.
"""
column = min(index, values.shape[-1] - 1)
return np.array(values[..., 0, 0, column], order="C", copy=True)
if linear.phi_constant is not None:
return CarrierChord(constant=_element(linear.phi_constant))
if linear.phi_expansion is not None:
expansion = linear.phi_expansion
return CarrierChord(
expansion=dataclasses.replace(expansion, terms=_element(expansion.terms))
)
if linear.phi_coefficients is not None:
table = linear.polynomial
return CarrierChord(
table=dataclasses.replace(table, coefficients=_element(table.coefficients))
)
return None
[docs]
@dataclass(frozen=True)
class CarrierReference:
"""Where a run's carrier frame takes its shift, fixed for the run (SEP 35 6.1).
The shift is ``sigma = i Im x[0, 0, bin]``, ``x`` the
trial's own exponent ``Phi(z + h) - Phi(z)``: column 0 is the frame's mode
(``build_phi`` fixes the frame on the first mode; a coupled route's carrier is the
same in every channel), polarisation 0. The change of variable is exact for any
shift, so the choice of bin only changes how smooth the interpolated source is.
Attributes
----------
policy : {'scalar'}
The policy asked for (:data:`solprop.stepper.multistep.CarrierFrame`).
bin : int or None
The active bin nearest the reference frequency, ties to the lower index;
``None`` where the policy is inert (``sigma = 0`` for the run).
omega : float or None
That bin's angular frequency, rad/s; ``None`` with `bin`.
reason : str
How the reference was chosen, or why the policy is inert, for the run's log.
chord : CarrierChord or None, optional
The reference element's operator alone (:func:`carrier_chord`), for the step
cap and a backend that forms its shift on the host; ``None`` when inert.
"""
policy: CarrierFrame
bin: int | None
omega: float | None
reason: str
chord: CarrierChord | None = None
[docs]
@property
def active(self) -> bool: # numpydoc ignore=RT01
"""Whether the shift can be nonzero.
``False`` when the run takes ``sigma = 0``, the present arithmetic exactly.
"""
return self.bin is not None
[docs]
def shift(
self, exponent: Complex[np.ndarray, "n_modes n_pol n_omega"]
) -> Complex[np.ndarray, "1 1 1"]:
"""Return the shift for a trial's exponent.
Parameters
----------
exponent : numpy.ndarray
``x = Phi(z + h) - Phi(z)``, in the canonical layout.
Returns
-------
numpy.ndarray
Purely imaginary, shape ``(1, 1, 1)``, broadcasting against the state.
Raises
------
BackendError
If the policy is inert: such a run takes the unshifted arithmetic.
"""
if self.bin is None:
msg = f"the carrier frame is inert for this run: {self.reason}"
raise BackendError(msg)
# The real part (loss) is never shifted (SEP 35 section 10).
phase = np.imag(exponent[0, 0, self.bin]).reshape((1, 1, 1))
return 1j * phase
[docs]
def phase(self, exponent: Complex[np.ndarray, "n_modes n_pol n_omega"]) -> float:
"""Return the carrier phase, for the step cap.
Parameters
----------
exponent : numpy.ndarray
``x`` over a proposed step.
Returns
-------
float
``|Im x[0, 0, bin]|``, rad; 0 when the policy is inert.
"""
if self.bin is None:
return 0.0
return float(np.abs(np.imag(exponent[0, 0, self.bin])))
[docs]
def chord_phase(self, z1: float, z2: float) -> float:
"""Return the carrier phase from the chord alone.
Parameters
----------
z1, z2 : float
The proposed step's ends, m.
Returns
-------
float
``|Im (Phi(z2) - Phi(z1))|`` at the reference element, rad; 0 when
the policy is inert.
Raises
------
BackendError
If the reference has no chord (a separable operator).
"""
if self.bin is None:
return 0.0
if self.chord is None:
msg = "the carrier frame's reference has no chord on this operator"
raise BackendError(msg)
return float(np.abs(np.imag(self.chord.exponent(z1, z2))))
[docs]
def carrier_reference(
problem: PropagationProblem, method: Multistep
) -> CarrierReference | None:
"""Return where a run's carrier frame takes its shift, or ``None`` when off.
The reference rule of SEP 35 section 6.1. An envelope grid without the third
harmonic subtracts ``beta_0``, so its shift would be the table's rounding: the
policy is inert there and the run is the present arithmetic exactly. An envelope
grid with the third harmonic keeps the carrier phase whole, its operator is the
field grid's, and it is treated as one. The reference frequency is the grids'
``omega0``; a custom frame with another reference changes only how much of the
rotation the shift removes, never the step's exactness.
Parameters
----------
problem : solprop.translate.problem.PropagationProblem
The problem.
method : solprop.stepper.multistep.Multistep
The method.
Returns
-------
CarrierReference or None
``None`` for ``carrier_frame="off"`` or the interaction formulation.
"""
policy = method.carrier_frame
if policy == "off" or method.formulation != "exponential":
return None
grids = problem.grids
if problem.grid_kind == "envelope" and grids.carrier_2w0 is None:
return CarrierReference(
policy,
None,
None,
"an envelope grid without the third harmonic removes beta_0: sigma = 0",
)
nearest = _nearest_bin(grids.omega, grids.omega0)
if not bool(grids.active_mask[nearest]):
return CarrierReference(
policy,
None,
None,
f"the bin nearest the reference frequency ({nearest}) is inactive: "
"sigma = 0",
)
omega = float(grids.omega[nearest])
return CarrierReference(
policy,
nearest,
omega,
f"reference bin {nearest} at {omega:.6e} rad/s",
carrier_chord(problem.linear, nearest),
)
def _nearest_bin(omega: Float[np.ndarray, " n_omega"], omega0: float) -> int:
"""Return the bin nearest `omega0`, ties going to the lower index.
- ``omega``: the frequency axis, rad/s, in the grid's own order.
- ``omega0``: the reference frequency, rad/s.
"""
# argmin returns the first of equal distances: the lower index of the axis's order.
return int(np.argmin(np.abs(omega - omega0)))
def _carrier_refusal(
policy: CarrierFrame,
backend: str,
delivered: frozenset[str],
geometry: str | None,
) -> str | None:
"""Return why `backend` cannot step a carrier frame, or ``None`` when it can.
- ``geometry``: the spatial geometry's kind; ``None`` on a guided route.
"""
if policy == "off":
return None
if policy not in delivered:
return (
f"{backend}: Multistep(carrier_frame={policy!r}) is not delivered on this "
"backend; pass carrier_frame='off'"
)
if geometry is not None:
return (
f"{backend}: Multistep(carrier_frame={policy!r}) is not yet qualified on "
f"a free-space route ({geometry!r} geometry); pass carrier_frame='off'"
)
return None
[docs]
def refuse_carrier_frame(
problem: PropagationProblem,
stepper: StepperSettings,
backend: str,
*,
delivered: frozenset[str] = frozenset(),
) -> None:
"""Refuse a carrier frame where it is not yet delivered (SEP 35 section 5).
Parameters
----------
problem : solprop.translate.problem.PropagationProblem
The problem.
stepper : solprop.stepper.settings.StepperSettings
The run's stepper section, whose method is checked.
backend : str
The backend's name, for the message.
delivered : frozenset of str, optional
The policies this backend steps; none by default.
Raises
------
BackendError
Naming the policy and what does not deliver it.
"""
method = stepper.integrator
if not isinstance(method, Multistep):
return
geometry = problem.transform.geometry
refusal = _carrier_refusal(
method.carrier_frame,
backend,
delivered,
None if geometry is None else geometry.kind,
)
if refusal is not None:
raise BackendError(refusal)
[docs]
def refuse_adams(
problem: PropagationProblem,
stepper: StepperSettings,
backend: str,
*,
delivered: frozenset[str] = frozenset(),
) -> None:
"""Refuse what an Adams march does not execute (SEP 13 sections 2 and 6.2).
The interaction formulation's history is of source samples transported along a
diagonal flow, so it refuses a coupled flow by name rather than transport the
history through inverse actions (SEP 16 Q3); the exponential formulation steps every
coupled flow the problem admits
(:func:`solprop.translate.admission.check_general_route`). Either refuses the
carrier frames the backend does not deliver (:func:`refuse_carrier_frame`). The
``modified`` noise is admitted for both formulations (SEP 16 section 4.4): its draw
is fixed for the run and added to each sample's field at that sample's own
position, never to the propagating state, so conditional on the draw the source is
a deterministic, nonautonomous function of position that the history interpolates.
The split-step temporal collar is admitted: it changes the state only inside the
collar, where its first-order splitting error already lies (``docs/dev/stepper.md``
section 6), and it removes the collar's stability limit, which binds the Adams
methods long before Runge-Kutta's (SEP 13 phase 2).
Parameters
----------
problem : solprop.translate.problem.PropagationProblem
The problem.
stepper : solprop.stepper.settings.StepperSettings
The run's stepper section; any method but
:class:`~solprop.stepper.multistep.Multistep` passes untouched.
backend : str
The backend's name, for the message.
delivered : frozenset of str, optional
The carrier-frame policies this backend steps; none by default.
Raises
------
BackendError
Naming what the Adams march does not step here.
Examples
--------
>>> from solprop.backends.exponential import refuse_adams
>>> from solprop.driver import Simulation
>>> simulation = Simulation.from_gnlse(
... 0.11, 0.01, [0.0, 0.0, -1.183e-26], wavelength=835e-9,
... wavelength_limits=(500e-9, 2e-6), trange=1e-12,
... width=100e-15, peak_power=9.8, shape="sech",
... )
>>> request = simulation.run_request()
>>> refuse_adams(simulation.translate(), request.stepper, "numpy_ref") is None
True
"""
integrator = stepper.integrator
if not isinstance(integrator, Multistep):
return
if (
problem.linear.coupled_flow is not None
and integrator.formulation != "exponential"
):
msg = (
f"{backend}: the {integrator.name} integrator does not step a problem "
"with a coupled linear flow; use Multistep(formulation='exponential') or "
"the Runge-Kutta march"
)
raise BackendError(msg)
refuse_carrier_frame(problem, stepper, backend, delivered=delivered)