solprop.backends.host.adams#

The reference’s Adams march (SEP 13, SEP 14, SEP 39, SEP 52).

The controller, history, ledger and lifecycle of HostAdamsMarch, over the engine protocol (solprop.backends.engines.AdamsEngine) that native’s march::Engine mirrors: the reference’s engine is solprop.backends.numpy_ref.multistep.HostHistory. The march holds its own state – position, proposal, replay cursor and accepted norms (MarchState), the history’s entries, the order, the rejections and the call ledger – and asks its session only through MarchHost. The decisions are solprop.backends.adams_core’s functions of one policy record.

The method, its lifecycle and its numbers are those of solprop.backends.numpy_ref.multistep’s module documentation.

Classes

AcceptedStep(z, dz, order, nodes, carrier)

The last accepted step, as the session's dense observation reads it.

HostAdamsMarch(engine, method, host, *, ...)

March a state with an Adams method over an engine.

class solprop.backends.host.adams.AcceptedStep(z, dz, order, nodes, carrier)[source]#

Bases: object

The last accepted step, as the session’s dense observation reads it.

The counterpart of a native march call’s step_z, step_dz, step_order, step_nodes and step_carrier. Equality is by identity (eq=False) because it holds an array.

Attributes:
zfloat

Where the step started, m.

dzfloat

Its length, m.

orderint

Its order.

nodestuple of float

The history’s normalised positions it read, newest first, order of them.

carriernumpy.ndarray

Its trial’s carrier rotations (step_carrier()); empty without a carrier frame.

carrier: ndarray#
dz: float#
nodes: tuple[float, ...]#
order: int#
z: float#
class solprop.backends.host.adams.HostAdamsMarch(engine, method, host, *, policy, field, schedule=None, interpolate=False, shape=(), proposal=0.0, lag=1, name='numpy_ref')[source]#

Bases: object

March a state with an Adams method over an engine.

Parameters:
enginesolprop.backends.engines.AdamsEngine

The engine that holds the history’s rows.

methodsolprop.stepper.multistep.Multistep

The method.

hostsolprop.backends.host.marches.MarchHost

The session the march reports to.

policysolprop.stepper.multistep.MarchPolicy

Every number the controller and the landings read (SEP 39 section 4.2).

fieldcallable

Returns the committed state, for a budget’s error.

schedulesolprop.stepper.schedule.FixedSchedule or None, optional

The schedule to replay, or None to step adaptively.

interpolatebool, optional

Whether the run interpolates its planes (ADR-036, ADR-039): each accepted step’s record is then kept for the session’s dense observation (last_step).

shapetuple of int, optional

The state’s shape, which a snapshot’s is checked against.

proposalfloat, optional

The first proposal, m.

lagint, optional

The lag of the controller whose norms a replay keeps.

namestr, optional

The backend’s name, for messages.

Attributes:
statesolprop.backends.host.marches.MarchState

The march’s position, proposal, cursor and accepted norms.

ledgersolprop.backends.ledger.CallLedger

The run’s call counts.

last_stepAcceptedStep or None

The last accepted step of an interpolated run; None before one, and always without interpolation.

Raises:
solprop.exceptions.BackendError

If engine lacks a member the march calls.

advance(target)[source]#

Step towards target: the schedule’s replay, or adaptively.

Parameters:
targetfloat

The position to reach, m.

continue_from(snapshot)[source]#

Continue from a snapshot taken where the march now stands.

Installs the history, the order, the rejection count, the flags and the proposed step, so that the march goes on as the uninterrupted one would have; the session installs the state and the engine’s rows, once refusal() found nothing.

Parameters:
snapshotsolprop.output.records.MarchSnapshot

The snapshot.

property has_history: bool[source]#

Whether the march holds a history a snapshot could continue.

property in_flight: None[source]#

No step in flight: an Adams trial never overwrites the committed state.

last_step: AcceptedStep | None#
load(z, proposal, cursor)[source]#

Start a run afresh at a loaded position.

The history and the held trial are forgotten, and the run’s accounting starts afresh – the ledger, the last rejection and the collar’s flag – so that a backend loaded for another run counts that run’s calls alone and chooses its first order and step as a fresh backend would (SEP 22 section 4.7, SEP 39 R9). A resume restores its persisted ledger and flags afterwards.

Parameters:
zfloat

The position, m.

proposalfloat

The first proposal, m.

cursorint

The replay cursor at z.

march_to(target)[source]#

Step adaptively to target, landing on it exactly, or replay towards it.

Parameters:
targetfloat

Position to reach, m.

Raises:
ConvergenceError

If the proposal falls below the contract’s dz_min.

refusal(snapshot)[source]#

Return why a snapshot cannot continue this march, or None.

Parameters:
snapshotsolprop.output.records.MarchSnapshot

The snapshot, possibly read back from a file.

Returns:
str or None

The reason, or None when it can.

replay_step(dz, end, slack)[source]#

Take one prescribed step from the march’s position and accept it.

The unit a replay advances by: the startup of an empty history, the step and, when end is a hard kink, the restart. Called inside an attempt, whose reservation the caller opened.

Parameters:
dzfloat

The step, m.

endfloat

The schedule’s edge it ends on, m.

slackfloat

How far an edge may sit from a kink it lands on, m.

Returns:
float

The step’s scaled error norm, recorded and not acted on.

Raises:
ConvergenceError

If the norm is not finite: the field has diverged, and a replay cannot reject the step.

restore_ledger(logical)[source]#

Continue a resumed run’s cumulative call counts.

Parameters:
logicalcollections.abc.Mapping

The persisted logical counts (solprop.backends.ledger.CallLedger.to_record()).

snapshot_fields()[source]#

Return the march’s part of a snapshot at its accepted position.

The session adds the state and the engine’s rows (MarchSnapshot’s state and rows).

Returns:
dict or None

The snapshot’s other fields, or None with no history to continue.