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
Rows a plane's statistics buffer holds before it first has to grow. |
Functions
|
Return whether the count-th accepted step since the load is a step plane. |
|
Return where a state may be loaded, and a replay's cursor there. |
|
Return a proposal held to the boundary monitor's limits on a step. |
Classes
|
A march's dense output: what a session interpolates a crossed plane from. |
|
An Adams history's rows where the state lives, which a snapshot carries. |
|
What the reference's session reads of its backend. |
|
The march one session runs, built for it by the backend (native's |
|
A prepared run of a reference backend (SEP 47 section 5.2). |
|
The reference's |
- class solprop.backends.host.session.Dense(*args, **kwargs)[source]#
Bases:
ProtocolA march’s dense output: what a session interpolates a crossed plane from.
Native’s
session::Dense; the reference’s aresolprop.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.
- class solprop.backends.host.session.HistoryRows(*args, **kwargs)[source]#
Bases:
ProtocolAn Adams history’s rows where the state lives, which a snapshot carries.
- class solprop.backends.host.session.HostBackend(*args, **kwargs)[source]#
Bases:
ProtocolWhat 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).
- 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.
- 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:
objectThe march one session runs, built for it by the backend (native’s
Method).- Attributes:
- marchobject
The march: a
RungeKuttaMarch,HostAdamsMarchorHostLowStorageMarch, its session the march’s host.- denseDense or None
Its dense output when the run interpolates its planes;
Noneotherwise.- rowsHistoryRows or None
The Adams history’s rows a snapshot carries;
Nonefor the other marches.
- march: RungeKuttaMarch | HostAdamsMarch | HostLowStorageMarch#
- rows: HistoryRows | None = None#
- class solprop.backends.host.session.HostPrepared(backend, problem, request)[source]#
Bases:
objectA 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()). Eachstart()opens oneHostSessionover 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()).
- 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=Falsenever 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:
objectThe 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.
- 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
Startis kept.- Parameters:
- continuationcollections.abc.Mapping
- 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 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
Nonewhen 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:
Nonewhile 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
Nonewhere a snapshot would beNone.
- 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
Nonewithout 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), orNonewithout 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
Nonewhen the session is closed or its state poisoned.
- 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_ALARMreported 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 = kthe end of everyk-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
Nonewhen the step is nok-th; otherwise whether the march stops at its end –Falseat 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 (
validatechecks 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
Nonebefore one watches (no cap); a harness’s stand-in needs only itsinterval,step_capandtransverse.- 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.