solprop.backends.rk_core#

The Runge-Kutta march’s controller as functions of its policy and state (SEP 45).

The decisions of StepDriver._march_to – the equivalent norm and acceptance of an attempt, the start-up rule, the next proposal after an accepted step and the shrink after a rejected one – each as a function of the run’s RungeKuttaPolicy and the values it decides on, with no backend or field in reach. The march calls them, and SEP 45 section 4 specifies them; the native march executes the same algorithm and is held to these functions by the decision traces of tests/data/rk_traces.json.gz.

Every function performs the operations of the code it was extracted from, in the same order. The controller’s state is its own proposal: a cap or a landing shortens the executed step, never the proposal these functions take and return (SEP 45 section 4.3). A function that calls limit_step() raises its ConvergenceError before returning anything, so a caller that assigns only what is returned keeps the state the floor found (the three floor sites of section 4.3).

Functions

`decide`(policy, norm, dz, proposal)	Return an attempt's equivalent norm and whether it is accepted.
`propose`(policy, proposal, norms)	Return the proposal after an accepted step, from the history it completed.
`reject`(policy, proposal, equivalent)	Return the proposal after a rejected step: the proposal itself shrunk.
`rk_policy`(stepper)	Return the run's controller policy from its stepper settings.
`start_up`(policy, proposal, norm)	Return the proposal after the first accepted step, and the norm it records.

Classes

RungeKuttaPolicy(controller, dz_min, dz_max, ...)

Every number the Runge-Kutta march's controller reads during a run (SEP 45).

class solprop.backends.rk_core.RungeKuttaPolicy(controller, dz_min, dz_max, auto_init)[source]#

Bases: object

Every number the Runge-Kutta march’s controller reads during a run (SEP 45).

Attributes:

controllersolprop.stepper.controller.PIController: The controller, whose gains, factors, lag, estimator order and acceptance rule the decisions read.
dz_min, dz_maxfloat: The floor and the cap on a proposal, m.
auto_initbool: Whether the first accepted step takes the start-up rule.

auto_init: bool#

controller: PIController#

dz_max: float#

dz_min: float#

solprop.backends.rk_core.decide(policy, norm, dz, proposal)[source]#

Return an attempt’s equivalent norm and whether it is accepted.

What the controller learns from, and what a rejection is scaled by, is the norm the proposal would have scored; what decides acceptance is the error the executed step committed.

Parameters:

policyRungeKuttaPolicy: The run’s policy.
normfloat: The executed step’s scaled error norm.
dzfloat: The executed step, m.
proposalfloat: The controller’s proposal the step was landed from, m.

Returns:

tuple of float and bool: The equivalent norm, and whether the attempt is accepted.

solprop.backends.rk_core.propose(policy, proposal, norms)[source]#

Return the proposal after an accepted step, from the history it completed.

Parameters:

policyRungeKuttaPolicy: The run’s policy.
proposalfloat: The controller’s proposal, m.
normscollections.abc.Sequence of float: The accepted steps’ equivalent norms, oldest first, ending with this step’s.

Returns:

float: The next proposal, m.

Raises:

ConvergenceError: If it falls below the floor.

solprop.backends.rk_core.reject(policy, proposal, equivalent)[source]#

Return the proposal after a rejected step: the proposal itself shrunk.

A rejected step is retried at the step the rejection factor leaves; the factor is applied once, here, and not again on acceptance.

Parameters:

policyRungeKuttaPolicy: The run’s policy.
proposalfloat: The controller’s proposal, m.
equivalentfloat: The rejected attempt’s equivalent norm.

Returns:

float: The next proposal, m.

Raises:

ConvergenceError: If it falls below the floor.

solprop.backends.rk_core.rk_policy(stepper)[source]#

Return the run’s controller policy from its stepper settings.

Parameters:

steppersolprop.translate.problem.StepperSettings: The translated stepper settings.

Returns:

RungeKuttaPolicy: Its controller, floor, cap and start-up flag.

solprop.backends.rk_core.start_up(policy, proposal, norm)[source]#

Return the proposal after the first accepted step, and the norm it records.

The first proposal is a guess; its scaled norm says how far it is from the tolerance. The next proposal is the deadbeat step that norm implies, at most START_GROWTH times the first, and the history is told the norm the first step would have scored at that length, or zero when the cap binds, a norm so small it is round-off (SEP 14 section 4.2).

Parameters:

policyRungeKuttaPolicy: The run’s policy.
proposalfloat: The first accepted step’s proposal, m.
normfloat: Its equivalent norm, the history’s last value.

Returns:

tuple of float: The next proposal, m, and the value that replaces the history’s last.

Raises:

ConvergenceError: If the next proposal falls below the floor; the history is then left as it was.