Source code for solprop.backends.sessions
# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""The run layer's one door to a backend's sessions (SEP 47 phases 2 to 5).
:func:`start_session` starts a run through the backend's own preparation shape (SEP
47 section 5.2), ``backend.prepare(problem, request).start(start, ...)``, so a backend
chooses its session and nothing here names one. The NumPy reference's prepared
execution opens its own session
(:class:`solprop.backends.host.session.HostSession`); a native backend's
(``solprop_native.session.NativePrepared``) opens the native execution session
(``solprop_native.session.NativeSession``), on a CPU or a device build alike, which
refuses by name, before the start is loaded, what it does not run.
"""
from __future__ import annotations
from collections.abc import Callable
from typing import TYPE_CHECKING
from solprop.backends.session import RunSession, Start
from solprop.backends.session_core import AttemptListener
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_session"]
[docs]
def start_session(
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,
) -> RunSession:
"""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.session.RunSession
The session the backend's prepared execution opens: the native session
(``solprop_native.session.NativeSession``) for a native backend, and a
:class:`~solprop.backends.host.session.HostSession` for a reference
backend.
"""
prepared = backend.prepare(problem, request)
return prepared.start(
start, listener=listener, started=started, stop=stop, owns=owns
)