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

Backend(*args, **kwargs)

What every execution backend provides, and nothing more.

BackendHistory(z, dz, error_norm, accepted, ...)

What the stepper did between two observations.

Observation(z, field, noise_phase, ...[, ...])

The state at a save plane, on the host.

StepStats(z, step[, values])

The statistics a backend evaluated between two observations.

StepSummary(z, n_steps, n_rejected, ...)

What one march of a session towards a plane cost and achieved.

TimingProbe(*args, **kwargs)

Single trials of a loaded run, for an estimate or a calibration to time.

class solprop.backends.protocol.Backend(*args, **kwargs)[source]#

Bases: Protocol

What every execution backend provides, and nothing more.

docs/dev/backends.md section 1. A backend is constructed from a validated solprop.translate.problem.PropagationProblem and the solprop.translate.run_request.RunRequest it is run with (SEP 47 section 5.2); the numbers are the contract, and a backend is correct when it reproduces the numpy_ref oracle 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.

close()[source]#

Release the buffers and plans. Idempotent.

property closed: bool[source]#

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

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 None when 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.md section 3.4), so a result whose execution is not recorded is not reproducible. The driver writes this into solprop.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. backend and propagator_mode are always present; pools, plan flags and wisdom digests are a backend’s own.

name: str#
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 start opens the backend’s session.

reads_transverse_edge: bool#
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: object

What 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.md section 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.md section 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: object

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

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_history because the two are sampled differently: the history is every attempt, these are every period-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)
field: Complex[ndarray, 'n_modes n_pol n_omega'] | None#
n_rejected: int#
n_steps: int#
noise_phase: Float[ndarray, 'n_modes_p n_pol_p n_omega_p'] | None#
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#
step_stats: StepStats#
z: float#
class solprop.backends.protocol.StepStats(z, step, values=<factory>)[source]#

Bases: object

The statistics a backend evaluated between two observations.

The channel of docs/dev/kernel-contract.md section 9. A run whose solprop.stats.StatsSpec names a periodic subset gets one row every period accepted 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 not row * 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.

property n_rows: int[source]#

How many rows were taken since the previous observation.

property names: tuple[str, ...][source]#

The statistics the channel carries, sorted.

step: Int[ndarray, 'n_rows_step']#
values: Mapping[str, ndarray]#
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: object

What 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.md section 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
max_norm: float#
mean_norm: float#
met_tolerance: bool#
n_rejected: int#
n_steps: int#
wall_time: float#
z: float#
class solprop.backends.protocol.TimingProbe(*args, **kwargs)[source]#

Bases: Protocol

Single 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 for solprop.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_init by default, or the scheduled step at z for the low-storage march.