# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""The run records: what one run's march, session and monitor read (SEP 52 §5.1).
Each record is a frozen dataclass formed once per run by the shared builders here, from
the :class:`~solprop.translate.problem.PropagationProblem`, the
:class:`~solprop.translate.run_request.RunRequest` and the
:class:`~solprop.backends.session.Start`, so that every number either backend uses has
one source. :func:`run_records` forms them all:
- the method's policy: :class:`~solprop.stepper.multistep.MarchPolicy` for the Adams
march (:func:`adams_policy`), :class:`RungeKuttaPolicy` for the Runge-Kutta march and
the low-storage replay (:func:`runge_kutta_policy`), and the low-storage march's
:class:`LowStorageSettings`;
- the schedule, when one is fixed (a :class:`~solprop.stepper.schedule.FixedSchedule`);
- the :class:`PlanePlan`: the planes, step planes, statistics cadence, replay length and
the native session's capacities;
- the boundary monitor's :class:`MonitorRecords`: its :class:`MonitorConfig`, a
transverse edge's :class:`EdgeConfig`, and a resumed run's
:class:`MonitorContinuation`.
The native adapter converts them into what its extension reads; the reference reads
them where it would otherwise derive the same facts. :class:`Notice` and
:class:`EdgeNotice` are the backend-neutral form of a session's boundary verdicts.
The statistics lowering stays each backend's own: the native plan is lowered in C++,
and the reference evaluates the :class:`~solprop.stats.StatsSpec` directly.
Nothing here imports a backend, so the records are available without the native
package installed.
"""
import dataclasses
import enum
import math
from collections.abc import Mapping, Sequence
from dataclasses import dataclass, field
from typing import TYPE_CHECKING, cast
import numpy as np
from jaxtyping import Float, UInt
from solprop.backends.exponential import carrier_reference
from solprop.backends.memory import low_storage_flows
from solprop.monitor import (
_FLOOR, # pyright: ignore[reportPrivateUsage] - the floor the monitor judges by
FLOOR_MARGIN,
_count, # pyright: ignore[reportPrivateUsage] - one refusal of a count
)
from solprop.spatial_absorber import RAMP_K_FLOOR
from solprop.stepper.controller import START_GROWTH, PIController
from solprop.stepper.low_storage import LowStorageRungeKutta
from solprop.stepper.multistep import MarchPolicy, Multistep, march_policy
from solprop.stepper.schedule import LANDING_ULPS, FixedSchedule
from solprop.translate.routes import transverse_of
from solprop.transverse_monitor import BACKSTOP_READS, NOISE_FACTOR, REACH_GROWTH, READS
if TYPE_CHECKING:
from solprop.backends.session import Start
from solprop.boundaries import SplitCrossing
from solprop.monitor import BoundaryMonitor
from solprop.translate.problem import PropagationProblem, StepperSettings
from solprop.translate.run_request import RunRequest
from solprop.transverse_monitor import TransverseEdge, TransverseStatus
__all__ = [
"ATTEMPT_CAPACITY",
"CALL_ATTEMPTS",
"CALL_SECONDS",
"PLANE_COLUMNS",
"ROW_CAPACITY",
"STATUSES",
"EdgeConfig",
"EdgeNotice",
"EdgeNoticeKind",
"EdgeResumption",
"LowStorageSettings",
"MonitorConfig",
"MonitorContinuation",
"MonitorRecords",
"Notice",
"NoticeKind",
"PlanePlan",
"Resumption",
"RunRecords",
"RungeKuttaPolicy",
"adams_policy",
"collar_rests",
"declared",
"edge_config",
"edge_resumption",
"low_storage_settings",
"monitor_config",
"monitor_continuation",
"monitor_records",
"plane_plan",
"resumption",
"run_records",
"runge_kutta_policy",
]
CALL_ATTEMPTS = 256
"""A march call's most attempts, as the native marches bound them (SEP 39)."""
CALL_SECONDS = 0.1
"""A march call's most wall time, s."""
ATTEMPT_CAPACITY = 4096
"""The most attempts the native session holds between two events; a full buffer yields
a progress event carrying them (SEP 47 section 5.3)."""
ROW_CAPACITY = 1024
"""The most periodic rows it holds between two events, likewise."""
PLANE_COLUMNS = ("z", "collar_occupancy", "guard_low", "guard_high", "removed_fraction")
"""The monitor record's plane rows, in the native order (``watch::plane_columns``)."""
STATUSES: tuple["TransverseStatus", ...] = (
"clear",
"warned",
"stopped",
"insensitive",
"coarse",
"unwatched",
)
"""The transverse statuses in the native order (``transverse::Status``)."""
_NUMBERS = (
"launch_energy",
"launch_guard_low",
"launch_guard_high",
"launch_collar",
"guard_low_max",
"guard_high_max",
"guard_low_at",
"guard_high_at",
"collar_max",
"raw_removed_fraction",
"removed_signed",
"removed_fraction",
"floor_removed_fraction",
"raw_guard_max",
)
"""The numbers a resume reads from an earlier monitor record (``watch::Resumption``)."""
_COUNTS = ("steps", "skipped", "collar_left_out_checks")
"""The counts it reads, each whole or refused (``solprop.monitor._count``)."""
_EDGE_NUMBERS = (
"launch_energy",
"noise_allowance",
"raw_ramp_removed",
"noise_ramp_removed",
"noise_share_in_ramp",
"declared_share_in_ramp",
"spatial_removed",
"current",
"current_baseline",
"strip_baseline",
"strip_floor",
"strip_max",
"returned_max",
"largest_gap",
"warned_at",
)
"""The numbers a resume reads from an earlier edge record (``transverse::Resumption``).
"""
# -- the method's policy ------------------------------------------------------------
[docs]
@dataclass(frozen=True)
class RungeKuttaPolicy:
"""Every number the Runge-Kutta march reads and never changes during a run (SEP 45).
The controller's decisions read the controller, the floor, the cap and the start-up
flag (:mod:`solprop.backends.rk_core`); the landings read the rest, the fields of
:class:`~solprop.stepper.multistep.MarchPolicy` of the same names. The native march
receives it whole, with the controller's fields, and holds no default of its own.
Attributes
----------
controller : solprop.stepper.controller.PIController
The controller, whose gains, factors, lag, estimator order, tolerances and
acceptance rule the decisions read.
dz_min, dz_max : float
The floor and the cap on a proposal, m.
auto_init : bool
Whether the first accepted step takes the start-up rule.
stretch, z_end : float
The landing stretch (a ratio) and the run's end, m.
save_planes : tuple of float
The planes to land on, m; empty when the planes are interpolated.
interpolate : bool
Whether the save planes are observed densely.
hard_kinks : tuple of float
The operator's hard kinks, m.
breakpoints : tuple of float
The edges whose intervals cap a step, m: the operator's breakpoints with the
interval cap, otherwise only its first and last.
landing_ulps : int
:data:`~solprop.stepper.schedule.LANDING_ULPS`.
start_growth : float
:data:`~solprop.stepper.controller.START_GROWTH`.
quiet_interval : float or None
The boundary monitor's interval, m, which caps a step while the collar rests;
``None`` for a session, whose monitor holds its own.
"""
controller: PIController
dz_min: float
dz_max: float
auto_init: bool
stretch: float
z_end: float
save_planes: tuple[float, ...]
interpolate: bool
hard_kinks: tuple[float, ...]
breakpoints: tuple[float, ...]
landing_ulps: int
start_growth: float
quiet_interval: float | None
[docs]
def runge_kutta_policy(
problem: "PropagationProblem", stepper: "StepperSettings"
) -> RungeKuttaPolicy:
"""Return the Runge-Kutta march's policy of one run.
Parameters
----------
problem : solprop.translate.problem.PropagationProblem
The problem, whose operator's breakpoints and hard kinks the landings read.
stepper : solprop.translate.problem.StepperSettings
The run's stepper settings.
Returns
-------
RungeKuttaPolicy
The record, with no quiet interval.
"""
breakpoints = np.asarray(problem.linear.phi_breakpoints, dtype=np.float64)
if not stepper.interval_cap:
# The cumulative table makes the flow exact across its intervals, so only the
# table's two ends bound a step (SEP 14 section 4.1).
breakpoints = breakpoints[[0, -1]]
interpolate = bool(stepper.interpolate_planes)
return RungeKuttaPolicy(
controller=stepper.controller,
dz_min=float(stepper.dz_min),
dz_max=float(stepper.dz_max),
auto_init=bool(stepper.auto_init),
stretch=float(stepper.stretch),
z_end=float(stepper.z_end),
# Interpolated planes are stepped across (SEP 14 section 4.3).
save_planes=()
if interpolate
else tuple(float(z) for z in np.asarray(stepper.save_planes)),
interpolate=interpolate,
hard_kinks=tuple(float(z) for z in np.asarray(problem.linear.hard_kinks)),
breakpoints=tuple(float(z) for z in breakpoints),
landing_ulps=LANDING_ULPS,
start_growth=float(START_GROWTH),
quiet_interval=None,
)
[docs]
def adams_policy(
problem: "PropagationProblem",
stepper: "StepperSettings",
method: Multistep,
*,
carrier: bool,
) -> MarchPolicy:
"""Return the Adams march's policy of one run (SEP 39 section 4.2).
Parameters
----------
problem : solprop.translate.problem.PropagationProblem
The problem: the operator's breakpoints and kinks, and the in-stage temporal
collar, whose largest rate bounds each order's stable step in the exponential
formulation.
stepper : solprop.translate.problem.StepperSettings
The run's stepper settings.
method : solprop.stepper.multistep.Multistep
The method.
carrier : bool
Whether the engine's carrier frame is active
(:class:`~solprop.backends.exponential.CarrierReference`).
Returns
-------
solprop.stepper.multistep.MarchPolicy
The record, with no quiet interval.
"""
responses = problem.responses
collar = responses.temporal_absorber
collar_rate = (
0.5 * float(np.max(collar))
if collar is not None
and responses.absorber_scheme == "nonlinear"
and method.formulation == "exponential"
else 0.0
)
linear = problem.linear
return march_policy(
method,
dz_min=stepper.dz_min,
dz_max=stepper.dz_max,
stretch=stepper.stretch,
z_end=stepper.z_end,
save_planes=np.asarray(stepper.save_planes, dtype=np.float64).tolist(),
hard_kinks=np.asarray(linear.hard_kinks, dtype=np.float64).tolist(),
breakpoints=np.asarray(linear.phi_breakpoints, dtype=np.float64).tolist(),
interpolate=bool(stepper.interpolate_planes),
collar_rate=collar_rate,
carrier=carrier,
)
[docs]
@dataclass(frozen=True)
class LowStorageSettings:
"""What the low-storage replay reads beside the Runge-Kutta policy (SEP 24).
Attributes
----------
flows : int
The flow volumes a step holds on a CPU
(:func:`~solprop.backends.memory.low_storage_flows`): 0 recomputes each flow,
1 holds a constant operator's table ``exp(h_t D / 2)``, 2 a varying operator's
``P`` and ``Q``.
separable : bool
Whether the operator is a separable geometry's, whose increments are the
distances themselves.
origin : float
The operator's origin, ``linear.z_span[0]``, m, from which a table is built.
"""
flows: int
separable: bool
origin: float
[docs]
def low_storage_settings(
problem: "PropagationProblem", stepper: "StepperSettings"
) -> LowStorageSettings | None:
"""Return the low-storage replay's settings, or ``None`` for another march.
Parameters
----------
problem : solprop.translate.problem.PropagationProblem
The problem.
stepper : solprop.translate.problem.StepperSettings
The run's stepper settings.
Returns
-------
LowStorageSettings or None
The settings, when the run's integrator is the low-storage march.
"""
if not isinstance(stepper.integrator, LowStorageRungeKutta):
return None
return LowStorageSettings(
flows=low_storage_flows(problem, stepper, "native"),
separable=problem.linear.separable is not None,
origin=float(problem.linear.z_span[0]),
)
[docs]
def collar_rests(problem: "PropagationProblem", stepper: "StepperSettings") -> bool:
"""Return whether a run's stages may leave a quiet temporal collar out (SEP 21).
One rule for every backend: a modal or radial stage with the in-stage
(``"nonlinear"``) scheme and a temporal collar alone. The low-storage march, coupled
flows, the general modal route, a real-space collar sharing the term, and the
Cartesian, line and planar routes keep the collar in every stage (SEP 21 D15).
Parameters
----------
problem : solprop.translate.problem.PropagationProblem
The problem.
stepper : solprop.translate.problem.StepperSettings
The run's stepper settings.
Returns
-------
bool
True when the term may be left out while the collar is quiet.
"""
responses = problem.responses
geometry = problem.transform.geometry
resting_geometry = geometry is None or (
geometry.kind == "radial" and not np.any(geometry.absorber_rate)
)
return (
not isinstance(stepper.integrator, LowStorageRungeKutta)
and responses.temporal_absorber is not None
and responses.absorber_scheme == "nonlinear"
and problem.linear.coupled_flow is None
and problem.transform.modal_tables is None
and resting_geometry
)
# -- the plane plan -------------------------------------------------------------------
[docs]
@dataclass(frozen=True, eq=False)
class PlanePlan:
"""Where a run is observed and how its session buffers (SEP 47 section 5.3).
Equality is by identity (``eq=False``) because ``planes`` is an array.
Attributes
----------
z : float
Where the run starts, m.
planes : numpy.ndarray
The save planes, m, shape ``(n_z,)``.
next_plane : int
The first save plane strictly beyond `z`.
launch_pending : bool
Whether the plane at `z` is owed.
step_planes : int
Save every this many accepted steps; 0 for none.
dense : bool
Whether the planes are interpolated rather than landed on.
period : int
Accepted steps between the periodic statistics rows; 0 without rows.
replay_steps : int
A fixed schedule's steps; 0 without one.
replay_length : float
A fixed schedule's total length, m; 0.0 without one.
attempt_capacity, row_capacity : int
The most attempts and periodic rows the native session holds between two
events (:data:`ATTEMPT_CAPACITY`, :data:`ROW_CAPACITY`).
call_attempts : int
A march call's most attempts (:data:`CALL_ATTEMPTS`).
call_seconds : float
A march call's most wall time, s (:data:`CALL_SECONDS`).
"""
z: float
planes: Float[np.ndarray, " n_z"]
next_plane: int
launch_pending: bool
step_planes: int
dense: bool
period: int
replay_steps: int
replay_length: float
attempt_capacity: int
row_capacity: int
call_attempts: int
call_seconds: float
[docs]
@property
def fixed_positions(self) -> tuple[float, ...] | None: # numpydoc ignore=RT01
"""Every position a plane is observed at, m, when the plan fixes them all.
The start and the save planes; ``None`` with step planes or interpolated
planes, whose positions the march decides.
"""
if self.dense or self.step_planes:
return None
return (self.z, *(float(z) for z in self.planes))
[docs]
def plane_plan(request: "RunRequest", start: "Start") -> PlanePlan:
"""Return a run's plane plan.
Parameters
----------
request : solprop.translate.run_request.RunRequest
The run's request.
start : solprop.backends.session.Start
Where the run starts.
Returns
-------
PlanePlan
The plan, with the native session's capacities.
"""
observation = request.observation
spec = observation.stats
schedule = None if request.replay is None else request.replay.schedule
return PlanePlan(
z=float(start.z),
planes=np.ascontiguousarray(observation.save_planes, dtype=np.float64),
next_plane=int(start.plane_index),
launch_pending=bool(start.plane_pending),
step_planes=int(observation.step_planes),
dense=bool(observation.dense),
period=int(spec.period) if spec.periodic else 0,
replay_steps=0 if schedule is None else int(schedule.n_steps),
replay_length=0.0 if schedule is None else float(schedule.total_length),
attempt_capacity=ATTEMPT_CAPACITY,
row_capacity=ROW_CAPACITY,
call_attempts=CALL_ATTEMPTS,
call_seconds=CALL_SECONDS,
)
# -- the boundary monitor -------------------------------------------------------------
[docs]
@dataclass(frozen=True, eq=False)
class MonitorConfig:
"""A session's boundary monitor's configuration (``watch::Config``).
Equality is by identity (``eq=False``) because ``rate`` is an array.
Attributes
----------
policy : collections.abc.Mapping
The predictions' policy (:meth:`~solprop.monitor.BoundaryMonitor.watch_policy`'s
fields), its floor regions and launch floor zero: they are formed at the
launch.
floor_share : float
No light is judged below this share of the launch energy.
floor_margin : float
:data:`solprop.monitor.FLOOR_MARGIN`.
budget : float
The budget the finish's removal is judged against.
rate : numpy.ndarray
The collar's power rate on the coarse axis, 1/m, shape ``(n_t,)``.
can_rest : bool
Whether the route's stages may leave a quiet collar out (:func:`collar_rests`).
"""
policy: Mapping[str, object]
floor_share: float
floor_margin: float
budget: float
rate: Float[np.ndarray, " n_t"]
can_rest: bool
[docs]
def monitor_config(
monitor: "BoundaryMonitor", crossing: "SplitCrossing | None", *, can_rest: bool
) -> MonitorConfig:
"""Return a fresh monitor's configuration for a run.
The predictions' policy is the monitor's own with the split collar's crossing limit
the run gives it.
Parameters
----------
monitor : solprop.monitor.BoundaryMonitor
The run's fresh monitor.
crossing : solprop.boundaries.SplitCrossing or None
The split collar's crossing limit, under the split scheme.
can_rest : bool
Whether the route's stages may leave a quiet collar out.
Returns
-------
MonitorConfig
The configuration.
"""
configured = dataclasses.replace(monitor, crossing=crossing)
policy = configured.watch_policy()
policy["floor_regions"] = [0.0, 0.0, 0.0, 0.0]
policy["launch_floor"] = 0.0
return MonitorConfig(
policy=policy,
floor_share=_FLOOR,
floor_margin=FLOOR_MARGIN,
budget=float(monitor.check.budget),
rate=np.ascontiguousarray(monitor.weights[3], dtype=np.float64),
can_rest=bool(can_rest),
)
[docs]
@dataclass(frozen=True, eq=False)
class EdgeConfig:
"""A session's transverse edge's configuration (``transverse::Config``, SEP 40).
Every threshold is formed as :class:`~solprop.transverse_monitor.TransverseEdge`
forms it, so that a session compares the same numbers. Equality is by identity
(``eq=False``) because it holds arrays.
Attributes
----------
faces : tuple of str
The faces judged, in the edge's order.
warn, stop : float
``budget ** 2`` and ``(stop_factor * budget) ** 2``.
length : float
The run's length, m.
guard : float
The guard's width.
k_min : float
The safety ramp's least transverse wavenumber, 1/m.
k_floor : float
:data:`~solprop.spatial_absorber.RAMP_K_FLOOR`.
reads, backstop_reads, reach_growth, noise_factor : float
:mod:`solprop.transverse_monitor`'s constants of those names.
columns : numpy.ndarray
The spectral columns' weights, shape ``(n_columns,)``.
kappa : numpy.ndarray
Each column's transverse wavenumber, 1/m, shape ``(n_kappa,)``.
kappa_order : numpy.ndarray
Its ascending order, ``uint64``, shape ``(n_kappa,)``.
design : bool
Whether a safety ramp is designed.
ramp_rate : numpy.ndarray
The ramp's rate by column, 1/m; empty without a design.
collar, collar_rate : bool
Whether the design has a collar, and a collar rate.
declared : bool
Whether the run declares content above ``discard_above`` (:func:`declared`).
reads_edge : bool
Whether the backend reads the edge.
longest_step : float or None
A fixed schedule's longest step, m; ``None`` without one.
noise_share : float
The input noise's share of the weights on the first face.
noise_modes : float
The input noise's count of modes.
"""
faces: tuple[str, ...]
warn: float
stop: float
length: float
guard: float
k_min: float
k_floor: float
reads: float
backstop_reads: float
reach_growth: float
noise_factor: float
columns: Float[np.ndarray, " n_columns"]
kappa: Float[np.ndarray, " n_kappa"]
kappa_order: UInt[np.ndarray, " n_kappa"]
design: bool
ramp_rate: Float[np.ndarray, " n_ramp"]
collar: bool
collar_rate: bool
declared: bool
reads_edge: bool
longest_step: float | None
noise_share: float
noise_modes: float
[docs]
def declared(problem: "PropagationProblem") -> bool:
"""Return whether a run declares content above ``discard_above``.
Parameters
----------
problem : solprop.translate.problem.PropagationProblem
The problem.
Returns
-------
bool
True when its transverse specification sets ``discard_above``.
"""
design = transverse_of(problem.route)
return design is not None and design.specification.discard_above is not None
[docs]
def edge_config(
edge: "TransverseEdge",
*,
steps: Float[np.ndarray, " n_steps"] | None,
declared: bool,
reads: bool = True,
) -> EdgeConfig:
"""Return a fresh transverse edge's configuration for its launch's arguments.
Parameters
----------
edge : solprop.transverse_monitor.TransverseEdge
The run's fresh edge.
steps : numpy.ndarray or None
A fixed schedule's steps, m; ``None`` for an adaptive run.
declared : bool
Whether the run declares content above ``discard_above``.
reads : bool, optional
Whether the backend reads the edge.
Returns
-------
EdgeConfig
The configuration.
"""
design = edge.design
faces = edge._faces # pyright: ignore[reportPrivateUsage] - the edge's own geometry
weights = edge._weights # pyright: ignore[reportPrivateUsage]
first = faces[0].edge
modes = max(int(np.count_nonzero(first)), 1) * max(int(edge.band.size), 1)
return EdgeConfig(
faces=tuple(face.name for face in faces),
warn=edge.budget**2,
stop=(edge.stop_factor * edge.budget) ** 2,
length=float(edge.length),
guard=float(edge._guard), # pyright: ignore[reportPrivateUsage]
k_min=float(edge.k_min),
k_floor=float(RAMP_K_FLOOR),
reads=float(READS),
backstop_reads=float(BACKSTOP_READS),
reach_growth=float(REACH_GROWTH),
noise_factor=float(NOISE_FACTOR),
columns=np.ascontiguousarray(
edge._columns, # pyright: ignore[reportPrivateUsage]
dtype=np.float64,
),
kappa=np.ascontiguousarray(
edge._kappa, # pyright: ignore[reportPrivateUsage]
dtype=np.float64,
),
kappa_order=np.ascontiguousarray(
edge._kappa_order, # pyright: ignore[reportPrivateUsage]
dtype=np.uint64,
),
design=design is not None,
ramp_rate=np.empty(0, dtype=np.float64)
if design is None
else np.ascontiguousarray(design.ramp_rate, dtype=np.float64),
collar=design is not None and design.has_collar,
collar_rate=design is not None and design.collar_rate is not None,
declared=bool(declared),
reads_edge=bool(reads),
longest_step=float(np.max(steps)) if steps is not None and steps.size else None,
noise_share=float(np.sum(weights[first])) / float(np.sum(weights)),
noise_modes=float(modes),
)
[docs]
@dataclass(frozen=True)
class Resumption:
"""What a resume reads of an earlier monitor record (``watch::Resumption``).
Only the record's types are read: which numbers are restored, their defaults and the
fallbacks are the session's.
Attributes
----------
record : bool
Whether there is a record at all.
collar_quiet : bool
``bool(record.get("collar_quiet", False))``.
numbers : collections.abc.Mapping
Each number present in the record, by field; the counts already whole.
unwatched : tuple or None
The record's ``unwatched`` stretches, when it lists them.
resumed_at : tuple or None
The record's ``resumed_at``, when it lists them.
planes : tuple or None
The record's plane rows by :data:`PLANE_COLUMNS` (NaN for ``None``), when they
have those five columns.
"""
record: bool
collar_quiet: bool = False
numbers: Mapping[str, float] = field(default_factory=dict[str, float])
unwatched: tuple[tuple[float, ...], ...] | None = None
resumed_at: tuple[float, ...] | None = None
planes: tuple[tuple[float, ...], ...] | None = None
def _number(record: Mapping[str, object], name: str) -> float | None:
"""Return a record's number, or ``None`` when it is absent or not a number.
As ``solprop.monitor._number`` reads it, without its default, which the session's
reconstruction applies.
"""
value = record.get(name)
if isinstance(value, bool) or not isinstance(value, int | float):
return None
return float(value)
[docs]
def resumption(record: Mapping[str, object] | None) -> Resumption:
"""Return what a resume reads of an earlier execution's monitor record.
Read as :meth:`~solprop.monitor.BoundaryMonitor.resume` reads it: each number
present, the lists, and the plane rows when they have the five columns. A count
that is not whole is refused as that resume refuses it, once the record's launch
energy makes it read the counts.
Parameters
----------
record : collections.abc.Mapping or None
The ``boundary_monitor`` record of the latest earlier execution, or ``None``.
Returns
-------
Resumption
What the session restores from.
"""
if record is None:
return Resumption(record=False)
numbers: dict[str, float] = {}
for name in _NUMBERS:
value = _number(record, name)
if value is not None:
numbers[name] = value
launch = numbers.get("launch_energy", math.nan)
if launch > 0.0:
# `BoundaryMonitor.resume` reads the counts only past its launch test.
quiet = _number(record, "quiet_checks")
if quiet is not None and math.isfinite(quiet):
numbers["quiet_checks"] = float(_count(quiet, "quiet_checks"))
for name in _COUNTS:
value = _number(record, name)
numbers[name] = float(_count(0.0 if value is None else value, name))
listed = record.get("unwatched")
resumed = record.get("resumed_at")
rows = record.get("planes")
planes = None
if isinstance(rows, Mapping) and set(cast("Mapping[str, object]", rows)) == set(
PLANE_COLUMNS
):
columns = cast("Mapping[str, list[float | None]]", rows)
planes = tuple(
tuple(math.nan if one is None else float(one) for one in columns[name])
for name in PLANE_COLUMNS
)
return Resumption(
record=True,
collar_quiet=bool(record.get("collar_quiet", False)),
numbers=numbers,
unwatched=tuple(
tuple(float(one) for one in cast("list[float]", stretch))
for stretch in cast("list[object]", listed)
)
if isinstance(listed, list)
else None,
resumed_at=tuple(float(one) for one in cast("list[float]", resumed))
if isinstance(resumed, list)
else None,
planes=planes,
)
[docs]
@dataclass(frozen=True)
class EdgeResumption:
"""What a resume reads of an earlier edge record (``transverse::Resumption``).
Attributes
----------
record : bool
Whether there is a record at all.
numbers : collections.abc.Mapping
Each number present in the record, by field.
edge_baseline, edge_max, edge_max_raw : tuple of float or None
The per-face lists, once the record's launch energy and baseline make the
resume read them; each ``None`` otherwise or without a value per face.
reads : int or None
The reads, made whole, under the same condition.
transverse_status : str or None
The record's status, when it names one.
"""
record: bool
numbers: Mapping[str, float] = field(default_factory=dict[str, float])
edge_baseline: tuple[float, ...] | None = None
edge_max: tuple[float, ...] | None = None
edge_max_raw: tuple[float, ...] | None = None
reads: int | None = None
transverse_status: str | None = None
def _per_face(
record: Mapping[str, object], name: str, faces: int
) -> tuple[float, ...] | None:
"""Return a record's per-face list, or ``None`` when it has no value per face.
As ``TransverseEdge.resume``'s ``numbers`` reads it.
"""
value = record.get(name)
if not isinstance(value, list) or len(cast("list[object]", value)) != faces:
return None
return tuple(float(cast("float", one)) for one in cast("list[object]", value))
[docs]
def edge_resumption(record: object, faces: int) -> EdgeResumption:
"""Return what a resume reads of an earlier execution's transverse edge record.
Read as :meth:`~solprop.transverse_monitor.TransverseEdge.resume` reads it: each
number present, and, once the record's launch energy and baseline make that resume
read further, each per-face maximum that has a value per face and the reads, made
whole as it makes them.
Parameters
----------
record : object
The ``transverse`` entry of the earlier monitor record, or anything else when
there is none.
faces : int
The edge's face count.
Returns
-------
EdgeResumption
What the session restores from.
"""
if not isinstance(record, Mapping):
return EdgeResumption(record=False)
mapping = cast("Mapping[str, object]", record)
numbers: dict[str, float] = {}
for name in _EDGE_NUMBERS:
value = _number(mapping, name)
if value is not None:
numbers[name] = value
baseline = _per_face(mapping, "edge_baseline", faces)
launch = numbers.get("launch_energy", math.nan)
status = mapping.get("transverse_status")
if not (launch > 0.0 and baseline is not None):
# `TransverseEdge.resume` reads the maxima and the count only past its test of
# the launch and the baseline: a record it ignores is not read further.
return EdgeResumption(
record=True,
numbers=numbers,
transverse_status=status if isinstance(status, str) else None,
)
reads = _number(mapping, "reads")
return EdgeResumption(
record=True,
numbers=numbers,
edge_baseline=baseline,
edge_max=_per_face(mapping, "edge_max", faces),
edge_max_raw=_per_face(mapping, "edge_max_raw", faces),
reads=int(0.0 if reads is None else reads),
transverse_status=status if isinstance(status, str) else None,
)
[docs]
@dataclass(frozen=True)
class MonitorContinuation:
"""A monitored resume's continuation, as a session reads it.
Attributes
----------
record : Resumption
The earlier monitor record's resumption.
edge : EdgeResumption
Its transverse edge record's.
plane : bool
Whether the run resumes at a saved plane.
unwatched : tuple of tuple of float
The ``(start, end)`` stretches, m, run since without a monitor.
"""
record: Resumption
edge: EdgeResumption
plane: bool
unwatched: tuple[tuple[float, float], ...]
[docs]
def monitor_continuation(
monitor: "BoundaryMonitor", continuation: Mapping[str, object]
) -> MonitorContinuation:
"""Return a monitored resume's continuation records.
Parameters
----------
monitor : solprop.monitor.BoundaryMonitor
The run's fresh monitor, whose transverse edge gives the face count.
continuation : collections.abc.Mapping
As :attr:`solprop.backends.session.Start.monitor`.
Returns
-------
MonitorContinuation
The records.
"""
record = continuation.get("record")
mapping = (
cast("Mapping[str, object]", record) if isinstance(record, Mapping) else None
)
edge = monitor.transverse
faces = 0 if edge is None else len(edge._faces) # pyright: ignore[reportPrivateUsage]
stretches = cast("Sequence[tuple[float, float]]", continuation.get("unwatched", ()))
return MonitorContinuation(
record=resumption(mapping),
edge=edge_resumption(
None if mapping is None else mapping.get("transverse"), faces
),
plane=bool(continuation.get("plane", False)),
unwatched=tuple((float(start), float(end)) for start, end in stretches),
)
[docs]
@dataclass(frozen=True, eq=False)
class MonitorRecords:
"""A monitored run's boundary records.
Attributes
----------
config : MonitorConfig
The temporal monitor's configuration.
edge : EdgeConfig or None
A free-space run's transverse edge's, or ``None`` without one.
continuation : MonitorContinuation or None
A monitored resume's continuation, or ``None`` when the start carries none
(a session may still be continued before it watches).
"""
config: MonitorConfig
edge: EdgeConfig | None
continuation: MonitorContinuation | None
[docs]
def monitor_records(
problem: "PropagationProblem", request: "RunRequest", start: "Start"
) -> MonitorRecords | None:
"""Return a run's boundary records, or ``None`` without a monitor.
Parameters
----------
problem : solprop.translate.problem.PropagationProblem
The problem: the split collar's crossing limit, the quiet-collar rule and a
declared transverse specification.
request : solprop.translate.run_request.RunRequest
The run's request, with its fresh monitor.
start : solprop.backends.session.Start
Where the run starts, with any monitor continuation.
Returns
-------
MonitorRecords or None
The records.
"""
monitor = request.boundary.monitor
if monitor is None:
return None
stepper = request.stepper
edge = monitor.transverse
schedule = stepper.schedule
return MonitorRecords(
config=monitor_config(
monitor,
problem.split_crossing if monitor.split else None,
can_rest=collar_rests(problem, stepper),
),
edge=None
if edge is None
else edge_config(
edge,
steps=None if schedule is None else np.asarray(schedule.steps),
declared=declared(problem),
),
continuation=None
if start.monitor is None
else monitor_continuation(monitor, start.monitor),
)
# -- the boundary verdicts ------------------------------------------------------------
[docs]
class NoticeKind(enum.IntEnum):
"""A boundary monitor's notice's kind (``session::Notice::Kind``).
Attributes
----------
NONE : int
No notice.
GUARD : int
A guard occupancy, at the launch or at a check.
REMOVAL : int
The collar's removal at the end of a run.
CROSSING : int
A replay's step passes the split collar's cap.
READING : int
The split found nothing where the state holds light.
DIVISION : int
Light after a launch that held none, which the monitor divides by.
TRANSVERSE : int
The transverse edge's verdict (:class:`EdgeNotice`).
"""
NONE = 0
GUARD = 1
REMOVAL = 2
CROSSING = 3
READING = 4
DIVISION = 5
TRANSVERSE = 6
[docs]
@dataclass(frozen=True)
class Notice:
"""A boundary monitor's verdict (``session::Notice``): a warning or a stop.
Attributes
----------
kind : NoticeKind
What it is.
launch : bool
For a guard: whether it is the launch's judgement.
z : float
Where, m.
value : float
A guard's amplitude, or the removed fraction.
cap : float
A crossing's cap, m.
step : float
A crossing's longest step before the next check, m.
"""
kind: NoticeKind
launch: bool
z: float
value: float
cap: float
step: float
[docs]
class EdgeNoticeKind(enum.IntEnum):
"""A transverse edge's notice's kind (``transverse::Notice::Kind``).
Attributes
----------
NONE : int
No notice.
RAMP_BAND : int
The launch's share in the safety ramp's band.
UNWATCHED : int
The backend does not read the edge.
CLIP : int
A face's clip of the launch.
INSENSITIVE : int
The input noise's allowance exceeds the warning.
COARSE : int
A fixed schedule's longest step outruns the read spacing.
FACE : int
A face's judged share.
RETURNED : int
A requested collar's returned share.
RAMP_REMOVAL : int
The safety ramp's removal.
"""
NONE = 0
RAMP_BAND = 1
UNWATCHED = 2
CLIP = 3
INSENSITIVE = 4
COARSE = 5
FACE = 6
RETURNED = 7
RAMP_REMOVAL = 8
[docs]
@dataclass(frozen=True)
class EdgeNotice:
"""A transverse edge's verdict (``transverse::Notice``): a warning or a stop.
Attributes
----------
kind : EdgeNoticeKind
What it is.
stop : bool
Whether it stops the run.
face : int
The face it names, by index.
value : float
The share, allowance or step it names.
z : float
Where, m.
spacing : float
A coarse schedule's read spacing, m.
warned_at : float
Where the edge first warned, for a face's stop, m; NaN where it did not.
"""
kind: EdgeNoticeKind
stop: bool
face: int
value: float
z: float
spacing: float
warned_at: float
# -- one run's records ----------------------------------------------------------------
[docs]
@dataclass(frozen=True, eq=False)
class RunRecords:
"""Every record of one run, formed once by :func:`run_records` (SEP 52 §5.1).
Attributes
----------
policy : solprop.stepper.multistep.MarchPolicy or RungeKuttaPolicy
The method's policy: the Adams march's, or the Runge-Kutta march's, which the
low-storage replay reads too.
low_storage : LowStorageSettings or None
The low-storage replay's settings; ``None`` for another march.
schedule : solprop.stepper.schedule.FixedSchedule or None
The fixed schedule, when the run replays one.
planes : PlanePlan
The plane plan.
monitor : MonitorRecords or None
The boundary records; ``None`` without a monitor.
"""
policy: MarchPolicy | RungeKuttaPolicy
low_storage: LowStorageSettings | None
schedule: FixedSchedule | None
planes: PlanePlan
monitor: MonitorRecords | None
[docs]
def run_records(
problem: "PropagationProblem", request: "RunRequest", start: "Start"
) -> RunRecords:
"""Return one run's records.
Parameters
----------
problem : solprop.translate.problem.PropagationProblem
The translated problem.
request : solprop.translate.run_request.RunRequest
The run's request.
start : solprop.backends.session.Start
Where the run starts; its field is not read.
Returns
-------
RunRecords
The records.
Examples
--------
>>> from solprop.backends.records import run_records
>>> from solprop.backends.session import Start
>>> 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
>>> grid = EnvelopeGrid.from_limits(1.0, 835e-9, (500e-9, 2e-6), 1e-12)
>>> gnlse = problem_from([0.0, 0.0, -1.183e-26], omega_ref=grid.omega0,
... gamma=0.11, shock=False)
>>> launch = SechPulse(wavelength=835e-9, width=100e-15, peak_power=9.8)
>>> problem, request = assemble(grid, gnlse.mode, [gnlse.kerr], launch.build(grid),
... controller=PIController(rtol=1e-8, atol=1e-16),
... save_planes=[0.01], dz_max=0.01, dz_init=1e-3,
... density=1.0, shock=False, prefactor_index=1.0)
>>> records = run_records(problem, request, Start.entrance(problem))
>>> type(records.policy).__name__, records.planes.planes.tolist()
('RungeKuttaPolicy', [0.01])
>>> records.low_storage is None, records.monitor is None
(True, True)
"""
stepper = request.stepper
method = stepper.integrator
policy: MarchPolicy | RungeKuttaPolicy
if isinstance(method, Multistep):
reference = carrier_reference(problem, method)
policy = adams_policy(
problem,
stepper,
method,
carrier=reference is not None and reference.active,
)
else:
policy = runge_kutta_policy(problem, stepper)
return RunRecords(
policy=policy,
low_storage=low_storage_settings(problem, stepper),
schedule=stepper.schedule,
planes=plane_plan(request, start),
monitor=monitor_records(problem, request, start),
)