Source code for solprop.scan

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

"""Launch an explicitly selected scan script without evaluating CLI expressions.

``python -m solprop.scan script.py [options]`` (and ``solprop scan``): :func:`main`
parses the options into one execution policy (``_policy``: ``Local``, ``Pool``,
``Queue`` or ``Slurm``), sets it as the default executor of the scan script, which it
then runs as ``__main__``; a :func:`~solprop.driver.scan.run_scan` with an explicit
``executor`` still takes precedence. ``--emit-slurm`` writes the Slurm array script
instead, and ``python -m solprop.scan collect QUEUE --output OUT.h5`` collects a durable
queue into a scan file. :func:`current_executor` reads the policy in force. No option
is evaluated as Python. The manual page is ``docs/guide/workflows/scans.md``.
"""

import argparse
import runpy
import sys
from collections.abc import Sequence
from pathlib import Path

from solprop.driver._scan_context import _EXECUTOR, current_executor
from solprop.driver.executors import Executor, Local, Pool, Queue, Slurm
from solprop.driver.executors.queue import collect

__all__ = ["current_executor", "main"]

_DESCRIPTION = (
    "Launch an explicitly selected scan script without evaluating CLI expressions."
)

# The collect mode is dispatched before the script parser sees its arguments, so
# argparse cannot advertise it on its own: `collect` would otherwise be read as a
# script path. Both modes name it from here so the two descriptions cannot drift.
_COLLECT_HELP = (
    "collection mode:\n"
    "  python -m solprop.scan collect QUEUE --output OUT.h5\n"
    "    Collect the durable artifacts of the shared queue directory QUEUE into\n"
    "    the standalone scan file OUT.h5. Idempotent: an already collected point\n"
    "    is left untouched and a second run rewrites nothing."
)


[docs] def main(argv: Sequence[str] | None = None) -> int: """Run a scan script under an explicit CLI policy. Parameters ---------- argv : sequence of str or None, optional CLI arguments, or None to parse process arguments. Returns ------- int Zero after a successful script execution. """ arguments = list(sys.argv[1:] if argv is None else argv) if arguments and arguments[0] == "collect": parser = argparse.ArgumentParser( prog="python -m solprop.scan collect", description="Collect durable scan artifacts", epilog=_COLLECT_HELP, formatter_class=argparse.RawDescriptionHelpFormatter, ) parser.add_argument("queue", type=Path, help="the shared queue directory") parser.add_argument( "--output", "-o", type=Path, required=True, help="the scan file to write" ) args = parser.parse_args(arguments[1:]) collect(args.queue, args.output) return 0 parser = _parser() args = parser.parse_args(arguments) executor = _policy(args, parser) if args.emit_slurm is not None: if not isinstance(executor, Slurm): parser.error("--emit-slurm requires a Slurm policy") args.emit_slurm.write_text(executor.render(), encoding="utf-8") return 0 token = _EXECUTOR.set(executor) previous = sys.argv sys.argv = [str(args.script.resolve())] try: runpy.run_path(str(args.script.resolve()), run_name="__main__") finally: sys.argv = previous _EXECUTOR.reset(token) return 0
def _parser() -> argparse.ArgumentParser: """Declare CLI modes without interpreting values as Python expressions.""" parser = argparse.ArgumentParser( description=_DESCRIPTION, epilog=_COLLECT_HELP, formatter_class=argparse.RawDescriptionHelpFormatter, ) parser.add_argument("script", type=Path, help="the scan script to run") parser.add_argument( "--local", action="store_true", help="run every point in this process, one after another", ) parser.add_argument( "--queue", type=Path, help="the shared queue directory to claim points from" ) parser.add_argument( "--chunk", help="claim only chunk k of n of the points, zero-based, written k/n", ) parser.add_argument( "--submit", action="store_true", help="submit the scan as a Slurm array" ) parser.add_argument( "--emit-slurm", type=Path, help="write the Slurm array script to this file instead of submitting it", ) parser.add_argument( "--workers", type=int, help="the most worker processes (default: as the CPUs and memory admit)", ) parser.add_argument( "--threads", type=int, default=1, help="threads per worker (default: 1)" ) parser.add_argument( "--memory-limit", type=int, help="the memory the workers may use, in bytes (default: the allocation's)", ) parser.add_argument( "--fresh", action="store_true", help="start a fresh interpreter for every point", ) parser.add_argument( "--stale-age", type=float, help="seconds after which a queue claim on a point lapses, with --queue, " "--chunk or a Slurm mode (default: 600)", ) parser.add_argument( "--ntasks", type=int, default=1, help="Slurm array tasks (default: 1)" ) parser.add_argument( "--cpus-per-task", type=int, default=1, help="CPUs allocated to each Slurm task (default: 1)", ) parser.add_argument( "--mem", default="4G", help="memory for each Slurm task, MiB without a K/M/G/T suffix (default: 4G)", ) parser.add_argument( "--time", default="01:00:00", help="the Slurm wall-clock limit of each task (default: 01:00:00)", ) parser.add_argument("--partition", help="the Slurm partition") parser.add_argument( "--gres", help="Slurm generic resources for each task, for example gpu:1" ) parser.add_argument( "--mode", choices=("queue", "chunk"), default="queue", help="Slurm tasks claim points from a shared queue, or each runs a disjoint " "chunk (default: queue)", ) parser.add_argument( "--instances", type=int, default=0, help="controllers per Slurm task; 0 runs one (default: 0)", ) return parser def _policy(args: argparse.Namespace, parser: argparse.ArgumentParser) -> Executor: """Resolve one execution default while retaining explicit script precedence.""" slurm = args.submit or args.emit_slurm is not None worker_controls = ( args.workers is not None or args.memory_limit is not None or args.threads != 1 or args.fresh ) if args.local and (args.queue is not None or args.chunk is not None or slurm): parser.error("--local cannot be combined with queue, chunk or Slurm modes") if args.local and worker_controls: parser.error("--local cannot use process-pool resource controls") queued = args.queue is not None or args.chunk is not None if args.stale_age is not None and not (queued or slurm): parser.error( "--stale-age is a queue lease: use it with --queue, --chunk or Slurm" ) lease = {} if args.stale_age is None else {"stale_age": args.stale_age} if slurm: if args.memory_limit is not None: parser.error("use --mem for a Slurm allocation") if args.chunk is not None: parser.error("use --mode chunk and --ntasks for a Slurm submission") return Slurm( args.script, ntasks=args.ntasks, cpus_per_task=args.cpus_per_task, mem=args.mem, time=args.time, partition=args.partition, gres=args.gres, mode=args.mode, instances=args.instances, queue_path=args.queue, workers=args.workers, threads=args.threads, fresh=args.fresh, **lease, ) chunk = None if args.chunk is not None: try: k, n = args.chunk.split("/") chunk = (int(k), int(n)) except ValueError as error: parser.error(f"chunk must be zero-based k/n: {error}") if queued: return Queue( args.queue, **lease, pool=Pool( workers=args.workers, memory_limit=args.memory_limit, threads=args.threads, fresh=args.fresh, ), chunk=chunk, ) return ( Pool( workers=args.workers, memory_limit=args.memory_limit, threads=args.threads, fresh=args.fresh, ) if worker_controls else Local() ) if __name__ == "__main__": raise SystemExit(main())