solprop.translate.run_request#

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

The translated problem (solprop.translate.problem.PropagationProblem) says what is propagated. A RunRequest says how it is run: which integration method, how errors are controlled, which fixed itinerary is replayed, what is observed and kept, what the boundary watches and which method history is retained. 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 (solprop.backends.session).

The request separates method selection from error scaling and acceptance, as SEP 47 section 6.3 specifies:

IntegrationSpec names the method – an embedded Runge-Kutta tableau, the low-call Adams family or the fixed low-storage replay – and its options;
ErrorControlSpec holds the tolerances, the norm, the controller and the step limits;
ReplaySpec holds a fixed itinerary, when one is replayed;
ObservationRequest holds the planes, dense output, step planes, statistics and field retention;
BoundaryRequest holds the boundary monitor’s configuration;
HistoryPolicy says when the method’s history is kept for a resume.

describe_run() builds one from the stepper section translation resolved (StepperSettings) and the run’s settings; solprop.translate.problem.assemble() returns the request for a fresh run beside its problem, and RunRequest.for_run() adapts it to one run’s start, retention, monitor and history. The problem carries none of this (SEP 47 section 5.2).

Module Attributes

MARCH_SNAPSHOT_AUTO_BYTES

The automatic method-history retention limit, bytes (SEP 47 section 5.5).

Functions

describe_run(stepper, *[, stats, retention, ...])

Build the run request from a resolved stepper section and the run's settings.

Classes

`BoundaryRequest`([monitor])	What the boundary watches.
`ErrorControlSpec`(controller, dz_min, dz_max, ...)	Tolerances, the controller and the step limits.
`HistoryPolicy`([retention])	The method-history retention policy.
`HistoryRetention`(*values)	When the method's history is kept for a resume.
`IntegrationSpec`(kind, tableau, method, ...)	Which method integrates the run, and its options.
`MethodKind`(*values)	The integration method family.
`ObservationRequest`(save_planes, start_plane, ...)	What a run observes and keeps.
`ReplaySpec`(schedule)	A fixed itinerary, replayed rather than chosen.
`RunRequest`(integration, error_control, ...)	Every policy of one run, resolved before preparation.

class solprop.translate.run_request.BoundaryRequest(monitor=None)[source]#

Bases: object

What the boundary watches.

Attributes:

monitorsolprop.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#

class solprop.translate.run_request.ErrorControlSpec(controller, dz_min, dz_max, dz_init, stretch, auto_init, interval_cap)[source]#

Bases: object

Tolerances, the controller and the step limits.

Attributes:

controllersolprop.stepper.controller.PIController: The controller and its norm. A subclass that overrides a decision method is a reference-only experiment (SEP 47 section 6.3).
dz_minfloat: The step floor, m.
dz_maxfloat: The step ceiling, m.
dz_initfloat: The first proposal, m.
stretchfloat: The fraction by which a step may stretch to land on a plane.
auto_initbool: Whether the first proposal is chosen from the launch state.
interval_capbool: Whether a step is capped to the interval it starts in.

auto_init: bool#

controller: PIController#

dz_init: float#

dz_max: float#

dz_min: float#

interval_cap: bool#

stretch: float#

class solprop.translate.run_request.HistoryPolicy(retention=HistoryRetention.AUTO)[source]#

Bases: object

The method-history retention policy.

Attributes:

retentionHistoryRetention: When to keep it.

classmethod from_choice(choice)[source]#

Return the policy for the public resume_history choice.

Parameters:

choicebool or None: True keeps it always, False never and None automatically.

Returns:

HistoryPolicy: The policy.

retention: HistoryRetention = 'auto'#

class solprop.translate.run_request.HistoryRetention(*values)[source]#

Bases: Enum

When the method’s history is kept for a resume.

Attributes:

AUTOstr: Kept while it is at most MARCH_SNAPSHOT_AUTO_BYTES; omitted beyond that, which a resume reports.
REQUIREDstr: Always kept; a snapshot that cannot keep it fails rather than downgrading.
OFFstr: Never kept, by explicit choice.

AUTO = 'auto'#

OFF = 'off'#

REQUIRED = 'required'#

class solprop.translate.run_request.IntegrationSpec(kind, tableau, method, propagator_mode)[source]#

Bases: object

Which method integrates the run, and its options.

Attributes:

kindMethodKind: The method family.
tableausolprop.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.
methodMultistep, ComparisonMultistep, 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#

method: Multistep | ComparisonMultistep | LowStorageRungeKutta | None#

propagator_mode: Literal['auto', 'tabulate', 'recompute']#

property reference_only: bool[source]#

Return whether only the NumPy reference runs this method.

Returns:

bool: True for the benchmark-only comparison family, ComparisonMultistep (SEP 47 section 6.3): PEC, PECE, explicit Adams-Bashforth and the matched pairs, which native refuses; Multistep is the selected method every backend runs.

tableau: Tableau#

solprop.translate.run_request.MARCH_SNAPSHOT_AUTO_BYTES = 268435456#: The automatic method-history retention limit, bytes (SEP 47 section 5.5).

class solprop.translate.run_request.MethodKind(*values)[source]#

Bases: Enum

The integration method family.

Attributes:

RUNGE_KUTTAstr: An embedded Runge-Kutta tableau, adaptive or replayed.
ADAMSstr: The low-call Adams family (Multistep), including its benchmark-only comparison variants, which only the reference runs.
LOW_STORAGEstr: The fixed-schedule low-storage RK4IP replay (SEP 24).

ADAMS = 'adams'#

LOW_STORAGE = 'low_storage'#

RUNGE_KUTTA = 'runge_kutta'#

class solprop.translate.run_request.ObservationRequest(save_planes, start_plane, dense, step_planes, stats, retention)[source]#

Bases: object

What a run observes and keeps.

Attributes:

save_planesnumpy.ndarray: The requested planes, m, increasing, read-only.
start_planeint: The first save plane strictly beyond the starting state.
densebool: Whether planes are interpolated from dense output rather than landed on.
step_planesint: Observe the endpoint of every step_planes-th accepted step; 0 for none.
statssolprop.stats.StatsSpec: The plane statistics, and the periodic subset with its period.
retentionsolprop.output.schema.FieldRetention: Which observed planes keep their field.

dense: bool#

retention: FieldRetention#

save_planes: Float[ndarray, 'n_z']#

start_plane: int#

stats: StatsSpec#

step_planes: int#

class solprop.translate.run_request.ReplaySpec(schedule)[source]#

Bases: object

A fixed itinerary, replayed rather than chosen.

Attributes:

schedulesolprop.stepper.schedule.FixedSchedule: The step edges.

schedule: FixedSchedule#

class solprop.translate.run_request.RunRequest(integration, error_control, replay, observation, boundary, history, snapshots=False)[source]#

Bases: object

Every policy of one run, resolved before preparation.

Attributes:

integrationIntegrationSpec: The method.
error_controlErrorControlSpec: Tolerances, controller and step limits.
replayReplaySpec or None: A fixed itinerary; None for an adaptive run.
observationObservationRequest: Planes, statistics and field retention.
boundaryBoundaryRequest: The boundary monitor’s configuration.
historyHistoryPolicy: Method-history retention for a resume.
snapshotsbool: Whether snapshot requests may arrive during the run.

boundary: BoundaryRequest#

error_control: ErrorControlSpec#

for_run(*, stats=None, retention=None, start_plane=0, monitor=None, history=None, snapshots=False)[source]#

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:

statssolprop.stats.StatsSpec or None, optional: The statistics; this request’s own by default.
retentionsolprop.output.schema.FieldRetention or None, optional: Field retention, already resolved against the planes; every field by default.
start_planeint, optional: The first save plane beyond the starting state.
monitorsolprop.monitor.BoundaryMonitor or None, optional: A fresh boundary monitor, or None.
historyHistoryPolicy or None, optional: Method-history retention; automatic by default.
snapshotsbool, 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.translate.problem 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

history: HistoryPolicy#

integration: IntegrationSpec#

observation: ObservationRequest#

replay: ReplaySpec | None#

snapshots: bool = False#

property stepper: StepperSettings[source]#

Return the stepping policy as the one record translation resolved.

The method, the error control, the itinerary and the planes, gathered back into StepperSettings for the code that reads them together: the march drivers, the request-aware checks (solprop.translate.problem.validate_run()) and the run’s configuration record, whose hash they enter exactly as before.

Returns:

solprop.translate.problem.StepperSettings: The record, built once per request.

Examples

>>> from solprop.stepper import DOPRI5, PIController
>>> from solprop.translate.problem 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]

with_stepper(stepper)[source]#

Return this request with another stepper section, its other policies kept.

The statistics, retention, start, monitor, history and snapshot policy stay; the method, the error control, the itinerary and the planes are stepper’s. solprop.driver.simulation.Simulation.with_input() uses it for the planes left beyond an interior launch.

Parameters:

steppersolprop.translate.problem.StepperSettings: The new stepper section.

Returns:

RunRequest: The request.

Raises:

TranslationError: If this request’s start plane is not a plane of the new section.

Examples

>>> import dataclasses
>>> from solprop.stepper import DOPRI5, PIController
>>> from solprop.translate.problem 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]

solprop.translate.run_request.describe_run(stepper, *, stats=None, retention=None, start_plane=0, monitor=None, history=None, snapshots=False)[source]#

Build the run request from a resolved stepper section and the run’s settings.

Parameters:

steppersolprop.translate.problem.StepperSettings: The stepper section translation resolved; it supplies the method, error control, itinerary and planes.
statssolprop.stats.StatsSpec or None, optional: The statistics; none by default.
retentionsolprop.output.schema.FieldRetention or None, optional: Field retention, already resolved against the planes; every field by default.
start_planeint, optional: The first save plane beyond the starting state.
monitorsolprop.monitor.BoundaryMonitor or None, optional: A fresh boundary monitor to copy, or None.
historyHistoryPolicy or None, optional: Method-history retention; automatic by default.
snapshotsbool, 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.problem 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])