Source code for solprop.translate.run_request

# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later

"""The immutable run request a backend prepares beside its problem (SEP 47 section 6.3).

The problem (:class:`~solprop.translate.problem.PropagationProblem`) says *what* is
propagated; a :class:`RunRequest` says *how it is run*. Python resolves every default
before preparation, so a backend never invents a policy, and the request never changes
during a run: stop and snapshot requests travel separately
(:mod:`solprop.backends.session`). Its parts separate method selection from error
scaling and acceptance:

- :class:`IntegrationSpec` names the method (:class:`MethodKind`: an embedded
  Runge-Kutta tableau, the low-call Adams family or the fixed low-storage replay);
- :class:`ErrorControlSpec` holds the tolerances, norm, controller and step limits;
- :class:`ReplaySpec` holds a fixed itinerary, when one is replayed;
- :class:`ObservationRequest` holds the planes, dense output, step planes, statistics
  and field retention;
- :class:`BoundaryRequest` configures the boundary monitor;
- :class:`HistoryPolicy` (:class:`HistoryRetention`) says when the method's history is
  kept for a resume.

:func:`describe_run` builds one from the resolved
:class:`~solprop.stepper.settings.StepperSettings` and the run's settings;
:func:`solprop.translate.assembly.assemble` returns it beside its problem, which
:meth:`solprop.driver.simulation.Simulation.run_request` gives out, and
:meth:`RunRequest.for_run` adapts it to one run's start, retention, monitor and history.
"""

from __future__ import annotations

import dataclasses
import enum
import functools
from dataclasses import dataclass

import numpy as np
from jaxtyping import Float

from solprop._ownership import frozen_copy
from solprop.exceptions import TranslationError
from solprop.monitor import BoundaryMonitor
from solprop.output.store import FieldRetention
from solprop.stats import StatsSpec
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.settings import PropagatorMode, StepperSettings
from solprop.stepper.tableau import Tableau

__all__ = [
    "MARCH_SNAPSHOT_AUTO_BYTES",
    "BoundaryRequest",
    "ErrorControlSpec",
    "HistoryPolicy",
    "HistoryRetention",
    "IntegrationSpec",
    "MethodKind",
    "ObservationRequest",
    "ReplaySpec",
    "RunRequest",
    "describe_run",
]

MARCH_SNAPSHOT_AUTO_BYTES = 256 * 2**20
"""The largest Adams march snapshot a run keeps with ``resume_history=None``, bytes.

The snapshot -- the state and the history's rows, a few to sixty copies of the state --
is rewritten at every save plane; a state too large for that to be cheap keeps none
unless asked to, and its resume starts the history afresh (SEP 47 section 5.5).
"""


[docs] class MethodKind(enum.Enum): """The integration method family. Attributes ---------- RUNGE_KUTTA : str An embedded Runge-Kutta tableau, adaptive or replayed. ADAMS : str The low-call Adams family (``Multistep``). LOW_STORAGE : str The fixed-schedule low-storage RK4IP replay (SEP 24). """ RUNGE_KUTTA = "runge_kutta" ADAMS = "adams" LOW_STORAGE = "low_storage"
[docs] @dataclass(frozen=True) class IntegrationSpec: """Which method integrates the run, and its options. Attributes ---------- kind : MethodKind The method family. tableau : solprop.stepper.tableau.Tableau The embedded Runge-Kutta tableau. An Adams run still names the tableau that starts it and that its error control is scaled against. method : Multistep, LowStorageRungeKutta or None The Adams or low-storage method object, immutable; ``None`` for Runge-Kutta. propagator_mode : {'auto', 'tabulate', 'recompute'} How the linear propagator is formed. """ kind: MethodKind tableau: Tableau method: Multistep | LowStorageRungeKutta | None propagator_mode: PropagatorMode
[docs] @dataclass(frozen=True) class ErrorControlSpec: """Tolerances, the controller and the step limits. Attributes ---------- controller : solprop.stepper.controller.PIController The controller and its norm. dz_min : float The step floor, m. dz_max : float The step ceiling, m. dz_init : float The first proposal, m. stretch : float The fraction by which a step may stretch to land on a plane. auto_init : bool Whether the first proposal is chosen from the launch state. interval_cap : bool Whether a step is capped to the interval it starts in. """ controller: PIController dz_min: float dz_max: float dz_init: float stretch: float auto_init: bool interval_cap: bool
[docs] @dataclass(frozen=True) class ReplaySpec: """A fixed itinerary, replayed rather than chosen. Attributes ---------- schedule : solprop.stepper.schedule.FixedSchedule The step edges. """ schedule: FixedSchedule
[docs] @dataclass(frozen=True, eq=False) class ObservationRequest: """What a run observes and keeps. Attributes ---------- save_planes : numpy.ndarray The requested planes, m, increasing, read-only. start_plane : int The first save plane strictly beyond the starting state. dense : bool Whether planes are interpolated from dense output rather than landed on. step_planes : int Observe the endpoint of every ``step_planes``-th accepted step; ``0`` for none. stats : solprop.stats.StatsSpec The plane statistics, and the periodic subset with its period. retention : solprop.output.store.FieldRetention Which observed planes keep their field. """ save_planes: Float[np.ndarray, " n_z"] start_plane: int dense: bool step_planes: int stats: StatsSpec retention: FieldRetention
[docs] @dataclass(frozen=True, eq=False) class BoundaryRequest: """What the boundary watches. Attributes ---------- monitor : solprop.monitor.BoundaryMonitor or None A fresh, unrecorded monitor -- weights, collar, thresholds and any transverse edge -- that the session takes over and feeds; ``None`` watches nothing. """ monitor: BoundaryMonitor | None = None
[docs] class HistoryRetention(enum.Enum): """When the method's history is kept for a resume. Attributes ---------- AUTO : str Kept while it is at most :data:`MARCH_SNAPSHOT_AUTO_BYTES`; omitted beyond that, which a resume reports. REQUIRED : str Always kept; a snapshot that cannot keep it fails rather than downgrading. OFF : str Never kept, by explicit choice. """ AUTO = "auto" REQUIRED = "required" OFF = "off"
[docs] @dataclass(frozen=True) class HistoryPolicy: """The method-history retention policy. Attributes ---------- retention : HistoryRetention When to keep it. """ retention: HistoryRetention = HistoryRetention.AUTO
[docs] @classmethod def from_choice(cls, choice: bool | None) -> HistoryPolicy: """Return the policy for the public ``resume_history`` choice. Parameters ---------- choice : bool or None ``True`` keeps it always, ``False`` never and ``None`` automatically. Returns ------- HistoryPolicy The policy. """ if choice is None: return cls(HistoryRetention.AUTO) return cls(HistoryRetention.REQUIRED if choice else HistoryRetention.OFF)
[docs] @dataclass(frozen=True, eq=False) class RunRequest: """Every policy of one run, resolved before preparation. A :class:`~solprop.driver.simulation.Simulation` gives the request its translation built beside the problem through :meth:`~solprop.driver.simulation.Simulation.run_request`; :func:`describe_run` builds one from a stepper section of your own. Attributes ---------- integration : IntegrationSpec The method. error_control : ErrorControlSpec Tolerances, controller and step limits. replay : ReplaySpec or None A fixed itinerary; ``None`` for an adaptive run. observation : ObservationRequest Planes, statistics and field retention. boundary : BoundaryRequest The boundary monitor's configuration. history : HistoryPolicy Method-history retention for a resume. snapshots : bool Whether snapshot requests may arrive during the run. """ integration: IntegrationSpec error_control: ErrorControlSpec replay: ReplaySpec | None observation: ObservationRequest boundary: BoundaryRequest history: HistoryPolicy snapshots: bool = False
[docs] @functools.cached_property def stepper(self) -> StepperSettings: # numpydoc ignore=RT01 """Stepping policy as the one record translation resolved. The method, the error control, the itinerary and the planes, gathered back into :class:`~solprop.stepper.settings.StepperSettings` for the code that reads them together: the march drivers, the request-aware checks (:func:`solprop.translate.problem.validate_run`) and the run's configuration record, whose hash they enter. The record, built once per request. Examples -------- >>> from solprop.stepper import DOPRI5, PIController >>> from solprop.stepper.settings import StepperSettings >>> from solprop.translate.run_request import describe_run >>> settings = StepperSettings(DOPRI5, PIController(rtol=1e-8, atol=1e-14), ... 1e-9, 0.1, 1e-3, 1.1, None, [0.5, 1.0], "auto") >>> describe_run(settings).stepper.save_planes.tolist() [0.5, 1.0] """ integration, control = self.integration, self.error_control observation = self.observation return StepperSettings( tableau=integration.tableau, controller=control.controller, dz_min=control.dz_min, dz_max=control.dz_max, dz_init=control.dz_init, stretch=control.stretch, schedule=None if self.replay is None else self.replay.schedule, save_planes=observation.save_planes, propagator_mode=integration.propagator_mode, integrator=integration.method, interval_cap=control.interval_cap, auto_init=control.auto_init, interpolate_planes=observation.dense, step_planes=observation.step_planes, )
[docs] def with_stepper(self, stepper: StepperSettings) -> RunRequest: """Return this request with another stepper section, its other policies kept. The statistics, monitor, history and snapshot policy stay; the method, the error control, the itinerary and the planes are `stepper`'s. :meth:`solprop.driver.simulation.Simulation.with_input` uses it for the planes left beyond an interior launch. It takes a fresh request only: a field retention or a start plane is resolved against the planes, which the new section replaces, so a request that keeps every field from the entrance is the only one it accepts. Adapt the result to a run with :meth:`for_run`. Parameters ---------- stepper : solprop.stepper.settings.StepperSettings The new stepper section. Returns ------- RunRequest The request. Raises ------ TranslationError If this request keeps other than every field, or starts beyond the entrance (:meth:`for_run` has adapted it to a run). Examples -------- >>> import dataclasses >>> from solprop.stepper import DOPRI5, PIController >>> from solprop.stepper.settings import StepperSettings >>> from solprop.translate.run_request import describe_run >>> settings = StepperSettings(DOPRI5, PIController(rtol=1e-8, atol=1e-14), ... 1e-9, 0.1, 1e-3, 1.1, None, [0.5, 1.0], "auto") >>> request = describe_run(settings) >>> shorter = dataclasses.replace(settings, save_planes=[1.0]) >>> later = request.with_stepper(shorter) >>> later.observation.save_planes.tolist() [1.0] >>> request.for_run(start_plane=1).with_stepper(shorter) # doctest: +ELLIPSIS Traceback (most recent call last): ... solprop.exceptions.TranslationError: with_stepper takes a fresh request, ... """ observation = self.observation if observation.retention != FieldRetention() or observation.start_plane != 0: msg = ( "with_stepper takes a fresh request, which keeps every field from the " f"entrance; this one keeps {observation.retention} from save plane " f"{observation.start_plane}, resolved against the planes the new " "stepper section replaces. Call with_stepper on the request before " "for_run adapts it to a run" ) raise TranslationError(msg) return describe_run( stepper, stats=observation.stats, monitor=self.boundary.monitor, history=self.history, snapshots=self.snapshots, )
[docs] def for_run( self, *, stats: StatsSpec | None = None, retention: FieldRetention | None = None, start_plane: int = 0, monitor: BoundaryMonitor | None = None, history: HistoryPolicy | None = None, snapshots: bool = False, ) -> RunRequest: """Return this request with one run's observation, boundary and history. The method, the error control, the itinerary and the planes are kept: a backend prepared for this request serves the returned one. Parameters ---------- stats : solprop.stats.StatsSpec or None, optional The statistics; this request's own by default. retention : solprop.output.store.FieldRetention or None, optional Field retention, already resolved against the planes; every field by default. start_plane : int, optional The first save plane beyond the starting state. monitor : solprop.monitor.BoundaryMonitor or None, optional A fresh boundary monitor, or ``None``. history : HistoryPolicy or None, optional Method-history retention; automatic by default. snapshots : bool, optional Whether snapshot requests may arrive. Returns ------- RunRequest The run's request. Raises ------ TranslationError If `start_plane` is not a plane of the run. Examples -------- >>> from solprop.stepper import DOPRI5, PIController >>> from solprop.stepper.settings import StepperSettings >>> from solprop.translate.run_request import describe_run >>> settings = StepperSettings(DOPRI5, PIController(rtol=1e-8, atol=1e-14), ... 1e-9, 0.1, 1e-3, 1.1, None, [0.5, 1.0], "auto") >>> describe_run(settings).for_run(start_plane=1).observation.start_plane 1 """ observation = self.observation planes = observation.save_planes.size if not 0 <= start_plane <= planes: msg = f"start_plane {start_plane} is not a plane of a run with {planes}" raise TranslationError(msg) return dataclasses.replace( self, observation=dataclasses.replace( observation, start_plane=start_plane, stats=observation.stats if stats is None else stats, retention=FieldRetention() if retention is None else retention, ), boundary=BoundaryRequest(monitor), history=HistoryPolicy() if history is None else history, snapshots=snapshots, )
[docs] def describe_run( stepper: StepperSettings, *, stats: StatsSpec | None = None, retention: FieldRetention | None = None, start_plane: int = 0, monitor: BoundaryMonitor | None = None, history: HistoryPolicy | None = None, snapshots: bool = False, ) -> RunRequest: """Build the run request from a resolved stepper section and the run's settings. Parameters ---------- stepper : solprop.stepper.settings.StepperSettings The stepper section translation resolved; it supplies the method, error control, itinerary and planes. stats : solprop.stats.StatsSpec or None, optional The statistics; none by default. retention : solprop.output.store.FieldRetention or None, optional Field retention, already resolved against the planes; every field by default. start_plane : int, optional The first save plane beyond the starting state. monitor : solprop.monitor.BoundaryMonitor or None, optional A fresh boundary monitor to copy, or ``None``. history : HistoryPolicy or None, optional Method-history retention; automatic by default. snapshots : bool, optional Whether snapshot requests may arrive. Returns ------- RunRequest The request. Raises ------ TranslationError If `start_plane` is not a plane of the run. Examples -------- >>> from solprop.grid import EnvelopeGrid >>> from solprop.nonlinear.gnlse import problem_from >>> from solprop.pulses import SechPulse >>> from solprop.stepper import PIController >>> from solprop.translate.assembly import assemble >>> from solprop.translate.run_request import describe_run >>> grid = EnvelopeGrid.from_limits(1.0, 835e-9, (500e-9, 2e-6), 4e-12) >>> gnlse = problem_from([0.0, 0.0, -1.2e-26], omega_ref=grid.omega0, ... gamma=0.11, shock=False) >>> start = SechPulse(wavelength=835e-9, width=1e-13, peak_power=1.0).build(grid) >>> problem, request = assemble( ... grid, gnlse.mode, [gnlse.kerr], start, ... controller=PIController(rtol=1e-8, atol=1e-14), save_planes=[1.0], ... dz_max=0.1, dz_init=1e-3, shock=False, prefactor_index=1.0, density=1.0, ... ) >>> again = describe_run(request.stepper) >>> again.integration.kind.value, again.observation.save_planes.tolist() ('runge_kutta', [1.0]) """ settings = stepper planes = frozen_copy(settings.save_planes, np.float64) if not 0 <= start_plane <= planes.size: msg = f"start_plane {start_plane} is not a plane of a run with {planes.size}" raise TranslationError(msg) integrator = settings.integrator if isinstance(integrator, LowStorageRungeKutta): kind = MethodKind.LOW_STORAGE elif isinstance(integrator, Multistep): kind = MethodKind.ADAMS else: kind = MethodKind.RUNGE_KUTTA return RunRequest( integration=IntegrationSpec( kind=kind, tableau=settings.tableau, method=integrator, propagator_mode=settings.propagator_mode, ), error_control=ErrorControlSpec( controller=settings.controller, dz_min=settings.dz_min, dz_max=settings.dz_max, dz_init=settings.dz_init, stretch=settings.stretch, auto_init=settings.auto_init, interval_cap=settings.interval_cap, ), replay=None if settings.schedule is None else ReplaySpec(settings.schedule), observation=ObservationRequest( save_planes=planes, start_plane=start_plane, dense=settings.interpolate_planes, step_planes=settings.step_planes, stats=StatsSpec() if stats is None else stats, retention=FieldRetention() if retention is None else retention, ), boundary=BoundaryRequest(monitor), history=HistoryPolicy() if history is None else history, snapshots=snapshots, )