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:
IntegrationSpecnames the method (MethodKind: an embedded Runge-Kutta tableau, the low-call Adams family or the fixed low-storage replay);ErrorControlSpecholds the tolerances, norm, controller and step limits;ReplaySpecholds a fixed itinerary, when one is replayed;ObservationRequestholds the planes, dense output, step planes, statistics and field retention;BoundaryRequestconfigures the boundary monitor;HistoryPolicy(HistoryRetention) says when the method’s history is kept for a resume.
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
The largest Adams march snapshot a run keeps with |
Functions
|
Build the run request from a resolved stepper section and the run's settings. |
Classes
|
What the boundary watches. |
|
Tolerances, the controller and the step limits. |
|
The method-history retention policy. |
|
When the method's history is kept for a resume. |
|
Which method integrates the run, and its options. |
|
The integration method family. |
|
What a run observes and keeps. |
|
A fixed itinerary, replayed rather than chosen. |
|
Every policy of one run, resolved before preparation. |
- class solprop.translate.run_request.BoundaryRequest(monitor=None)[source]#
Bases:
objectWhat 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;
Nonewatches 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:
objectTolerances, 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.
- controller: PIController#
- class solprop.translate.run_request.HistoryPolicy(retention=HistoryRetention.AUTO)[source]#
Bases:
objectThe method-history retention policy.
- Attributes:
- retentionHistoryRetention
When to keep it.
- classmethod from_choice(choice)[source]#
Return the policy for the public
resume_historychoice.- Parameters:
- choicebool or None
Truekeeps it always,Falsenever andNoneautomatically.
- Returns:
- HistoryPolicy
The policy.
- retention: HistoryRetention = 'auto'#
- class solprop.translate.run_request.HistoryRetention(*values)[source]#
Bases:
EnumWhen 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:
objectWhich 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;
Nonefor Runge-Kutta.- propagator_mode{‘auto’, ‘tabulate’, ‘recompute’}
How the linear propagator is formed.
- kind: MethodKind#
- method: Multistep | LowStorageRungeKutta | None#
- 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:
EnumThe 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:
objectWhat 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;0for none.- statssolprop.stats.StatsSpec
The plane statistics, and the periodic subset with its period.
- retentionsolprop.output.store.FieldRetention
Which observed planes keep their field.
- retention: FieldRetention#
- save_planes: Float[ndarray, 'n_z']#
- class solprop.translate.run_request.ReplaySpec(schedule)[source]#
Bases:
objectA 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:
objectEvery policy of one run, resolved before preparation.
A
Simulationgives the request its translation built beside the problem throughrun_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;
Nonefor 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#
- 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
StepperSettingsfor 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.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 withfor_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])