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

NumpyRefBackend(problem, request, *[, grid, ...])

Propagate one Kerr and plasma problem with interaction-picture DOPRI5.

class solprop.backends.numpy_ref.backend.BlockResidual(flow)#

Bases: object

R_s(z) state for 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: object

Propagate one Kerr and plasma problem with interaction-picture DOPRI5.

The oracle of docs/dev/backends.md section 2. It implements solprop.backends.protocol.Backend and 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.md section 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 a solprop.grid.TimeGrid; the kernel contract carries the array group solprop.translate.masks.Grids and 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 zdw statistic.

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; None for 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.

close()[source]#

Release the buffers. Idempotent.

property closed: bool[source]#

Whether the backend has released its buffers, as a failure may.

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; None for 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.

name: str = 'numpy_ref'#
property node_chunk: int[source]#

The nodes a response pass of this backend holds at once.

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.

propagator_default: Literal['auto', 'tabulate', 'recompute'] = 'tabulate'#
reads_transverse_edge: bool = True#
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: object

The 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']#
temporal_rate: Float[ndarray, 'n_to'] | None#