solprop.backends.host.session#

The NumPy reference’s run session: the schedule of a run (SEP 47, SEP 52).

HostSession is the RunSession that serves every numpy_ref run, and the Python counterpart of native’s session.cpp, whose scheduling decisions are this module’s transcribed. It owns the run’s schedule: the save planes and step planes, the natural stops, the bounded yields, the landing targets, the halts and the snapshot latch, the dense observation of a plane a step crossed (through the backend’s Dense), the periodic statistics rows, the boundary monitor’s and the transverse edge’s checks with the split collar’s sums, the quadrature alarm’s report, the load of the start with its noise, the events and the exports. It drives the run’s march directly (HostMethod), as the march’s MarchHost; the state and every state-sized operation are the backend’s workspace’s (NumpyWorkspace).

Boundary warnings are barriers. The monitor’s and the edge’s warnings go into a sink (solprop.monitor.BoundaryMonitor.sink) rather than being issued where they arise, and each is reported, in order, as a WARNING barrier event at the committed endpoint it arose at, whose consumer emits it (emit_warning()): its filters may raise it, which fails the run there. Once allowed, the next advance does the rest of that point’s work, once, as native’s session does.

HostPrepared is the prepared execution (SEP 47 section 5.2) a reference backend returns from prepare; each of its starts opens one session. The session composes the parts every Python session shares (solprop.backends.session_core) with the lifecycle ledger (SessionLedger). It imports nothing of the native backend’s.

Module Attributes

INITIAL_STEP_STATS_CAPACITY

Rows a plane's statistics buffer holds before it first has to grow.

Functions

natural_stop(every, count, z, target)

Return whether the count-th accepted step since the load is a step plane.

start_position(problem, stepper, z)

Return where a state may be loaded, and a replay's cursor there.

step_cap(monitor, quiet, proposal, z)

Return a proposal held to the boundary monitor's limits on a step.

Classes

Dense(*args, **kwargs)

A march's dense output: what a session interpolates a crossed plane from.

HistoryRows(*args, **kwargs)

An Adams history's rows where the state lives, which a snapshot carries.

HostBackend(*args, **kwargs)

What the reference's session reads of its backend.

HostMethod(march[, dense, rows])

The march one session runs, built for it by the backend (native's Method).

HostPrepared(backend, problem, request)

A prepared run of a reference backend (SEP 47 section 5.2).

HostSession(backend, problem, request, start, *)

The reference's RunSession.

class solprop.backends.host.session.Dense(*args, **kwargs)[source]#

Bases: Protocol

A march’s dense output: what a session interpolates a crossed plane from.

Native’s session::Dense; the reference’s are solprop.backends.numpy_ref.dense’s.

crosses(position, target)[source]#

Return whether a march that returned at position stepped across target.

Parameters:
positionfloat

The committed position, m.

targetfloat

The plane, m.

Returns:
bool

Whether the plane is observed inside the last step.

observe(position)[source]#

Hold the committed state aside; make the state the field at position.

Parameters:
positionfloat

The plane, m, inside the last accepted step.

restore()[source]#

Make the held committed state current again.

class solprop.backends.host.session.HistoryRows(*args, **kwargs)[source]#

Bases: Protocol

An Adams history’s rows where the state lives, which a snapshot carries.

export()[source]#

Return copies of the rows, by name.

Returns:
dict

The rows.

install(rows, shape)[source]#

Install rows export() returned, for a state of shape.

Parameters:
rowscollections.abc.Mapping

The rows, by name.

shapetuple of int

The state’s shape.

nbytes()[source]#

Return the bytes export() would copy.

Returns:
int

The size of every row.

class solprop.backends.host.session.HostBackend(*args, **kwargs)[source]#

Bases: Protocol

What the reference’s session reads of its backend.

Attributes:
namestr

The registry name.

reads_transverse_edgebool

Whether a free-space run’s transverse edge is read (SEP 40 section 5.3).

close()[source]#

Release the buffers.

property closed: bool[source]#

Whether the backend has released its buffers.

memory_ledger()[source]#

Return every retained buffer by name, bytes.

Returns:
dict

The ledger.

metadata()[source]#

Return the execution’s facts.

Returns:
dict

The record.

method(host)[source]#

Return a fresh march, and its dense output and rows, reporting to host.

Parameters:
hostobject

The session, as the march’s MarchHost.

Returns:
HostMethod

The method.

name: str#
reads_transverse_edge: bool#
property request: RunRequest[source]#

Request the backend was built for.

property workspace: NumpyWorkspace[source]#

Workspace that holds the state.

class solprop.backends.host.session.HostMethod(march, dense=None, rows=None)[source]#

Bases: object

The march one session runs, built for it by the backend (native’s Method).

Attributes:
marchobject

The march: a RungeKuttaMarch, HostAdamsMarch or HostLowStorageMarch, its session the march’s host.

denseDense or None

Its dense output when the run interpolates its planes; None otherwise.

rowsHistoryRows or None

The Adams history’s rows a snapshot carries; None for the other marches.

dense: Dense | None = None#
march: RungeKuttaMarch | HostAdamsMarch | HostLowStorageMarch#
rows: HistoryRows | None = None#
class solprop.backends.host.session.HostPrepared(backend, problem, request)[source]#

Bases: object

A prepared run of a reference backend (SEP 47 section 5.2).

The backend was built for the problem and a request – it lowered the method, the error control, the itinerary, the planes and the statistics then – so preparing binds the problem and the request one run serves, a request that differs from the backend’s own only in its start, retention, monitor and history (for_run()). Each start() opens one HostSession over the backend.

Parameters:
backendsolprop.backends.protocol.Backend

The constructed reference backend; it stays its caller’s unless a session owns it.

problemsolprop.translate.problem.PropagationProblem

The translated problem.

requestsolprop.translate.run_request.RunRequest

The run’s request.

Raises:
solprop.backends.session.SessionError

If the request is not one run of the backend’s own (foreign_request()).

solprop.exceptions.BackendError

If the request asks for statistics the problem does not carry (statistics_unavailable()).

property backend: str[source]#

Registered name of the backend that prepared it.

close()[source]#

Refuse further starts and close the backend it was prepared on; idempotent.

A caller that keeps the backend for later runs leaves the preparation open: a session it started with owns=False never closes the backend.

memory_ledger()[source]#

Return every retained buffer by name, bytes.

Returns:
collections.abc.Mapping

The backend’s ledger.

metadata()[source]#

Return the execution metadata recorded with the run.

Returns:
collections.abc.Mapping

The backend’s own (solprop.backends.protocol.Backend.metadata()).

start(start, *, listener=None, started=None, stop=None, owns=True)[source]#

Start a session from an initial state or a checkpoint.

Parameters:
startsolprop.backends.session.Start

Where the run starts; the session takes its field.

listenercallable or None, optional

Called with each attempt as it is made, for a progress reporter.

startedcallable or None, optional

Called with the start, the end and the plane count when propagation begins.

stopsolprop.log.StopFlag or None, optional

The run’s stop token.

ownsbool, optional

Whether closing the session closes the backend.

Returns:
solprop.backends.session.RunSession

The started HostSession.

Raises:
solprop.backends.session.SessionError

If this preparation is closed.

class solprop.backends.host.session.HostSession(backend, problem, request, start, *, listener=None, started=None, stop=None, owns=True)[source]#

Bases: object

The reference’s RunSession.

Parameters:
backendsolprop.backends.protocol.Backend

The reference backend (a HostBackend), constructed for problem. A backend reused from an earlier run is loaded again from start; the session builds its own march (HostBackend.method()), and closes the backend with itself when owns is set.

problemsolprop.translate.problem.PropagationProblem

The translated problem.

requestsolprop.translate.run_request.RunRequest

The run’s policies.

startsolprop.backends.session.Start

Where the run starts. The session loads it – the field, the noise, the call ledgers and any method history – and takes its field.

listenercallable or None, optional

Called with each attempt as it is made, for a progress reporter. It observes only; it cannot change the run.

startedcallable or None, optional

Called with the start, the end and the plane count when propagation begins.

stopsolprop.log.StopFlag or None, optional

The run’s stop token, polled before every trial.

ownsbool, optional

Whether closing the session closes the backend. A caller that reuses its backend for later runs (a runner, a scan) keeps it open.

Attributes:
reads_transverse_edgebool

The backend’s (SEP 40 section 5.3), which the service loop reads.

Raises:
solprop.exceptions.BackendError

If backend is not a reference backend, is closed, or start does not fit the problem: its field’s shape, or its position off the operator table or off a replayed schedule’s edges.

absorb(record)[source]#

Accumulate an accepted step’s split collar’s sums (SEP 52 section 5.2).

The removal adds over every accepted step since the previous check, which the next reading drains; the found occupancies are the latest accepted step’s. A step that took no split sums leaves both as they were.

Parameters:
recordsolprop.backends.engines.AcceptRecord

What the step’s finish reported.

acknowledge(receipt)[source]#

Release the pending batch and allow advancing across its barrier.

Parameters:
receiptsolprop.backends.events.Receipt

The pending batch’s receipt.

advance(*, work_limit=256, deadline=0.1)[source]#

Run to the next barrier and report it.

A batch ends at the next observation, snapshot, warning or terminal outcome, or at a bounded yield: once work_limit attempts are made or deadline has passed, the march returns at its next accepted endpoint, exactly as at a natural stop, and the batch reports only progress. Nothing numerical depends on where a yield falls.

Parameters:
work_limitint, optional

Attempts before a yield.

deadlinefloat, optional

Host seconds before a yield, s.

Returns:
solprop.backends.events.EventBatch

The events, ending at a barrier.

cap(proposal, z)[source]#

Return a proposal held to the quiet collar’s, the edge’s and split’s limits.

Parameters:
proposalfloat

The controller’s proposal, m.

zfloat

Where the step starts, m.

Returns:
float

The capped proposal, m.

close()[source]#

Release the backend when the session owns it; idempotent.

property closed: bool[source]#

Whether the session was closed.

property collar_quiet: bool[source]#

Whether the stages leave a quiet in-stage temporal collar out (SEP 21).

continue_monitor(continuation)[source]#

Continue a resumed run’s boundary-monitor record, before it is attached.

The record is read from the run’s output, which the service loop opens only once the session has loaded its start, so that the opened record states the loaded backend’s execution facts; it reaches the session before its first advance past the launch plane. A continuation given in the Start is kept.

Parameters:
continuationcollections.abc.Mapping

As solprop.backends.session.Start.monitor.

Raises:
solprop.backends.session.SessionError

If the monitor is already watching.

execution_record()[source]#

Return the session’s execution facts.

Returns:
collections.abc.Mapping

The backend’s metadata, with this run’s call or evaluation counts, and the boundary monitor’s record once it watches.

export(ticket, recipe, out=None)[source]#

Fill a destination with a pending observation’s converted field.

Parameters:
ticketsolprop.backends.events.ExportTicket

The pending observation’s ticket.

recipesolprop.backends.export.ExportRecipe

The conversion.

outnumpy.ndarray or None, optional

The destination; a new array by default.

Returns:
numpy.ndarray

The converted field.

property finished: bool[source]#

Whether the session yielded its terminal event.

property in_flight: tuple[float, float] | None[source]#

Low-storage step a failure abandoned in flight, or None.

Its start and length, m, while the state is neither of its ends.

march_export_refusal()[source]#

Return None: every march the reference admits carries its history.

Returns:
None

The Adams history exports its rows; the other marches keep none.

property march_refusal: str | None[source]#

Why the start’s method history could not be installed.

The reason, or None when it was installed or the start carried none.

march_snapshot(ticket)[source]#

Return the method history at a pending observation, when the march has one.

The march’s part of the snapshot, the committed state and the history’s rows, at an accepted endpoint: None while a dense observation holds the state between endpoints, for a march that keeps no history, and before the first sample.

Parameters:
ticketsolprop.backends.events.ExportTicket

The pending observation’s ticket.

Returns:
solprop.output.records.MarchSnapshot or None

The history at the ticket’s position, or None.

Raises:
solprop.exceptions.BackendError

If a low-storage step was abandoned in flight.

march_snapshot_nbytes()[source]#

Return the size a method-history snapshot would have, copying nothing.

Returns:
int or None

The state and every row, bytes, or None where a snapshot would be None.

Raises:
solprop.exceptions.BackendError

If a low-storage step was abandoned in flight.

monitor_record()[source]#

Return the boundary monitor’s record.

Returns:
collections.abc.Mapping or None

Its summary, or None without a monitor.

natural_stop(target)[source]#

Return whether the march stops at the endpoint just accounted.

Parameters:
targetfloat

The position the march is stepping to, m.

Returns:
bool

Whether a step plane, a halt or a warning barrier stops it there.

noise_phase(ticket)[source]#

Return the noise phase at a pending observation.

Parameters:
ticketsolprop.backends.events.ExportTicket

The pending observation’s ticket.

Returns:
numpy.ndarray or None

The phase, shape (n_modes, n_pol, n_omega), or None without noise.

pending_ticket()[source]#

Return a ticket for the committed state after a failure outside the session.

A service failure, or a signal raised while the session held no uncommitted state, leaves the field where the last commit put it. When a batch is pending, the ticket is bound to it; otherwise a failed terminal batch is issued, so the state can be exported for a terminal checkpoint and nothing advances again.

Returns:
solprop.backends.events.ExportTicket or None

The ticket, or None when the session is closed or its state poisoned.

poll_stop()[source]#

Raise when the run’s stop flag is set; called before every trial.

record(end, dz, norm, accepted)[source]#

Append one attempt to the history since the last event.

A diverged attempt’s norm (overflowed or NaN) is recorded as infinity, which the controller never accepts. An accepted attempt’s quadrature score is read then, and one above QUADRATURE_ALARM reported once a plane: a statistic and a log line, never a controller input.

Parameters:
endfloat

The attempt’s end, m.

dzfloat

Its length, m.

normfloat

The scaled error norm as executed.

acceptedbool

Whether it was accepted.

request_snapshot()[source]#

Latch a snapshot for the next eligible accepted endpoint.

Returns:
solprop.backends.session.SnapshotReceipt

The request’s receipt; a request while one is outstanding joins it.

status()[source]#

Return a read-only summary of the session.

Returns:
solprop.backends.session.SessionStatus

Position, plane, attempts and lifecycle state.

stepped()[source]#

Account the step just committed: the monitor, the edge, the row and stop.

A warning on the way suspends the rest of the point’s work, which the next advance does once the warning’s barrier is acknowledged.

undelivered(ticket)[source]#

Deliver the attempts and rows made since the previous event, once.

For a terminal checkpoint written after a failure outside the session (a service failure, or a signal out of a propagation), whose attempts no event delivered. The caller joins them to the chunks it holds since the last saved plane (solprop.backends.events.join_attempts()).

Parameters:
ticketsolprop.backends.events.ExportTicket

The pending ticket the checkpoint is written for.

Returns:
tuple

The attempts and the rows (without a batch axis); empty when every attempt was delivered.

solprop.backends.host.session.INITIAL_STEP_STATS_CAPACITY = 64#

Rows a plane’s statistics buffer holds before it first has to grow.

solprop.backends.host.session.natural_stop(every, count, z, target)[source]#

Return whether the count-th accepted step since the load is a step plane.

With step_planes = k the end of every k-th accepted step is a plane (SEP 14 phase 3): the march returns there, short of its target. A step that lands on the target is saved as the target; one that crosses a densely observed target is saved after it. The session’s rule (HostSession.natural_stop()), which a decision-trace harness drives the real march with.

Parameters:
everyint

The step planes’ period k; zero for none.

countint

Accepted steps since the load, this one included.

zfloat

Its end, m.

targetfloat

The position the march is stepping to, m.

Returns:
bool or None

None when the step is no k-th; otherwise whether the march stops at its end – False at the target, whose plane observes it.

solprop.backends.host.session.start_position(problem, stepper, z)[source]#

Return where a state may be loaded, and a replay’s cursor there.

Parameters:
problemsolprop.translate.problem.PropagationProblem

The problem, whose operator table bounds the position.

steppersolprop.translate.problem.StepperSettings

The run’s stepper settings, whose schedule a replay follows.

zfloat

The requested position, m.

Returns:
tuple

The position, m, and how many steps of a replayed schedule it has consumed (zero for an adaptive run).

Raises:
BackendError

If z lies outside the operator table, or a schedule is replayed and z is not one of its edges: every save plane is one (validate checks it), so this fires only for a position the run never stopped at.

solprop.backends.host.session.step_cap(monitor, quiet, proposal, z)[source]#

Return a proposal held to the boundary monitor’s limits on a step.

The session’s rule (HostSession.cap()), which a decision-trace harness drives the real march with.

Parameters:
monitorsolprop.monitor.BoundaryMonitor or None

The attached monitor, or None before one watches (no cap); a harness’s stand-in needs only its interval, step_cap and transverse.

quietbool

Whether the stages leave a quiet in-stage temporal collar out.

proposalfloat

The controller’s proposal, m.

zfloat

Where the step starts, m.

Returns:
float

The proposal, or the quiet collar’s interval, the transverse edge’s read spacing or the split collar’s crossing limit when shorter, m.