solprop.backends.host.session#

The NumPy reference’s run session (SEP 47 sections 5 and 6.6).

HostSession is the RunSession that serves every numpy_ref run, in both precisions: the launch-before-monitor order, the plane schedule, the snapshot latch, bounded yields, chunked attempts, exports and the terminal outcome with its checkpoint eligibility, over the reference’s own driver (solprop.backends.host.driver.HostDriver), through its halt and yield hooks (request_halt, clear_halt, halt_ahead, set_halt_check) and its read-only march state (halted, holding_plane, position, drain_attempts). HostPrepared is the prepared execution (SEP 47 section 5.2) a reference backend returns from prepare; each of its starts opens one.

The session composes the parts every Python session shares (solprop.backends.session_core: the attempt counter, the yield check, the snapshot latch, the shared observation and its exports, and the preparation’s refusals) with the lifecycle ledger (SessionLedger). It imports nothing of the inherited driver the native backend still subclasses (solprop.backends.driver).

Classes

`HostPrepared`(driver, problem, request)	A prepared run of a reference backend (SEP 47 section 5.2).
`HostSession`(driver, problem, request, start, *)	The reference's `RunSession`.

class solprop.backends.host.session.HostPrepared(driver, 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:

driversolprop.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]#

Return the registered name of the backend that prepared it.

Returns:

str: The backend’s registered name.

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(driver, problem, request, start, *, listener=None, started=None, stop=None, owns=True)[source]#

Bases: object

The reference’s RunSession.

Parameters:

driversolprop.backends.protocol.Backend: The reference backend (a HostDriver), constructed for problem. A driver reused from an earlier run is loaded again from start, which restores everything its march reads. The session closes it 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 into the driver – 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 driver. A caller that reuses its driver for later runs (a runner, a scan) keeps it open.

Raises:

solprop.exceptions.BackendError: If driver is not a reference driver.

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 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.

close()[source]#

Release the driver; idempotent.

property closed: bool[source]#

Return whether the session was closed.

Returns:

bool: True once closed.

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.

property driver: Backend[source]#

Return the reference backend, whose facts the service loop records.

Returns:

solprop.backends.protocol.Backend: The backend.

execution_record()[source]#

Return the session’s execution facts.

Returns:

collections.abc.Mapping: The driver’s metadata.

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]#

Return whether the session yielded its terminal event.

Returns:

bool: True once finished.

march_export_refusal()[source]#

Return why the march cannot export its history, or None.

Returns:

str or None: The reason, or None when it can.

property march_refusal: str | None[source]#

Return why the start’s method history could not be installed.

Returns:

str or None: 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.

Parameters:

ticketsolprop.backends.events.ExportTicket: The pending observation’s ticket.

Returns:

solprop.output.schema.MarchSnapshot or None: The history at the ticket’s position, or None.

march_snapshot_nbytes()[source]#

Return the size a method-history snapshot would have.

Returns:

int or None: Bytes, or None when the march keeps no history.

monitor_record()[source]#

Return the boundary monitor’s record.

Returns:

collections.abc.Mapping or None: Its summary, or None without a monitor.

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 driver 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.

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.

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.