solprop.driver.run#
The outer loop of a run: save planes in, saved planes out.
The inner loop, many adaptive or replayed steps between two save planes, lives inside a
backend and is compiled; run_problem() is the Python loop around it, which runs a
few hundred times at most (docs/dev/architecture.md section 5). It starts the
backend’s session and hands it to solprop.driver.session_loop, which opens the
output (open_run()), lands on each save plane in turn and hands the plane, its
step history converted by history_of(), to the output handler;
plane_from_observation() builds the same plane from one session observation by
hand. It never conjugates a spectrum and never touches the state between planes: the
backend owns the step loop and the output handler the sign convention on disk
(docs/dev/conventions.md section 2); a plane crosses as a
solprop.output.records.SavedPlane in the internal FFT convention, with modal
amplitudes in true-power units. field_retention(), retention_at() and
check_snapshot_request() resolve what a run keeps. Progress goes to a
solprop.log.ProgressReporter; the protocol is docs/dev/architecture.md
section 14. The manual page is
docs/guide/setup/running.md.
Module Attributes
The execution record's entry for what a restart keeps and restores (SEP 47 5.5). |
Functions
|
Refuse unsupported snapshot policies before allocating native resources. |
|
Return a run's field retention, resolved against its saved planes. |
|
Return a backend's step history in the form an output handler stores. |
|
Open a run's output with the runtime facts outside its scientific identity. |
|
Turn one observation and its statistics into the plane an output handler stores. |
|
Return the method-history retention an execution record states at z. |
|
Run one translated problem to its save planes, writing each one out. |
Classes
|
A session's execution facts, as the service loop's records read them. |
- solprop.driver.run.RESTART_RECORD = 'restart'#
The execution record’s entry for what a restart keeps and restores (SEP 47 5.5).
Optional:
"retention", what the run kept of its method history at the record’s position (_MarchKeeper), and, in a resumed execution,"restoration"(what it restored,solprop.driver.resume._continue_march) and"monitor"(how the boundary monitor was restored). Each decision is a mapping with a"state"and a"reason". An execution that has persisted nothing yet records none, which a reader takes as unknown, never as a reason (retention_at).
- class solprop.driver.run.SessionFacts(session)[source]#
Bases:
objectA session’s execution facts, as the service loop’s records read them.
The output and record helpers (
solprop.driver.run) read the run’s name, metadata, method history and in-flight state, which the session answers through its protocol: its execution record, its method-history snapshot and size, and the in-place step a failure left in flight (in_flight, a low-storage step’s, SEP 47 section 5.5).- Parameters:
- sessionsolprop.backends.session.RunSession
The session.
- property in_flight: tuple[float, float] | None[source]#
In-place step a failure left in flight, or
None.Where the step started and its length, m, as the session reports it.
- march_snapshot()[source]#
Return the session’s method history at its pending committed state.
- Returns:
- solprop.output.records.MarchSnapshot or None
The session’s snapshot (
march_snapshot()), orNonewithout one or with no batch pending, for which the session’spending_ticket()gives none.
- solprop.driver.run.check_snapshot_request(request, output, snapshots, resume_history, fields)[source]#
Refuse unsupported snapshot policies before allocating native resources.
No backend is refused by name: every backend’s fused and exponential Adams engines, the native backend’s resident one included, export their history (SEP 29 section 6.6).
- Parameters:
- requestsolprop.translate.run_request.RunRequest
The run’s request, whose method decides what a snapshot needs.
- outputOutput
Requested optical writer.
- snapshotsSnapshotController or None
Optional snapshot request controller.
- resume_historybool or None
Whether the caller explicitly disabled Adams history retention.
- fieldsFieldsChoice
Saved-field retention policy.
- Raises:
- DriverError
If snapshots are requested outside their supported scope.
- solprop.driver.run.field_retention(request, fields, field_planes)[source]#
Return a run’s field retention, resolved against its saved planes.
The driver’s door to
solprop.output.store.field_retention_refusal(), the validatorSimulationSettingsandrun_scan()share.- Parameters:
- requestsolprop.translate.run_request.RunRequest
The run’s request: its save planes, and the entrance, are the planes.
- fieldsobject
"all","planes"or"none".- field_planescollections.abc.Sequence of int
Saved-plane indices for
"planes", negative from the end.
- Returns:
- solprop.output.store.FieldRetention
The rule, its indices counted from the entrance.
- Raises:
- DriverError
If the request is not valid, names a plane outside the run, asks for
fields='planes'whilestep_planessaves an unknown number of planes.
Examples
>>> from solprop.driver import Simulation >>> from solprop.driver.run import field_retention >>> simulation = Simulation.from_gnlse( ... 0.11, 0.01, [0.0, 0.0, -1.183e-26], wavelength=835e-9, ... wavelength_limits=(500e-9, 2e-6), trange=1e-12, ... width=100e-15, peak_power=9.8, shape="sech", n_save=3, ... ) >>> field_retention(simulation.run_request(), "planes", [-1]).field_planes (2,)
- solprop.driver.run.history_of(history)[source]#
Return a backend’s step history in the form an output handler stores.
The two records carry the same five columns, and two of them mean different things on the two sides of the seam: the backend’s
zis the position at the end of each attempt and itswall_timeis the clock reading since the previous observation, which is what a stepper measures cheaply, whilesolprop.output.records.StepHistorystores the position at the start of each attempt and the time that one attempt took, which is what a reader wants per row. The conversion is made here: the start is the end less the length, to round-off, and the per-attempt times are the differences of the clock, the first from zero.- Parameters:
- historysolprop.backends.protocol.BackendHistory
The attempts a backend reports, each ending at its
z.
- Returns:
- solprop.output.records.StepHistory
The same attempts, each starting at its
z, with per-attempt times.
- solprop.driver.run.open_run(output, metadata, backend, binding)[source]#
Open a run’s output with the runtime facts outside its scientific identity.
A run refused after its resources were prepared and before its first step (a failed haCC consistency check, SEP 20 section 5.4) is recorded by this alone: the record, with the binding’s provenance, and no plane or terminal checkpoint, so it cannot be mistaken for a propagation state.
- Parameters:
- outputsolprop.output.store.Output
The handler, not yet open.
- metadatasolprop.output.metadata.RunMetadata
The run’s record, without its backend.
- backendsolprop.backends.protocol.Backend or SessionFacts
What executes the run, whose metadata the record’s backend section takes.
- bindingsolprop.translate.tdse.TDSEBinding or None
A TDSE response’s binding, whose metadata the record carries too.
- Returns:
- solprop.output.store.CheckpointOutput or None
The handler’s checkpoint interface, or
Nonefor a handler without one.
- solprop.driver.run.plane_from_observation(observation, stats=None, *, field=True)[source]#
Turn one observation and its statistics into the plane an output handler stores.
The seam’s arrays are one trajectory’s, as a stored plane is, so no shape changes on the way (
docs/dev/conventions.mdsection 6). Nothing is conjugated – the field stays in the internal FFT convention, and the handler converts it on the way to storage (docs/dev/conventions.mdsection 2). Nothing is rescaled either: the field is whatever amplitude the observation carries, the backend’s vacuum-normalised one unless the caller has applied the interface conversion to true-power amplitudes (a session’s export withExportRecipe(power=True, ...); seedocs/dev/decisions.md).- Parameters:
- observationsolprop.backends.protocol.Observation
The state at a save plane, as a session observes it.
- statscollections.abc.Mapping, optional
The plane’s statistics, keyed by statistic name. Empty when omitted.
- fieldbool, optional
Whether the plane keeps the field and its noise phase;
False, or an observation that carries no field, builds a field-free plane (SEP 22), which copies neither.
- Returns:
- solprop.output.records.SavedPlane
The position, the field, the statistics and the step history.
Examples
>>> import numpy as np >>> from solprop.backends.protocol import BackendHistory, Observation >>> from solprop.driver.run import plane_from_observation >>> history = BackendHistory(np.array([0.5]), np.array([0.5]), np.array([0.3]), ... np.array([True]), np.array([0.02])) >>> observation = Observation(0.5, np.ones((1, 1, 4), complex), None, history, 1, 0) >>> plane = plane_from_observation(observation, {"energy": np.ones((1, 1))}) >>> plane.z, plane.shape, plane.stats["energy"].shape (0.5, (1, 1, 4), (1, 1))
- solprop.driver.run.retention_at(execution, z)[source]#
Return the method-history retention an execution record states at z.
- Parameters:
- executioncollections.abc.Mapping or None
An execution record (
solprop.output.records.RunOutcome.execution).- zfloat
The position a resume starts from, m.
- Returns:
- collections.abc.Mapping or None
The retention decision recorded there, or
Nonewhen the record states none at z: nothing persisted yet, or a decision recorded at another position.
- solprop.driver.run.run_problem(problem, backend, output, *, start, metadata, stats_spec=None, progress=None, progress_period=10.0, tdse_binding=None, resume_history=None, fields='all', field_planes=(), snapshots=None, tdse_archive=None, boundary_monitor=None, stop=None, recipe=None, restoration=None, interpolated_resume=False)[source]#
Run one translated problem to its save planes, writing each one out.
The loop of
docs/dev/architecture.mdsection 5, usable without asolprop.driver.simulation.Simulation. The run starts a session on the constructed backend from start (SEP 47); the handler is opened here, saved to plane by plane, and closed in afinallyso that an interrupted run leaves a readable file. The backend stays open for the caller, who may start another run on it.The plane at
problem.initial.zis saved first, with an empty step history, and then each save plane in turn: propagate, observe, collect statistics, save. Steps land on the planes exactly, so a saved field is an exact step endpoint and there is no interpolation (docs/dev/stepper.mdsection 3), unless the request asks for dense output. Withbackend.request.observation.step_planesthe march also stops at the end of everystep_planes-th accepted step, which is saved too before the same plane is asked for again. A plane whose propagation did not meet its tolerance is logged as a warning naming that plane (docs/dev/stepper.mdsection 8).- Parameters:
- problemsolprop.translate.problem.PropagationProblem
The translated problem.
- backendsolprop.backends.protocol.Backend
The backend stepping it, constructed for problem and its run’s request (
request), whose save planes are the itinerary; the run’s own request is that one with this run’s start, retention, statistics, monitor and history (for_run()). The run loads start into it and leaves it open.- outputsolprop.output.store.Output
Where the planes go. Closed when the loop ends, whether or not it succeeded.
- startsolprop.backends.session.Start
Where the run starts:
entrance()for a fresh run, or a resumed state with itsplane_index, the first save plane strictly beyond it. A resume loads either the last regular plane or a separate terminal checkpoint at its actual absolute position; the launch plane is written when the handler holds no regular observations, so a resumed run never stores it twice. The session takes the start’s field.- metadatasolprop.output.metadata.RunMetadata
The record of the run, written when the handler opens.
solprop.driver.metadata.metadata_for()builds one.- stats_specsolprop.stats.StatsSpec, optional
Which statistics to collect at each plane. Defaults to the backend’s request’s own (section 8 of
docs/dev/kernel-contract.md).- progressProgressReporter, {‘auto’, ‘bar’, ‘log’, ‘none’} or None, optional
Where progress goes.
Nonetakes the process default (solprop.log.default_progress(),"auto"unlesssolprop.log.configure_logging()was told otherwise): asolprop.log.BarReporterdrawing one redrawing line on standard error when that is a terminal or the process is a Jupyter kernel, and asolprop.log.LogReporter– a periodic line, one line per plane and one at the end, all atINFO– otherwise, so redirected, piped and captured output gets lines and never a bar. The four names force a choice; a reporter is used as given, and must define all ofProgressReporter’s calls (subclassNullReporterto inherit no-ops).- progress_periodfloat, optional
Seconds between the line reporter’s periodic lines, s;
0leaves only the plane and closing lines. A bar has its own redraw period and a given reporter its own business, so it is ignored for both.- tdse_bindingsolprop.translate.tdse.TDSEBinding or None, optional
Explicit live atomic runtime owned by the caller. Its ledgers and execution facts are captured before the caller closes it. TDSE requires an output supporting the separate checkpoint capability.
- resume_historybool or None, optional
Whether an output that can keep it (
save_march) keeps the Adams march’s state at every save plane and terminal checkpoint, so that a resume continues the history instead of starting it afresh.Nonekeeps it while it is at mostMARCH_SNAPSHOT_AUTO_BYTES.- fields{‘all’, ‘planes’, ‘none’}, optional
Which saved planes keep their field (SEP 22): every one (the default), those of field_planes, or none. A plane that keeps none stores its position, its statistics and its step history, and is not copied, converted or stored; the march is the same either way. A terminal checkpoint, written when the run stops, carries the field whatever this says, so a stopped run resumes.
- field_planessequence of int, optional
Saved-plane indices for
fields='planes', the entrance as 0 and negative from the end.- snapshotssolprop.output.SnapshotController or None, optional
Requests immutable disk copies at committed accepted steps, each serviced at the next accepted endpoint, after every interpolated plane its step crossed. Requires HDF5 and all fields.
- tdse_archivesolprop.output.tdse_archive.TDSEArchiveWriter or None, optional
Live archive to suspend and copy beside the optical writer.
- boundary_monitorsolprop.monitor.BoundaryMonitor or None, optional
Watches the time window’s edges (SEP 21): attached to the backend once its launch is recorded and fed every committed step. Its record is written into the execution record at every save plane without the per-plane rows, which the closing record (complete, failed or out of budget) carries, and its removed fraction is reported at the end.
Nonewatches nothing.- stopsolprop.log.StopFlag or None, optional
The run’s own stop flag, any object with an
is_set()method (SEP 41, S17). It is polled before the first step, before every trial step (on a nativeMultistep()march, before every native call) and between save planes; once it is set the run writes its state as for SIGTERM, tells the reporter throughinterrupted, and raisesStopRequested, whichrun()turns into a return.- recipesolprop.output.records.RecipeRecord or None, optional
The recipe the run was built from (SEP 41, S2), recorded in a plane store at the first run start and never rewritten;
Nonerecords none.- restorationcollections.abc.Mapping or None, optional
On a resume, what the caller restored of the method history, written into every execution record under
outcome.execution["restart"]beside what this execution keeps;Nonerecords no restoration. When the start carries a method history (start.march), this is the record of its restoration, and a history the session cannot install is warned about and recorded as reset instead.- interpolated_resumebool, optional
Whether a resume continues afresh from a plane interpolated inside a step (
resume="interpolated"). A plane store then appends the start’s position to the annotationINTERPOLATED_RESUMES_ANNOTATIONbefore the first step, so a run stopped or failed later still records it.
- Raises:
- DriverError
If the statistics given here disagree with the request’s own about the between-planes channel; if the record and the problem disagree about whether this is a general modal run; if the start’s
plane_indexis not a plane of this problem; or if the field retention is not valid, names a plane outside the run, asks forfields='planes'besidestep_planes(whose plane count is not known in advance), or is not'all'for an output that cannot store field-free planes; or ifprogressis neither a name nor aProgressReporter.
Examples
>>> from solprop.backends.registry import select >>> from solprop.backends.session import Start >>> from solprop.driver.run import run_problem >>> from solprop.driver.metadata import metadata_for >>> from solprop.grid import EnvelopeGrid >>> from solprop.nonlinear.gnlse import problem_from >>> from solprop.output import MemoryOutput >>> from solprop.pulses import SechPulse >>> from solprop.stepper import PIController >>> from solprop.translate.assembly import assemble >>> grid = EnvelopeGrid.from_limits(0.01, 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) >>> start = SechPulse(wavelength=835e-9, width=100e-15, peak_power=9.8).build(grid) >>> problem, request = assemble(grid, gnlse.mode, [gnlse.kerr], start, ... controller=PIController(rtol=1e-6, atol=1e-16), ... save_planes=[0.005, 0.01], dz_max=0.01, dz_init=1e-3, ... density=1.0, shock=False, prefactor_index=1.0) >>> backend = select("numpy_ref", problem, request, grid=grid, modes=[gnlse.mode]) >>> handler = MemoryOutput() >>> run_problem(problem, backend, handler, start=Start.entrance(problem), ... metadata=metadata_for(problem, request, grid, modes=[gnlse.mode])) >>> backend.close() >>> handler.n_saved, handler["z"].tolist() (3, [0.0, 0.005, 0.01])