Source code for solprop.backends.sessions

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

"""Which run session serves a loaded backend (SEP 47 phase 2).

The NumPy reference runs in its own session
(:class:`solprop.backends.host.session.HostSession`, over
:class:`solprop.backends.host.driver.HostDriver`); every other backend -- the native
bridge, until its own session replaces it in phase 3 -- runs in the transitional
session over the inherited driver
(:class:`solprop.backends.driver_session.DriverSession`). :func:`start_session` chooses
by the driver's type, so the run layer has one door. :func:`start_group` is the door
for a group of compatible members (SEP 47 section 6.7), served on every backend by the
transitional group over the lockstep runners
(:class:`solprop.backends.driver_session.DriverGroupSession`).
"""

from __future__ import annotations

from collections.abc import Callable, Sequence
from typing import TYPE_CHECKING

from solprop.backends.driver_session import (
    AttemptListener,
    DriverGroupSession,
    DriverSession,
)
from solprop.backends.host.driver import HostDriver
from solprop.backends.host.session import HostSession
from solprop.backends.session import Start
from solprop.log import StopFlag
from solprop.translate.problem import PropagationProblem
from solprop.translate.run_request import RunRequest

if TYPE_CHECKING:
    # The scripted drivers of the test suite stand in for a backend.
    from solprop.backends.protocol import Backend

__all__ = ["start_group", "start_session"]


[docs] def start_session( # noqa: PLR0913 - the session context backend: 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, ) -> DriverSession: """Start the session that serves `backend` for one run. Parameters ---------- backend : solprop.backends.protocol.Backend The backend, constructed for `problem`. A backend reused from an earlier run is loaded again from `start`, which restores everything a march reads. 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 takes its field. listener : callable or None, optional Called with each attempt as it is made, for a progress reporter. 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. owns : bool, optional Whether closing the session closes the backend. Returns ------- solprop.backends.driver_session.DriverSession A :class:`~solprop.backends.host.session.HostSession` for a reference backend, or the transitional session for any other. """ session = HostSession if isinstance(backend, HostDriver) else DriverSession return session( backend, problem, request, start, listener=listener, started=started, stop=stop, owns=owns, )
[docs] def start_group( members: Sequence[Backend], problems: Sequence[PropagationProblem], requests: Sequence[RunRequest], starts: Sequence[Start], *, stop: StopFlag | None = None, ) -> DriverGroupSession: """Start the group that advances compatible members through one fixed schedule. Parameters ---------- members : collections.abc.Sequence of solprop.backends.protocol.Backend One constructed backend per member, all of one backend; the group owns them once constructed. 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. starts : collections.abc.Sequence of solprop.backends.session.Start Each member's entrance. stop : solprop.log.StopFlag or None, optional A group-wide stop token. Returns ------- solprop.backends.driver_session.DriverGroupSession The started group (:class:`~solprop.backends.session.GroupSession`). """ return DriverGroupSession(members, problems, requests, starts, stop=stop)