solprop.backends.numpy_ref.engines#

The reference’s Runge-Kutta engines over its workspace (SEP 52 section 5.2).

Two RungeKuttaEngine implementations, the counterparts of native’s resident engines. NumpyRungeKutta forms an interaction-picture embedded Runge-Kutta trial from the workspace’s committed state and keeps its stages and end state until accept() finishes and commits it; a rejected trial leaves the committed state as it was. NumpyLowStorage is the low-storage RK4 step of SEP 24 (solprop.backends.low_storage), whose trial overwrites the state in place and is in flight until it is accepted. The Adams engine is solprop.backends.numpy_ref.multistep.HostHistory.

Classes

NumpyLowStorage(workspace, method, schedule, ...)

The host engine: the four register passes over host arrays (SEP 24 6.5).

NumpyRungeKutta(workspace, tableau)

The interaction-picture embedded Runge-Kutta trial over a workspace.

class solprop.backends.numpy_ref.engines.NumpyLowStorage(workspace, method, schedule, propagator_mode)[source]#

Bases: object

The host engine: the four register passes over host arrays (SEP 24 6.5).

The workspace’s state is the register A and is updated in place by the trial; B and C are this engine’s host arrays, allocated at the first step. Each pass makes one source evaluation through the workspace’s lab_source (the complete source, the noise draw advanced to the pass’s position and the in-stage absorbers included) and takes P and Q from its propagator or the table, allocating transients as the reference does. The step’s three positions are known before its first pass, so their host scalars are read together (stage_bundles) and the evaluations take the kept bundles.

The commit contract (SEP 52 section 5.2): trial() overwrites the state, and from its start until accept() returns the engine is in_flight. An exception or a non-finite result in that interval leaves no committed state at that position; only reset(), at a load, clears the flag.

The flows. "tabulate" on a constant operator holds one volume, exp(h_t D / 2), built at the first step after a load and reused while the steps keep the same key h_t, their run’s mean step (table_steps(), SEP 24 Q10): a uniform schedule’s steps are differences of rounded positions and differ in their last bits. The table is built from the key alone, from the operator’s origin to h_t / 2 – a constant operator’s increment is the distance itself – so its exponent carries one rounding of D h_t / 2 and none of the step’s position (fl(z + h/2) - z would be off by up to half an ulp of z, an error that accumulates). Each reused flow’s exponent is then off by |D| |h - h_t| / 2, a few ulps of the position times |D|, which does not accumulate over the run. A varying operator’s P and Q change every step, and "tabulate" forms the pair once per step; "recompute" forms each flow in the finish that applies it, from the positions, whose differences telescope. The treatments agree to rounding, not bit for bit.

The stiffness indicator (SEP 24 section 6.3, Q1): h rho = 2 ||F3 - F2|| / ||F2 - g1|| over the norm mask estimates |h lambda| of the linearised source on the content the step integrates (for u' = lambda u it is exactly |h lambda|), the quantity the stability interval of section 4.6 bounds. It is kept in stiffness and never enters the norm column. It reads the content’s margin, not the worst case: measured on an ionising capillary it passed 2.785 on the step before the replay diverged, and beside an in-stage collar it read 0.17 to 0.65 of h alpha_max / 2 as the collar held less or more of the field.

Parameters:
workspacesolprop.backends.numpy_ref.workspace.NumpyWorkspace

The reference’s workspace, whose state, evaluations and finish are used. The native session keeps its registers resident and never takes this engine.

methodsolprop.stepper.low_storage.LowStorageRungeKutta

The march.

schedulesolprop.stepper.schedule.FixedSchedule or None

The replayed schedule, whose runs key the flow table; None only for an engine that never tabulates.

propagator_mode{‘tabulate’, ‘recompute’}

Whether the step’s flows are held for it.

Attributes:
stiffnessfloat

h rho of the last completed trial, dimensionless; NaN before one, or when F2 - g1 vanished on the norm mask.

Notes

What the engine holds between steps is the registers B and C and, on a constant operator tabulating, the table: held() names them for the backend’s memory ledger, and close() releases them.

accept(dz)[source]#

Finish the state the trial left and commit it; the step leaves flight.

Parameters:
dzfloat

The step, m, which the split collar’s rate needs.

Returns:
solprop.backends.engines.AcceptRecord

The stiffness indicator and the finish’s split collar’s sums.

close()[source]#

Release the registers and the flow table.

extend(z, dz)[source]#

Refuse: the low-storage march replays and observes no plane densely.

Parameters:
zfloat

Where the step started, m.

dzfloat

The step, m.

Raises:
BackendError

Always.

held()[source]#

Return the bytes of every array the engine holds between steps, by name.

Returns:
dict

register_accumulator, register_stage and propagators (the table), each zero while it is not allocated.

property in_flight: bool[source]#

Whether a trial overwrote the state and its accept has not returned.

reading()[source]#

Return the committed state’s boundary reading.

Returns:
solprop.backends.engines.BoundaryReading

The workspace’s reading.

reset()[source]#

Drop the flow table and a step left in flight: a state was loaded.

A resume builds the table again from its own first step.

trial(z, dz)[source]#

Take one RK4IP step in place, in the four passes of the register form.

The engine is in flight from here until accept() returns.

Parameters:
zfloat

Where the step starts, m.

dzfloat

The step, m, positive.

Returns:
float

0.0, “not estimated”; or, when the field has diverged, the accepted state’s non-finite squared norm over the norm mask.

class solprop.backends.numpy_ref.engines.NumpyRungeKutta(workspace, tableau)[source]#

Bases: object

The interaction-picture embedded Runge-Kutta trial over a workspace.

Every stage is evaluated. The tableau’s first-same-as-last property would let the last stage of one step serve as the first of the next, after rebasing it by exp(dPhi) because the interaction picture is re-anchored every step; the reference does not take that saving, so that no stage it uses depends on the bookkeeping of the step before (docs/dev/stepper.md section 10, trap 10).

Parameters:
workspacesolprop.backends.numpy_ref.workspace.NumpyWorkspace

The workspace whose state is stepped.

tableausolprop.stepper.tableau.Tableau

The embedded pair.

Attributes:
evaluationsint

Physical source evaluations of the trials since the engine was built, for one run, rejected trials included (SEP 30 records work rather than estimating it from steps).

accept(dz)[source]#

Finish the held trial and commit it as the workspace’s state.

Parameters:
dzfloat

The accepted step, m.

Returns:
solprop.backends.engines.AcceptRecord

The finish’s split collar’s sums.

extend(z, dz)[source]#

Hold the held trial’s continuous extension, before it is accepted.

With v0 the state at the step’s anchor, k_i its stage derivatives in the anchor’s frame and v1 = v0 + h sum_i b_i k_i, the coefficients are DOPRI5’s (Hairer, Noersett and Wanner, II.6): v0, v1 - v0, h k1 - (v1 - v0), (v1 - v0) - h k7 - (h k1 - (v1 - v0)) and h sum_i d_i k_i.

Parameters:
zfloat

Where the trial started, m.

dzfloat

The step, m.

property extension: tuple[float, float, list[ndarray]] | None[source]#

The held extension: its step’s start and length, m, and its coefficients.

property in_flight: bool[source]#

Whether a trial overwrote the committed state; never, on this engine.

reading()[source]#

Return the committed state’s boundary reading.

Returns:
solprop.backends.engines.BoundaryReading

The workspace’s reading.

property stages: list[Complex[ndarray, 'n_modes n_pol n_omega']][source]#

The held trial’s stage derivatives, in its anchor’s frame.

trial(z, dz)[source]#

Form a trial from the committed state at z over dz; return its norm.

A problem carrying linear.coupled_flow multiplies each stage’s scalar propagator by the section’s Schur matrix-function action; the two factors commute, so their product is the flow of the sum. A "frozen_residual" flow adds the explicit residual to each stage’s lab-frame source, before the interaction picture’s own factors carry it back, so it is integrated by the embedded pair exactly as the material response is.

Parameters:
zfloat

Where the trial starts, m.

dzfloat

The step, m, positive.

Returns:
float

The scaled error norm of the step’s embedded difference.

property trial_state: Complex[ndarray, 'n_modes n_pol n_omega'][source]#

The held trial’s raw end state, before the accepted step’s finish.