# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""The low-storage interaction-picture RK4 march: replay-only, accepted in place.
SEP 24 (``docs/dev/seps/archive/``,
``sep-0024-low-storage-interaction-picture-runge-kutta.md``).
Classical fourth-order Runge-Kutta in the interaction picture anchored at the step's
midpoint, Lawson's transformation [1]_ in Hult's arrangement [2]_. For a step
``[z_n, z_n + h]`` with ``z_m = z_n + h/2``, ``P = U(z_m, z_n)``, ``Q = U(z_n + h,
z_m)`` and ``U(z_2, z_1) = exp(Phi(z_2) - Phi(z_1))``, the step is
``g1 = P F(z_n, A_n)``, ``F2 = F(z_m, P A_n + h/2 g1)``,
``F3 = F(z_m, P A_n + h/2 F2)``, ``F4 = F(z_n + h, Q (P A_n + h F3))``,
``A_{n+1} = Q (P A_n + h/6 g1 + h/3 F2 + h/3 F3) + h/6 F4``,
with ``F`` the complete source (the response, the in-stage absorbers and the
``modified`` noise draw at the evaluation's position). Only forward flows are applied,
four per element, and on a constant operator ``P = Q = exp(h D / 2)``.
**The register form** (SEP 24 section 4.3) holds three field-sized registers beside the
source pipeline's scratch ``S``: the state ``A``, overwritten in place by ``P A`` and
then by the accepted step, the accumulator ``B`` and the stage register ``C``. A step
is four passes, each forming an input, evaluating ``F`` into ``S`` and folding it into
the registers:
==== ============== ======================================================
pass evaluation finish
==== ============== ======================================================
1 ``F1`` at z_n ``A <- P A``; ``g <- P S``; ``B <- A + h/6 g``;
``C <- A + h/2 g``
2 ``F2`` at z_m ``B <- B + h/3 S``; ``C <- A + h/2 S``
3 ``F3`` at z_m ``B <- B + h/3 S``; ``C <- Q (A + h S)``
4 ``F4`` at end ``A <- Q B + h/6 S``
==== ============== ======================================================
**The march** (the reference's
:class:`solprop.backends.numpy_ref.marches.low_storage.HostLowStorageMarch`; the native
session's replay) replays a prescribed schedule and never rejects, so it accepts each
step in place: from the start of the step's trial to its accept the engine is *in
flight* and every entry that reads or advances the state refuses it, until a load
replaces the state (SEP 24 section 6.2, ADR-050). It records no error estimate: the step
history's norm is 0.0, "not estimated" (section 6.3). Divergence is detected on the
accepted state's norm instead.
**The engine** holds the registers and makes the passes: it is a
:class:`~solprop.backends.engines.RungeKuttaEngine` with the documented destructive
trial (SEP 52 section 5.2). The reference's is
:class:`~solprop.backends.numpy_ref.engines.NumpyLowStorage`, over the workspace's
``lab_source`` and ``propagator``; native's is resident. The table keys
(:func:`table_steps`, :func:`schedule_key`) are stateless numerical code the two
backends share (SEP 47 Part III decision 5).
References
----------
.. [1] J. D. Lawson, "Generalized Runge-Kutta processes for stable systems with large
Lipschitz constants", SIAM Journal on Numerical Analysis 4, 372 (1967).
doi:10.1137/0704033
.. [2] J. Hult, "A fourth-order Runge-Kutta in the interaction picture method for
simulating supercontinuum generation in optical fibers", J. Lightwave Technol.
25, 3770 (2007). doi:10.1109/JLT.2007.909373
"""
import numpy as np
from jaxtyping import Float
from solprop.stepper.schedule import LANDING_ULPS, FixedSchedule
__all__ = ["schedule_key", "table_steps"]
[docs]
def table_steps(schedule: FixedSchedule) -> Float[np.ndarray, " n_steps"]:
"""Return the step each of a schedule's steps builds and keys the flow table on.
SEP 24 Q10, decided in phase 2: the mean step of the step's **run**, the longest
stretch of consecutive steps within :data:`~solprop.stepper.schedule.LANDING_ULPS`
ulps of the run's first, the ulps being of the run's farthest position (or of the
step, near the origin). :meth:`~solprop.stepper.schedule.FixedSchedule.uniform`
takes a segment's steps from differences of rounded positions, which differ in their
last bits by up to an ulp of the *position*: far from the origin that is many ulps
of the step, and a table keyed on one step's own value within ulps of the step was
rebuilt nearly every step. Keyed on the run's mean ``h_bar`` instead, a uniform
segment builds one table and reuses it; each flow's exponent is then off by ``|D| |h
- h_bar| / 2``, a few ulps of the position times ``|D|``, and the error does not
drift: the steps of a run sum to ``n h_bar`` to rounding, so the phase the flows
apply over a run is the run's own. A schedule whose steps all differ (a discovered
one) has runs of one step and keys each step on itself.
Parameters
----------
schedule : solprop.stepper.schedule.FixedSchedule
The schedule replayed.
Returns
-------
numpy.ndarray
One key per step, m, shape ``(n_steps,)``: constant over a run.
Examples
--------
>>> from solprop.backends.low_storage import table_steps
>>> from solprop.stepper import FixedSchedule
>>> schedule = FixedSchedule.uniform(0.0, 1.0, 0.1, save_planes=[0.25, 1.0])
>>> keys = table_steps(schedule)
>>> len(set(keys.tolist())), round(float(keys[0]), 12), round(float(keys[-1]), 12)
(2, 0.083333333333, 0.09375)
"""
steps, edges = schedule.steps, schedule.edges
keys = np.empty_like(steps)
start = 0
while start < steps.size:
end = start + 1
while end < steps.size:
reach = max(abs(float(edges[start])), abs(float(edges[end + 1])))
slack = LANDING_ULPS * float(
max(np.spacing(reach), np.spacing(steps[start]))
)
if abs(float(steps[end] - steps[start])) > slack:
break
end += 1
# A run of one keys on its own step, unrounded by the edges' difference.
keys[start:end] = (
steps[start]
if end - start == 1
else (edges[end] - edges[start]) / (end - start)
)
start = end
return keys
[docs]
def schedule_key(
keys: Float[np.ndarray, " n_steps"],
edges: Float[np.ndarray, " n_edges"],
z: float,
dz: float,
) -> float:
"""Return the table key of the schedule step from `z`, from :func:`table_steps`.
Found by position rather than by a step counter, so that it needs no count of the
steps taken before.
Parameters
----------
keys : numpy.ndarray
:func:`table_steps` of the schedule.
edges : numpy.ndarray
The schedule's edges, m.
z : float
Where the step starts, m.
dz : float
The step, m.
Returns
-------
float
The key, m.
"""
index = int(np.searchsorted(edges, z + 0.5 * dz)) - 1
return float(keys[min(max(index, 0), keys.size - 1)])