solprop.backends.numpy_ref.backend#
The reference backend: its lowering, its marches and the refusals (SEP 52).
One NumpyRefBackend steps one problem in plain NumPy. It builds the
workspace that holds the state and does every state-sized operation
(NumpyWorkspace) and, for each run, the
engines a march asks of it
(NumpyRungeKutta,
HostHistory,
HostLowStorage), the run’s march and its dense
output (NumpyRefBackend.method()); it keeps prepare, the metadata, the
memory ledger, the timing probe and close. Every run is the reference’s own
session’s (HostSession), which schedules it.
The step control follows docs/dev/stepper.md section 3 exactly: the controller’s
proposal is its state, the executed step’s own norm decides acceptance and is what
the history records, and the equivalent norm of the proposal is what the controller
and a rejection see.
Classes
|
Propagate one Kerr and plasma problem with interaction-picture DOPRI5. |
- class solprop.backends.numpy_ref.backend.BlockResidual(flow)#
Bases:
objectR_s(z) statefor a held flow’s positions (SEP 16 phases 5 and 6).A history sample’s residual is formed against the section of every trial it serves, about six; its action depends only on the section and the sample’s flow weights, so each pair’s action is formed once and kept, the least recently used dropped first: each trial’s endpoint, at a new position, is used once.
- Parameters:
- flow_CoupledFlow
The held flow.
- class solprop.backends.numpy_ref.backend.NumpyRefBackend(problem, request, *, grid=None, modes=None, profiles=None, tdse_binding=None, options=None)[source]#
Bases:
objectPropagate one Kerr and plasma problem with interaction-picture DOPRI5.
The oracle of
docs/dev/backends.mdsection 2. It implementssolprop.backends.protocol.Backendand steps a single problem on either grid: mode-averaged or multimode on the fixed transverse quadrature, scalar or vector-isotropic, with the Kerr term, the delayed Raman term and the plasma. Mode-averaged propagation is the one-node case of the same pipeline and not a second code path.Refusals. A problem is refused by name, with
solprop.exceptions.BackendError, when its flags declare a spectral response, when a Raman kernel meets two polarisation components, or when the transform and the state would both carry the transverse components. A term silently dropped would run, converge and be wrong.Convention. Every array held or returned is in the FFT convention of
docs/dev/conventions.mdsection 2; the backend never conjugates. The output layer converts on the way to disk and the processing accessors on the way to a user.The grid. The statistics delegate to
solprop.stats.collect(), which needs asolprop.grid.TimeGrid; the kernel contract carries the array groupsolprop.translate.masks.Gridsand no grid object, so the grid is supplied here instead. This is a known gap in the contract.- Parameters:
- problemsolprop.translate.problem.PropagationProblem
The validated kernel problem.
- requestsolprop.translate.run_request.RunRequest
The run’s policies: method, error control, itinerary, planes and statistics.
validate_run()checks the pair again here, before anything is allocated: validation is the backend’s defence, not the caller’s courtesy.- gridsolprop.grid.TimeGrid, optional
The grid the state lives on, needed only by the statistics.
- modescollections.abc.Sequence, optional
The propagated modes, in state order, needed only by the
zdwstatistic.- profilescollections.abc.Mapping, optional
The z-profiles keyed by statistic name, needed only by the profile statistics.
- tdse_bindingsolprop.translate.tdse.TDSEBinding or None, optional
Driver-owned persistent atomic plans, required exactly when the problem declares a TDSE response. The driver closes this binding after the backend.
- optionssolprop.backends.session.ExecutionOptions or None, optional
The run’s execution options, from which the node chunk is planned;
Nonefor the automatic choice.
- Attributes:
- namestr
The registry name,
"numpy_ref".- reads_transverse_edgebool
True: the reference reads a free-space run’s transverse edge on the host.
- helperssolprop._helpers.Helpers
The uncompiled stage-table and Adams-basis evaluations,
PLAIN, which the engines and marches are passed rather than choosing one (SEP 29 section 6.6).
- Raises:
- BackendError
Naming what the backend refuses.
Examples
>>> from solprop.backends.numpy_ref import NumpyRefBackend >>> 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) >>> 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-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) >>> from solprop.backends.events import Progress >>> from solprop.backends.session import Start >>> backend = NumpyRefBackend(problem, request, grid=grid) >>> session = backend.prepare(problem, request).start(Start.entrance(problem)) >>> kinds = [] # the barriers; a bounded yield on a slow host adds a Progress >>> while not session.finished: ... batch = session.advance() ... kinds += [ ... type(event).__name__ ... for event in batch.events ... if not isinstance(event, Progress) ... ] ... session.acknowledge(batch.receipt) >>> kinds ['ObservationReady', 'ObservationReady', 'Terminal'] >>> session.close()
- available_device_memory()[source]#
Return None for host execution.
- Returns:
- int or None
None: the reference runs on the host.
- property chunk_plan: NodeChunkPlan[source]#
Node-chunk plan and what chose it.
- edge_memory(space)[source]#
Return what reading the edge holds in the state’s memory space.
What
solprop.driver.estimate.estimate()adds: it attaches no monitor.- Parameters:
- spaceobject
The run’s transverse grid.
- Returns:
- int
Zero: a read on the host holds nothing beside the state there.
- helpers: Helpers = Helpers(name='plain')#
- property march: RungeKuttaMarch | HostAdamsMarch | HostLowStorageMarch[source]#
The latest run’s march: a session’s, the timing probe’s, or a fresh one.
- march_export_refusal()[source]#
Return
None: every march the reference admits carries its history.- Returns:
- None
The Adams engines export and install their rows; the Runge-Kutta and low-storage marches keep none.
- memory_ledger()[source]#
Return the size of every buffer the backend works in, in bytes.
The workspace’s (
memory_ledger()): what one step has resident at its peak, every buffer named even when it is empty.- Returns:
- dict
Buffer name to bytes.
- metadata()[source]#
Return what this execution was, for the run’s record.
A saved run has to say what produced it: the thread configuration alone was measured to move one step by a factor of nine, so a result whose execution is not recorded is not reproducible. The record is the name, the resolved propagator mode and the node chunk; for an Adams run the latest run’s cumulative logical source calls, and otherwise its physical
source_evaluations(SEP 24 section 5); and the workspace’s facts: the benchmark-gated plasma source and a host source’s ledger, execution and last evaluation. A PEC predictor is explicitly labelled and is never reported as an accepted-field diagnostic.- Returns:
- dict
JSON-serialisable scalars, keyed by name.
- method(host)[source]#
Return a fresh march for one run, its dense output and its history’s rows.
Each run steps with engines and a march of its own, over the backend’s workspace, so that a backend loaded again repeats a fresh backend’s run (SEP 22 section 4.7): its call ledger, its counts, its held trial and its dense output start afresh. The run’s session is the march’s host.
- Parameters:
- hostobject
The run’s session, the march’s
MarchHost;Nonefor a march that never steps.
- Returns:
- solprop.backends.host.session.HostMethod
The march, with its dense output when the run interpolates its planes and the Adams history’s rows.
- prepare(problem, request)[source]#
Prepare a run of this backend for one problem and request (SEP 47 5.2).
The backend lowered the method, the error control, the itinerary, the planes and the statistics where it was built; preparing binds the problem and the request a run serves – this backend’s own, or one run’s adaptation of it (
for_run()) – and each start of the result opens the reference’s own session (HostSession).- Parameters:
- problemsolprop.translate.problem.PropagationProblem
The translated problem: this backend’s, or one derived from it with another input (
solprop.driver.runner.check_derived_problem()).- requestsolprop.translate.run_request.RunRequest
The run’s request.
- Returns:
- solprop.backends.session.PreparedExecution
The prepared execution.
- property request: RunRequest[source]#
Request this backend was built for.
Its method, error control, itinerary, planes and statistics; a run adapts it with
for_run().
- timing_probe(start)[source]#
Load a start and return single trials of this run’s march from it.
The start’s field, noise, position and resume flag are loaded as a session loads them; its method history, ledgers and monitor continuation are not read. A Runge-Kutta trial leaves the loaded state alone; a low-storage march’s step advances the discarded registers in place, so a backend probed so is closed afterwards (SEP 47 section 6.6).
- Parameters:
- startsolprop.backends.session.Start
Where the trials start; its field is taken.
- Returns:
- solprop.backends.protocol.TimingProbe
The probe.
- Raises:
- BackendError
If the backend is closed or the start does not fit the problem.
- property workspace: NumpyWorkspace[source]#
The workspace: the state and every state-sized operation on it.
- class solprop.backends.numpy_ref.backend.SourceTables(synthesis, projection, t_window, t_window_derivative, omega_window, temporal_rate)#
Bases:
objectThe problem’s tables a source evaluation multiplies by.
The arrays the passes read, gathered once from the problem.
- Attributes:
- synthesisnumpy.ndarray
transform.synthesis.- projectionnumpy.ndarray
transform.projection.- t_windownumpy.ndarray
grids.t_window_fine.- t_window_derivativenumpy.ndarray
grids.t_window_fine_derivative.- omega_windownumpy.ndarray
grids.omega_window.- temporal_ratenumpy.ndarray or None
responses.temporal_absorber_fine.
- classmethod of(problem)#
Return the problem’s own tables.
- Parameters:
- problemsolprop.translate.problem.PropagationProblem
The problem.
- Returns:
- SourceTables
References to its arrays, uncopied.
- omega_window: Float[ndarray, 'n_omega']#
- projection: Float[ndarray, 'n_modes n_columns']#
- synthesis: Float[ndarray, 'n_rows n_modes_s']#
- t_window: Float[ndarray, 'n_to']#
- t_window_derivative: Float[ndarray, 'n_to']#