solprop.backends.driver_session#

A transitional execution session over the inherited driver interface (SEP 47).

Until the native session (SEP 47 phase 3) owns its run, the native backend still subclasses solprop.backends.driver.StepDriver. DriverSession presents any such driver through the session protocol of solprop.backends.session, so the Python service loop (solprop.driver.service) has one contract to serve. It absorbs the plane schedule the old run loop kept – the launch plane, each save plane, natural stops and step planes – the launch-before-monitor order, the snapshot latch and the terminal outcome with its checkpoint eligibility.

DriverGroupSession does the same for a group (SEP 47 section 6.7): it presents the lockstep runners a batched scan steps compatible members with through the group protocol, GroupSession.

Both are temporary internal adapters, named in SEP 47’s Part II with their removal milestone; nothing outside the session machinery constructs them directly.

Module Attributes

AttemptListener

Called with each attempt's end, length and acceptance, for a progress reporter.

Classes

DriverGroupSession(members, problems, ...[, ...])

A GroupSession over the lockstep runners.

DriverSession(driver, problem, request, start, *)

A RunSession over an inherited driver.

solprop.backends.driver_session.AttemptListener#

Called with each attempt’s end, length and acceptance, for a progress reporter.

alias of Callable[[float, float, bool], None]

class solprop.backends.driver_session.DriverGroupSession(members, problems, requests, starts, *, stop=None)[source]#

Bases: object

A GroupSession over the lockstep runners.

It loads each member from its start, then hands the loaded members to the backend’s lockstep runner (solprop.backends.registry.select_batch(): the reference’s HostGroup, the native bridge’s LockstepRunner), and presents the runner’s common fixed-schedule march through the group protocol: one window per save plane, each member’s own events, tickets and outcome, and the failure distinction of SEP 47 section 6.7. It is a temporary internal adapter, like DriverSession.

As the batched scan always has, the first advance gives every member its boundary monitor before the launch plane is reported, so that a launch a monitor refuses ends that member at once.

Parameters:
memberscollections.abc.Sequence of solprop.backends.protocol.Backend

One constructed backend per member, all of one backend. Once the group is constructed it owns them and closes them with itself; a construction that fails leaves them to the caller.

problemscollections.abc.Sequence of solprop.translate.problem.PropagationProblem

Each member’s independently translated problem.

requestscollections.abc.Sequence of solprop.translate.run_request.RunRequest

Each member’s run request, with its own fresh boundary monitor; their save planes and statistics are the group’s common schedule.

startscollections.abc.Sequence of solprop.backends.session.Start

Each member’s start: its entrance, with no method history or monitor to continue. The group takes each start’s field.

stopsolprop.log.StopFlag or None, optional

A group-wide stop token, polled before every common step.

Raises:
solprop.backends.session.SessionError

If the sequences differ in length or are empty, or if a start is not a fresh entrance.

solprop.exceptions.BackendError

If the runner refuses the members (select_batch): another backend, or another schedule, planes or periodic statistics.

acknowledge(receipt)[source]#

Release the pending batch and allow advancing past it.

Parameters:
receiptsolprop.backends.events.Receipt

The pending batch’s receipt.

advance()[source]#

Run every running member through the next common window, and report it.

Returns:
solprop.backends.events.GroupBatch

Each member’s events in the window.

close()[source]#

Release every member and the runner; idempotent.

property closed: bool[source]#

Return whether the group was closed.

Returns:
bool

True once closed.

execution_record(member)[source]#

Return one member’s execution facts, with the group’s strategy.

Parameters:
memberint

The member’s position.

Returns:
collections.abc.Mapping

Its backend provenance.

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

Fill a destination with one member’s converted field at a pending ticket.

Parameters:
memberint

The member’s position.

ticketsolprop.backends.events.ExportTicket

A ticket of the pending batch, for this member: its position is the member’s own.

recipesolprop.backends.export.ExportRecipe

The conversion.

outnumpy.ndarray or None, optional

The destination; a new array by default.

Returns:
numpy.ndarray

The member’s converted field.

property finished: bool[source]#

Return whether the group’s terminal batch was issued.

Returns:
bool

True once every member has ended.

member_status(member)[source]#

Return one member’s committed position, counters and outcome.

Parameters:
memberint

The member’s position.

Returns:
solprop.backends.session.SessionStatus

Its status; a member that ended reports its own outcome while the group goes on.

monitor_record(member)[source]#

Return one member’s boundary-monitor record.

Parameters:
memberint

The member’s position.

Returns:
collections.abc.Mapping or None

Its record as it closed or as it stands, or None when unwatched.

property n_members: int[source]#

Return the number of members.

Returns:
int

The members.

noise_phase(member, ticket)[source]#

Return one member’s noise phase at a pending ticket.

Parameters:
memberint

The member’s position.

ticketsolprop.backends.events.ExportTicket

A ticket of the pending batch.

Returns:
numpy.ndarray or None

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

class solprop.backends.driver_session.DriverSession(driver, problem, request, start, *, listener=None, started=None, stop=None, owns=True)[source]#

Bases: object

A RunSession over an inherited driver.

Parameters:
driversolprop.backends.protocol.Backend

The driver, 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 (or native call).

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.

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 (a native march after its next call and one step), 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 wrapped driver, for the transitional service paths.

Returns:
solprop.backends.protocol.Backend

The driver.

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.

property monitor: BoundaryMonitor | None[source]#

Return the session’s own boundary monitor, for transitional reporting.

Returns:
solprop.monitor.BoundaryMonitor or None

The monitor, or None.

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.