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