Source code for solprop.backends.driver_session

# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later

"""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 :class:`solprop.backends.driver.StepDriver`. :class:`DriverSession` presents
any such driver through the session protocol of :mod:`solprop.backends.session`, so the
Python service loop (:mod:`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.

:class:`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, :class:`~solprop.backends.session.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.
"""

from __future__ import annotations

import dataclasses
import time
from collections.abc import Callable, Mapping, Sequence
from types import TracebackType
from typing import TYPE_CHECKING, cast

import numpy as np

from solprop.backends.events import (
    Eligibility,
    Event,
    EventBatch,
    ExportTicket,
    GroupBatch,
    ObservationKind,
    ObservationReady,
    Outcome,
    Progress,
    Receipt,
    ServiceKind,
    ServiceRequired,
    Terminal,
    join_attempts,
)
from solprop.backends.export import ExportRecipe, apply_recipe
from solprop.backends.protocol import (
    BackendHistory,
    Observation,
    StepStats,
    StepSummary,
)
from solprop.backends.session import (
    DEFAULT_DEADLINE,
    DEFAULT_WORK_LIMIT,
    SessionError,
    SessionLedger,
    SessionState,
    SessionStatus,
    SnapshotReceipt,
    Start,
)
from solprop.exceptions import StopRequested
from solprop.log import NullReporter, StopFlag
from solprop.monitor import BoundaryMonitor
from solprop.output.schema import MarchSnapshot
from solprop.translate.linop import power_weight_at
from solprop.translate.problem import PropagationProblem
from solprop.translate.run_request import RunRequest

if TYPE_CHECKING:
    # Under TYPE_CHECKING, so that the runtime type checks of the test suite do not
    # hold the scripted drivers to the full protocol or check a refused export
    # destination's shape before the session refuses it.
    from jaxtyping import Complex

    from solprop.backends.driver import StepDriver
    from solprop.backends.protocol import Backend

__all__ = ["AttemptListener", "DriverGroupSession", "DriverSession"]

AttemptListener = Callable[[float, float, bool], None]
"""Called with each attempt's end, length and acceptance, for a progress reporter."""


class _Attempts(NullReporter):
    """Forwards a driver's per-attempt progress and its start, and nothing else.

    The service loop reports planes itself; :class:`~solprop.log.NullReporter` drops
    the rest.

    Parameters
    ----------
    listener : callable
        Called with each attempt.
    started : callable or None, optional
        Called once, when the driver first propagates; ``None`` drops it.
    """

    def __init__(
        self,
        listener: AttemptListener,
        started: Callable[[float, float, int], None] | None = None,
    ) -> None:
        """Hold the listeners."""
        self._listener = listener
        self._started = started

    def started(self, z_start: float, z_end: float, n_planes: int) -> None:
        """Forward the driver's start, made when it first propagates.

        Parameters
        ----------
        z_start : float
            Where propagation starts, m.
        z_end : float
            Where it ends, m.
        n_planes : int
            The number of save planes.
        """
        if self._started is not None:
            self._started(z_start, z_end, n_planes)

    def step(self, z: float, dz: float, accepted: bool) -> None:
        """Forward one attempt.

        Parameters
        ----------
        z : float
            Where the attempt ended, m.
        dz : float
            Its length, m.
        accepted : bool
            Whether it was accepted.
        """
        self._listener(z, dz, accepted)


def _hook(driver: object, name: str, *arguments: object) -> None:
    """Call a driver's halt hook when it has one.

    The halt latch and the yield check belong to the inherited
    :class:`~solprop.backends.driver.StepDriver`; a driver written to the bare
    protocol (a test double) has neither, and then runs whole planes.

    Parameters
    ----------
    driver : object
        The driver.
    name : str
        The hook's name.
    *arguments : object
        Its arguments.
    """
    hook = getattr(driver, name, None)
    if hook is not None:
        hook(*arguments)


def _recorded(driver: Backend, z: float) -> Observation:
    """Return the attempts a driver recorded since its last observation, field-free.

    For a driver whose state was left in flight, which refuses
    :meth:`~solprop.backends.protocol.Backend.observe`. The record is the step driver's
    own history and periodic rows (:class:`solprop.backends.driver.StepDriver`),
    drained as an observation drains them.

    Parameters
    ----------
    driver : solprop.backends.protocol.Backend
        The driver.
    z : float
        The last committed position, m.

    Returns
    -------
    solprop.backends.protocol.Observation
        The attempts and rows, with no field.
    """
    stepping = cast("StepDriver[object]", driver)
    entries, stepping._history = stepping._history, []  # pyright: ignore[reportPrivateUsage]
    history = BackendHistory(
        z=np.array([entry[0] for entry in entries], dtype=np.float64),
        dz=np.array([entry[1] for entry in entries], dtype=np.float64),
        error_norm=np.array([entry[2] for entry in entries], dtype=np.float64),
        accepted=np.array([entry[3] for entry in entries], dtype=np.bool_),
        wall_time=np.array([entry[4] for entry in entries], dtype=np.float64),
    )
    rows = stepping._drain_step_stats()  # pyright: ignore[reportPrivateUsage]
    return Observation(
        z=z,
        field=None,
        noise_phase=None,
        step_history=history,
        n_steps=history.n_steps,
        n_rejected=history.n_rejected,
        step_stats=rows,
    )


_EMPTY_SUMMARY = StepSummary(
    z=0.0,
    n_steps=0,
    n_rejected=0,
    max_norm=0.0,
    mean_norm=0.0,
    wall_time=0.0,
    met_tolerance=True,
)


class _YieldDue:
    """Says whether a bounded advance has reached its attempt bound or its deadline.

    A class rather than a closure in :meth:`DriverSession.advance`, so that no function
    object is made per call (each one costs the coverage lane's import hook a compile).

    Parameters
    ----------
    session : DriverSession
        The session whose attempts are counted.
    limit : int
        The attempt count at which the march halts.
    started : float
        The advance's start, in :func:`time.perf_counter` seconds.
    deadline : float
        The seconds after `started` at which the march halts.
    """

    def __init__(
        self, session: DriverSession, limit: int, started: float, deadline: float
    ) -> None:
        self._session = session
        self._limit = limit
        self._started = started
        self._deadline = deadline

    def __call__(self) -> bool:
        """Return whether the attempt bound or the deadline has been reached.

        Returns
        -------
        bool
            True once the march should halt at its next accepted endpoint.
        """
        return (
            self._session._listened >= self._limit
            or time.perf_counter() - self._started >= self._deadline
        )


[docs] class DriverSession: """A :class:`~solprop.backends.session.RunSession` over an inherited driver. Parameters ---------- driver : solprop.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. problem : solprop.translate.problem.PropagationProblem The translated problem. request : solprop.translate.run_request.RunRequest The run's policies. start : solprop.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. listener : callable or None, optional Called with each attempt as it is made, for a progress reporter. It observes only; it cannot change the run. started : callable or None, optional Called with the start, the end and the plane count when propagation begins. stop : solprop.log.StopFlag or None, optional The run's stop token, polled before every trial (or native call). owns : bool, optional Whether closing the session closes the driver. A caller that reuses its driver for later runs (a runner, a scan) keeps it open. """ def __init__( # noqa: PLR0913 - the session context self, driver: Backend, problem: PropagationProblem, request: RunRequest, start: Start, *, listener: AttemptListener | None = None, started: Callable[[float, float, int], None] | None = None, stop: StopFlag | None = None, owns: bool = True, ) -> None: """Load the starting state into the driver.""" self._driver = driver self._problem = problem self._request = request self._ledger = SessionLedger() self._planes = np.asarray(request.observation.save_planes, dtype=np.float64) self._owns = owns self._index = start.plane_index self._launch_pending = start.plane_pending # The session takes over the request's fresh monitor and feeds it. self._monitor: BoundaryMonitor | None = request.boundary.monitor self._monitor_resume = start.monitor self._attached = False self._generation = 0 self._z = float(start.z) self._attempts = 0 self._rejected = 0 self._stepped = False self._summary: StepSummary | None = None # Attempts a field fetch drained that no event has delivered yet. self._undelivered: list[tuple[BackendHistory, StepStats]] = [] self._snapshot_requests = 0 self._snapshot_pending: int | None = None self._observed: Observation | None = None self._observed_generation = -1 self._converted: ExportRecipe | None = None self._listened = 0 # Whether the observation's own array was handed out unconverted (export). self._lent = False def counted(z: float, dz: float, accepted: bool) -> None: """Count an attempt and pass it on to the listener. Parameters ---------- z : float The position the attempt started from, m. dz : float The attempted step, m. accepted : bool Whether the step was accepted. """ self._listened += 1 if listener is not None: listener(z, dz, accepted) driver.set_progress(_Attempts(counted, started)) driver.set_stop(stop) driver.set_initial( np.asarray(start.take_field()), start.noise, z=float(start.z), resume=start.resume, ) if start.ledgers is not None: logical = start.ledgers.get("logical", {}) atomic = start.ledgers.get("atomic", {}) driver.restore_call_ledgers(logical, atomic) # pyright: ignore[reportArgumentType] # After the field, which resets the method's history, as a resume always did. self._march_refusal = ( None if start.march is None else driver.restore_march(start.march) ) # -- protocol -------------------------------------------------------------------
[docs] @property def driver(self) -> Backend: """Return the wrapped driver, for the transitional service paths. Returns ------- solprop.backends.protocol.Backend The driver. """ return self._driver
[docs] @property def finished(self) -> bool: """Return whether the session yielded its terminal event. Returns ------- bool True once finished. """ return self._ledger.finished
[docs] @property def closed(self) -> bool: """Return whether the session was closed. Returns ------- bool True once closed. """ return self._ledger.state is SessionState.CLOSED
[docs] def status(self) -> SessionStatus: """Return a read-only summary of the session. Returns ------- solprop.backends.session.SessionStatus Position, plane, attempts and lifecycle state. """ return SessionStatus( z=self._z, plane_index=self._index, attempts=self._attempts, rejected=self._rejected, state=self._ledger.state, outcome=self._ledger.outcome, )
[docs] def advance( # noqa: PLR0911 - one return per barrier kind self, *, work_limit: int = DEFAULT_WORK_LIMIT, deadline: float = DEFAULT_DEADLINE, ) -> EventBatch: """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_limit : int, optional Attempts before a yield. deadline : float, optional Host seconds before a yield, s. Returns ------- solprop.backends.events.EventBatch The events, ending at a barrier. """ self._ledger.check_advance() if self._launch_pending: self._launch_pending = False return self._observation(ObservationKind.LAUNCH, -1, _EMPTY_SUMMARY) if not self._attached: self._attach_monitor() if self._snapshot_pending is not None and self._at_endpoint(): return self._snapshot() if self._index >= self._planes.size: return self._complete() target = float(self._planes[self._index]) started = time.perf_counter() limit = self._listened + max(int(work_limit), 1) due = _YieldDue(self, limit, started, deadline) _hook(self._driver, "set_halt_check", due) try: step = self._driver.propagate_to(target) except StopRequested as error: return self._terminal(Outcome.STOPPED, error) except Exception as error: return self._terminal(Outcome.FAILED, error) finally: _hook(self._driver, "set_halt_check", None) self._account(step) summary = self._summary_so_far(step) if self._snapshot_pending is None and not self._driver_halted(): # A yield latched between native calls that the target came first. _hook(self._driver, "clear_halt") reached_target = bool(np.isclose(step.z, target, rtol=1e-12, atol=0.0)) if reached_target: plane = self._index self._index += 1 self._summary = None return self._observation(ObservationKind.PLANE, plane, summary) if self._driver_halted(): # A halt short of the target is never a step plane: the driver counts a # step plane first and stops there unhalted, so a coincident plane is # observed below and the latch, still set, is serviced at the next advance # (SEP 47 section 5.3: a coincident plane's transaction precedes the # snapshot). if self._snapshot_pending is not None: return self._snapshot() # A bounded yield: no barrier, only progress; the plane goes on later. _hook(self._driver, "clear_halt") history, rows = self._chunk() return self._issue([Progress(self._z, history, rows)]) self._summary = None return self._observation( ObservationKind.STEP if self._request.observation.step_planes else ObservationKind.NATURAL, self._index, summary, )
[docs] def acknowledge(self, receipt: Receipt) -> None: """Release the pending batch and allow advancing across its barrier. Parameters ---------- receipt : solprop.backends.events.Receipt The pending batch's receipt. """ self._ledger.acknowledge(receipt) # One observation lives at a time: a consumer that kept it holds its own. self._observed = None self._converted = None self._lent = False
[docs] def export( self, ticket: ExportTicket, recipe: ExportRecipe, out: Complex[np.ndarray, "n_modes n_pol n_omega"] | None = None, ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: """Fill a destination with a pending observation's converted field. Parameters ---------- ticket : solprop.backends.events.ExportTicket The pending observation's ticket. recipe : solprop.backends.export.ExportRecipe The conversion. out : numpy.ndarray or None, optional The destination; a new array by default. Returns ------- numpy.ndarray The converted field. """ self._ledger.check_ticket(ticket) spatial = self._problem.transform.geometry is not None if recipe.power and spatial: # A spatial route's field measure is already the stored quantity. recipe = dataclasses.replace(recipe, power=False) weight = power_weight_at(self._problem, ticket.z) if recipe.power else None observed = self._fielded(ticket) converted = self._converted if converted is not None and (converted != recipe or out is not None): # Converted in place for another recipe, and handed out so: observe the raw # field again rather than write to an array a consumer holds. self._observed = None self._converted = None observed = self._fielded(ticket) state = self._field(ticket) if self._converted is not None: # Converted in place for this recipe already: the same detached result. return state identity = not recipe.optics and (weight is None or bool(np.all(weight == 1.0))) if identity and out is None and (observed.field_owned or spatial): # An observation's arrays are read-only and nothing writes to them again # (Backend.observe), so an export with nothing to convert is that array. # A modal field the backend may still hold is detached by a copy, as the # true-power conversion always detached it. Once lent, the array is never # converted in place. self._lent = True return state if out is None and observed.field_owned and not self._lent: # The driver made this array for this session alone, which hands out only # the export: convert it where it is (SEP 47 section 5.4). self._converted = recipe # The flag is the observation's own array's, which `state` is. whole = observed.require_field() whole.setflags(write=True) try: apply_recipe(whole, recipe, weight=weight, out=whole) finally: whole.setflags(write=False) return whole return apply_recipe(state, recipe, weight=weight, out=out)
[docs] def noise_phase(self, ticket: ExportTicket) -> np.ndarray | None: """Return the noise phase at a pending observation. Parameters ---------- ticket : solprop.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. """ self._ledger.check_ticket(ticket) observed = self._fielded(ticket) phase = observed.noise_phase return None if phase is None else np.array(phase)
[docs] def pending_ticket(self) -> ExportTicket | None: """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. """ if self.closed or self._driver.in_flight is not None: return None if self._ledger.state is not SessionState.PENDING: self._generation += 1 self._z = float(getattr(self._driver, "_z", self._z)) self._ledger.issue(outcome=Outcome.FAILED) receipt = self._ledger.pending assert receipt is not None return ExportTicket(receipt, self._generation, self._z)
[docs] def request_snapshot(self) -> SnapshotReceipt: """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. """ self._ledger.check_open() if self._snapshot_pending is not None: return SnapshotReceipt(self._snapshot_pending, coalesced=True) self._snapshot_requests += 1 self._snapshot_pending = self._snapshot_requests _hook(self._driver, "request_halt") return SnapshotReceipt(self._snapshot_pending, coalesced=False)
[docs] def continue_monitor(self, continuation: Mapping[str, object]) -> None: """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 :class:`~solprop.backends.session.Start` is kept. Parameters ---------- continuation : collections.abc.Mapping As :attr:`solprop.backends.session.Start.monitor`. Raises ------ solprop.backends.session.SessionError If the monitor is already watching. """ if self._attached: msg = "a boundary monitor is continued before it watches the run" raise SessionError(msg) if self._monitor_resume is None: self._monitor_resume = continuation
[docs] def undelivered(self, ticket: ExportTicket) -> tuple[BackendHistory, StepStats]: """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 (:func:`solprop.backends.events.join_attempts`). Parameters ---------- ticket : solprop.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. """ self._ledger.check_ticket(ticket) return self._chunk()
[docs] def march_snapshot(self, ticket: ExportTicket) -> MarchSnapshot | None: """Return the method history at a pending observation, when the march has one. Parameters ---------- ticket : solprop.backends.events.ExportTicket The pending observation's ticket. Returns ------- solprop.output.schema.MarchSnapshot or None The history at the ticket's position, or ``None``. """ self._ledger.check_ticket(ticket) snapshot = self._driver.march_snapshot() if snapshot is None or snapshot.z != ticket.z: return None return snapshot
[docs] def march_snapshot_nbytes(self) -> int | None: """Return the size a method-history snapshot would have. Returns ------- int or None Bytes, or ``None`` when the march keeps no history. """ return self._driver.march_snapshot_nbytes(self._z)
[docs] def march_export_refusal(self) -> str | None: """Return why the march cannot export its history, or ``None``. Returns ------- str or None The reason, or ``None`` when it can. """ return self._driver.march_export_refusal()
[docs] @property def march_refusal(self) -> str | None: """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. """ return self._march_refusal
[docs] def execution_record(self) -> Mapping[str, object]: """Return the session's execution facts. Returns ------- collections.abc.Mapping The driver's metadata. """ return self._driver.metadata()
[docs] def monitor_record(self) -> Mapping[str, object] | None: """Return the boundary monitor's record. Returns ------- collections.abc.Mapping or None Its summary, or ``None`` without a monitor. """ return None if self._monitor is None else self._monitor.summary()
[docs] @property def monitor(self) -> BoundaryMonitor | None: """Return the session's own boundary monitor, for transitional reporting. Returns ------- solprop.monitor.BoundaryMonitor or None The monitor, or ``None``. """ return self._monitor
[docs] def close(self) -> None: """Release the driver; idempotent.""" if self._ledger.close(): self._driver.set_stop(None) if self._owns: self._driver.close()
def __enter__(self) -> "DriverSession": # noqa: UP037 - runtime type hook """Return the session. Returns ------- DriverSession This session. """ return self def __exit__( self, kind: type[BaseException] | None, error: BaseException | None, trace: TracebackType | None, ) -> None: """Close the session. Parameters ---------- kind : type or None The exception type, if one is propagating. error : BaseException or None The exception, if one is propagating. trace : types.TracebackType or None Its traceback. """ del kind, error, trace self.close() # -- internals ------------------------------------------------------------------ def _attach_monitor(self) -> None: """Restore and attach the boundary monitor after the launch plane's commit.""" self._attached = True if self._monitor is None: return resume = self._monitor_resume if resume is not None: self._monitor.resume( resume.get("record"), # pyright: ignore[reportArgumentType] plane=bool(resume.get("plane", False)), unwatched=resume.get("unwatched", ()), # pyright: ignore[reportArgumentType] ) self._driver.attach_monitor(self._monitor) def _account(self, summary: StepSummary) -> None: """Advance the committed position and the state generation. Parameters ---------- summary : solprop.backends.protocol.StepSummary What the propagation did. """ self._stepped = self._stepped or summary.n_steps > summary.n_rejected self._z = float(summary.z) self._generation += 1 def _drain(self, *, field: bool) -> Observation: """Observe the driver, draining its attempts and rows since the last drain. Every attempt is drained exactly once, so the status counts them here. Parameters ---------- field : bool Whether the field crosses too. Returns ------- solprop.backends.protocol.Observation The observation. """ return self._counted(self._driver.observe(field=field)) def _counted(self, observed: Observation) -> Observation: """Count a drained observation's attempts into the status. Parameters ---------- observed : solprop.backends.protocol.Observation Attempts drained from the driver, once. Returns ------- solprop.backends.protocol.Observation The same observation. """ self._attempts += observed.n_steps self._rejected += observed.n_rejected return observed def _chunk(self) -> tuple[BackendHistory, StepStats]: """Drain the attempts and rows since the previous event, for the next one. A state left in flight cannot be observed; the attempts recorded before the abandoned step are drained from the driver's record instead (:func:`_recorded`). Returns ------- tuple The attempts and the rows (without a batch axis), delivered by exactly one event (:mod:`solprop.backends.events`). """ drained = ( self._counted(_recorded(self._driver, self._z)) if self._driver.in_flight is not None else self._drain(field=False) ) chunks = [*self._undelivered, (drained.step_history, drained.step_stats)] self._undelivered = [] return join_attempts(chunks) def _summary_so_far(self, step: StepSummary) -> StepSummary: """Merge a propagation's summary with the yields before it on the same plane. Parameters ---------- step : solprop.backends.protocol.StepSummary The latest propagation. Returns ------- solprop.backends.protocol.StepSummary The summary of the plane so far. """ before = self._summary if before is None: merged = step else: accepted_before = before.n_steps - before.n_rejected accepted_now = step.n_steps - step.n_rejected accepted = accepted_before + accepted_now merged = StepSummary( z=step.z, n_steps=before.n_steps + step.n_steps, n_rejected=before.n_rejected + step.n_rejected, max_norm=max(before.max_norm, step.max_norm), mean_norm=0.0 if accepted == 0 else ( before.mean_norm * accepted_before + step.mean_norm * accepted_now ) / accepted, wall_time=before.wall_time + step.wall_time, met_tolerance=before.met_tolerance and step.met_tolerance, ) self._summary = merged return merged def _at_endpoint(self) -> bool: """Return whether the driver stands at an accepted endpoint. Returns ------- bool False while a dense observation holds the state between endpoints. """ # The starting position is no accepted endpoint of this session: an Adams # march holds no history there to snapshot. return self._stepped and getattr(self._driver, "_dense_ahead", None) is None def _driver_halted(self) -> bool: """Return whether the driver stopped at a requested halt. Returns ------- bool True while the latch is set and the driver did not reach its target. """ return bool(getattr(self._driver, "_halted", False)) def _issue( self, events: list[Event], *, outcome: Outcome | None = None ) -> EventBatch: """Issue a batch of events under a new receipt. Parameters ---------- events : list The events; tickets are bound to the receipt here. outcome : solprop.backends.events.Outcome or None, optional The terminal outcome, when the batch ends the session. Returns ------- solprop.backends.events.EventBatch The batch. """ receipt = self._ledger.issue(outcome=outcome) bound: list[Event] = [] for event in events: ticket = getattr(event, "ticket", None) if ticket is not None: event = dataclasses.replace( # noqa: PLW2901 event, ticket=dataclasses.replace(ticket, receipt=receipt) ) bound.append(event) return EventBatch(receipt, tuple(bound)) def _ticket(self) -> ExportTicket: """Return an unbound ticket for the current committed state. Returns ------- solprop.backends.events.ExportTicket The ticket, its receipt filled in when the batch is issued. """ return ExportTicket(Receipt(self._ledger.session, 0), self._generation, self._z) def _observation( self, kind: ObservationKind, plane: int, summary: StepSummary ) -> EventBatch: """Observe the driver field-free and report it. Parameters ---------- kind : solprop.backends.events.ObservationKind Why it was observed. plane : int The save plane it answers. summary : solprop.backends.protocol.StepSummary The propagation that reached it. Returns ------- solprop.backends.events.EventBatch One observation. """ history, rows = self._chunk() self._observed = None try: stats = dict(self._driver.stats(self._request.observation.stats)) except Exception as error: return self._terminal(Outcome.FAILED, error, (history, rows)) event = ObservationReady( z=self._z, kind=kind, plane_index=plane, history=history, step_stats=rows, stats=stats, summary=summary, ticket=self._ticket(), ) return self._issue([event]) def _snapshot(self) -> EventBatch: """Report a snapshot service request at the current accepted endpoint. It delivers the attempts and rows since the previous event; the consumer joins them to those it holds since the previous observation for the running checkpoint, and keeps them for the next plane (SEP 47 section 5.5). Returns ------- solprop.backends.events.EventBatch The snapshot request. """ history, rows = self._chunk() _hook(self._driver, "clear_halt") self._snapshot_pending = None return self._issue( [ ServiceRequired( kind=ServiceKind.SNAPSHOT, z=self._z, message="snapshot at an accepted endpoint", ticket=self._ticket(), history=history, step_stats=rows, ) ] ) def _complete(self) -> EventBatch: """Run the final checks and report completion. Returns ------- solprop.backends.events.EventBatch The terminal event. """ chunk = self._chunk() try: if self._monitor is not None and self._attached: self._monitor.finish() except Exception as error: return self._terminal(Outcome.FAILED, error, chunk) return self._issue( [ Terminal( Outcome.COMPLETED, self._z, Eligibility.ELIGIBLE, None, None, *chunk, ) ], outcome=Outcome.COMPLETED, ) def _terminal( self, outcome: Outcome, error: BaseException, chunk: tuple[BackendHistory, StepStats] | None = None, ) -> EventBatch: """Report a stop or failure at the last committed position. Parameters ---------- outcome : solprop.backends.events.Outcome Stopped or failed. error : BaseException The primary failure or the stop request. chunk : tuple or None, optional The attempts and rows since the previous event, when already drained for an event the failure replaced; drained here otherwise. Returns ------- solprop.backends.events.EventBatch The terminal event, with a ticket when the state is valid. """ poisoned = self._driver.in_flight is not None history, rows = self._chunk() if chunk is None else chunk self._generation += 1 self._z = float(getattr(self._driver, "_z", self._z)) event = Terminal( outcome, self._z, Eligibility.POISONED if poisoned else Eligibility.ELIGIBLE, error, None if poisoned else self._ticket(), history, rows, ) return self._issue([event], outcome=outcome) def _fielded(self, ticket: ExportTicket) -> Observation: """Observe the field for a ticket once, sharing it among its consumers. Parameters ---------- ticket : solprop.backends.events.ExportTicket A valid ticket. Returns ------- solprop.backends.protocol.Observation The driver's observation with its field. """ if self._observed is None or self._observed_generation != ticket.generation: observed = self._drain(field=True) if observed.n_steps or observed.step_stats.n_rows: # Attempts a field fetch drained belong to the next event's chunk. self._undelivered.append((observed.step_history, observed.step_stats)) self._observed = observed self._observed_generation = ticket.generation self._converted = None self._lent = False return self._observed def _field(self, ticket: ExportTicket) -> np.ndarray: """Return the committed field for a ticket, without a batch axis. Parameters ---------- ticket : solprop.backends.events.ExportTicket A valid ticket. Returns ------- numpy.ndarray The field, internal units and convention, read-only. """ field = self._fielded(ticket).field assert field is not None # observed with its field # A view of its own, as every fetch has handed out: a destination a caller # passes back is then never taken for the source and is checked as one. return field.view()
def _bound(event: Event, receipt: Receipt) -> Event: """Return an event with its ticket bound to the batch that delivers it. Parameters ---------- event : solprop.backends.events.Event An event, with an unbound ticket or none. receipt : solprop.backends.events.Receipt The batch's receipt. Returns ------- solprop.backends.events.Event The event, its ticket bound; the same event when it carries none. """ ticket = getattr(event, "ticket", None) if ticket is None: return event return dataclasses.replace( event, # pyright: ignore[reportArgumentType] ticket=dataclasses.replace(ticket, receipt=receipt), )
[docs] class DriverGroupSession: """A :class:`~solprop.backends.session.GroupSession` over the lockstep runners. It loads each member from its start, then hands the loaded members to the backend's lockstep runner (:func:`solprop.backends.registry.select_batch`: the reference's :class:`~solprop.backends.host.group.HostGroup`, the native bridge's :class:`~solprop.backends.batch.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 :class:`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 ---------- members : collections.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. problems : collections.abc.Sequence of solprop.translate.problem.PropagationProblem Each member's independently translated problem. requests : collections.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. starts : collections.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. stop : solprop.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. """ def __init__( self, members: Sequence[Backend], problems: Sequence[PropagationProblem], requests: Sequence[RunRequest], starts: Sequence[Start], *, stop: StopFlag | None = None, ) -> None: """Load every member from its start and build the lockstep runner.""" from solprop.backends.registry import select_batch # noqa: PLC0415 - cycle count = len(members) if count == 0 or not count == len(problems) == len(requests) == len(starts): msg = ( f"a group needs one problem, request and start per member, and got " f"{count} members, {len(problems)} problems, {len(requests)} " f"requests and {len(starts)} starts" ) raise SessionError(msg) observation = requests[0].observation for start in starts: fresh = start.march is None and start.monitor is None if not fresh or start.plane_index: msg = ( "a group starts its members at their entrance, with no method " "history or monitor record to continue" ) raise SessionError(msg) for member, start in zip(members, starts, strict=True): member.set_initial( np.asarray(start.take_field()), start.noise, z=float(start.z), resume=start.resume, ) self._members = tuple(members) self._problems = tuple(problems) self._requests = tuple(requests) self._planes = np.asarray(observation.save_planes, dtype=np.float64) self._runner = select_batch(self._members) self._runner.set_stop(stop) self._ledger = SessionLedger() self._launched = False self._index = 0 self._generation = 0 self._z = float(starts[0].z) self._outcomes: list[Outcome | None] = [None] * count self._attempts = [0] * count self._rejected = [0] * count self._observed: dict[int, Observation] = {} self._observed_generation = -1 # Set once a group-wide stop or failure ended every running member. self._broken = False # Each member's attempts drained since its previous event and not yet delivered. self._drained: dict[int, tuple[BackendHistory, StepStats]] = {} # -- protocol -------------------------------------------------------------------
[docs] @property def n_members(self) -> int: """Return the number of members. Returns ------- int The members. """ return len(self._members)
[docs] @property def finished(self) -> bool: """Return whether the group's terminal batch was issued. Returns ------- bool True once every member has ended. """ return self._ledger.finished
[docs] @property def closed(self) -> bool: """Return whether the group was closed. Returns ------- bool True once closed. """ return self._ledger.state is SessionState.CLOSED
[docs] def advance(self) -> GroupBatch: """Run every running member through the next common window, and report it. Returns ------- solprop.backends.events.GroupBatch Each member's events in the window. """ self._ledger.check_advance() if not self._launched: self._launched = True return self._launch() if self._index >= self._planes.size: return self._complete() target = float(self._planes[self._index]) try: summary = self._runner.propagate_to(target) except StopRequested as error: return self._ended(Outcome.STOPPED, error) except Exception as error: return self._ended(Outcome.FAILED, error) self._z = float(summary.z) self._generation += 1 plane = self._index self._index += 1 return self._window(ObservationKind.PLANE, plane, summary)
[docs] def acknowledge(self, receipt: Receipt) -> None: """Release the pending batch and allow advancing past it. Parameters ---------- receipt : solprop.backends.events.Receipt The pending batch's receipt. """ self._ledger.acknowledge(receipt) self._observed = {}
[docs] def export( self, member: int, ticket: ExportTicket, recipe: ExportRecipe, out: Complex[np.ndarray, "n_modes n_pol n_omega"] | None = None, ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: """Fill a destination with one member's converted field at a pending ticket. Parameters ---------- member : int The member's position. ticket : solprop.backends.events.ExportTicket A ticket of the pending batch, for this member: its position is the member's own. recipe : solprop.backends.export.ExportRecipe The conversion. out : numpy.ndarray or None, optional The destination; a new array by default. Returns ------- numpy.ndarray The member's converted field. """ self._ledger.check_ticket(ticket) problem = self._problems[self._member(member)] if recipe.power and problem.transform.geometry is not None: # A spatial route's field measure is already the stored quantity. recipe = dataclasses.replace(recipe, power=False) weight = power_weight_at(problem, ticket.z) if recipe.power else None field = self._fielded(ticket, member).field assert field is not None # observed with its field return apply_recipe(field, recipe, weight=weight, out=out)
[docs] def noise_phase(self, member: int, ticket: ExportTicket) -> np.ndarray | None: """Return one member's noise phase at a pending ticket. Parameters ---------- member : int The member's position. ticket : solprop.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. """ self._ledger.check_ticket(ticket) phase = self._fielded(ticket, self._member(member)).noise_phase return None if phase is None else np.array(phase)
[docs] def member_status(self, member: int) -> SessionStatus: """Return one member's committed position, counters and outcome. Parameters ---------- member : int The member's position. Returns ------- solprop.backends.session.SessionStatus Its status; a member that ended reports its own outcome while the group goes on. """ index = self._member(member) outcome = self._outcomes[index] state = self._ledger.state if outcome is not None and state is not SessionState.CLOSED: state = SessionState.FINISHED return SessionStatus( z=self._cursor(index), plane_index=self._index, attempts=self._attempts[index], rejected=self._rejected[index], state=state, outcome=outcome, )
[docs] def execution_record(self, member: int) -> Mapping[str, object]: """Return one member's execution facts, with the group's strategy. Parameters ---------- member : int The member's position. Returns ------- collections.abc.Mapping Its backend provenance. """ return self._runner.member_metadata()[self._member(member)]
[docs] def monitor_record(self, member: int) -> Mapping[str, object] | None: """Return one member's boundary-monitor record. Parameters ---------- member : int The member's position. Returns ------- collections.abc.Mapping or None Its record as it closed or as it stands, or ``None`` when unwatched. """ return self._runner.member_records[self._member(member)]
[docs] def close(self) -> None: """Release every member and the runner; idempotent.""" if self._ledger.close(): self._runner.set_stop(None) self._runner.close()
def __enter__(self) -> "DriverGroupSession": # noqa: UP037 - runtime type hook """Return the group. Returns ------- DriverGroupSession This group. """ return self def __exit__( self, kind: type[BaseException] | None, error: BaseException | None, trace: TracebackType | None, ) -> None: """Close the group. Parameters ---------- kind : type or None The exception type, if one is propagating. error : BaseException or None The exception, if one is propagating. trace : types.TracebackType or None Its traceback. """ del kind, error, trace self.close() # -- internals ------------------------------------------------------------------ def _member(self, member: int) -> int: """Return a valid member position. Parameters ---------- member : int The position asked for. Returns ------- int The same position. Raises ------ solprop.backends.session.SessionError If the group has no such member. """ if not 0 <= member < len(self._members): msg = f"the group has {len(self._members)} members, not a member {member}" raise SessionError(msg) return member def _cursor(self, index: int) -> float: """Return one member's committed position. Members are stepped in turn, so after a failure partway through a common step a member ahead of the failing one stands at the step's end, its step neither validated nor recorded -- in flight, and so poisoned -- and the others at the step's start. Parameters ---------- index : int The member's position. Returns ------- float The position, m. """ return float(getattr(self._members[index], "_z", self._z)) def _running(self) -> list[int]: """Return the members that have not ended. Returns ------- list of int Their positions. """ return [index for index, ended in enumerate(self._outcomes) if ended is None] def _chunks(self) -> list[tuple[BackendHistory, StepStats]]: """Drain every member's attempts and rows since the previous window. Returns ------- list of tuple Each member's attempts and rows (without a batch axis), in member order. """ chunks: list[tuple[BackendHistory, StepStats]] = [] for index in range(len(self._members)): # One member at a time, each kept until an event delivers it: a later # member's failure, or the statistics', ends the group with the attempts # already drained delivered by the terminals. Each event drains once. observation = self._members[index].observe(field=False) self._attempts[index] += observation.n_steps self._rejected[index] += observation.n_rejected self._drained[index] = ( observation.step_history, observation.step_stats, ) chunks.append(self._drained[index]) return chunks def _final_chunk(self, index: int) -> tuple[BackendHistory, StepStats] | None: """Drain one member's attempts after a group-wide stop or failure. A member left in flight cannot be observed; the attempts it recorded before the abandoned step are drained from its record instead (:func:`_recorded`). Parameters ---------- index : int The member's position. Returns ------- tuple or None Its attempts and rows, or ``None`` when its state cannot be read at all. """ member = self._members[index] try: observed = ( _recorded(member, self._cursor(index)) if member.in_flight is not None else member.observe(field=False) ) except Exception: return None self._attempts[index] += observed.n_steps self._rejected[index] += observed.n_rejected return observed.step_history, observed.step_stats def _ticket(self, z: float | None = None) -> ExportTicket: """Return an unbound ticket for a committed state of the current generation. Parameters ---------- z : float or None, optional The member's committed position, m; the window's end by default. Returns ------- solprop.backends.events.ExportTicket The ticket, its receipt filled in when the batch is issued. """ return ExportTicket( Receipt(self._ledger.session, 0), self._generation, self._z if z is None else z, ) def _member_stopped( self, index: int, chunk: tuple[BackendHistory, StepStats] ) -> Terminal | None: """Return a stopped member's terminal event, or ``None`` if it runs on. Parameters ---------- index : int The member's position. chunk : tuple Its attempts and rows since its previous event. Returns ------- solprop.backends.events.Terminal or None The boundary stop that ended it, which ends it alone. """ stop = self._runner.member_stops[index] if stop is None: return None self._outcomes[index] = Outcome.FAILED cursor = self._cursor(index) return Terminal( Outcome.FAILED, cursor, Eligibility.ELIGIBLE, stop, self._ticket(cursor), *chunk, ) def _launch(self) -> GroupBatch: """Give each member its monitor and report the launch planes. Returns ------- solprop.backends.events.GroupBatch Each member's launch plane, or the boundary stop that refused it. """ try: self._runner.attach_monitors( [request.boundary.monitor for request in self._requests] ) except Exception as error: return self._ended(Outcome.FAILED, error) return self._window(ObservationKind.LAUNCH, -1, _EMPTY_SUMMARY) def _window( self, kind: ObservationKind, plane: int, summary: StepSummary ) -> GroupBatch: """Report a window's end: each running member's plane, or its boundary stop. Parameters ---------- kind : solprop.backends.events.ObservationKind The launch or a save plane. plane : int The save plane, ``-1`` for the launch. summary : solprop.backends.protocol.StepSummary The common march to it; its maximum norm is a group diagnostic. Returns ------- solprop.backends.events.GroupBatch The window's events. """ try: chunks = self._chunks() stats = self._runner.stats(self._requests[0].observation.stats) except Exception as error: return self._ended(Outcome.FAILED, error) events: list[tuple[Event, ...]] = [] for index, chunk in enumerate(chunks): if self._outcomes[index] is not None: events.append(()) continue stopped = self._member_stopped(index, chunk) if stopped is not None: events.append((stopped,)) continue events.append( ( ObservationReady( z=self._z, kind=kind, plane_index=plane, history=chunk[0], step_stats=chunk[1], stats={ name: np.asarray(value[index]) for name, value in stats.items() }, summary=summary, ticket=self._ticket(), ), ) ) if not self._running(): # Every member ended at its own boundary: nothing is left to advance. return self._issue(events, outcome=Outcome.COMPLETED) return self._issue(events) def _complete(self) -> GroupBatch: """Run each watched member's final check and report every outcome. Returns ------- solprop.backends.events.GroupBatch Each running member's completion, or the final warning that failed it. """ try: chunks = self._chunks() self._runner.finish_monitors() except Exception as error: return self._ended(Outcome.FAILED, error) events: list[tuple[Event, ...]] = [] for index, chunk in enumerate(chunks): if self._outcomes[index] is not None: events.append(()) continue stopped = self._member_stopped(index, chunk) if stopped is not None: events.append((stopped,)) continue self._outcomes[index] = Outcome.COMPLETED events.append( ( Terminal( Outcome.COMPLETED, self._cursor(index), Eligibility.ELIGIBLE, None, None, *chunk, ), ) ) return self._issue(events, outcome=Outcome.COMPLETED) def _ended(self, outcome: Outcome, error: BaseException) -> GroupBatch: """End every running member with a group-wide stop or failure. Parameters ---------- outcome : solprop.backends.events.Outcome Stopped or failed. error : BaseException The primary failure or the stop request. Returns ------- solprop.backends.events.GroupBatch Each running member's terminal event at its own committed position. """ self._generation += 1 self._broken = True chunks = [ join_attempts( [ self._drained.get(index, (None, None)), self._final_chunk(index) or (None, None), ] ) for index in range(len(self._members)) ] events: list[tuple[Event, ...]] = [] for index, chunk in enumerate(chunks): if self._outcomes[index] is not None: events.append(()) continue self._outcomes[index] = outcome poisoned = self._members[index].in_flight is not None history, rows = chunk cursor = self._cursor(index) events.append( ( Terminal( outcome, cursor, Eligibility.POISONED if poisoned else Eligibility.ELIGIBLE, error, None if poisoned else self._ticket(cursor), history, rows, ), ) ) return self._issue(events, outcome=outcome, error=error) def _issue( self, members: list[tuple[Event, ...]], *, outcome: Outcome | None = None, error: BaseException | None = None, ) -> GroupBatch: """Issue a window's events under a new receipt. Parameters ---------- members : list Each member's events; tickets are bound to the receipt here. outcome : solprop.backends.events.Outcome or None, optional The group's outcome, when the batch ends it. error : BaseException or None, optional A group-wide failure's primary error. Returns ------- solprop.backends.events.GroupBatch The batch. """ receipt = self._ledger.issue(outcome=outcome) # Every drained attempt is delivered by this batch. self._drained = {} bound = tuple( tuple(_bound(event, receipt) for event in events) for events in members ) return GroupBatch(receipt, bound, outcome, error) def _fielded(self, ticket: ExportTicket, member: int) -> Observation: """Observe a member's field for a ticket once, shared by its exports. A window's fields are observed together, once; after a group-wide failure each member is observed alone, since a member left in flight refuses observation. Parameters ---------- ticket : solprop.backends.events.ExportTicket A valid ticket. member : int The member's position. Returns ------- solprop.backends.protocol.Observation The member's observation with its field. """ if self._observed_generation != ticket.generation: self._observed = {} self._observed_generation = ticket.generation if member not in self._observed: # The window's attempts were drained when it ended; nothing ran since. if self._broken: self._observed[member] = self._members[member].observe(field=True) else: self._observed.update( enumerate(self._runner.observe_members(field=True)) ) return self._observed[member]