Source code for solprop.backends.host.session

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

"""The NumPy reference's run session (SEP 47 sections 5 and 6.6).

:class:`HostSession` is the :class:`~solprop.backends.session.RunSession` that serves
every ``numpy_ref`` run, in both precisions: the launch-before-monitor order, the plane
schedule, the snapshot latch, bounded yields, chunked attempts, exports and the terminal
outcome with its checkpoint eligibility, over the reference's own driver
(:class:`solprop.backends.host.driver.HostDriver`). It imports nothing of the inherited
driver the native bridge still runs on.

**A recorded exception.** The reference otherwise shares only stateless numerical
modules with the native bridge, but for phase 2 its lifecycle is the transitional
session's (:class:`solprop.backends.driver_session.DriverSession`), reused by
subclassing: it drives any driver through the backend protocol and the halt and yield
hooks a host driver keeps (``request_halt``, ``clear_halt``, ``set_halt_check``,
``poll_halt`` and the latch ``_halted``). The exception is removed when a later step of
SEP 47 restructures this session into the reference's own.
"""

from __future__ import annotations

from collections.abc import Callable
from typing import TYPE_CHECKING

from solprop.backends.driver_session import AttemptListener, DriverSession
from solprop.backends.host.driver import HostDriver
from solprop.backends.session import Start
from solprop.exceptions import BackendError
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__ = ["HostSession"]


[docs] class HostSession(DriverSession): """The reference's :class:`~solprop.backends.session.RunSession`. Parameters ---------- driver : solprop.backends.protocol.Backend The reference backend (a :class:`~solprop.backends.host.driver.HostDriver`), constructed for `problem`. 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 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. 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. Raises ------ solprop.exceptions.BackendError If `driver` is not a reference driver. """ 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: """Refuse a driver that is not the reference's, and load the starting state.""" if not isinstance(driver, HostDriver): msg = ( f"the reference session serves a host driver, not " f"{type(driver).__name__}" ) raise BackendError(msg) super().__init__( driver, problem, request, start, listener=listener, started=started, stop=stop, owns=owns, )