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
|
|
|
The reference's state and every state-sized operation on it (SEP 52 section 5.1). |
|
The problem's tables a source evaluation multiplies by. |
- class solprop.backends.numpy_ref.workspace.BlockResidual(flow)[source]#
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.workspace.NumpyWorkspace(problem, request, *, chunk_plan, propagator_mode, grid=None, modes=None, profiles=None, tdse_binding=None, name='numpy_ref')[source]#
Bases:
objectThe 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;
Noneotherwise.- 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’sfinish()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
Nonefor 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
Nonewith no noise, no ramp or on a resumed launch.
- 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), withG_sthe frozen block of the step’s section.- Parameters:
- zfloat
Where the step starts, m.
- dzfloat
The step, m.
- Returns:
- object
The step’s
CoupledBlock, orNonewithout 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
dPhiof 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.mdsection 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 ofP 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 hit 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 becauseexp(c dz (mu_max - mu_min))increases withc.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 butdzand 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 whatmemory_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.mdsection 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), eachNonewhen no coupled flow is carried.
- helpers: Helpers = Helpers(name='plain')#
- hoist(z0)[source]#
Evaluate once per step what every stage of it subtracts.
Phiis 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 bundlesstage_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
inputnoise 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
Fin the lab frame.
- load(field, noise, *, z, resume)[source]#
Load a state and its noise realisation, masked to the active band.
The
inputnoise model’s draw is added at the run’s launch, never on a resume; themodifiedmodel 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
Nonefor 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
inputdraw.
- 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.mdsection 8 is measured against. Every buffer is named even when it is empty.The space-domain entries are sized by
node_chunkand not by the node count, which is the whole point of the chunk loop (architecture.mdsection 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 noise: Complex[ndarray, 'n_modes n_pol n_omega'] | None[source]#
The
modifiednoise model’s realisation, orNonewith 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
Nonewhen the modified model is not in use.
- noise_phase(z)[source]#
Return
Im Phiat a position, orNonewithout 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.mdsection 8 for any node count: one batched inverse transform of every modal column, then, per chunk ofnode_chunknodes, 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.
- 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.
- residual(lab, section, bundle)[source]#
Return the explicit residual’s lab-frame source term, or nothing.
Nonefor 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) uin the state’s layout, orNone.
- 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
nanwhen the rule has no embedded pair, because the difference is then identically zero and reading that as convergence would be wrong; andnanwhere the polarisation itself vanishes, at a true vacuum end, because a relative measure of nothing says nothing. The session reports a value aboveQUADRATURE_ALARMonce per plane, and thequadrature_errorstatistic 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), withU(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 equalstage_scalars()’s bit for bit, and are kept until the nexthoist(): a laterstage_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 bundlestage_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;
Noneunloaded.
- 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 statisticssolprop.stats.StatDefinitionmarksbackendare 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 Phiat the stage’s position, from the same terms.An expansion of
Phiis cumulative and vanishes at the start of the range, so its value at a position is the bundle’sphi_atagainst 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:
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)[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']#