solprop.backends.adams_core#

The Adams march’s controller as functions of its policy and its state (SEP 39).

The decisions of AdamsMarch – the stencil and scored orders, the step-size factor, a rejection and its restart, the order choice, the proposal’s caps and the approach to a landing – each as a function of the run’s MarchPolicy and the values it decides on, with no backend, engine or field in reach. The march calls them, and SEP 39 section 4 specifies them; the native march executes the same algorithm and is held to these functions by the decision traces of tests/data/adams_traces.json.gz.

Every function performs the operations of the code it was extracted from, in the same order, including how a comparison treats a NaN: min(a, b) is b only if b < a, max over a list keeps the first element unless a later one compares strictly greater.

Functions

`approach`(policy, z, stop, step_targets, target)	Return the step to take, where it ends and whether it lands on a kink.
`carrier_capped`(policy, z, proposal, chord_phase)	Return the proposal shortened to the carrier frame's phase cap.
`choose_order`(policy, current, scores, dz, *, ...)	Return the order to store, and the order and norm that set the next step.
`collar_reentry`(policy, proposal, order, *, ...)	Return the proposal held to the collar's stable step as its term returns.
`factor`(policy, norm, order, *, growth)	Return the elementary step-size factor of an order-order local defect.
`next_landing`(policy, z, step_targets, target)	Return the next forced landing after z: save plane, hard kink or end.
`order_weight`(policy, norm, order, dz, *, quiet)	Return an order's weight: its defect's step factor, capped for stability.
`quiet_capped`(proposal, *, quiet, interval)	Return the proposal, held to the monitor's interval while the collar rests.
`rejection`(policy, norm, order, *, ...)	Return what a rejected trial of order order leaves.
`replay_kink`(policy, end, slack)	Return whether a replayed step's end is a hard kink: one within slack of it.
`stable_factor`(policy, order, dz, *, quiet)	Return the largest factor on dz an in-stage collar leaves an order stable.
`stencil`(policy, z, dz, positions, rows, ...)	Return a trial's nodes, rows, order and scored orders.
`targets`(policy, target)	Return the caps and landings of one march to target.

Classes

`Rejection`(factor, rejections, restart)	What a rejected trial leaves (SEP 39 section 4.4).
`Stencil`(nodes, rows, order, orders)	A trial's history and the orders it scores (SEP 39 section 4.3, step 5).

class solprop.backends.adams_core.Rejection(factor, rejections, restart)[source]#

Bases: object

What a rejected trial leaves (SEP 39 section 4.4).

Attributes:

factorfloat: The factor on the rejected step that gives the next proposal.
rejectionsint: The consecutive rejections after this one, reset to zero by a restart.
restartbool: Whether the history is emptied: the restart after restart_after in a row.

factor: float#

rejections: int#

restart: bool#

class solprop.backends.adams_core.Stencil(nodes, rows, order, orders)[source]#

Bases: object

A trial’s history and the orders it scores (SEP 39 section 4.3, step 5).

Attributes:

nodeslist of float: The history’s normalised positions (z_j - z) / h, newest first.
rowsnumpy.ndarray: Their engine rows, in the same order.
orderint: The step’s own order, min(q, n).
orderslist of int: The orders scored: the step’s own first, then under variable order its lower and its higher neighbour where the history can form them.

nodes: list[float]#

order: int#

orders: list[int]#

rows: Int[ndarray, 'n_held']#

solprop.backends.adams_core.approach(policy, z, stop, step_targets, target)[source]#

Return the step to take, where it ends and whether it lands on a kink.

Parameters:

policysolprop.stepper.multistep.MarchPolicy: The run’s policy.
zfloat: The current position, m.
stopsolprop.stepper.schedule.Landing: The landing the shared rule chose for the proposal.
step_targetssolprop.stepper.schedule.StepTargets: The caps and landings.
targetfloat: The end of this march, m.

Returns:

tuple: The step, m; its end position, m; and whether that end is a hard kink.

solprop.backends.adams_core.carrier_capped(policy, z, proposal, chord_phase)[source]#

Return the proposal shortened to the carrier frame’s phase cap.

Under a carrier frame no step covers more than the policy’s carrier cap of carrier phase (SEP 35 section 6.4), measured by one chord of the reference element’s operator over the proposal, the largest over the batch. Applied before the landing rule, so a shortened step is not a landing; a fixed schedule’s replay is not capped.

Parameters:

policysolprop.stepper.multistep.MarchPolicy: The run’s policy.
zfloat: The current position, m.
proposalfloat: The controller’s proposal, m.
chord_phasecallable: (z1, z2) -> phase, the chord’s largest phase over the batch, rad.

Returns:

float: The proposal, or the shorter step the cap allows, m.

Notes

Called under a carrier frame only (policy.carrier); without one the proposal is not capped.

solprop.backends.adams_core.choose_order(policy, current, scores, dz, *, quiet)[source]#

Return the order to store, and the order and norm that set the next step.

Under a fixed order the stored order is the method’s while the step’s own defect sets the next step (SEP 39 section 4.5, R1). Under variable order the scored order with the largest weight is adopted when it beats the step’s own by the hysteresis; each order is weighed by the step its defect allows, capped at the step an in-stage collar leaves it stable at. The cap weighs the choice only; the step is the chosen order’s defect’s.

Parameters:

policysolprop.stepper.multistep.MarchPolicy: The run’s policy.
currentint: The step’s own order, the first key of scores.
scoresmapping: The scaled defect of every scored order, in the stencil’s order.
dzfloat: The accepted step, m.
quietbool: Whether the stages leave a quiet collar out.

Returns:

tuple: The stored order q_s, the control order q_c and its norm.

solprop.backends.adams_core.collar_reentry(policy, proposal, order, *, was_quiet, quiet)[source]#

Return the proposal held to the collar’s stable step as its term returns.

While a quiet collar is left out of the stages the order choice ignores its stability limit (stable_factor()), so the march may hold a high order and a long step; on the first attempt after the term returns that step would be unstable for it. That attempt is held to the stable step of the stored order, and the order choice weighs the limit again from there. The caller records quiet as the flag of the attempt, whatever this returns.

Parameters:

policysolprop.stepper.multistep.MarchPolicy: The run’s policy.
proposalfloat: The proposal, m.
orderint: The stored order, q.
was_quietbool: Whether the collar was quiet at the last attempt, w_Q.
quietbool: Whether it is quiet now, Q.

Returns:

float: The proposal, or the collar’s stable step when its term has just returned, m.

solprop.backends.adams_core.factor(policy, norm, order, *, growth)[source]#

Return the elementary step-size factor of an order-order local defect.

The defect scales as h^{order+1} (SEP 13 section 4.4), so the exponent is 1/(order + 1), not the Runge-Kutta pair’s fixed one.

Parameters:

policysolprop.stepper.multistep.MarchPolicy: The run’s policy, for the safety and smallest factors.
normfloat: The scaled defect.
orderint: The order the defect belongs to.
growthfloat: The largest factor allowed.

Returns:

float: The factor on the step.

solprop.backends.adams_core.next_landing(policy, z, step_targets, target)[source]#

Return the next forced landing after z: save plane, hard kink or end.

Parameters:

policysolprop.stepper.multistep.MarchPolicy: The run’s policy, for its landing tolerance.
zfloat: The current position, m.
step_targetssolprop.stepper.schedule.StepTargets: The planes and kinks.
targetfloat: The end of the current march, m.

Returns:

float or None: The nearest landing strictly beyond z plus the tolerance, or None when none lies ahead.

solprop.backends.adams_core.order_weight(policy, norm, order, dz, *, quiet)[source]#

Return an order’s weight: its defect’s step factor, capped for stability.

Parameters:

policysolprop.stepper.multistep.MarchPolicy: The run’s policy.
normfloat: The order’s scaled defect.
orderint: The order.
dzfloat: The accepted step, m.
quietbool: Whether the stages leave a quiet collar out.

Returns:

float: safety norm ** (-1 / (order + 1)), infinite for a zero defect, at most stable_factor().

solprop.backends.adams_core.quiet_capped(proposal, *, quiet, interval)[source]#

Return the proposal, held to the monitor’s interval while the collar rests.

The rule of solprop.backends.driver.StepDriver._quiet_capped, with the collar’s state and the monitor’s interval passed in.

Parameters:

proposalfloat: The controller’s proposal, m.
quietbool: Whether the stages leave a quiet collar out.
intervalfloat or None: The monitor’s interval, m, or None without a monitor.

Returns:

float: The proposal, or the interval while the collar is left out, m.

solprop.backends.adams_core.rejection(policy, norm, order, *, rejections, held)[source]#

Return what a rejected trial of order order leaves.

A rejection leaves the accepted history untouched. Repeated rejections mean the history itself is the problem – a parasitic mode of the multistep recurrence that a smaller step cannot remove, because every stencil still interpolates it – so after restart_after in a row the method restarts from the accepted state, paying one startup call.

Parameters:

policysolprop.stepper.multistep.MarchPolicy: The run’s policy.
normfloat: The rejected trial’s scaled defect, possibly not finite.
orderint: Its order.
rejectionsint: The consecutive rejections before this one.
heldint: The history entries held.

Returns:

Rejection: The factor, the new count and whether the history restarts.

solprop.backends.adams_core.replay_kink(policy, end, slack)[source]#

Return whether a replayed step’s end is a hard kink: one within slack of it.

Parameters:

policysolprop.stepper.multistep.MarchPolicy: The run’s policy, for its kinks.
endfloat: The schedule’s edge the step ends on, m.
slackfloat: The replay’s tolerance, m (solprop.backends.driver.replay_tolerance()).

Returns:

bool: Whether the history restarts there.

solprop.backends.adams_core.stable_factor(policy, order, dz, *, quiet)[source]#

Return the largest factor on dz an in-stage collar leaves an order stable.

Parameters:

policysolprop.stepper.multistep.MarchPolicy: The run’s policy.
orderint: The predictor order.
dzfloat: The step, m.
quietbool: Whether the stages leave a quiet collar out.

Returns:

float: c P_order / (dz rho), infinite without an in-stage collar or while it rests.

solprop.backends.adams_core.stencil(policy, z, dz, positions, rows, stored_order, *, last_rejected)[source]#

Return a trial’s nodes, rows, order and scored orders.

Each order’s defect is its k + 1-node corrector through the new source less its k-node predictor; a neighbour is scored when the history can form it, and the order never rises straight after a rejection.

Parameters:

policysolprop.stepper.multistep.MarchPolicy: The run’s policy.
zfloat: The anchor, m.
dzfloat: The step, m.
positions, rowssequence: The history’s positions, m, and engine rows, oldest first.
stored_orderint: The order the last acceptance stored, q.
last_rejectedbool: Whether the last attempt was rejected.

Returns:

Stencil: The stencil.

solprop.backends.adams_core.targets(policy, target)[source]#

Return the caps and landings of one march to target.

Parameters:

policysolprop.stepper.multistep.MarchPolicy: The run’s policy.
targetfloat: The end of this march, m.

Returns:

solprop.stepper.schedule.StepTargets: The planes (none when they are interpolated), the kinks and the interval edges; the run’s end when planes are interpolated, otherwise target.