solprop.backends.ledger#

The Adams march’s bookkeeping, shared by both backends (SEP 13 section 5, SEP 39).

The call ledger and its record, the budget’s error, a history entry and whether a problem’s source is structurally zero: what the native session and the reference’s host march both keep, with no arithmetic of either.

Functions

`budget_error`(max_calls, spent, z, cost, field)	Return the error of an Adams trial the source-call budget cannot pay for.
`source_absent`(problem)	Return whether a problem's complete source is structurally zero.

Classes

`CallLedger`([startup, predictor, corrected, ...])	Expensive source evaluations of one run, by purpose (SEP 13 section 5).
`Derivative`(z, value, identity[, slot])	One entry of an Adams march's derivative history, in the current anchor's frame.

class solprop.backends.ledger.CallLedger(startup=0, predictor=0, corrected=0, rejected=0, accepted_steps=0, rejected_steps=0, restarts=0, failure_restarts=0, dense_observations=0, orders=<factory>)[source]#

Bases: object

Expensive source evaluations of one run, by purpose (SEP 13 section 5).

Attributes:

startupint: Evaluations at an accepted field to start or restart the history.
predictorint: Evaluations at a predicted field, accepted or not.
correctedint: Evaluations at a corrected, accepted field; PEC makes none.
rejectedint: Evaluations spent on steps that were then rejected (included in the above).
accepted_steps, rejected_stepsint: Step counts.
restartsint: History restarts at hard kinks.
failure_restartsint: History restarts after RESTART_AFTER consecutive rejections.
dense_observationsint: Save planes observed by interpolation instead of a landing; none costs a call.
orderslist of int: The predictor order of every accepted step. Its record (to_record()) run-length encodes it, as [order, count] pairs: a run’s order settles, and the record is rewritten at every saved plane.

accepted_steps: int = 0#

corrected: int = 0#

dense_observations: int = 0#

failure_restarts: int = 0#

classmethod from_record(record)[source]#

Restore validated cumulative counts without restoring numerical history.

Parameters:

recordmapping: Persisted counter fields and accepted predictor orders, as to_record() writes them.

Returns:

CallLedger: Independently owned counters, the orders decoded step by step.

Raises:

BackendError: If a counter is absent, unknown, negative or not an integer, an order run is not a pair of positive integers, or the runs do not count one order per accepted step.

Examples

>>> from solprop.backends.ledger import CallLedger
>>> ledger = CallLedger(accepted_steps=3, orders=[1, 2, 2])
>>> CallLedger.from_record(ledger.to_record()) == ledger
True

orders: list[int]#

predictor: int = 0#

rejected: int = 0#

rejected_steps: int = 0#

restarts: int = 0#

startup: int = 0#

to_record()[source]#

Return the ledger as its run record holds it, the orders run-length encoded.

The encoding is extended from the orders appended since the last record. A list of orders that was replaced, or shortened, is encoded afresh.

Returns:

dict: Every counter by name, and orders as [order, count] pairs, in step order, no two neighbours of the same order.

Examples

>>> from solprop.backends.ledger import CallLedger
>>> CallLedger(accepted_steps=5, orders=[1, 2, 2, 3, 3]).to_record()["orders"]
[[1, 1], [2, 2], [3, 2]]

property total: int[source]#

Every charged source evaluation.

Startup, predictor and corrected evaluations together.

class solprop.backends.ledger.Derivative(z, value, identity, slot=-1)[source]#

Bases: object

One entry of an Adams march’s derivative history, in the current anchor’s frame.

Attributes:

zfloat: Where the derivative was evaluated, m.
valuenumpy.ndarray or None: The history store’s row, complex128 of shape (n_batch, n_modes, n_pol, n_omega), or None for an engine that keeps its rows resident (the native state).
identitystr: Which field it was evaluated at: "accepted", or "predicted" for the predicted field PEC stores in its place.
slotint: Its row of the history store; -1 before it has one.

identity: str#

slot: int = -1#

value: Complex[ndarray, 'n_batch n_modes n_pol n_omega'] | None#

z: float#

solprop.backends.ledger.budget_error(max_calls, spent, z, cost, field)[source]#

Return the error of an Adams trial the source-call budget cannot pay for.

One message for every march that keeps the budget: solprop’s and the native session’s, which charge the same calls (SEP 39 section 4.9).

Parameters:

max_callsint or None: The method’s budget.
spentint: The calls charged so far (CallLedger.total).
zfloat: The last accepted position, m.
costint: The calls the refused trial needs.
fieldnumpy.ndarray: The accepted state there, (n_modes, n_pol, n_omega), owned by the error.

Returns:

solprop.exceptions.ResponseBudgetError: Carrying the last accepted position and state and the calls spent.

solprop.backends.ledger.source_absent(problem)[source]#

Return whether a problem’s complete source is structurally zero.

No response is compiled beyond the accumulation, and no in-stage absorber, no atomic response and no general or spatial pipeline adds a term: SEP 16 section 4.2 then requires the exact chord rather than an interpolated compensation, which need not cancel even at the endpoint. Decided from the problem’s structure, never from a sample that happens to vanish.

Parameters:

problemsolprop.translate.problem.PropagationProblem: The problem.

Returns:

bool: Whether every source evaluation is identically zero.