solprop.stepper.settings#

The stepper section of a run: method, controller, step limits, schedule and planes.

StepperSettings is section 7 of the kernel contract (docs/dev/kernel-contract.md): the record that RunRequest.stepper gathers a request’s method, error control, itinerary and planes back into, and that describe_run() builds a request from. It is run-specification data (docs/dev/architecture.md section 3), so it lives beside the tableaux, controllers and schedules it holds: below translation, which resolves it, and below the backends and the driver, which read it. PropagatorMode names the stage-propagator choice it carries.

Module Attributes

PropagatorMode

Whether the backend tabulates the stage propagators or recomputes them.

Classes

StepperSettings(tableau, controller, dz_min, ...)

The tableau, the controller and the schedule of a run.

solprop.stepper.settings.PropagatorMode#

Whether the backend tabulates the stage propagators or recomputes them.

"auto", the default, is the backend’s own choice, resolved at construction and recorded in the run’s metadata: tabulate for numpy_ref, whose two complex exponentials per stage the table is worth memoising, and recompute for native, where both signs come from one real exp and a sincos in the stage that formed them, so the table buys residency and nothing else (docs/dev/backends.md section 3.6). Either can still be asked for by name; the two agree bitwise, so the choice is memory and not numbers.

alias of Literal[‘auto’, ‘tabulate’, ‘recompute’]

class solprop.stepper.settings.StepperSettings(tableau, controller, dz_min, dz_max, dz_init, stretch, schedule, save_planes, propagator_mode, integrator=None, interval_cap=True, auto_init=False, interpolate_planes=False, step_planes=0)[source]#

Bases: object

The tableau, the controller and the schedule of a run.

Section 7 of the kernel contract. The tolerances and the norm choice live in the controller and nowhere else.

Attributes:
tableausolprop.stepper.tableau.Tableau

Nodes, matrix, solution weights, error weights b - b_hat, orders and the first-same-as-last flag.

controllersolprop.stepper.controller.PIController

Tolerances, safety, growth caps, the PI exponents, the lag, the reject-free switch, the estimator order and the norm weights.

dz_minfloat

Floor on the controller’s proposal, m. A proposal below it raises rather than being clamped silently; it never applies to a landing step.

dz_maxfloat

Cap on the proposal, m.

dz_initfloat

First step, m.

stretchfloat

Landing stretch factor: a target within this multiple of the capped proposal is landed on directly. 1 switches it off.

schedulesolprop.stepper.schedule.FixedSchedule or None

A fixed schedule to replay, whose edges must contain every save plane and hard kink. None for an adaptive run.

save_planesnumpy.ndarray

Positions in z the driver will ask for, m, shape (n_z,), increasing. Steps land on them exactly; there is no dense output.

propagator_mode{‘auto’, ‘tabulate’, ‘recompute’}

Whether the backend tabulates the stage propagator factors or recomputes them. "auto" leaves the choice to the backend, which records what it resolved.

integratorsolprop.stepper.multistep.Multistep or LowStorageRungeKutta or None

A low-call Adams method to step with instead of the tableau (SEP 13), the low-storage RK4 march (SEP 24), or None for the Runge-Kutta march. With a schedule an Adams method replays the schedule’s steps (SEP 16 section 5); the low-storage march replays one and nothing else.

interval_capbool

Whether a step is capped at the width of the operator-table interval it starts in. The cumulative table makes the flow exact across intervals, so the cap is off on the diagonal-flow routes and on for a coupled flow, whose flow error the embedded estimate does not see (SEP 14 section 4.1).

auto_initbool

Whether the start-up rule takes the step after the first from the first step’s own error estimate (PIController.start_factor); False grows from dz_init at the growth cap.

interpolate_planesbool

Step across the save planes and observe each inside its accepted step, through the tableau’s continuous extension or the Adams march’s own polynomial (SEP 14 phase 3); False lands on them. The end of the run and every hard kink are landed on either way.

step_planesint

A positive k also saves the end of every k-th accepted step: the march returns to its session there, short of its target, and marches on (SEP 14 phase 3). 0 saves the requested planes only.

Raises:
TranslationError

If the step caps are not ordered, the stretch is below one, the save planes are not increasing and positive, or the low-storage march is asked for without a schedule, with interpolated planes or with a schedule step longer than dz_max.

Examples

>>> from solprop.stepper import DOPRI5, PIController
>>> from solprop.stepper.settings import StepperSettings
>>> settings = StepperSettings(DOPRI5, PIController(rtol=1e-8, atol=1e-14),
...                            1e-9, 0.1, 1e-3, 1.1, None, [0.5, 1.0], "tabulate")
>>> settings.save_planes.tolist()
[0.5, 1.0]
auto_init: bool = False#
controller: PIController#
dz_init: float#
dz_max: float#
dz_min: float#
integrator: Multistep | LowStorageRungeKutta | None = None#
interpolate_planes: bool = False#
interval_cap: bool = True#
propagator_mode: Literal['auto', 'tabulate', 'recompute']#
save_planes: Float[ndarray, 'n_z'] | Sequence[float]#
schedule: FixedSchedule | None#
step_planes: int = 0#
stretch: float#
tableau: Tableau#
property z_end: float[source]#

Last save plane, where the run stops, m.

Examples

>>> from solprop.stepper import DOPRI5, PIController
>>> from solprop.stepper.settings import StepperSettings
>>> StepperSettings(DOPRI5, PIController(rtol=1e-8, atol=1e-14), 1e-9, 0.1,
...                 1e-3, 1.1, None, [0.5, 1.0], "tabulate").z_end
1.0