solprop.backends.numpy_ref.workspace#

The reference’s workspace: its state and every state-sized operation (SEP 52).

NumpyWorkspace holds one run’s state and the problem’s tables, and does every operation a march, an engine or the session asks of the state: loading it, the stage scalars and the source, the accepted step’s finish, the band mask, the statistics, the boundary monitor’s and the transverse edge’s readings, the quadrature alarm and the host source’s reservation. It holds no march state – no position, proposal, history or ledger – and is reused across a scan’s points, a load replacing its state. The engines (solprop.backends.numpy_ref.engines, HostHistory, HostLowStorage) are what the marches ask of it.

The contract is consumed only through its evaluation functions – solprop.translate.linop.delta_phi(), solprop.translate.linop.unitary_phase(), solprop.translate.responses.prefactor_at(), and the scalar tables responses.density and transform.taper_scale – never through the coefficient arrays, so the representation of the z tables can change without touching a backend.

Classes

BlockResidual(flow)

R_s(z) state for a held flow's positions (SEP 16 phases 5 and 6).

NumpyWorkspace(problem, request, *, ...[, ...])

The reference's state and every state-sized operation on it (SEP 52 section 5.1).

SourceTables(synthesis, projection, ...)

The problem's tables a source evaluation multiplies by.

class solprop.backends.numpy_ref.workspace.BlockResidual(flow)[source]#

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.workspace.NumpyWorkspace(problem, request, *, chunk_plan, propagator_mode, grid=None, modes=None, profiles=None, tdse_binding=None, name='numpy_ref')[source]#

Bases: object

The reference’s state and every state-sized operation on it (SEP 52 section 5.1).

Built once per backend from the validated problem and request, and reused for every run the backend serves: load() replaces the state and everything that describes it. It keeps no march state. The engines read and write the state only through these operations, and the session (today the backend’s step driver) reads the statistics and the boundary readings from them.

Parameters:
problemsolprop.translate.problem.PropagationProblem

The validated problem.

requestsolprop.translate.run_request.RunRequest

Its run’s request: the stepper’s tableau and controller, which the trials read, and the statistics, whose far-field tables are formed here.

chunk_plansolprop.backends.node_chunk.NodeChunkPlan

The node chunk the response passes hold at once.

propagator_mode{‘tabulate’, ‘recompute’}

The resolved propagator mode: whether a step’s exponents are kept for the step.

gridsolprop.grid.TimeGrid, optional

The grid the state lives on, which the statistics need.

modescollections.abc.Sequence, optional

The propagated modes, in state order, for the statistics that need them.

profilescollections.abc.Mapping, optional

The z-profiles keyed by statistic name.

tdse_bindingsolprop.translate.tdse.TDSEBinding, optional

The host response binding a TDSE problem declares; None otherwise.

namestr, optional

The backend’s name, for messages.

Attributes:
collar_quietbool

Whether the modal stage leaves a quiet in-stage temporal collar out (SEP 21): set by the session from the boundary monitor, read by every stage.

axis_scansint

The on-axis plasma scans actually run (SEP 19), so that a test can see that a rule with a node on the axis supplies that row instead of a fresh scan.

helperssolprop._helpers.Helpers

The uncompiled stage-table and Adams-basis evaluations, PLAIN (SEP 29 section 6.6).

bind_monitor(monitor)[source]#

Read a boundary monitor’s energies from now on, or stop with None.

A monitor of the "split_step" scheme also has each accepted step’s finish() take the split collar’s sums.

Parameters:
monitorsolprop.monitor.BoundaryMonitor or None

The run’s monitor.

channels(values, action)[source]#

Mix the channel axis by one coupled-flow action, or return the values.

Parameters:
valuesnumpy.ndarray

Any array of the state’s layout.

actionnumpy.ndarray or None

The action on the active bins, or None for a problem with no coupled flow, which is every route but the coherent wall.

Returns:
numpy.ndarray

The mixed values, or values itself.

clean_columns(edge)[source]#

Return each column’s launched energy without the input noise, or None.

What the safety ramp is judged on, so a run with no ramp needs none. It is formed where the load has both parts; only a resume that found no record of the monitor has none, and then it is formed from the state.

Parameters:
edgesolprop.transverse_monitor.TransverseEdge

The run’s edge.

Returns:
numpy.ndarray or None

The unweighted energies, or None with no noise, no ramp or on a resumed launch.

close()[source]#

Release the buffers. Idempotent.

committed()[source]#

Return the committed state, refusing an unloaded workspace.

Returns:
numpy.ndarray

The state itself, not a copy.

Raises:
BackendError

If no state is loaded.

coupled_block(z, dz)[source]#

Return the frozen block of the section a step from z is anchored in.

The exponential formulation steps a coupled flow’s constant-Schur and frozen-residual sections against the reference (Delta Phi / h) I + G_s (SEP 16 section 4.5), with G_s the frozen block of the step’s section.

Parameters:
zfloat

Where the step starts, m.

dzfloat

The step, m.

Returns:
object

The step’s CoupledBlock, or None without a coupled flow.

delta_phi(bundle)[source]#

Return the stage’s propagator exponent from the bundle.

One linear combination of the terms the workspace holds over the bundle’s floats. A problem that took the z table has no such form and falls back to solprop.translate.linop.delta_phi().

Parameters:
bundlesolprop.translate.stage.StageScalars

The stage’s scalars.

Returns:
numpy.ndarray

Phi(z1) - Phi(z0) in the state’s layout.

edge_reading(edge, *, faces=True, current=False, full=False)[source]#

Return what the transverse edge asks of the committed state (SEP 44).

Parameters:
edgesolprop.transverse_monitor.TransverseEdge

The run’s edge.

facesbool, optional

Whether the faces are read.

currentbool, optional

Whether a collar’s inward current is wanted.

fullbool, optional

Whether every node is wanted, not only the rows a read uses.

Returns:
object

The edge’s reading of the host state.

error_norm(error, state, advanced)[source]#

Return the controller’s scaled norm of a trial step’s embedded difference.

Parameters:
errornumpy.ndarray

The embedded difference, carried to the step’s end.

statenumpy.ndarray

The state before the step.

advancednumpy.ndarray

The state after it.

Returns:
float

The scaled norm.

exponents(z, dz)[source]#

Return the memoised dPhi of a step, keyed by the stage fraction.

The anchor is hoisted once per step and each exponent is evaluated once and negated for the inverse, never evaluated forward and backward independently (docs/dev/stepper.md section 4). The propagator mode decides whether the exponents are kept for the whole step or evaluated per stage; the exponent itself is one linear combination of the terms over the bundle’s weights, whatever the representation (solprop.translate.stage).

Parameters:
zfloat

Position at the start of the step, m.

dzfloat

Length of the step, m.

Returns:
callable

(fraction, bundle) -> dPhi, of the state’s broadcast shape.

finish(state, dz)[source]#

Apply the once-per-accepted-step boundary treatments to a kept step.

The hard band mask and, when the "split_step" absorber scheme is active, the temporal collar, followed by the mask again: its product in time spreads content into every bin, so the band is imposed last. Applied only to a step that is kept, never to one about to be thrown away. While a monitor of that scheme is bound, the split collar’s sums are taken here from the masked field before the split, the field the removal and the occupancies describe (SEP 52 section 4): what the split removes, P (1 - exp(-alpha h)), and the energies of P exp(-alpha h / 2).

Parameters:
statenumpy.ndarray

The state at the end of an accepted step, shape (n_modes, n_pol, n_omega); not modified.

dzfloat

The length of that step, m, which the collar’s rate needs.

Returns:
numpy.ndarray

The finished state, a new array.

solprop.backends.engines.AcceptRecord

The split collar’s sums; the defaults (nothing removed, nothing found) without a split collar or a bound monitor of its scheme.

flow_actions(section, dz)[source]#

Return the memoised forward and inverse flow actions of one step.

The generator is frozen across the step – at the midpoint of the section the step’s anchor lies in – so an action depends on the stage fraction only through the length c_i h it covers, and the six distinct DOPRI5 fractions need at most six pairs; the tableau uses the last one twice and the zero fraction is the identity. The whole step’s pair is checked against that section’s declared conditioning row, which bounds every shorter one because exp(c dz (mu_max - mu_min)) increases with c.

The pairs also survive between steps, for the one section and trial length last seen: a fixed schedule and an accepted adaptive step both repeat their dz, and an action that depends on nothing but dz and a frozen generator is then the same matrix. Exactly one pair of them is held, so what a step has resident at its peak – which is what memory_ledger() reports – is unchanged, and a step that crosses into the next section rebuilds, which is a cache invalidation at the section edge and is what makes the edge a kink of the flow (docs/dev/stepper.md section 2). The conditioning of a held length was measured when it was built.

Parameters:
sectionint

The section the step’s anchor lies in.

dzfloat

The length of the trial step, m.

Returns:
callable

fraction -> (U, U^-1), each None when no coupled flow is carried.

helpers: Helpers = Helpers(name='plain')#
hoist(z0)[source]#

Evaluate once per step what every stage of it subtracts.

Phi is cumulative, so each stage’s increment is against the same anchor. On the RDW gradient the Clenshaw pass over the scalar tables is the largest part of what the host does per step, and this is a sixth of it. The bundles stage_bundles() kept are dropped.

Parameters:
z0float

The step’s anchor, m.

property input_floor: Complex[ndarray, 'n_modes n_pol n_omega'] | None[source]#

The input noise draw the state carries (the monitor’s floor), or None.

install(state)[source]#

Make an array the committed state, as it is.

A dense observation’s interpolated field and the accepted state it restores afterwards, and a resumed snapshot’s state, go in here; nothing is masked.

Parameters:
statenumpy.ndarray

The state, shape (n_modes, n_pol, n_omega).

lab_source(lab, position, *, purpose='predictor')[source]#

Evaluate the source once, untransported, at a lab-frame field.

The same passes as source(), with the stage’s inverse propagator replaced by ones: a multiplication by one is exact, so the sample is the lab-frame source bit for bit, and every route’s evaluation stays the one the Runge-Kutta trial uses. The sample the exponential formulation and the low-storage step integrate.

lab is taken as given: it is not masked to the active band, as load() masks the state it loads. On a masked field the sample equals the hoisted first stage at the same position bit for bit; a field with content outside the band (an unmasked launch) is another input, whose source differs by what that content makes (4.3e-13 of the peak on the optmat argon capillary). The stage scalars at (position, position) do not depend on the anchor last hoisted: a held anchor is reused only at its own position.

Parameters:
labnumpy.ndarray

The lab-frame field at position, in the state’s layout.

positionfloat

The evaluation position, m.

purpose{‘startup’, ‘predictor’, ‘corrected’, ‘diagnostic’}, optional

The host source’s accounting label; ignored when none is bound.

Returns:
numpy.ndarray

The complete source F in the lab frame.

load(field, noise, *, z, resume)[source]#

Load a state and its noise realisation, masked to the active band.

The input noise model’s draw is added at the run’s launch, never on a resume; the modified model keeps it apart and adds it at every stage. The quadrature alarm of a previous run is forgotten (SEP 22 section 4.7).

Parameters:
fieldnumpy.ndarray

The state, complex128, shape (n_modes, n_pol, n_omega), which the caller has checked against the problem’s.

noisesolprop.noise.NoiseRealisation or None

The realisation to carry, or None for the problem’s own.

zfloat

The position the state belongs to, m, inside the operator table.

resumebool

Whether field came back from a saved plane, and so never takes the input draw.

mask(state)[source]#

Zero a state outside the active band.

Parameters:
statenumpy.ndarray

A state, shape (n_modes, n_pol, n_omega).

Returns:
numpy.ndarray

A new masked array.

memory_ledger()[source]#

Return the size of every buffer the workspace works in, in bytes.

The reference backend allocates its stage and transform buffers per pass instead of keeping a preallocated pool, so this reports what one step has resident at its peak – which is what the optimised backends hold for the whole run, and what the budget of docs/dev/architecture.md section 8 is measured against. Every buffer is named even when it is empty.

The space-domain entries are sized by node_chunk and not by the node count, which is the whole point of the chunk loop (architecture.md section 13): holding (n_to, n_pol n_nodes) for every node at once would be 210 MB against 45 MB on the comb-to-continuum target.

Returns:
dict

Buffer name to bytes.

metadata()[source]#

Return the workspace’s execution facts for the run’s record.

Returns:
dict

The benchmark-gated plasma source’s form and, with a host source, its ledger, execution and last evaluation; JSON-serialisable.

property node_chunk: int[source]#

The nodes a response pass holds at once.

property noise: Complex[ndarray, 'n_modes n_pol n_omega'] | None[source]#

The modified noise model’s realisation, or None with any other.

noise_at(bundle)[source]#

Return the shot-noise field advanced to a stage’s position.

N(z) = N0 exp(i Im Phi(omega, z)): dispersion yes, loss and gain no, from the same terms as the linear flow, so the noise costs one multiply-add per element per stage and no transform.

Parameters:
bundlesolprop.translate.stage.StageScalars

The stage’s scalars.

Returns:
numpy.ndarray or None

The advanced noise, or None when the modified model is not in use.

noise_phase(z)[source]#

Return Im Phi at a position, or None without a noise model.

Parameters:
zfloat

The position, m.

Returns:
numpy.ndarray or None

The phase in radians, in the state’s layout.

nonlinear(lab, bundle, inverse_propagator, *, purpose='predictor')[source]#

Evaluate one stage derivative through the transform passes.

The pipeline of architecture.md section 8 for any node count: one batched inverse transform of every modal column, then, per chunk of node_chunk nodes, the synthesis GEMM, the fused response pass and the projection GEMM accumulated over the chunks, then one batched forward transform, the crop and the prefactor. Mode-averaged propagation is the one-node, one-column case of exactly this code.

Parameters:
labnumpy.ndarray

The stage’s lab-frame field, in the state’s layout.

bundlesolprop.translate.stage.StageScalars

The stage’s scalars.

inverse_propagatornumpy.ndarray

The factor that carries the derivative back to the step’s anchor.

purpose{‘startup’, ‘predictor’, ‘corrected’, ‘diagnostic’}, optional

The host source’s accounting label; ignored when none is bound.

Returns:
numpy.ndarray

The stage derivative in the anchor’s frame.

prefactor(bundle)[source]#

Return the response prefactor at the stage’s position, from the bundle.

Parameters:
bundlesolprop.translate.stage.StageScalars

The stage’s scalars.

Returns:
numpy.ndarray

The prefactor times the crop scale, in m/(V s) per unit polarisation.

property problem: PropagationProblem[source]#

The problem the workspace was built for.

propagator(anchor, position, *, hold=False)[source]#

Return the linear propagator U(position, anchor).

Only the Adams engine holds it for the step’s source call (source()): the low-storage engine applies its flows at once, and a held one would be a volume its ledger does not name.

Parameters:
anchor, positionfloat

The step’s anchor and its end, m.

holdbool, optional

Whether to keep it for the next source() at the same pair.

Returns:
numpy.ndarray

exp(Phi(position) - Phi(anchor)) in the state’s layout, an array the caller owns.

reading()[source]#

Return the boundary monitor’s reading of the committed state (SEP 21).

The state’s energy, its four weighted energies and, under a split collar’s crossing limit, its occupancy; the split’s own sums travel in each step’s AcceptRecord.

Returns:
solprop.backends.engines.BoundaryReading

The reading.

Raises:
BackendError

If no monitor is bound or no state is loaded.

record_trial(*, accepted)[source]#

Tell the bound source how the last reserved trial ended (SEP 20 5.8).

Parameters:
acceptedbool

Whether it was accepted.

release_calls()[source]#

Release the unspent part of a trial’s reservation.

reserve_calls(count)[source]#

Reserve a whole trial’s host-source calls before its first evaluation.

Parameters:
countint

The trial’s logical response calls.

Raises:
solprop.exceptions.ResponseBudgetError

If the bound source’s budget cannot pay for them.

reset_quadrature()[source]#

Forget the alarm, so that the next plane reports its own.

residual(lab, section, bundle)[source]#

Return the explicit residual’s lab-frame source term, or nothing.

None for every problem but a "frozen_residual" coupled flow: the constant section has an identically zero residual and is not multiplied by one, so its arithmetic is bit for bit what it was.

Parameters:
labnumpy.ndarray

The stage’s lab-frame field.

sectionint

The step’s flow section.

bundlesolprop.translate.stage.StageScalars

The stage’s scalars, with the section’s weights.

Returns:
numpy.ndarray or None

R_s(z_1) u in the state’s layout, or None.

restore_atomic_ledger(atomic)[source]#

Restore a resumed run’s atomic call counts into the bound source.

Parameters:
atomiccollections.abc.Mapping

The persisted counts.

Raises:
BackendError

If no host source is bound.

score_quadrature()[source]#

Score the quadrature from the last stage of an accepted step.

The relative difference between the projections of the same node polarisation with the Kronrod rule and with its embedded Gauss subset, at the cost of one extra forward transform per accepted step rather than a whole second evaluation of the transform. It is a statistic and a warning, never a controller input: a quadrature too coarse for the integrand is a modelling error the step size cannot fix, and feeding it to the controller would only shrink the step until the run stopped.

The value is nan when the rule has no embedded pair, because the difference is then identically zero and reading that as convergence would be wrong; and nan where the polarisation itself vanishes, at a true vacuum end, because a relative measure of nothing says nothing. The session reports a value above QUADRATURE_ALARM once per plane, and the quadrature_error statistic reads it.

Returns:
float

The alarm, dimensionless, or NaN.

float

Where the last stage was evaluated, m, or NaN without one.

source(lab, anchor, position, *, purpose='predictor')[source]#

Evaluate the source once, in the interaction frame of a step’s anchor.

The one expensive evaluation of an interaction-formulation Adams step: the nonlinear source at a lab-frame field, with the run’s noise and in-stage absorber. A propagator propagator() held for the same pair is reused.

Parameters:
labnumpy.ndarray

The lab-frame field at position, in the state’s layout.

anchor, positionfloat

The step’s anchor and the evaluation position, m.

purpose{‘startup’, ‘predictor’, ‘corrected’, ‘diagnostic’}, optional

The host source’s accounting label; ignored when none is bound.

Returns:
numpy.ndarray

U(anchor, position) N(lab, position).

numpy.ndarray

U(position, anchor), with U(z_2, z_1) = exp(Phi(z_2) - Phi(z_1)).

stage_bundles(z0, positions)[source]#

Return the host scalars of several stages of one step, taken together.

A trial knows all its stage positions before its first stage, and reading each scalar table once over all of them (solprop.translate.stage.scalars_at()) costs a Python call and a Clenshaw dispatch per table rather than per table and position. The bundles equal stage_scalars()’s bit for bit, and are kept until the next hoist(): a later stage_scalars() at the same anchor and position returns the kept bundle, so a step loop written one stage at a time takes them without change. Bundles of several anchors are kept side by side (kernel schema 29): the low-storage engine reads each of its three positions as its own anchor. A caller passes only positions the trial will evaluate.

Parameters:
z0float

The step’s anchor, m.

positionscollections.abc.Sequence of float

The stages’ positions, m.

Returns:
tuple of solprop.translate.stage.StageScalars

One bundle per position, in order.

stage_scalars(z0, z1)[source]#

Return the host scalars of one stage, from the anchor to the node.

The anchor’s own weights come from hoist() when the caller has already taken them for this step, and are evaluated here otherwise. A bundle stage_bundles() took for this anchor and position is returned as kept.

Parameters:
z0float

The step’s anchor, m.

z1float

The stage’s position, m.

Returns:
solprop.translate.stage.StageScalars

The bundle.

property state: Complex[ndarray, 'n_modes n_pol n_omega'] | None[source]#

The committed state, internal units and FFT convention; None unloaded.

stats(spec, z)[source]#

Collect the requested statistics of the committed state at a position.

The statistics of the saved field go to solprop.stats.collect(); there is exactly one definition of each in the package and that is it. The statistics solprop.stats.StatDefinition marks backend are of quantities a saved plane does not carry – the electron density, the peak ionisation rate, the on-axis intensity, the quadrature error – and are formed here from the workspace’s own buffers.

Parameters:
specsolprop.stats.StatsSpec

Which statistics and which windows.

zfloat

The committed state’s position, m.

Returns:
dict

Small host arrays keyed by statistic name.

property stepper: StepperSettings[source]#

The run’s stepper settings: the tableau, controller and schedule.

unitary_phase(bundle)[source]#

Return Im Phi at the stage’s position, from the same terms.

An expansion of Phi is cumulative and vanishes at the start of the range, so its value at a position is the bundle’s phi_at against the same arrays and the noise costs no second representation.

Parameters:
bundlesolprop.translate.stage.StageScalars

The stage’s scalars.

Returns:
numpy.ndarray

The phase, rad, in the state’s layout.

class solprop.backends.numpy_ref.workspace.SourceTables(synthesis, projection, t_window, t_window_derivative, omega_window, temporal_rate)[source]#

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)[source]#

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#