Source code for solprop.driver.executors
# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""Execute independent scan points under an explicit resource policy.
``Executor`` is the protocol: ``run(points, work)`` yields one result per point,
possibly in completion order, each carrying its global index. Four policies satisfy it,
one per module: :class:`~solprop.driver.executors.local.Local` (sequential, in the
calling process), :class:`~solprop.driver.executors.pool.Pool` (spawned workers sized by
CPUs and memory), :class:`~solprop.driver.executors.queue.Queue` (a durable file queue
drained by controllers sharing a filesystem) and
:class:`~solprop.driver.executors.slurm.Slurm` (an array job of queue controllers). The
design is ``docs/dev/scans.md``.
"""
from collections.abc import Callable, Iterable, Iterator
from typing import Protocol, runtime_checkable
from solprop.driver.executors.local import Local
from solprop.driver.executors.pool import Pool
from solprop.driver.executors.queue import Queue
from solprop.driver.executors.slurm import Slurm
__all__ = ["Executor", "Local", "Pool", "Queue", "Slurm"]
[docs]
@runtime_checkable
class Executor(Protocol):
"""Run point work while preserving the identity carried by every result.
:func:`~solprop.driver.scan.run_scan` needs only :meth:`run`, and calls a
``validate(work)`` method before it writes anything where an executor has one. The
rest of what it does is decided by the four executors' classes, a closed set: an
executor of any other class runs as ``Local`` and ``Pool`` do, its points' results
written by the calling process, without the backend ``Local`` keeps between
points, or the stop refusal, durable preparation and collection of ``Queue`` and
``Slurm``.
"""
[docs]
def run[T, R](self, points: Iterable[T], work: Callable[[T], R]) -> Iterator[R]:
"""Execute work for each point.
Parameters
----------
points : iterable
Descriptions of independent work.
work : callable
Turn one description into a result containing its global index.
Yields
------
object
Result, possibly in completion order. Storage uses its global index.
"""
...