solprop.backends.session#
The execution-session contract between solprop and a backend (SEP 47 section 5).
Python constructs and validates the scientific problem
(solprop.translate.problem.PropagationProblem) and resolves every run policy
into an immutable solprop.translate.run_request.RunRequest. A backend prepares
them once (SessionBackend.prepare()), and the prepared execution starts one
RunSession per trajectory. The session is the only owner of that trajectory’s
mutable numerical state: the field, the method’s history, the controller and monitor,
the counters and cursors, and the pending events. Python’s service loop
(solprop.driver.service) advances it, services the events it yields – files,
callbacks, warnings, progress – and acknowledges them:
prepared = backend.prepare(problem, request, options)
with prepared.start(start) as session:
while not session.finished:
batch = session.advance(work_limit=256, deadline=0.1)
service(batch)
session.acknowledge(batch.receipt)
Yields are exact transport no-ops (SEP 47 section 5.1): the attempt bound, the deadline, the event capacity and the timing of acknowledgments change when control returns, never the numerical state or the control trace.
Event storage is bounded (SEP 47 section 5.3): every event delivers, exactly once,
the attempts and periodic rows made since the previous event – a yield’s
Progress as much as an observation, a snapshot or
the terminal event – and a row’s step indexes its own chunk’s attempts. A session
therefore buffers no more than one advance’s attempts, and the service loop, not the
session, assembles a plane’s or a checkpoint’s history from the chunks
(solprop.backends.events.join_attempts()). The status counts every attempt once,
as it is drained.
Control requests travel separately from the immutable request: a thread-safe
StopToken asks for a stop at the next safe boundary, and
RunSession.request_snapshot() latches a snapshot for the next eligible accepted
endpoint (SEP 47 section 5.5).
A GroupSession advances compatible trajectories through one common fixed
schedule, a window at a time, and reports each member’s own events and outcome (SEP 47
section 6.7).
SessionLedger is the lifecycle bookkeeping every Python session shares:
receipts, the pending barrier, closing and poisoning. It holds no numerical state.
Module Attributes
Attempts one |
|
Host seconds after which |
Classes
|
Execution choices that are not part of the numerical problem. |
|
Compatible trajectories advanced together through one common fixed schedule. |
|
A backend's lowering of one problem and request, reusable across sessions. |
|
One trajectory's numerical execution, owned by its backend. |
|
A backend that prepares executions (SEP 47 section 6.1). |
The lifecycle bookkeeping of a Python session; no numerical state. |
|
|
Where a session is in its lifecycle. |
|
A compact, read-only view of a session, for reporting. |
|
Identifies a snapshot request until it is fulfilled or refused. |
|
Where a session starts: an initial state, or a checkpoint being resumed. |
A thread-safe request to stop a run at its next safe boundary. |
Exceptions
|
A session was used outside its lifecycle. |
- solprop.backends.session.DEFAULT_DEADLINE = 0.1#
Host seconds after which
advanceyields at its next safe boundary, s.
- solprop.backends.session.DEFAULT_WORK_LIMIT = 256#
Attempts one
advancemakes at most before yielding, as the native marches do.Python signal handlers run only between native calls, so a bounded return keeps a long run interruptible (SEP 47 section 5.5).
- class solprop.backends.session.ExecutionOptions(node_budget=None, backend_options=<factory>)[source]#
Bases:
objectExecution choices that are not part of the numerical problem.
Two runs may share their scientific description while differing in these (SEP 47 section 4.3). They are recorded as execution metadata, never compared by a restart.
- Attributes:
- node_budgetint or None
An explicit workspace budget for node chunks, bytes;
Noneleaves the backend’s automatic choice. An explicit budget is authoritative.- backend_optionscollections.abc.Mapping
Backend-specific execution options, passed through untouched (for example a native CPU execution record).
- class solprop.backends.session.GroupSession(*args, **kwargs)[source]#
Bases:
ProtocolCompatible trajectories advanced together through one common fixed schedule.
A group request is a sequence of independently translated member problems that pass the compatibility predicate a batched scan groups its points by; the common schedule’s maximum error norm is a diagnostic only (SEP 47 section 6.7). Each
advance()runs every member still running through the next common schedule window – to the next save plane – and reports each member’s own events (GroupBatch):with group: while not group.finished: batch = group.advance() service(batch) # each member's planes and outcome group.acknowledge(batch.receipt)
Failure. A boundary error, or a boundary warning raised as an error, ends that member alone with a
Terminal, and the others go on. A non-finite error norm, a step floor, a trial exception or an in-flight failure ends the group: every member still running ends with the same error. Members are stepped in turn, so earlier members may already have advanced the failed scheduled step: each terminal reports that member’s actual committed position and checkpoint eligibility, and no common cursor or rollback is invented. A group-wide stop request ends every running member at a common accepted endpoint.- acknowledge(receipt)[source]#
Release a window’s batch and allow advancing past it.
- Parameters:
- receiptsolprop.backends.events.Receipt
The batch’s receipt.
- execution_record(member)[source]#
Return one member’s execution facts.
- Parameters:
- memberint
The member’s index, from zero.
- Returns:
- collections.abc.Mapping
The member’s execution record.
- 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 index, from zero.
- ticketsolprop.backends.events.ExportTicket
The member’s pending ticket.
- recipesolprop.backends.export.ExportRecipe
The conversion.
- outnumpy.ndarray or None, optional
The destination; a new array by default.
- Returns:
- numpy.ndarray
The filled destination.
- member_status(member)[source]#
Return one member’s committed position, counters and outcome.
- Parameters:
- memberint
The member’s index, from zero.
- Returns:
- SessionStatus
The member’s status.
- class solprop.backends.session.PreparedExecution(*args, **kwargs)[source]#
Bases:
ProtocolA backend’s lowering of one problem and request, reusable across sessions.
- class solprop.backends.session.RunSession(*args, **kwargs)[source]#
Bases:
ProtocolOne trajectory’s numerical execution, owned by its backend.
See
solprop.backends.sessionfor the loop that drives it.- acknowledge(receipt)[source]#
Release a 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 until a barrier, the attempt bound or the deadline, and report it.
- Parameters:
- work_limitint, optional
Attempts before a yield.
- deadlinefloat, optional
Host seconds before a yield, s.
- 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.
- march_snapshot(ticket)[source]#
Return the method history at a pending observation, when retained.
- Parameters:
- ticketsolprop.backends.events.ExportTicket
The pending observation’s ticket.
- march_snapshot_nbytes()[source]#
Return the size a method-history snapshot would have, without making it.
- class solprop.backends.session.SessionBackend(*args, **kwargs)[source]#
Bases:
ProtocolA backend that prepares executions (SEP 47 section 6.1).
- prepare(problem, request, options)[source]#
Lower a problem and request; refuse an unsupported one before allocating.
- Parameters:
- problemsolprop.translate.problem.PropagationProblem
The translated problem.
- requestsolprop.translate.run_request.RunRequest
What the run asks of the backend.
- optionsExecutionOptions
The execution options.
- exception solprop.backends.session.SessionError(*args, parameter=None, rule=None)[source]#
Bases:
BackendErrorA session was used outside its lifecycle.
Raised for a stale or foreign receipt, an advance across an unacknowledged barrier, use after close or after a terminal outcome, or an export with an expired ticket.
- class solprop.backends.session.SessionLedger[source]#
Bases:
objectThe lifecycle bookkeeping of a Python session; no numerical state.
It issues receipts, records the pending barrier, refuses stale or foreign receipts and advancing across an unacknowledged barrier, and remembers whether the session finished, failed or closed.
Examples
>>> from solprop.backends.session import SessionLedger >>> ledger = SessionLedger() >>> receipt = ledger.issue() >>> ledger.ticket_valid(receipt) True >>> ledger.acknowledge(receipt) >>> ledger.ticket_valid(receipt) False
- acknowledge(receipt)[source]#
Accept the pending batch’s receipt.
- Parameters:
- receiptsolprop.backends.events.Receipt
The receipt to acknowledge.
- Raises:
- SessionError
If the receipt is not the pending one: foreign, stale or repeated.
- check_advance()[source]#
Refuse to advance a session that is pending, finished or closed.
- Raises:
- SessionError
Naming the state that forbids it.
- check_ticket(ticket)[source]#
Refuse an export with an expired or foreign ticket.
- Parameters:
- ticketsolprop.backends.events.ExportTicket
The ticket presented.
- Raises:
- SessionError
If its batch is no longer pending.
- close()[source]#
Mark the session closed.
- Returns:
- bool
True the first time, False when it was already closed.
- property finished: bool[source]#
Return whether a terminal batch was issued.
- Returns:
- bool
True once the session yielded its terminal event.
- issue(*, outcome=None)[source]#
Issue the receipt of a new pending batch.
- Parameters:
- outcomesolprop.backends.events.Outcome or None, optional
The batch’s terminal outcome, when it ends the session.
- Returns:
- solprop.backends.events.Receipt
The batch’s receipt.
- class solprop.backends.session.SessionState(*values)[source]#
Bases:
EnumWhere a session is in its lifecycle.
- Attributes:
- READYstr
It can advance.
- PENDINGstr
A batch is out; it advances again once that batch is acknowledged.
- FINISHEDstr
It yielded a terminal event; nothing more can happen but close.
- CLOSEDstr
Its resources are released.
- CLOSED = 'closed'#
- FINISHED = 'finished'#
- PENDING = 'pending'#
- READY = 'ready'#
- class solprop.backends.session.SessionStatus(z, plane_index, attempts, rejected, state, outcome=None)[source]#
Bases:
objectA compact, read-only view of a session, for reporting.
- Attributes:
- zfloat
The committed position, m.
- plane_indexint
The next save plane to observe.
- attemptsint
Attempts made, accepted and rejected.
- rejectedint
Rejected attempts among them.
- stateSessionState
Lifecycle state.
- outcomesolprop.backends.events.Outcome or None
The terminal outcome, once finished.
- state: SessionState#
- class solprop.backends.session.SnapshotReceipt(request, coalesced)[source]#
Bases:
objectIdentifies a snapshot request until it is fulfilled or refused.
- Attributes:
- requestint
Sequence number of the request in its session, from 1.
- coalescedbool
Whether it joined an equivalent request still outstanding, so that one snapshot fulfils both (SEP 47 section 5.5 makes coalescing explicit).
- class solprop.backends.session.Start(field, z, noise=None, plane_index=0, march=None, ledgers=None, monitor=None, plane_pending=True, resume=False)[source]#
Bases:
objectWhere a session starts: an initial state, or a checkpoint being resumed.
A start is handed to one session, which takes its field (
take_field()): the session loads a copy made once at start, and the start forgets the array, so an input that nothing else holds – a runner’s caller’s array – is released before the first step rather than held through the run by every frame that passed the start along (SEP 47 section 5.4).- Attributes:
- fieldnumpy.ndarray or None
The state in internal amplitude units and the FFT convention, complex, shape
(n_modes, n_pol, n_omega);Noneonce a session took it. Mutating the caller’s array after the start changes nothing.- zfloat
Its position, m.
- noisesolprop.noise.NoiseRealisation or None
The run’s noise realisation, when a noise model is active.
- plane_indexint
The first save plane strictly beyond z.
- marchsolprop.output.schema.MarchSnapshot or None
A method history to restore, when resuming one that was retained.
- ledgerscollections.abc.Mapping or None
Persisted call ledgers to restore (TDSE and budgeted sources).
- monitorcollections.abc.Mapping or None
When resuming a monitored run, the monitor’s continuation:
"record", its persisted record;"plane", whether the resumed position is a saved plane;"unwatched", the spans the earlier executions left unwatched.- plane_pendingbool
Whether the plane at z is owed (the launch plane of a fresh run, or a resumed position whose plane was not saved).
- resumebool
Whether field was loaded from a plane the run already saved, so that an
inputnoise realisation is not added a second time.
- classmethod entrance(problem, *, noise=None)[source]#
Return the fresh start of a problem: its launch state, its launch plane owed.
- Parameters:
- problemsolprop.translate.problem.PropagationProblem
The translated problem.
- noisesolprop.noise.NoiseRealisation or None, optional
A realisation to carry instead of the one the problem was assembled with.
- Returns:
- Start
The start at
problem.initial.z, before the first save plane.
- march: MarchSnapshot | None = None#
- noise: NoiseRealisation | None = None#
- class solprop.backends.session.StopToken[source]#
Bases:
objectA thread-safe request to stop a run at its next safe boundary.
Setting it from any thread – a GUI’s stop button, a signal handler on the main thread, a scan’s supervisor – asks every session attached to it to finish the attempt in hand, complete that endpoint’s mandatory accounting, and end with
STOPPED(SEP 47 section 5.5). It implementssolprop.log.StopFlag.Examples
>>> from solprop.backends.session import StopToken >>> token = StopToken() >>> token.is_set() False >>> token.set() >>> token.is_set() True
- attach(listener)[source]#
Call listener whenever the token is set, and now if it already is.
Native sessions attach the store of their own atomic flag, so that a stop set from another thread reaches a march that holds no Python lock.
- Parameters:
- listenercallable
Called with no arguments. It must not raise and must not block.
- Returns:
- callable
Detaches the listener.