Source code for solprop.driver.settings

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

"""How a run is stepped, what it records and which backend executes it.

:class:`SimulationSettings` and the checks that admit it, and the settings defaults a
keyword route applies: its save planes, its controller and its absorbing boundaries
(SEP 21). The manual page is ``docs/guide/setup/running.md``.
"""

import dataclasses
import math
import numbers
import warnings
from collections.abc import Callable, Sequence
from dataclasses import dataclass
from typing import Any, Literal, SupportsIndex, cast

import numpy as np
from jaxtyping import Float
from numpy.typing import ArrayLike

from solprop._display import Displayed, engineering, line, summarise
from solprop._ownership import frozen_copy
from solprop.adiabatic import AdiabaticAccuracy
from solprop.backends.registry import resolve_name
from solprop.backends.session import ExecutionOptions, positive_count
from solprop.boundaries import Absorber, SpatialAbsorber, no_absorber
from solprop.boundaries import absorber as collar
from solprop.driver.defaults import (
    default_controller,
    default_integrator,
    default_rtol,
    default_scheme,
    default_step,
)
from solprop.exceptions import BackendError, DriverError, GridError, SolpropWarning
from solprop.grid import TimeGrid
from solprop.modes.quadrature import TransverseQuadrature
from solprop.monitor import DEFAULT_BOUNDARY_CHECK, BoundaryCheck
from solprop.nonlinear.tdse import TDSEExecution
from solprop.output.records import DefaultsResolution
from solprop.output.store import FieldsChoice, field_retention_refusal
from solprop.profiles import ZProfile
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.runge_kutta import RungeKutta
from solprop.stepper.schedule import LANDING_ULPS, FixedSchedule, replay_tolerance
from solprop.translate.masks import AbsorberScheme
from solprop.translate.problem import PropagatorMode

__all__ = [
    "DEFAULT_N_SAVE",
    "LOOSE_ADAMS_RTOL",
    "LOW_STORAGE_BACKENDS",
    "NoiseSetting",
    "SimulationSettings",
    "default_collar",
    "keyword_settings",
]

LOOSE_ADAMS_RTOL = 5e-2
"""The ``rtol`` from which an adaptive Adams run is warned on.

An error of five per cent or more allowed per step compounds through the method's
history, and its predictor-corrector estimate is unreliable there
(``docs/guide/numerics/choosing-a-stepper.md``).
"""

DEFAULT_N_SAVE = 201
"""Observations a run records when given neither ``n_save`` nor ``save_planes``.

Evenly spaced over the run's interval ``[initial_z, length]``, both ends included
(SEP 51). The TDSE capillary's route default is two instead.
"""

_RECIPE_EXECUTION = ("fields", "field_planes", "resume_history")
"""The settings a recipe's ``[execution]`` table holds: a change of any other one drops
the recipe, which would no longer describe the run (SEP 41, S2)."""


def _held_budget(value: SupportsIndex | None) -> int | None:
    """Return a settings node budget as an ``int``, refused before translation.

    Any integral budget, a NumPy integer among them, is held as an ``int``, and a
    budget that is not one is refused when the settings are made, rather than when the
    backend is built after the output has opened.

    - ``value``: the budget given, bytes.
    - Returns: the budget, or ``None`` for the backend's automatic choice.
    """
    if value is None:
        return None
    try:
        return positive_count("node_budget", value)
    except BackendError as error:
        raise DriverError(str(error), parameter="node_budget") from None


_EXECUTION_SETTINGS = (
    "backend",
    "node_budget",
    "resume_history",
    "tdse_execution",
    "fields",
    "field_planes",
    "boundary_check",
)
"""The settings read when a run executes, not when it is translated."""

NoiseSetting = Literal["default", "input", "modified"] | None
"""What a constructor's ``noise`` keyword takes (SEP 37).

A model, ``None`` for a noiseless run, or ``"default"``, the keyword's default, which
resolves to ``"input"`` wherever the run can carry noise and to none where it cannot,
recording which in the run's :class:`~solprop.output.records.NoiseResolution`.
"""


class _Defaulted(str):
    """A setting's value that a default rule chose rather than the caller.

    A copy made with :func:`dataclasses.replace` carries the marker with the value, so
    the copy resolves the rule again for its own route or planes (the collar scheme),
    while a value the caller names, even an equal one, is a plain string and stays as
    given.
    """

    __slots__ = ()


[docs] @dataclass(frozen=True, eq=False) class SimulationSettings(Displayed): """How a run is stepped, what it records and which backend executes it. Everything that is *not* a physics object, in one group, so that a simulation can be constructed from the physics and this. Equality is by identity (``eq=False``) because ``save_planes`` is an array. Attributes ---------- controller : solprop.stepper.controller.PIController or None Tolerances, safety and gains; the tolerances and the norm choice live here and nowhere else (``docs/dev/kernel-contract.md`` section 7). ``None``, the default, takes the route's from :data:`~solprop.driver.defaults.ROUTE_DEFAULTS` (SEP 37) when an interface builds the run: the :data:`~solprop.driver.defaults.SPATIAL_RTOL` and :data:`~solprop.driver.defaults.SPATIAL_ATOL` of :meth:`~solprop.driver.simulation.Simulation.from_free` on a radial grid and of :meth:`~solprop.driver.simulation.Simulation.from_planar`, the :data:`~solprop.driver.defaults.FREE_RTOL` and :data:`~solprop.driver.defaults.FREE_ATOL` of :meth:`~solprop.driver.simulation.Simulation.from_free` on a Cartesian or line grid. An explicit controller always wins, and settings that already belong to a route keep its default. The other fields are keyword-only. save_planes : numpy.ndarray or None Positions to record the run at, m, finite and strictly increasing, inside the run's interval ``[initial_z, length]``, where ``length`` is the grid's (SEP 51). The entrance and the end are recorded anyway and are added when absent; either may be listed and is kept once, a position within :data:`~solprop.stepper.schedule.LANDING_ULPS` ulps of an endpoint being that endpoint. An empty list records the two endpoints alone. A sequence is adopted as a read-only float64 array, so that two runs specified the same way record the same planes whichever type they passed and therefore hash alike. Give this or `n_save`, not both; given neither, the run records :data:`DEFAULT_N_SAVE`. A simulation holds its settings *resolved*: the positions after its entrance, the last exactly its length, and `n_save` ``None``. n_save : int or None How many evenly spaced observations to record over ``[initial_z, length]``, both ends included: an integer of at least 2. Give this or `save_planes`. dz_max : float Cap on the controller's proposal, m. dz_init : float First step, m. dz_min : float or None Floor on the proposal, m; ``None`` takes :func:`solprop.stepper.controller.default_dz_min` of the run length. A proposal below it raises rather than being clamped silently. stretch : float or None Landing stretch factor; ``None`` takes :data:`solprop.translate.problem.DEFAULT_STRETCH`. auto_init : bool Whether the start-up rule takes the step after the first from the first step's own error estimate, rather than growing from `dz_init` at the growth cap (SEP 14). The convenience constructors set it when no `dz_init` is given. It is off for a coupled flow and a reject-free controller. interval_cap : bool or None Whether a step is capped at the width of its operator-table interval. ``None`` caps it only for a coupled flow or a reject-free controller (SEP 14). interpolate_planes : bool Observe the save planes inside accepted steps instead of landing on them (SEP 14 phase 3): through the Adams march's own polynomial or, with ``RungeKutta()``, DOPRI5's continuous extension. Every plane but the run's end and a hard kink is then interpolated. Refused beside a coupled flow, the per-step temporal collar and the ``modified`` noise. step_planes : int A positive ``k`` also saves the end of every ``k``-th accepted step, the march's own positions, beside the requested planes (SEP 14 phase 3); ``0`` saves the requested planes only. Not in scans. integrator : Multistep, RungeKutta, LowStorageRungeKutta or None The method that steps the run (``docs/guide/numerics/choosing-a-stepper.md``). ``None``, the default, takes ``Multistep()``, or ``RungeKutta()`` where the interface's builder sets it (:meth:`~solprop.driver.simulation.Simulation.from_gnlse`, :meth:`~solprop.driver.simulation.Simulation.from_waveguide` and :meth:`~solprop.driver.simulation.Simulation.from_free`; ``docs/guide/numerics/choosing-a-stepper.md``); the stored value is the resolved method. ``Multistep()`` is the low-call exponential Adams method, which ``numpy_ref`` and ``native`` execute for supported configurations; ``RungeKutta()`` is the interaction-picture DOPRI5 march, which every backend executes and which holds a third of the Adams history's memory. ``LowStorageRungeKutta()`` replays `schedule` with RK4 in three registers and no error estimate (SEP 24); every backend executes it (:data:`LOW_STORAGE_BACKENDS`), and ``"auto"`` resolves as for any integrator. schedule : solprop.stepper.schedule.FixedSchedule or None A fixed schedule to replay instead of stepping adaptively (``docs/dev/stepper.md`` section 8). Its edges must contain every save plane, which :meth:`solprop.stepper.schedule.FixedSchedule.uniform` guarantees. propagator_mode : {'auto', 'tabulate', 'recompute'} Whether the backend tabulates the stage propagators (``docs/dev/kernel-contract.md``). density : solprop.profiles.ZProfile or float or None Number density along z in m^-3 that multiplies the compiled responses; ``None`` takes the mode's own path. The GNLSE passes 1.0 (``docs/guide/waveguides/gnlse.md``). Refused beside a mixture and beside a gas medium, which carry their own. shock : bool Keep the ``omega`` dependence of the normalisation prefactor, which is the optical shock term. prefactor_index : float or None Use this constant in the prefactor and power weight; None uses Re n_eff. The GNLSE passes 1.0, leaving its power normalisation and Phi unchanged. absorber_scheme : {'nonlinear', 'split_step'} or None How the temporal collar is applied (``docs/guide/numerics/boundaries.md``). ``None``, the default, is the route's: ``"split_step"`` on the radial, free-space and planar routes unless planes are interpolated (SEP 21), and ``"nonlinear"`` elsewhere. ``"nonlinear"`` adds ``-alpha(t) E(t) / 2`` inside every stage; ``"split_step"`` multiplies the accepted state by ``exp(-alpha(t) h / 2)`` once per step, a Lie splitting, first order wherever the collar does any work and unconditionally stable. absorber : solprop.boundaries.Absorber or None The collar rates. Its spectral part folds into the linear operator and its temporal part crosses the seam as a rate (``docs/guide/numerics/boundaries.md``). quadrature : solprop.modes.quadrature.TransverseQuadrature or None The fixed transverse rule a multimode run integrates the nonlinear polarisation on (``docs/guide/waveguides/mode-sets.md``). ``None`` builds the mode-averaged single-node transform, which needs exactly one mode. components : sequence of str or None Which transverse Cartesian components the multimode transform resolves at each node, a non-empty subset of ``("x", "y")``; ``None`` takes the union of the modes' nonzero components at the entrance (``("x",)`` for HE_1m modes at ``phi = 0``; ``docs/dev/conventions.md`` section 5). Refused without a `quadrature`. Kept as a tuple copied from the sequence given. ionisation_field_range : tuple of float or None Lowest and highest field amplitude in V/m the compiled ionisation-rate table has to cover. Required beside a plasma response whose rate is not already a table; the table holds its last value above the upper limit, so one set too low is a silent clip. node_budget : int or None Bytes of node-chunk buffers a response pass may hold (``docs/dev/architecture.md`` section 13). An execution setting, outside the resume key: the backend plans its node chunk from it when it is prepared, and it may change after translation. ``None``, the default, leaves the choice to the backend, which takes 1 GiB on a free-space, line or planar grid and 64 MiB otherwise (:data:`~solprop.backends.node_chunk.DEFAULT_SPATIAL_NODE_BUDGET`, :data:`~solprop.backends.node_chunk.DEFAULT_NODE_BUDGET`); an explicit budget is authoritative. stats : solprop.stats.StatsSpec or None Which statistics to collect at every saved plane; ``None`` collects none. polarisation_taper : bool Whether the spectral collar tapers the nonlinear polarisation as well as absorbing the field through the linear operator. Default ``False``, which is :func:`solprop.translate.assembly.assemble`'s: the taper costs a systematic error of the size of the field's content in the collar, and the rate absorber acts either way (``docs/guide/numerics/boundaries.md``). backend : str Registry name of the backend to execute the run. The default ``"auto"`` resolves to ``"native"`` at settings construction, and refuses if it isn't installed or this processor is below its baseline. The stored name is concrete, including in scan workers. A backend's import or construction errors never trigger a fallback. resume_history : bool or None Whether the output keeps the Adams march's state at every save plane and terminal checkpoint, so that a resume continues the history -- its samples, its order and its proposed step -- as the uninterrupted run would, instead of starting it afresh at order one. ``None``, the default, keeps it while it is at most :data:`solprop.translate.run_request.MARCH_SNAPSHOT_AUTO_BYTES`; it is outside the resume key. Every backend's fused and exponential Adams engines, the native backend's resident one included, export and install their history. fields : {'all', 'planes', 'none'} Which saved planes keep their field (SEP 22): every one, the default; those of `field_planes`; or none, for a run wanted as statistics alone. A plane without its field stores no field and no noise phase, and an in-memory output is allocated for the kept fields only; the march is the same. A terminal checkpoint carries the field anyway, so a stopped run resumes, but a file whose last regular plane kept no field resumes only from one. Outside the resume key, like `resume_history`: it changes what is kept, not what is computed. In a scan, :func:`~solprop.driver.scan.run_scan`'s own `fields` decide, and a builder that sets this is refused. Beside ``LowStorageRungeKutta()``, a step abandoned in flight leaves no checkpoint, so a file resumes from the last plane that kept its field. field_planes : sequence of int Saved-plane indices for ``fields='planes'``, the entrance as 0 and negative from the end; empty otherwise. Refused beside `step_planes`, whose plane count is not known in advance. evanescent_rate : float or None The spatial operator's evanescent field attenuation cap in m^-1, positive and finite (SEP 22 section 4.4). ``None``, the default, keeps :data:`solprop.spatial.EVANESCENT_RATE`; :func:`solprop.spatial.physical_evanescent_rate` gives the rate at which the grid's non-propagating content decays physically. Refused without a spatial grid; a replayed step it would overflow is refused at translation. spatial_absorber : solprop.boundaries.SpatialAbsorber, False or None The transverse boundary of a free-space run (SEP 40). ``None``, the default, is ``SpatialAbsorber(real_space=False)``: a wall or a wrap at the grid's outer size and a safety ramp on its outer wavenumbers, folded into the operator as an exact diagonal rate. A :class:`~solprop.boundaries.SpatialAbsorber` asks for a real-space collar too, in the room the grid has outside its requested size (``collar_fraction``). ``False`` carries no ramp either; the boundary monitor still runs. A specification is refused on modal runs. adiabatic_accuracy : solprop.adiabatic.AdiabaticAccuracy or None The forward-field and reflected-energy budgets a radial medium varying along z must meet (SEP 34 section 4.5). ``None``, the default, is ``AdiabaticAccuracy()``, both 1e-4; a path exceeding them is refused. tdse_execution : solprop.nonlinear.tdse.TDSEExecution or None Explicit atomic runtime resources for a TDSE response. Requires an explicit ``backend="numpy_ref"`` and a Multistep integrator. Execution resources are outside the scientific resume identity; attempted-call budgets are cumulative. boundary_check : solprop.monitor.BoundaryCheck or None How the run watches its time window's edges (SEP 21): guard and collar occupancy at the launch and every committed step, a warning and then a stop when light reaches the edge, and the energy the temporal collar removed at the end. The default :class:`~solprop.monitor.BoundaryCheck` warns at a field-error budget of 1e-3 and stops at ten times it; ``None`` watches nothing. Raises ------ DriverError If `save_planes` is a bare number, holds a position that is not finite or does not increase strictly, or is given beside `n_save`, or if `n_save` is not an integer of at least 2; each message names the fix. Positions outside the run's interval are refused when a simulation adopts the settings, where the interval is known. Also if the field retention is not valid, asks for ``fields='planes'`` beside `step_planes`. Examples -------- >>> from solprop.driver import SimulationSettings >>> from solprop.stepper import PIController >>> settings = SimulationSettings( ... controller=PIController(rtol=1e-8, atol=1e-14), ... save_planes=[0.5, 1.0], dz_max=0.1, dz_init=1e-3, ... backend="numpy_ref", ... ) >>> settings.save_planes.tolist(), settings.backend ([0.5, 1.0], 'numpy_ref') """ controller: PIController | None = None _: dataclasses.KW_ONLY # A bare number is admitted by the annotation so that it is refused by name, with # the fix, rather than by the run-time type check. save_planes: Float[np.ndarray, " n_z"] | Sequence[float] | float | None = None n_save: int | SupportsIndex | float | None = None dz_max: float dz_init: float dz_min: float | None = None stretch: float | None = None auto_init: bool = False interval_cap: bool | None = None interpolate_planes: bool = False step_planes: int = 0 schedule: FixedSchedule | None = None propagator_mode: PropagatorMode = "auto" density: ZProfile | float | None = None shock: bool = True prefactor_index: float | None = None absorber: Absorber | None = None absorber_scheme: AbsorberScheme | None = None quadrature: TransverseQuadrature | None = None components: Sequence[str] | None = None ionisation_field_range: tuple[float, float] | None = None node_budget: int | SupportsIndex | None = None stats: StatsSpec | None = None polarisation_taper: bool = False backend: str = "auto" integrator: Multistep | RungeKutta | LowStorageRungeKutta | None = None resume_history: bool | None = None tdse_execution: TDSEExecution | None = None fields: FieldsChoice = "all" field_planes: Sequence[int] = () evanescent_rate: float | None = None spatial_absorber: SpatialAbsorber | Literal[False] | None = None adiabatic_accuracy: AdiabaticAccuracy | None = None boundary_check: BoundaryCheck | None = DEFAULT_BOUNDARY_CHECK _default_integrator: Multistep | RungeKutta | None = dataclasses.field( default=None, repr=False, compare=False ) """The default the settings chose for an unnamed integrator. A copy made with :func:`dataclasses.replace` carries it with the integrator, so the copy still knows the caller named none; any other integrator counts as named.""" _route: str | None = dataclasses.field(default=None, repr=False, compare=False) """The row of :data:`~solprop.driver.defaults.ROUTE_DEFAULTS` the interface that built the settings reads, or ``None`` for settings built by hand. A copy made with :func:`dataclasses.replace` carries it, so a copy takes the route's defaults again, and the route's choice never counts as named.""" _default_controller: PIController | None = dataclasses.field( default=None, repr=False, compare=False ) """The controller the settings took from the route's defaults. A copy carries it with the controller, so the copy still knows the caller gave none; any other controller counts as given.""" # Whether the caller named the integrator, set per instance in __post_init__. integrator_named = False # Whether the controller is the route's default, set per instance in __post_init__. controller_defaulted = False def _planes_text(self) -> str: """Return the save planes summarised, for printing.""" if self.save_planes is None: count = DEFAULT_N_SAVE if self.n_save is None else self.n_save return f"{count} planes" + ("" if self.n_save else " (default)") planes = np.asarray(self.save_planes, dtype=float) return summarise(planes, "m").replace("values", "planes") def __repr__(self) -> str: """Return a one-line description with the save planes summarised, not dumped. Returns ------- str For example ``SimulationSettings(<201 planes, 0 m to 1.5 m>, rtol=1e-06, backend=auto)``. """ return line( "SimulationSettings", [ ("", self._planes_text()), *( [("", "interface default tolerances")] if self.controller is None else [ ("rtol", f"{self.controller.rtol:g}"), ("atol", f"{self.controller.atol:g}"), ] ), ("backend", self.backend), ], ) def _default_text(self, text: str) -> str: """Mark the integrator's name when it is the route's default. - Returns: `text`, then ``"(default)"`` or ``"(gnlse default)"`` where no integrator was named. """ if self.integrator_named: return text return f"{text} ({'' if self._route is None else self._route + ' '}default)" def _describe(self) -> tuple[str, list[tuple[str, object]]]: """Return the title and rows of the printed block. - Returns: the title and ``(key, value)`` rows. """ schedule = "adaptive" if self.schedule is None else type(self.schedule).__name__ return "SimulationSettings", [ ("save planes", self._planes_text()), ("integrator", self._default_text(type(self.integrator).__name__)), ( "tolerances", "the interface's default" if self.controller is None else f"rtol {self.controller.rtol:g}, atol {self.controller.atol:g}" + ( f" ({self._route} default)" if self.controller_defaulted and self._route is not None else "" ), ), ("steps", f"{schedule}, dz_max {engineering(self.dz_max, 'm')}"), ("shock term", self.shock), ( "absorber", ( f"{_scheme(self)} scheme" + ("" if self.absorber_scheme_named else " (default)") ) if self.absorber is not None else "none", ), ("statistics", "none" if self.stats is None else type(self.stats).__name__), ("backend", self.backend), ] def __post_init__(self) -> None: """Adopt a read-only plane array and check the selectors. Raises ------ DriverError If the plane selectors are malformed (:func:`_selectors`), or if `resume_history` is not a boolean or ``None``. """ planes, count = _selectors(self.save_planes, self.n_save) object.__setattr__(self, "save_planes", planes) object.__setattr__(self, "n_save", count) refusal = field_retention_refusal(self.fields, self.field_planes) if refusal is not None: raise DriverError(refusal, parameter=("fields", "field_planes")) object.__setattr__(self, "field_planes", tuple(self.field_planes)) if self.components is not None: # A copy, so that changing the caller's list afterwards changes nothing # (issue #471); translation reads it as a tuple either way. object.__setattr__(self, "components", tuple(self.components)) object.__setattr__(self, "node_budget", _held_budget(self.node_budget)) if self.resume_history is not None and not isinstance( self.resume_history, bool ): # A truthy string such as a recipe's "none" would otherwise be read as # True by the history policy, the opposite of what it says (issue #703). msg = ( "resume_history must be True, False or None, got " f"{self.resume_history!r}" ) raise DriverError(msg, parameter="resume_history") self._resolve_defaults() if self.fields == "planes" and self.step_planes: msg = ( "fields='planes' names saved planes by index, and step_planes saves " "the march's own steps as well, so the plane count is not known in " "advance; keep fields='all' or 'none' beside step_planes" ) raise DriverError( msg, parameter=("fields", "step_planes"), rule="fields-planes-step-planes", ) if self.tdse_execution is not None: _admit_tdse_execution(self) # The annotation refuses another integrator first wherever the annotations are # checked at run time, as in the test suite. if not isinstance( self.integrator, Multistep | RungeKutta | LowStorageRungeKutta ): # pragma: no cover msg = ( "integrator must be Multistep(), RungeKutta() or " f"LowStorageRungeKutta(), got {self.integrator!r}" ) raise DriverError(msg, parameter="integrator") if isinstance(self.integrator, LowStorageRungeKutta): backend = _admit_low_storage(self.integrator, self.backend, self) object.__setattr__(self, "backend", backend) # An Adams integrator resolves "auto" as the Runge-Kutta march does: every # backend steps the exponential formulation on every route, and the # interaction one on every route but a coupled flow, which it refuses by name # (SEP 16 phases 3 and 5). object.__setattr__(self, "backend", resolve_name(self.backend)) if isinstance(self.integrator, Multistep): rtol = getattr(self.controller, "rtol", None) if self.schedule is None and rtol is not None and rtol >= LOOSE_ADAMS_RTOL: msg = ( f"rtol={rtol:g} is loose for the Adams method: an error of this " "size allowed per step compounds through its history, and its " "error estimate is unreliable there. Take rtol at most 1e-2, or " "integrator=RungeKutta() for a rough look" ) warnings.warn(msg, SolpropWarning, stacklevel=3) def _resolve_defaults(self) -> None: """Take the route's default for each of the stepping choices the caller left. The integrator, the controller and the collar scheme each come from :data:`~solprop.driver.defaults.ROUTE_DEFAULTS` when not given. A default carried by a copy is resolved again, so it follows the copy's route and planes; a value the caller gave is kept. """ carried = ( self.integrator is not None and self.integrator is self._default_integrator ) object.__setattr__( self, "integrator_named", self.integrator is not None and not carried ) if not self.integrator_named: default = default_integrator(self._route) if carried and type(self.integrator) is type(default): default = self.integrator object.__setattr__(self, "integrator", default) object.__setattr__(self, "_default_integrator", default) controller = self.controller defaulted = controller is not None and controller is self._default_controller if controller is None and self._route is not None: controller = default_controller(self._route) defaulted = True object.__setattr__(self, "controller", controller) object.__setattr__(self, "controller_defaulted", defaulted) if defaulted: object.__setattr__(self, "_default_controller", controller) if self.absorber_scheme is None or isinstance(self.absorber_scheme, _Defaulted): scheme = default_scheme( self._route, interpolate_planes=self.interpolate_planes ) object.__setattr__(self, "absorber_scheme", _Defaulted(scheme))
[docs] @property def absorber_scheme_named(self) -> bool: # numpydoc ignore=RT01 """Whether the caller named the collar scheme, rather than taking the route's. False when :attr:`absorber_scheme` is the route's default. """ return not isinstance(self.absorber_scheme, _Defaulted)
[docs] def execution_options(self) -> ExecutionOptions: """Return the execution options a backend is prepared with (SEP 47). The node budget is an execution choice, not part of the scientific problem: the translation records none, and the backend plans its node chunk from it when it is prepared (:func:`solprop.backends.node_chunk.plan_node_chunk`). Returns ------- solprop.backends.session.ExecutionOptions The explicit :attr:`node_budget`, or the backend's automatic choice. Examples -------- >>> from solprop.driver import SimulationSettings >>> settings = SimulationSettings( ... save_planes=[1.0], dz_max=0.1, dz_init=0.01, node_budget=2**26 ... ) >>> settings.execution_options().node_budget 67108864 """ return ExecutionOptions(node_budget=self.node_budget)
[docs] def defaults_resolution(self) -> DefaultsResolution: """Return which stepping choices took the route's default (#87, SEP 41). Returns ------- solprop.output.records.DefaultsResolution The route, and which of the integrator, the relative tolerance and the collar scheme came from its row of the defaults table. Examples -------- >>> from solprop.driver import SimulationSettings >>> settings = SimulationSettings( ... save_planes=[1.0], dz_max=0.1, dz_init=0.01, backend="numpy_ref" ... ) >>> settings.defaults_resolution() DefaultsResolution(route=None, defaulted=('integrator', 'absorber_scheme')) """ defaulted = ( *(() if self.integrator_named else ("integrator",)), *(("rtol",) if self.controller_defaulted else ()), *(() if self.absorber_scheme_named else ("absorber_scheme",)), ) return DefaultsResolution(self._route, defaulted)
[docs] def with_boundaries( self, grid: TimeGrid, *, absorber: Absorber | Literal[False] | None = None, absorber_scheme: AbsorberScheme | None = None, boundary_check: BoundaryCheck | None = DEFAULT_BOUNDARY_CHECK, spatial_absorber: SpatialAbsorber | Literal[False] | None = None, ) -> "SimulationSettings": """Return these settings with a spatial constructor's boundary keywords applied. Each keyword may be given here or in the settings, not both (SEP 21 section 5, SEP 40); its default leaves the settings' own. Parameters ---------- grid : solprop.grid.TimeGrid The run's time grid, which sizes a collar switched off. absorber : solprop.boundaries.Absorber, False or None, optional The temporal and spectral collar. ``False`` zeroes the rates of the settings' absorber and keeps its lengths, or without one builds the hard band mask alone. absorber_scheme : {'nonlinear', 'split_step'} or None, optional How the temporal collar is applied. boundary_check : solprop.monitor.BoundaryCheck or None, optional How the run watches its time window's edges; ``None`` watches nothing. spatial_absorber : solprop.boundaries.SpatialAbsorber, False or None, optional The transverse boundary. Returns ------- SimulationSettings The settings, replaced where a keyword applies. Raises ------ DriverError If a keyword is given beside settings that declare their own, or ``absorber=False`` beside a scheme. Examples -------- >>> from solprop.driver import SimulationSettings >>> from solprop.grid import EnvelopeGrid >>> grid = EnvelopeGrid.from_limits(0.01, 835e-9, (500e-9, 2e-6), 1e-12) >>> settings = SimulationSettings(save_planes=[1.0], dz_max=0.1, dz_init=0.01) >>> settings.with_boundaries(grid, boundary_check=None).boundary_check is None True """ changes: dict[str, object] = {} if absorber is False: if absorber_scheme is not None: msg = ( "absorber=False switches the temporal collar off, so there is " f"nothing for absorber_scheme={absorber_scheme!r} to apply; give " "one or the other" ) raise DriverError(msg) current = self.absorber changes["absorber"] = ( no_absorber(grid) if current is None else dataclasses.replace( current, spectral_rate=np.zeros_like(current.spectral_rate), user_rate=None, temporal_rate=np.zeros(grid.n_t), temporal_rate_fine=np.zeros(grid.n_to), temporal=False, ) ) elif absorber is not None: if self.absorber is not None: msg = ( "the settings already declare an absorber; give it there or as " "the absorber keyword, not both" ) raise DriverError(msg) changes["absorber"] = absorber if absorber_scheme is not None: if self.absorber_scheme_named and self.absorber_scheme != absorber_scheme: msg = ( f"the settings already declare absorber_scheme=" f"{self.absorber_scheme!r}; give it there or as the keyword" ) raise DriverError(msg) changes["absorber_scheme"] = absorber_scheme if not ( boundary_check is DEFAULT_BOUNDARY_CHECK or boundary_check == self.boundary_check ): if self.boundary_check != DEFAULT_BOUNDARY_CHECK: msg = ( "the settings already declare a boundary_check; give it there or " "as the boundary_check keyword, not both" ) raise DriverError(msg) changes["boundary_check"] = boundary_check if spatial_absorber is not None and spatial_absorber != self.spatial_absorber: if self.spatial_absorber is not None: msg = ( "the settings already declare a spatial_absorber; give it there or " "as the spatial_absorber keyword, not both" ) raise DriverError(msg) changes["spatial_absorber"] = spatial_absorber return dataclasses.replace(self, **changes) if changes else self
def _admit_tdse_execution(settings: SimulationSettings) -> None: """Refuse TDSE execution resources beside settings a TDSE run cannot step with. Each refusal names the setting at fault, in the order a caller would fix them: the execution record, then the integrator. """ if not isinstance(settings.tdse_execution, TDSEExecution): msg = ( "tdse_execution must be a TDSEExecution, got " f"{type(settings.tdse_execution).__name__}" ) raise DriverError(msg, parameter="tdse_execution") if not isinstance(settings.integrator, Multistep): msg = ( "tdse_execution requires integrator=Multistep(), the Adams method the TDSE " f"response steps with; got {type(settings.integrator).__name__}()" ) raise DriverError( msg, parameter=("tdse_execution", "integrator"), rule="tdse-multistep" ) def _quiet_collar(settings: SimulationSettings) -> bool: """Return whether a run's settings opt in to the quiet collar (ADR-057). - Returns: True when the boundary check asks for it. """ check = settings.boundary_check return check is not None and check.quiet_collar
[docs] def keyword_settings( route: str, length: float, *, rtol: float | None, atol: float, dz_max: float | None, dz_init: float | None, # The other settings fields, each typed on SimulationSettings itself. **fields: Any, ) -> SimulationSettings: """Return the settings a keyword route builds: its controller and its steps. Parameters ---------- route : str The row of :data:`~solprop.driver.defaults.ROUTE_DEFAULTS` the route reads. length : float The guide's length, m, which the default steps are fractions of. rtol : float or None The caller's relative tolerance, which is never raised silently; ``None`` takes the route's (:func:`~solprop.driver.defaults.default_rtol`), and the settings record that the controller is the default. atol : float The absolute tolerance, in the route's field unit. dz_max, dz_init : float or None The largest and the first step, m; ``None`` takes :func:`~solprop.driver.defaults.default_step`, and a first step so chosen is refined by the start-up rule. **fields : Any Every other field of :class:`SimulationSettings`. Returns ------- SimulationSettings The settings. Examples -------- >>> from solprop.driver.settings import keyword_settings >>> settings = keyword_settings( ... "gnlse", 0.4, rtol=None, atol=1e-14, dz_max=None, dz_init=None, ... save_planes=[0.4], ... ) >>> settings.controller.rtol, settings.dz_max, settings.controller_defaulted (1e-07, 0.2, True) """ if rtol is None: controller = PIController(rtol=default_rtol(route), atol=atol) default = controller else: controller, default = PIController(rtol=rtol, atol=atol), None return SimulationSettings( controller=controller, _default_controller=default, _route=route, dz_max=default_step("dz_max", length) if dz_max is None else dz_max, dz_init=default_step("dz_init", length) if dz_init is None else dz_init, auto_init=dz_init is None, **fields, )
LOW_STORAGE_BACKENDS = ("native", "numpy_ref") """The backends that execute :class:`~solprop.stepper.low_storage.LowStorageRungeKutta`. ``numpy_ref`` from SEP 24's phase 1 and solprop-native from phase 3, on every route the translation admits the march on; ``backend="auto"`` resolves as for every other integrator (:func:`solprop.backends.registry.resolve_name`: the native backend). """ def _admit_low_storage( integrator: LowStorageRungeKutta, backend: str, settings: SimulationSettings ) -> str: """Refuse what the low-storage march cannot run, before translation (SEP 24 5). The march replays a prescribed schedule, lands on its edges and accepts every step, so it needs a schedule and has no interpolated planes. Every registered backend executes it (:data:`LOW_STORAGE_BACKENDS`), so the backend passes as asked. """ if settings.schedule is None: msg = ( f"the {integrator.name} march replays a prescribed schedule; pass " "schedule=FixedSchedule.uniform(...), or step adaptively with RungeKutta()" ) raise DriverError( msg, parameter=("integrator", "schedule"), rule="low-storage-needs-schedule" ) if settings.interpolate_planes: msg = ( f"the {integrator.name} march lands on its schedule's edges and has no " "dense output; drop interpolate_planes" ) raise DriverError( msg, parameter=("integrator", "interpolate_planes"), rule="low-storage-no-interpolation", ) return backend def _same_setting(old: object, new: object) -> bool: """Return whether two values of one settings field are the same setting. - Returns: True for the same object, equal arrays, or values that compare equal; an object compared by identity (``eq=False``) is the same only as itself, which is what :func:`dataclasses.replace` keeps for every field it is not given. """ if old is new: return True if isinstance(old, np.ndarray) or isinstance(new, np.ndarray): # The other side is an array-like setting (save_planes given as a list). left = np.asarray(cast("np.ndarray", old)) right = np.asarray(cast("np.ndarray", new)) return left.shape == right.shape and bool(np.array_equal(left, right)) try: return bool(old == new) except ValueError: # A container of arrays has no single truth value; it is not provably the same. return False _BOTH_SELECTORS = ( "give one of n_save and save_planes, not both; to carry a count to settings that " "hold positions, pass dataclasses.replace(settings, n_save=N, save_planes=None)" ) def _selectors( save_planes: object, n_save: object ) -> tuple[Float[np.ndarray, " n_z"] | None, int | None]: """Return the plane selectors as settings hold them, refusing a malformed one. The checks that need no interval (SEP 51 section 5.5): a bare number, a position that is not finite or does not increase strictly, both selectors, and a count that is not an integer of at least 2. Positions are a read-only float64 array, m. """ if save_planes is not None and n_save is not None: raise DriverError( _BOTH_SELECTORS, parameter=("save_planes", "n_save"), rule="save-planes-or-n-save", ) count = None if n_save is not None: if isinstance(n_save, bool) or not isinstance(n_save, numbers.Integral): msg = f"n_save is an integer of at least 2, got {n_save!r}" raise DriverError(msg, parameter="n_save") count = int(n_save) if count < 2: msg = ( f"n_save is an integer of at least 2, got {count}: it counts the " "entrance and the end, which a run always records" ) raise DriverError(msg, parameter="n_save") if save_planes is None: return None, count if isinstance(save_planes, bool): msg = f"save_planes takes positions in m, got {save_planes!r}" raise DriverError(msg, parameter="save_planes") if isinstance(save_planes, numbers.Integral): msg = ( f"save_planes={save_planes!r} reads as one position in m, not a count; for " f"evenly spaced planes pass n_save={save_planes!r}" ) raise DriverError(msg, parameter="save_planes", rule="save-planes-count") given = cast("ArrayLike", save_planes) if isinstance(save_planes, numbers.Real) or np.ndim(given) == 0: msg = ( f"save_planes={save_planes!r} is a single position; pass " f"[{save_planes!r}], or n_save for evenly spaced planes" ) raise DriverError(msg, parameter="save_planes") planes = frozen_copy(np.reshape(given, -1), np.float64) for index, position in enumerate(planes.tolist()): if not math.isfinite(position): msg = f"save plane {position!r} is not finite" raise DriverError(msg, parameter="save_planes") previous = float(planes[index - 1]) if index and position <= previous: relation = "repeats" if position == previous else "follows" msg = ( f"save plane {position!r} m {relation} {previous!r} m; the positions " "must increase strictly" ) raise DriverError(msg, parameter="save_planes") return planes, count def _at(position: float, endpoint: float) -> bool: """Return whether a position is an endpoint, within the marches' landing slack. :data:`~solprop.stepper.schedule.LANDING_ULPS` ulps of the endpoint itself, the slack a march lands on a target with (SEP 51 section 5.4). """ return bool(abs(position - endpoint) <= LANDING_ULPS * math.ulp(endpoint)) def _observation_planes( save_planes: Float[np.ndarray, " _"] | None, n_save: int | None, *, entrance: float, length: float, default: int | None = None, ) -> Float[np.ndarray, " n_z"]: """Return the positions a run records after its entrance, the last exactly `length`. The one placement rule of SEP 51, for selectors :func:`_selectors` admitted: a count places that many observations evenly over ``[entrance, length]``, both included; positions within :data:`~solprop.stepper.schedule.LANDING_ULPS` ulps of an endpoint become it, each endpoint is kept once, the end is added when absent and a position outside the interval is refused; neither selector takes `default`, :data:`DEFAULT_N_SAVE` unless given. Resolving the result again against the same interval returns it unchanged. Positions in m; `entrance` before `length`. """ if save_planes is None: count = n_save or (DEFAULT_N_SAVE if default is None else default) # linspace's last value is exactly `length`. return frozen_copy(np.linspace(entrance, length, count)[1:], np.float64) planes = np.array(save_planes, dtype=np.float64) for index, position in enumerate(planes): if _at(position, length): planes[index] = length elif _at(position, entrance): planes[index] = entrance elif position < entrance: msg = ( f"save plane {position:g} m lies before the entrance, initial_z = " f"{entrance:g} m; the run records [{entrance:g} m, {length:g} m]" ) raise DriverError(msg, parameter="save_planes", rule="save-planes-outside") elif position > length: msg = ( f"save plane {position:g} m lies beyond the end of the run, " f"grid.length = {length:g} m; the run records [{entrance:g} m, " f"{length:g} m]: raise length (or grid.length), or drop the plane" ) raise DriverError(msg, parameter="save_planes", rule="save-planes-outside") # Normalization can only merge an endpoint with a listed neighbour. interior = np.unique(planes[(planes > entrance) & (planes < length)]) return frozen_copy(np.append(interior, length), np.float64) def _run_length(length: float | None, grid: TimeGrid | None) -> float: """Return a keyword route's one length, m, from `length`, `grid` or both (SEP 51). Given both, they must agree within :data:`~solprop.stepper.schedule.LANDING_ULPS` ulps of ``grid.length``, which is then the canonical value; a supplied grid is never rebuilt, and a conflict is never settled silently. """ if grid is None: if length is None: msg = "a length or a grid is required: pass length=, or grid=" raise DriverError(msg, parameter=("length", "grid"), rule="length-or-grid") return length if length is not None and not _at(length, float(grid.length)): msg = ( f"length = {length!r} m and grid.length = {grid.length!r} m disagree: the " "run ends at its one length, so give one of them, or make them agree" ) raise DriverError(msg, parameter=("length", "grid"), rule="length-grid") return float(grid.length) def _replay_refusal( schedule: FixedSchedule, entrance: float, length: float ) -> str | None: """Return why a replayed schedule does not cover a run's interval, or ``None``. Its start agrees with the entrance under the endpoint rule, and its end with the length within :func:`~solprop.stepper.schedule.replay_tolerance`, which allows the rounding its step sum accumulates (SEP 51 section 5.7). """ if not _at(schedule.z_start, entrance): return ( f"the replayed schedule starts at {schedule.z_start:g} m, but the run's " f"entrance is {entrance:g} m" ) if abs(schedule.z_end - length) > replay_tolerance(schedule, length): return ( f"the replayed schedule ends at {schedule.z_end!r} m, but the run ends at " f"its length, {length!r} m; replay a schedule over the run's interval, " "such as FixedSchedule.uniform(z_start, length, ...)" ) return None def _adopted( settings: SimulationSettings, *, entrance: float, length: float ) -> SimulationSettings: """Return settings resolved for a run over ``[entrance, length]``, m (SEP 51 5.6). Validated against the run whatever they hold, a count, a list or resolved positions; the result holds the positions after the entrance ending exactly at `length`, and ``n_save=None``. Settings already resolved for the run are returned as they are. An interior launch's schedule is left to its own refusal. """ if not (math.isfinite(entrance) and 0.0 <= entrance < length): msg = ( f"initial_z must be finite, nonnegative and before the end of the run, " f"grid.length = {length:g} m; got {entrance!r}" ) raise DriverError(msg, parameter="initial_z") # __post_init__ holds the selectors as _selectors returns them. planes = _observation_planes( cast("np.ndarray | None", settings.save_planes), cast("int | None", settings.n_save), entrance=entrance, length=length, ) if settings.schedule is not None and entrance == 0.0: refusal = _replay_refusal(settings.schedule, entrance, length) if refusal is not None: raise DriverError(refusal, parameter="schedule", rule="replay-interval") current = settings.save_planes if current is not None and np.array_equal(current, planes): return settings return dataclasses.replace(settings, save_planes=planes, n_save=None) def _scheme(settings: SimulationSettings) -> AbsorberScheme: """Return the collar scheme the settings resolve to.""" return cast("AbsorberScheme", str(settings.absorber_scheme)) def _spatial_settings(settings: SimulationSettings, route: str) -> SimulationSettings: """Give a spatial run's settings the route's defaults (SEP 37, SEP 21). - Returns: `settings`, reading the route's row of :data:`~solprop.driver.defaults.ROUTE_DEFAULTS` for whatever the caller left: the controller (:data:`~solprop.driver.defaults.SPATIAL_RTOL` for radial and planar runs, :data:`~solprop.driver.defaults.FREE_RTOL` for Cartesian and line ones), the integrator (``RungeKutta()`` in free space, whose Adams history would be too large) and the collar scheme (``"split_step"`` unless planes are interpolated). Settings that already belong to a route, this one or another (settings copied from a modal run, for a comparison), keep what that route resolved and are returned as they are. """ if settings._route is not None: return settings return dataclasses.replace(settings, _route=route) def _boundary( absorber: Absorber | Literal[False] | None, scheme: AbsorberScheme | None, grid: TimeGrid, *, default: Callable[[TimeGrid], Absorber] | None = None, ) -> tuple[Absorber | None, AbsorberScheme | None]: """Resolve a builder's absorber keywords (SEP 21 section 5). - ``absorber``: the collar given; ``False`` switches both soft collars off and keeps the hard band mask; ``None`` takes `default`. - ``scheme``: the temporal scheme given; ``None`` is the default scheme. - ``default``: the route's collar when none is given; ``None`` is :func:`default_collar`. - Returns: the absorber (``None`` for none) and the scheme, ``None`` where the settings are to take the route's default. """ if absorber is False: if scheme is not None: msg = ( "absorber=False switches the temporal collar off, so there is nothing " f"for absorber_scheme={scheme!r} to apply; give one or the other" ) raise DriverError( msg, parameter=("absorber", "absorber_scheme"), rule="absorber-scheme-needs-absorber", ) return no_absorber(grid), None if absorber is None: absorber = default_collar(grid) if default is None else default(grid) return absorber, scheme
[docs] def default_collar(grid: TimeGrid) -> Absorber: """Return a route's default absorbing boundaries on a grid (SEP 21). :func:`solprop.boundaries.absorber` at its defaults, spectral-only when the grid leaves too little room outside the request for a temporal collar to taper (``collar_fraction=0`` and no rounding slack). Parameters ---------- grid : TimeGrid The run's grid. Returns ------- Absorber The default collar. Examples -------- >>> from solprop.driver.settings import default_collar >>> from solprop.grid import FieldGrid >>> grid = FieldGrid.from_limits(1.5, 800e-9, (90e-9, 4e-6), 400e-15) >>> default_collar(grid).temporal True """ try: return collar(grid) except GridError: # No room for a temporal taper outside the request: the spectral collar alone. return collar(grid, temporal=False)
def _spatial_default( settings: SimulationSettings, grid: TimeGrid ) -> SimulationSettings: """Give a spatial run whose settings declare no absorber the default collar. The temporal and spectral collars become the routes' default (SEP 21, D6); the transverse boundary is the settings' ``spatial_absorber`` (SEP 40). """ if settings.absorber is not None: return settings return dataclasses.replace(settings, absorber=default_collar(grid))