solprop.backends.protocol#
The seam: what a backend is, and what comes back from one.
Everything that touches the propagated state during a run is reached through this one
protocol, and only the backends know how the state is laid out, transformed and stepped
(docs/dev/backends.md section 1). The protocol is drawn at the level of operations
on the state rather than at the array-namespace level, because an xp-style
abstraction would force every backend to keep the array compiler’s structure —
out-of-place transforms, separate scaling passes, materialised stages, one reduction per
statistic — and that structure is precisely what a fast backend exists to change.
A backend is constructed from a validated
solprop.translate.problem.PropagationProblem, takes host arrays and returns
host arrays; its buffers, layout and plans are private, and the state is never a
parameter of anything a run’s session is asked. Selection by name and the availability
rules are in solprop.backends.registry.
Sign convention. Every complex array crossing this seam, in either direction, is in
the FFT convention of docs/dev/conventions.md section 2, with the phase origin
at the first time sample: spectral_convention = "fft". The output layer conjugates
on the way to disk and the processing accessors on the way to a user. Backends
never conjugate.
Classes
|
What every execution backend provides, and nothing more. |
|
What the stepper did between two observations. |
|
The state at a save plane, on the host. |
|
The statistics a backend evaluated between two observations. |
|
What one march of a session towards a plane cost and achieved. |
|
Single trials of a loaded run, for an estimate or a calibration to time. |
- class solprop.backends.protocol.Backend(*args, **kwargs)[source]#
Bases:
ProtocolWhat every execution backend provides, and nothing more.
docs/dev/backends.mdsection 1. A backend is constructed from a validatedsolprop.translate.problem.PropagationProblemand thesolprop.translate.run_request.RunRequestit is run with (SEP 47 section 5.2); the numbers are the contract, and a backend is correct when it reproduces thenumpy_reforacle to the stated bound.- Attributes:
- namestr
The registry name, for example
"numpy_ref".- reads_transverse_edgebool
Whether it reads a free-space run’s transverse edge (SEP 40 section 5.3), which a run with a requested real-space collar needs.
Examples
>>> from solprop.backends.protocol import Backend >>> names = [name for name in sorted(dir(Backend)) if not name.startswith("_")] >>> names[:4] ['available_device_memory', 'close', 'closed', 'edge_memory'] >>> names[4:8] ['march_export_refusal', 'memory_ledger', 'metadata', 'prepare'] >>> names[8:] ['request', 'timing_probe']
- available_device_memory()[source]#
Return currently free device bytes, or None for a host backend.
- Returns:
- int or None
Free device memory excluding live allocations and allocator reserves. Host memory is admitted independently by the controller.
- edge_memory(space)[source]#
Return what reading the transverse edge holds in the state’s memory space.
- Parameters:
- spaceobject
The run’s transverse grid.
- Returns:
- int
The bytes, from the grid alone; zero for a read on the host.
- march_export_refusal()[source]#
Return why this backend’s Adams march cannot carry its history, or
None.- Returns:
- str or None
The reason, or
Nonewhen it can or when the march keeps none.
- memory_ledger()[source]#
Return the size of every buffer the backend holds.
- Returns:
- dict
Buffer name to bytes, including transform work areas. Every buffer is named even when it is empty.
- metadata()[source]#
Return what this execution is, for the run’s record.
A saved run has to say what produced it, not only what was computed: the thread configuration alone moved one step by a factor of nine (
docs/dev/backends.mdsection 3.4), so a result whose execution is not recorded is not reproducible. The driver writes this intosolprop.output.metadata.RunMetadata.backend, which is outside the resume key – a run continued on the other backend is the same run.- Returns:
- dict
JSON-serialisable scalars keyed by name.
backendandpropagator_modeare always present; pools, plan flags and wisdom digests are a backend’s own.
- prepare(problem, request)[source]#
Prepare a run for one problem and request (SEP 47 section 5.2).
- Parameters:
- problemsolprop.translate.problem.PropagationProblem
The problem the backend was built for, or one derived from it with another input.
- requestsolprop.translate.run_request.RunRequest
The run’s request: the backend’s own, or one run’s adaptation of it.
- Returns:
- solprop.backends.session.PreparedExecution
The prepared execution, whose
startopens the backend’s session.
- property request: RunRequest[source]#
Run request the 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.
- Parameters:
- startsolprop.backends.session.Start
Where the trials start; its field is taken.
- Returns:
- TimingProbe
The probe (SEP 47 section 6.6).
- class solprop.backends.protocol.BackendHistory(z, dz, error_norm, accepted, wall_time)[source]#
Bases:
objectWhat the stepper did between two observations.
Recorded whether the run was adaptive or replayed a fixed schedule, because the embedded error estimate costs nothing extra and is computed either way (
docs/dev/stepper.mdsection 8): a replayed schedule too coarse for the tolerance it is scaled by is then reported rather than silent.- Attributes:
- znumpy.ndarray
Position at the end of each step, m, float64, shape
(n_steps,).- dznumpy.ndarray
Length of each step, m, float64, shape
(n_steps,), positive.- error_normnumpy.ndarray
The scaled embedded error norm of each step as executed, float64, shape
(n_steps,): a clipped or stretched step records the norm it actually scored, the same norm that decides its acceptance. The controller’s own history holds the proposal’s equivalent norm instead (solprop.stepper.controller.PIController.equivalent_norm();docs/dev/stepper.mdsection 3), which is never recorded here. A rejected trial that diverged, whose norm overflowed or was NaN, is recorded as infinity; every other entry is finite.- acceptednumpy.ndarray
Whether each step was accepted, Boolean, shape
(n_steps,).- wall_timenumpy.ndarray
Seconds elapsed at the end of each step, measured from the previous observation, float64, shape
(n_steps,), non-decreasing.
- Raises:
- BackendError
If the arrays are not all the same length, a step length is not positive, or an entry is not finite, other than a rejected step’s infinite norm.
Examples
>>> import numpy as np >>> from solprop.backends.protocol import BackendHistory >>> history = BackendHistory(np.array([0.1, 0.2]), np.array([0.1, 0.1]), ... np.array([0.4, 0.5]), np.array([True, True]), ... np.array([0.01, 0.02])) >>> history.n_steps, history.n_rejected (2, 0)
- accepted: Bool[ndarray, 'n_accepted']#
- dz: Float[ndarray, 'n_dz']#
- error_norm: Float[ndarray, 'n_norm']#
- property n_rejected: int[source]#
Number of rejected steps.
Examples
>>> import numpy as np >>> from solprop.backends.protocol import BackendHistory >>> BackendHistory(np.array([0.1]), np.array([0.1]), np.array([2.0]), ... np.array([False]), np.array([0.5])).n_rejected 1
- property n_steps: int[source]#
Number of steps recorded, accepted and rejected together.
Examples
>>> import numpy as np >>> from solprop.backends.protocol import BackendHistory >>> BackendHistory(*(np.zeros(0) for _ in range(3)), ... np.zeros(0, bool), np.zeros(0)).n_steps 0
- wall_time: Float[ndarray, 'n_wall']#
- z: Float[ndarray, 'n_steps']#
- class solprop.backends.protocol.Observation(z, field, noise_phase, step_history, n_steps, n_rejected, step_stats=<factory>)[source]#
Bases:
objectThe state at a save plane, on the host.
Section 9 of
docs/dev/kernel-contract.md. Host arrays only: device arrays never cross the seam. The field is in the lab frame and the FFT convention (spectral_convention = "fft"), so the output layer conjugates it on the way to disk and the processing accessors on the way to a user.- Attributes:
- zfloat
Position of the plane, m.
- fieldnumpy.ndarray or None
The state, complex128, shape
(n_modes, n_pol, n_omega), in the square root of watts;Nonefor an observation that asked for no field (observe(field=False), SEP 22 section 5.1).- noise_phasenumpy.ndarray or None
Im Phi(omega, z)in radians, same shape, when a noise model is active and the field is observed, so that processing can restore the shot-noise background the propagating field never carried.Noneotherwise.- step_historyBackendHistory
What the stepper did since the previous observation.
- n_stepsint
Steps taken since the previous observation, accepted and rejected together.
- n_rejectedint
Rejected steps among them.
- step_statsStepStats
The rows a periodic statistics subset produced between the previous observation and this one, empty unless the run asked for one. Separate from
step_historybecause the two are sampled differently: the history is every attempt, these are everyperiod-th accepted step.
- Raises:
- BackendError
If a field is not finite, a noise phase is given without a field or does not match it, the step counts disagree with the history, or a statistics row points past the history it indexes.
Examples
>>> import numpy as np >>> from solprop.backends.protocol import Observation, BackendHistory >>> history = BackendHistory(np.array([1.0]), np.array([1.0]), np.array([0.3]), ... np.array([True]), np.array([0.02])) >>> plane = Observation(1.0, np.zeros((1, 1, 8), complex), None, history, 1, 0) >>> plane.z, plane.field.flags.writeable (1.0, False)
- require_field()[source]#
Return the observed field, refusing an observation that asked for none.
- Returns:
- numpy.ndarray
The read-only field, shape
(n_modes, n_pol, n_omega).
- Raises:
- BackendError
If the observation carries no field (
observe(field=False)).
Examples
>>> import numpy as np >>> from solprop.backends.protocol import Observation, BackendHistory >>> empty = BackendHistory(np.empty(0), np.empty(0), np.empty(0), ... np.empty(0, bool), np.empty(0)) >>> Observation(0.0, np.ones((1, 1, 2), complex), None, empty, 0, 0 ... ).require_field().shape (1, 1, 2)
- step_history: BackendHistory#
- class solprop.backends.protocol.StepStats(z, step, values=<factory>)[source]#
Bases:
objectThe statistics a backend evaluated between two observations.
The channel of
docs/dev/kernel-contract.mdsection 9. A run whosesolprop.stats.StatsSpecnames aperiodicsubset gets one row everyperiodaccepted steps, evaluated inside the backend’s own step loop from the state that step just committed, and drained here at each save plane. Evaluating every statistic on every accepted step costs about a fifth of a step; a subset and a period are the two knobs that make the same information affordable.Empty when the run asked for no periodic subset, which is the default.
- Attributes:
- znumpy.ndarray
Position of each row, m, float64, shape
(n_rows,), increasing.- stepnumpy.ndarray
Index of the accepted step each row was taken after, into the same observation’s
BackendHistory, int64, shape(n_rows,), increasing. The history counts rejected attempts too, so this is notrow * period.- valuescollections.abc.Mapping
The statistics, keyed by catalogue name, each with a leading row axis and then the statistic’s own shape, with no batch axis:
(n_rows, *shape).
- Raises:
- BackendError
If the two index arrays disagree in length, are not increasing, or a value’s leading axis is not the row count.
Examples
>>> import numpy as np >>> from solprop.backends.protocol import StepStats >>> rows = StepStats(np.array([0.1, 0.2]), np.array([0, 1]), ... {"energy": np.ones((2, 1, 1))}) >>> rows.n_rows, rows.names (2, ('energy',)) >>> StepStats.empty().n_rows 0
- classmethod empty()[source]#
Return the channel a run without a periodic subset carries.
- Returns:
- StepStats
No rows and no statistics.
- step: Int[ndarray, 'n_rows_step']#
- z: Float[ndarray, 'n_rows']#
- class solprop.backends.protocol.StepSummary(z, n_steps, n_rejected, max_norm, mean_norm, wall_time, met_tolerance)[source]#
Bases:
objectWhat one march of a session towards a plane cost and achieved.
A handful of host scalars, so that a driver can report progress and warn about a tolerance that was not met without pulling the whole step history across the seam every plane.
- Attributes:
- zfloat
Position reached, m, which is the plane that was asked for.
- n_stepsint
Steps taken, accepted and rejected together.
- n_rejectedint
Rejected steps among them.
- max_normfloat
Largest scaled error norm over the accepted steps; 0 when none were taken.
- mean_normfloat
Mean scaled error norm over the accepted steps.
- wall_timefloat
Seconds the call took.
- met_tolerancebool
Whether every accepted step scored at or below one. False on a replayed schedule too coarse for its tolerance, which the driver logs (
stepper.mdsection 8).
- Raises:
- BackendError
If a count is negative, more steps were rejected than taken, or a norm or time is negative or not finite.
Examples
>>> from solprop.backends.protocol import StepSummary >>> StepSummary(1.0, 42, 0, 0.7, 0.4, 0.31, True).met_tolerance True
- class solprop.backends.protocol.TimingProbe(*args, **kwargs)[source]#
Bases:
ProtocolSingle trials of a loaded run, for an estimate or a calibration to time.
Returned by
Backend.timing_probe()(SEP 47 section 6.6). A trial is one step’s arithmetic from the loaded state, and commits nothing: the backend’s state, position and step history stay those of the load, though a work counter may count the trial’s evaluations. It is a supported internal operation forsolprop.driver.simulation.Simulation.estimate()and the SEP 46 calibration, not a propagation executor: a run is driven through a session (solprop.backends.session).The low-storage march (SEP 24) has no separate trial: its step accepts in place, so a probe’s trial advances the discarded registers the load put there, and it has no trial field to read back. A backend probed so is closed afterwards.
- field()[source]#
Return the last trial’s end state on the host, as a kept step would be.
The state after the accepted-step boundary treatments, read once per trial. A backend that can read it back only by finishing the step in its own state loads the loaded state again afterwards, so the probe still commits nothing.
- Returns:
- numpy.ndarray
An owning copy in internal units and the FFT convention.
- Raises:
- solprop.exceptions.BackendError
With no trial since the last readback, or for the low-storage march, which has no trial state.
- trial(z=None, dz=None)[source]#
Take one trial step and keep its end state for
field().- Parameters:
- zfloat or None, optional
Where the trial starts, m; the loaded position by default.
- dzfloat or None, optional
Its length, m, positive; the problem’s
dz_initby default, or the scheduled step at z for the low-storage march.