solprop.translate.run_request#

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

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

describe_run() builds one from the resolved StepperSettings and the run’s settings; solprop.translate.assembly.assemble() returns it beside its problem, which solprop.driver.simulation.Simulation.run_request() gives out, and RunRequest.for_run() adapts it to one run’s start, retention, monitor and history.

Module Attributes

MARCH_SNAPSHOT_AUTO_BYTES

The largest Adams march snapshot a run keeps with resume_history=None, bytes.

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.

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, 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 | LowStorageRungeKutta | None#
propagator_mode: Literal['auto', 'tabulate', 'recompute']#
tableau: Tableau#
solprop.translate.run_request.MARCH_SNAPSHOT_AUTO_BYTES = 268435456#

The largest Adams march snapshot a run keeps with resume_history=None, bytes.

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

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).

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.store.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.

A Simulation gives the request its translation built beside the problem through run_request(); describe_run() builds one from a stepper section of your own.

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.store.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.stepper.settings import StepperSettings
>>> from solprop.translate.run_request import describe_run
>>> settings = StepperSettings(DOPRI5, PIController(rtol=1e-8, atol=1e-14),
...                            1e-9, 0.1, 1e-3, 1.1, None, [0.5, 1.0], "auto")
>>> describe_run(settings).for_run(start_plane=1).observation.start_plane
1
history: HistoryPolicy#
integration: IntegrationSpec#
observation: ObservationRequest#
replay: ReplaySpec | None#
snapshots: bool = False#
property stepper: StepperSettings[source]#

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.

The record, built once per request.

Examples

>>> from solprop.stepper import DOPRI5, PIController
>>> from solprop.stepper.settings import StepperSettings
>>> from solprop.translate.run_request import describe_run
>>> settings = StepperSettings(DOPRI5, PIController(rtol=1e-8, atol=1e-14),
...                            1e-9, 0.1, 1e-3, 1.1, None, [0.5, 1.0], "auto")
>>> describe_run(settings).stepper.save_planes.tolist()
[0.5, 1.0]
with_stepper(stepper)[source]#

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

The statistics, monitor, history and snapshot policy stay; the method, the error control, the itinerary and the planes are stepper’s. solprop.driver.simulation.Simulation.with_input() uses it for the planes left beyond an interior launch. It takes a fresh request only: a field retention or a start plane is resolved against the planes, which the new section replaces, so a request that keeps every field from the entrance is the only one it accepts. Adapt the result to a run with for_run().

Parameters:
steppersolprop.stepper.settings.StepperSettings

The new stepper section.

Returns:
RunRequest

The request.

Raises:
TranslationError

If this request keeps other than every field, or starts beyond the entrance (for_run() has adapted it to a run).

Examples

>>> import dataclasses
>>> from solprop.stepper import DOPRI5, PIController
>>> from solprop.stepper.settings import StepperSettings
>>> from solprop.translate.run_request import describe_run
>>> settings = StepperSettings(DOPRI5, PIController(rtol=1e-8, atol=1e-14),
...                            1e-9, 0.1, 1e-3, 1.1, None, [0.5, 1.0], "auto")
>>> request = describe_run(settings)
>>> shorter = dataclasses.replace(settings, save_planes=[1.0])
>>> later = request.with_stepper(shorter)
>>> later.observation.save_planes.tolist()
[1.0]
>>> request.for_run(start_plane=1).with_stepper(shorter)
Traceback (most recent call last):
    ...
solprop.exceptions.TranslationError: with_stepper takes a fresh request, ...
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.stepper.settings.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.store.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.assembly import assemble
>>> from solprop.translate.run_request import describe_run
>>> grid = EnvelopeGrid.from_limits(1.0, 835e-9, (500e-9, 2e-6), 4e-12)
>>> gnlse = problem_from([0.0, 0.0, -1.2e-26], omega_ref=grid.omega0,
...                      gamma=0.11, shock=False)
>>> start = SechPulse(wavelength=835e-9, width=1e-13, peak_power=1.0).build(grid)
>>> problem, request = assemble(
...     grid, gnlse.mode, [gnlse.kerr], start,
...     controller=PIController(rtol=1e-8, atol=1e-14), save_planes=[1.0],
...     dz_max=0.1, dz_init=1e-3, shock=False, prefactor_index=1.0, density=1.0,
... )
>>> again = describe_run(request.stepper)
>>> again.integration.kind.value, again.observation.save_planes.tolist()
('runge_kutta', [1.0])