# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""The stepper section of a run: method, controller, step limits, schedule and planes.
:class:`StepperSettings` is section 7 of the kernel contract
(``docs/dev/kernel-contract.md``): the record that
:attr:`RunRequest.stepper <solprop.translate.run_request.RunRequest.stepper>` gathers a
request's method, error control, itinerary and planes back into, and that
:func:`~solprop.translate.run_request.describe_run` builds a request from. It is
run-specification data (``docs/dev/architecture.md`` section 3), so it lives beside the
tableaux, controllers and schedules it holds: below translation, which resolves it, and
below the backends and the driver, which read it. :data:`PropagatorMode` names the
stage-propagator choice it carries.
"""
from collections.abc import Sequence
from dataclasses import dataclass, fields
from typing import Literal
import numpy as np
from jaxtyping import Float
from solprop._ownership import frozen_copy
from solprop.exceptions import TranslationError
from solprop.stepper.controller import PIController
from solprop.stepper.low_storage import LowStorageRungeKutta
from solprop.stepper.multistep import Multistep
from solprop.stepper.schedule import FixedSchedule
from solprop.stepper.tableau import Tableau, continuous_extension
__all__ = ["PropagatorMode", "StepperSettings"]
PropagatorMode = Literal["auto", "tabulate", "recompute"]
"""Whether the backend tabulates the stage propagators or recomputes them.
``"auto"``, the default, is the backend's own choice, resolved at construction and
recorded in the run's metadata: ``tabulate`` for ``numpy_ref``, whose two complex
exponentials per stage the table is worth memoising, and ``recompute`` for
``native``, where both signs come from one real ``exp`` and a ``sincos`` in the
stage that formed them, so the table buys residency and nothing else
(``docs/dev/backends.md`` section 3.6). Either can still be asked for by name; the two
agree bitwise, so the choice is memory and not numbers.
"""
_ADAMS_CONTROL = frozenset({"rtol", "atol", "weights", "region"})
"""The controller fields the Adams march reads. It chooses its steps by its own
``safety``, ``min_factor`` and ``max_growth``
(:class:`~solprop.stepper.multistep.Multistep`)."""
def _refuse_unread_control(controller: PIController) -> None:
"""Refuse a controller setting the Adams march would ignore, by name."""
default = PIController(rtol=controller.rtol, atol=controller.atol)
unread = [
one.name
for one in fields(PIController)
if one.name not in _ADAMS_CONTROL
and getattr(controller, one.name) != getattr(default, one.name)
]
if unread:
msg = (
"Multistep() reads only the controller's rtol, atol, weights and region, "
"and chooses its steps by its own safety, min_factor and max_growth: "
f"PIController's {', '.join(unread)} would be ignored. Set them on "
"Multistep, or leave them at their defaults"
)
raise TranslationError(msg)
[docs]
@dataclass(frozen=True, eq=False)
class StepperSettings:
"""The tableau, the controller and the schedule of a run.
Section 7 of the kernel contract. The tolerances and the norm choice live in the
controller and nowhere else.
Attributes
----------
tableau : solprop.stepper.tableau.Tableau
Nodes, matrix, solution weights, error weights ``b - b_hat``, orders and the
first-same-as-last flag.
controller : solprop.stepper.controller.PIController
Tolerances, safety, growth caps, the PI exponents, the lag, the reject-free
switch, the estimator order and the norm weights.
dz_min : float
Floor on the controller's *proposal*, m. A proposal below it raises rather than
being clamped silently; it never applies to a landing step.
dz_max : float
Cap on the proposal, m.
dz_init : float
First step, m.
stretch : float
Landing stretch factor: a target within this multiple of the capped proposal is
landed on directly. 1 switches it off.
schedule : solprop.stepper.schedule.FixedSchedule or None
A fixed schedule to replay, whose edges must contain every save plane and hard
kink. ``None`` for an adaptive run.
save_planes : numpy.ndarray
Positions in z the driver will ask for, m, shape ``(n_z,)``, increasing. Steps
land on them exactly, unless `interpolate_planes` observes them inside
accepted steps.
propagator_mode : {'auto', 'tabulate', 'recompute'}
Whether the backend tabulates the stage propagator factors or recomputes them.
``"auto"`` leaves the choice to the backend, which records what it resolved.
integrator : solprop.stepper.multistep.Multistep or LowStorageRungeKutta or None
A low-call Adams method to step with instead of the tableau (SEP 13), the
low-storage RK4 march (SEP 24), or ``None`` for the Runge-Kutta march. With a
`schedule` an Adams method replays the schedule's steps (SEP 16 section 5);
the low-storage march replays one and nothing else.
interval_cap : bool
Whether a step is capped at the width of the operator-table interval it starts
in. The cumulative table makes the flow exact across intervals, so the cap is
off on the diagonal-flow routes and on for a coupled flow, whose flow error the
embedded estimate does not see (SEP 14 section 4.1). The Runge-Kutta and
low-storage marches read it; an Adams march caps by its method's own
:attr:`~solprop.stepper.multistep.Multistep.interval_cap`, which ``assemble``
records here.
auto_init : bool
Whether the start-up rule takes the step after the first from the first step's
own error estimate (``PIController.start_factor``); ``False`` grows from
`dz_init` at the growth cap.
interpolate_planes : bool
Step across the save planes and observe each inside its accepted step, through
the tableau's continuous extension or the Adams march's own polynomial (SEP 14
phase 3); ``False`` lands on them. The end of the run and every hard kink are
landed on either way.
step_planes : int
A positive ``k`` also saves the end of every ``k``-th accepted step: the
march returns to its session there, short of its target, and marches on
(SEP 14 phase 3). ``0`` saves the requested planes only.
Raises
------
TranslationError
If the step caps are not ordered, the stretch is below one, the save
planes are not increasing and positive, or the low-storage march is asked for
without a schedule, with interpolated planes or with a schedule step longer
than `dz_max`.
Examples
--------
>>> from solprop.stepper import DOPRI5, PIController
>>> from solprop.stepper.settings import StepperSettings
>>> settings = StepperSettings(DOPRI5, PIController(rtol=1e-8, atol=1e-14),
... 1e-9, 0.1, 1e-3, 1.1, None, [0.5, 1.0], "tabulate")
>>> settings.save_planes.tolist()
[0.5, 1.0]
"""
tableau: Tableau
controller: PIController
dz_min: float
dz_max: float
dz_init: float
stretch: float
schedule: FixedSchedule | None
save_planes: Float[np.ndarray, " n_z"] | Sequence[float]
propagator_mode: PropagatorMode
integrator: Multistep | LowStorageRungeKutta | None = None
interval_cap: bool = True
auto_init: bool = False
interpolate_planes: bool = False
step_planes: int = 0
def __post_init__(self) -> None:
"""Adopt a read-only plane array and check the caps.
Raises
------
TranslationError
Naming the offending field.
"""
planes = frozen_copy(np.reshape(self.save_planes, -1), np.float64)
object.__setattr__(self, "save_planes", planes)
if planes.size == 0 or not np.all(np.diff(planes) > 0.0):
msg = f"save_planes must be non-empty and increasing, got {planes}"
raise TranslationError(msg)
if planes[0] <= 0.0:
msg = f"save_planes must be positive, got {planes[0]!r} first"
raise TranslationError(msg)
if not 0.0 < self.dz_min <= self.dz_init <= self.dz_max:
msg = (
f"the step caps must satisfy 0 < dz_min <= dz_init <= dz_max, got "
f"{self.dz_min!r}, {self.dz_init!r}, {self.dz_max!r}"
)
raise TranslationError(msg)
if not self.stretch >= 1.0:
msg = f"stretch must be at least 1, got {self.stretch!r}"
raise TranslationError(msg)
if self.step_planes < 0:
msg = f"step_planes must be 0 (off) or a positive count: {self.step_planes}"
raise TranslationError(msg)
if isinstance(self.integrator, LowStorageRungeKutta):
self._check_low_storage(self.integrator)
if isinstance(self.integrator, Multistep):
_refuse_unread_control(self.controller)
if self.interpolate_planes and self.schedule is not None:
msg = "interpolated planes lie inside adaptive steps; a schedule lands"
raise TranslationError(msg)
if (
self.interpolate_planes
and self.integrator is None
and continuous_extension(self.tableau) is None
):
msg = f"{self.tableau.name} has no continuous extension; use DOPRI5"
raise TranslationError(msg)
def _check_low_storage(self, method: LowStorageRungeKutta) -> None:
"""Refuse what the low-storage march cannot replay, before any allocation.
The march accepts every step in place and has no estimate, so it replays a
prescribed schedule and nothing else (SEP 24 section 5); `dz_max` stays a true
statement about the run it records, so a longer schedule step is refused.
"""
if self.schedule is None:
msg = (
f"the {method.name} march replays a prescribed schedule; pass "
"schedule=FixedSchedule.uniform(...), or step adaptively with "
"RungeKutta()"
)
raise TranslationError(msg)
if self.interpolate_planes:
msg = (
f"the {method.name} march lands on its schedule's edges and has no "
"dense output; drop interpolate_planes"
)
raise TranslationError(msg)
# A schedule's steps are differences of rounded positions, so one may exceed
# the step it was cut to by a few ulps of those positions.
span = max(abs(self.schedule.z_start), abs(self.schedule.z_end), self.dz_max)
longest = self.schedule.max_step
if longest > self.dz_max + 4.0 * float(np.spacing(span)):
msg = (
f"the schedule's longest step is {longest:.6g} m and dz_max is "
f"{self.dz_max:.6g} m; the {method.name} march records dz_max as a "
"limit of the run, so raise dz_max to the schedule's longest step"
)
raise TranslationError(msg)
[docs]
@property
def z_end(self) -> float: # numpydoc ignore=RT01
"""Last save plane, where the run stops, m.
Examples
--------
>>> from solprop.stepper import DOPRI5, PIController
>>> from solprop.stepper.settings import StepperSettings
>>> StepperSettings(DOPRI5, PIController(rtol=1e-8, atol=1e-14), 1e-9, 0.1,
... 1e-3, 1.1, None, [0.5, 1.0], "tabulate").z_end
1.0
"""
return float(np.max(self.save_planes))