MATE-runtime 1.0.0__py3-none-any.whl

MATE/cli/commands.py

@@ -0,0 +1,573 @@
+"""The commands of the ``MATE`` command line ([X] §24, [C] §21, design §3.14).
+
+Each ``cmd_<name>`` function takes the parsed arguments and returns the exit status: 0
+success, 1 refusal (software, interface, preconditions, deferred feature), 2 run failures,
+3 usage error. Reports go to stdout, errors to stderr.
+"""
+
+import argparse
+import sys
+import tempfile
+from collections.abc import Sequence
+from pathlib import Path
+
+from packaging.utils import canonicalize_name
+
+from MATE.compat.interface import Outcome, check_interface
+from MATE.config.loader import LoadedProtocol, load_protocol
+from MATE.config.model import Value
+from MATE.config.toml import parse_toml_value
+from MATE.errors import ProtocolRefused, Refusal, SoftwareCompatibilityError
+from MATE.launch import exec_run, launch
+from MATE.modules import registry
+from MATE.modules.construct import (ModuleConstructionError, construct_module,
+                                    declared_defaults, missing_parameters)
+from MATE.modules.discovery import ModuleEntry, installed_modules
+from MATE.modules.software import ModuleRef, check_software, render
+from MATE.observation.control import send_command
+from MATE.run.plan import LaunchResult
+from MATE.run.specs import NormalisedSpecs, is_collective, normalise_specs
+from MATE.scheduling.slurm import SubmissionError
+from MATE.storage.lease import RunBusyError
+
+from MATE.cli import workdir
+
+__all__ = [
+    "REPLAY_REFUSAL",
+    "DASHBOARD_REFUSAL",
+    "UsageError",
+    "cmd_launch", "cmd_status", "cmd_verify", "cmd_runs", "cmd_diff", "cmd_show",
+    "cmd_branch", "cmd_control", "cmd_list", "cmd_matrix", "cmd_check", "cmd_search",
+    "cmd_install", "cmd_replay", "cmd_dashboard", "cmd_exec_run",
+    "matrix",
+]
+
+REPLAY_REFUSAL = ("MATE replay: visual replay is not available in MATE 1.0.0 (the replay "
+                  "interface of systems is not yet specified)")
+DASHBOARD_REFUSAL = ("the terminal dashboard is not available in MATE 1.0.0; control a run "
+                     "with 'MATE control <run> stop|suspend|resume|checkpoint|verbosity'")
+
+_FAILURES = ("method_error", "system_error", "refused")
+
+
+class UsageError(Exception):
+    """A command-line argument the command cannot use (exit status 3)."""
+
+
+def _out(text: str) -> None:
+    """Print a report."""
+    print(text, file=sys.stdout)
+
+
+def _err(text: str) -> None:
+    """Print an error."""
+    print(text, file=sys.stderr)
+
+
+# --- launching ---------------------------------------------------------------------------------
+
+
+def _sweep(specs: Sequence[str]) -> list[tuple[str, Sequence[Value]]]:
+    """``--sweep path=v1,v2`` -> (path, values), each value a TOML value ([C] R21.2)."""
+    out = []
+    for spec in specs:
+        path, sep, values = spec.partition("=")
+        if not sep or not path.strip() or not values.strip():
+            raise UsageError(f"--sweep {spec!r}: expected <path>=<v1>,<v2>,...")
+        try:
+            parsed = parse_toml_value(f"[{values}]")
+        except ValueError as exc:
+            raise UsageError(f"--sweep {spec!r}: {exc}") from None
+        out.append((path.strip(), tuple(parsed)))  # type: ignore[arg-type]
+    return out
+
+
+def _overrides(args: argparse.Namespace) -> dict[str, Value]:
+    """The ``[execution]`` keys given on the command line ([C] R21.1)."""
+    out: dict[str, Value] = {}
+    for key in ("workers", "executor", "scheduler", "verbosity", "workdir", "retention",
+                "checkpoint_every"):
+        value = getattr(args, key, None)
+        if value is not None:
+            out[key] = str(value) if key == "workdir" else value
+    return out
+
+
+def _sinks(args: argparse.Namespace) -> list[str] | None:
+    """``--sinks S,...``."""
+    if getattr(args, "sinks", None) is None:
+        return None
+    return [s.strip() for s in args.sinks.split(",") if s.strip()]
+
+
+def _load(load: object, debug: bool = False) -> LoadedProtocol | int:
+    """Call a loading thunk; a refusal is printed and gives status 1.
+
+    No run directory exists yet: the software check's tracebacks go to stderr under
+    ``--debug``.
+    """
+    try:
+        return load()  # type: ignore[operator]
+    except ProtocolRefused as exc:
+        _err(exc.render())
+    except SoftwareCompatibilityError as exc:
+        _err(exc.render())
+        traces = [f.debug for f in exc.report.failures if f.debug]
+        if traces:
+            _err("\n".join(traces) if debug else "Rerun with --debug to print the traceback.")
+    except ValueError as exc:
+        _err(str(exc))
+    return 1
+
+
+def _launch(loaded: LoadedProtocol, args: argparse.Namespace) -> int:
+    """Launch and report; a submission ``sbatch`` cannot make gives status 1."""
+    try:
+        result = launch(loaded, sinks=_sinks(args), debug=args.debug, dry_run=args.dry_run)
+    except SubmissionError as exc:
+        _err(str(exc))
+        return 1
+    return _report(loaded, result, args.dry_run)
+
+
+def _report(loaded: LoadedProtocol, result: LaunchResult, dry_run: bool) -> int:
+    """Print what a launch did; status 2 when a run failed."""
+    names = {row.identity: row.directory for row in loaded.runs}
+    for note in loaded.notes:
+        _out(note)
+    failed = 0
+    skipped = dict(result.skipped)
+    for ref, cause in result.runs.items():
+        if ref in skipped:
+            shown = f"left alone, {skipped[ref]}"
+        elif cause is None:
+            shown = "prepared" if dry_run else "submitted" if result.submitted else "not run"
+        else:
+            shown = cause.kind + (f" ({cause.detail})" if cause.detail else "")
+            if cause.generation is not None:
+                shown += f" at generation {cause.generation}"
+            failed += cause.kind in _FAILURES
+        _out(f"  {names.get(ref, ref.fingerprint[:12]):<10} {shown}")
+    for _, message in result.missing:
+        _out(f"  {message}")
+    if result.submitted:
+        _out(f"submitted Slurm job(s): {', '.join(result.submitted)}")
+    _out(f"{len(result.runs)} run(s) in {result.workdir}"
+         + (f", {failed} failed" if failed else ""))
+    return 2 if failed else 0
+
+
+def cmd_launch(args: argparse.Namespace) -> int:
+    """``MATE launch <proto.toml>``: load, check, schedule ([X] §24)."""
+    if args.dashboard:
+        _err(DASHBOARD_REFUSAL)
+        return 1
+    sweep = _sweep(args.sweep or [])
+    loaded = _load(lambda: load_protocol(Path(args.protocol), cwd=Path.cwd(),
+                                         execution_overrides=_overrides(args), sweep=sweep),
+                   args.debug)
+    if isinstance(loaded, int):
+        return loaded
+    return _launch(loaded, args)
+
+
+def _branch_target(text: str) -> tuple[Path, int | str]:
+    """``<run>@<generation>``."""
+    run, sep, generation = text.rpartition("@")
+    if not sep or not run:
+        raise UsageError(f"{text!r}: expected <run directory>@<generation>")
+    if generation == "end":
+        return Path(run), "end"
+    try:
+        g = int(generation)
+    except ValueError:
+        raise UsageError(f"{text!r}: the generation is an integer or 'end'") from None
+    if g < 0:
+        raise UsageError(f"{text!r}: the generation is an integer >= 0 or 'end'")
+    return Path(run), g
+
+
+def cmd_branch(args: argparse.Namespace) -> int:
+    """``MATE branch <run>@<g> --count N --root-seed S`` ([C] R21.3)."""
+    run, generation = _branch_target(args.target)
+    if args.root_seed == "fresh":
+        root_seed: int | str = "fresh"
+    else:
+        try:
+            root_seed = int(args.root_seed)
+        except ValueError:
+            raise UsageError(f"--root-seed {args.root_seed!r}: an integer or 'fresh'") from None
+    try:
+        raw = workdir.branch_protocol(run, generation, args.count, root_seed)  # type: ignore[arg-type]
+    except workdir.WorkdirError as exc:
+        _err(exc.message)
+        return exc.exit_status
+    overrides = _overrides(args)
+    if "workdir" not in overrides:
+        overrides["workdir"] = str(Path.cwd() / raw["protocol"]["name"])
+    loaded = _load(lambda: load_protocol(raw, cwd=Path.cwd(), execution_overrides=overrides),
+                   args.debug)
+    if isinstance(loaded, int):
+        return loaded
+    return _launch(loaded, args)
+
+
+def cmd_exec_run(args: argparse.Namespace) -> int:
+    """Hidden ``MATE exec-run <run directory>`` ([X] SC4); a run left alone gives status 0."""
+    try:
+        return exec_run(Path(args.directory), debug=args.debug)
+    except RunBusyError as exc:
+        _out(exc.message)
+        return 0
+
+
+# --- the workdir -------------------------------------------------------------------------------
+
+
+def _workdir_call(call: object) -> int:
+    """Print what a workdir reader returns; its errors carry their status."""
+    try:
+        text = call()  # type: ignore[operator]
+    except workdir.WorkdirError as exc:
+        _err(exc.message)
+        return exc.exit_status
+    _out(text)
+    return 0
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    """``MATE status <workdir>`` ([C] R21.4)."""
+    return _workdir_call(lambda: workdir.status(Path(args.workdir), args.protocol))
+
+
+def cmd_verify(args: argparse.Namespace) -> int:
+    """``MATE verify <workdir>`` ([C] R19.8): non-zero on any violation."""
+    try:
+        text, ok = workdir.verify_workdir(Path(args.workdir), args.protocol)
+    except workdir.WorkdirError as exc:
+        _err(exc.message)
+        return exc.exit_status
+    (_out if ok else _err)(text)
+    return 0 if ok else 1
+
+
+def cmd_runs(args: argparse.Namespace) -> int:
+    """``MATE runs <workdir>`` ([C] R21.4)."""
+    return _workdir_call(lambda: workdir.runs(Path(args.workdir), args.protocol))
+
+
+def cmd_diff(args: argparse.Namespace) -> int:
+    """``MATE diff <a> <b>`` ([C] R21.5)."""
+    return _workdir_call(lambda: workdir.diff(Path(args.a), Path(args.b)))
+
+
+def cmd_show(args: argparse.Namespace) -> int:
+    """``MATE show <run or workdir>`` (design §1.2)."""
+    return _workdir_call(lambda: workdir.show(Path(args.path), args.objective, args.subpop))
+
+
+def cmd_control(args: argparse.Namespace) -> int:
+    """``MATE control <run> <command> [value]`` (DD-3)."""
+    directory = Path(args.run)
+    if not (directory / "plan.json").is_file():
+        raise UsageError(f"{directory}: not a run directory (no plan.json)")
+    if args.command_name == "verbosity" and args.value is None:
+        raise UsageError("control verbosity: a value is required")
+    try:
+        seq = send_command(directory, args.command_name, args.value)
+    except ValueError as exc:
+        raise UsageError(str(exc)) from None
+    _out(f"command {seq} ({args.command_name}) sent to {directory}")
+    return 0
+
+
+# --- modules -----------------------------------------------------------------------------------
+
+
+def _modules() -> list[ModuleEntry]:
+    """Installed modules, one per (kind, name)."""
+    seen: dict[tuple[str, str], ModuleEntry] = {}
+    for e in installed_modules():
+        seen.setdefault((e.kind, e.name), e)
+    return list(seen.values())
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    """``MATE list``: installed modules and their software status ([X] S10)."""
+    entries = _modules()
+    if not entries:
+        _out("no module installed")
+        return 0
+    for e in entries:
+        report = check_software([ModuleRef(e.kind, e.name)], None)
+        if report.ok:
+            status = "ok"
+        else:
+            f = report.failures[0]
+            status = f"failed: requires {f.requirement}; found {f.found}"
+        _out(f"{e.kind:<7} {e.name:<24} {e.distribution} {e.distribution_version:<10} "
+             f"{status}")
+    return 0
+
+
+class _Module:
+    """A module as ``MATE matrix`` sees it: constructed on its declared defaults, or why not."""
+
+    def __init__(self, entry: ModuleEntry) -> None:
+        self.entry = entry
+        self.instance: object | None = None
+        self.specs: NormalisedSpecs | None = None
+        self.note = ""
+        report = check_software([ModuleRef(entry.kind, entry.name)], None)
+        if not report.ok:
+            f = report.failures[0]
+            self.note = f"software: requires {f.requirement}; found {f.found}"
+            return
+        cls = report.classes[(entry.kind, entry.name)]
+        missing = missing_parameters(cls)
+        if missing:
+            self.note = f"needs settings: {', '.join(missing)}"
+            return
+        try:
+            self.instance = construct_module(cls, declared_defaults(cls))
+        except ModuleConstructionError as exc:
+            self.note = exc.message
+            return
+        if entry.kind == "system":
+            owns = bool(getattr(self.instance.capabilities, "owns_loop", False))  # type: ignore[union-attr]
+            specs, refusals = normalise_specs(self.instance, owns_loop=owns)  # type: ignore[arg-type]
+            if specs is None:
+                self.note = "; ".join(r.message for r in refusals)
+                self.instance = None
+                return
+            self.specs = specs
+            if owns:
+                self.note = "owns its loop"
+            elif is_collective(specs):
+                self.note = "collective evaluation (not available in MATE 1.0.0)"
+
+    @property
+    def usable(self) -> bool:
+        """Whether cells can be computed for it."""
+        return self.instance is not None and not self.note
+
+
+def _cell(method: _Module, system: _Module) -> tuple[str, bool]:
+    """``(cell text, compatible)`` of one pair ([X] MX2)."""
+    specs = system.specs
+    assert specs is not None and specs.interface is not None
+    report = check_interface(specs.interface, specs.performance, specs.roles,
+                             method.instance.requirements,  # type: ignore[union-attr]
+                             system.instance.capabilities)  # type: ignore[union-attr]
+    if report.outcome is Outcome.INCOMPATIBLE:
+        dims = ", ".join(dict.fromkeys(m.dimension for m in report.mismatches))
+        return f"incompatible ({dims})", False
+    if report.outcome is Outcome.CONDITIONAL:
+        bounds = ", ".join(dict.fromkeys(f"{c.organ}.{c.bound}" for c in report.conditional))
+        return f"conditional ({bounds})", True
+    return "compatible", True
+
+
+_REQUIRED = frozenset({"P-META-MISSING", "P-SETTING-MISSING"})
+
+
+def _required(refusals: Sequence[Refusal]) -> str:
+    """``method: a, b; system: c``: the settings a smoke protocol lacks, by module."""
+    groups: dict[str, list[str]] = {}
+    for r in refusals:
+        kind = "system" if r.code == "P-SETTING-MISSING" else "method"
+        groups.setdefault(kind, []).append(r.where.rsplit(" ", 1)[-1])
+    return "; ".join(f"{kind}: {', '.join(names)}" for kind, names in groups.items())
+
+
+def _smoke(method: str, system: str, directory: Path) -> tuple[str, bool]:
+    """Two real generations of a pair ([X] MX2): ``(outcome, passed)``.
+
+    The outcome is ``ok``, the stop cause, or the settings the pair needs, declared without
+    a default: a protocol must write them, so the pair is not run, and that is no failure.
+    """
+    raw = {
+        "protocol": {"name": f"{method}-{system}"},
+        "system": {"module": system},
+        "method": {"module": method},
+        "replicates": {"count": 1, "root_seed": 0},
+        "stop": {"generations": 2},
+        "execution": {"executor": "serial", "retention": "minimal", "sinks": ["silent"],
+                      "workdir": str(directory / f"{method}-{system}")},
+    }
+    try:
+        loaded = load_protocol(raw, cwd=directory)
+    except ProtocolRefused as exc:
+        if all(r.code in _REQUIRED for r in exc.refusals):
+            return f"settings required ({_required(exc.refusals)})", True
+        return "refused (" + ", ".join(dict.fromkeys(r.code for r in exc.refusals)) + ")", False
+    except SoftwareCompatibilityError:
+        return "refused (software)", False
+    try:
+        result = launch(loaded)
+    except Exception as exc:   # a smoke test reports whatever breaks
+        return f"failed: {type(exc).__name__}: {exc}", False
+    causes = [c for c in result.runs.values() if c is not None]
+    if not causes:
+        return "not run", False
+    cause = causes[0]
+    if cause.kind == "criterion":
+        return "ok", True
+    return "failed: " + cause.kind + (f" ({cause.detail})" if cause.detail else ""), False
+
+
+def matrix(smoke: bool = False, entries: Sequence[ModuleEntry] | None = None
+           ) -> tuple[list[str], bool]:
+    """Compute the methods x systems table of installed modules ([X] §23.1).
+
+    Parameters
+    ----------
+    smoke : bool, default False
+        Run two generations of every compatible pair (serial executor, temporary
+        directory, seed 0, retention ``minimal``).
+    entries : sequence of ModuleEntry, optional
+        The modules; default every installed module.
+
+    Returns
+    -------
+    tuple
+        ``(lines, ok)``: a line per module that yields no cell (with the reason), then one
+        line per (method, system) pair; ``ok`` is ``False`` when a smoke run failed. A pair
+        whose modules declare settings without a default shows them as required and does
+        not fail.
+    """
+    entries = _modules() if entries is None else list(entries)
+    modules = [_Module(e) for e in entries]
+    methods = [m for m in modules if m.entry.kind == "method"]
+    systems = [m for m in modules if m.entry.kind == "system"]
+    lines: list[str] = []
+    for m in modules:
+        if not m.usable:
+            lines.append(f"{m.entry.kind} {m.entry.name}: {m.note}")
+    width_m = max((len(m.entry.name) for m in methods), default=6)
+    width_s = max((len(s.entry.name) for s in systems), default=6)
+    lines.append(f"{'method':<{width_m}}  {'system':<{width_s}}  result")
+    ok = True
+    with tempfile.TemporaryDirectory(prefix="MATE-matrix-") as tmp:
+        for m in methods:
+            for s in systems:
+                if not (m.usable and s.usable):
+                    cell = "-"
+                    compatible = False
+                else:
+                    cell, compatible = _cell(m, s)
+                if smoke and compatible:
+                    outcome, passed = _smoke(m.entry.name, s.entry.name, Path(tmp))
+                    ok = ok and passed
+                    cell += f"; smoke: {outcome}"
+                lines.append(f"{m.entry.name:<{width_m}}  {s.entry.name:<{width_s}}  {cell}")
+    return lines, ok
+
+
+def cmd_matrix(args: argparse.Namespace) -> int:
+    """``MATE matrix [--smoke]`` ([X] §23.1): status 2 when a smoke run fails."""
+    lines, ok = matrix(args.smoke)
+    _out("\n".join(lines))
+    return 0 if ok else 2
+
+
+def _settings(pairs: Sequence[str]) -> dict[str, Value]:
+    """``--set k=v`` -> settings, each value a TOML value."""
+    out: dict[str, Value] = {}
+    for pair in pairs:
+        key, sep, text = pair.partition("=")
+        if not sep or not key.strip():
+            raise UsageError(f"--set {pair!r}: expected <key>=<value>")
+        try:
+            out[key.strip()] = parse_toml_value(text)
+        except ValueError as exc:
+            raise UsageError(f"--set {pair!r}: {exc}") from None
+    return out
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    """``MATE check <module>`` ([X] §22): status 2 when a test fails (CF7)."""
+    # Imported here: the conformance suite is a heavy, separate part of the runtime.
+    from MATE.conformance import check_module
+
+    settings = _settings(args.set or [])
+    try:
+        results = check_module(args.module, kind=args.kind, system=args.system,
+                               method=args.method,
+                               settings=settings, tolerance=args.tolerance)
+    except (ProtocolRefused, SoftwareCompatibilityError) as exc:
+        _err(exc.render())
+        return 1
+    except ValueError as exc:
+        _err(str(exc))
+        return 1
+    failed = 0
+    for r in results:
+        failed += r.status == "fail"
+        _out(f"  {r.test:<15} {r.status:<5} {r.detail}".rstrip())
+    _out(f"{args.module}: {len(results)} test(s), {failed} failed")
+    return 2 if failed else 0
+
+
+def cmd_search(args: argparse.Namespace) -> int:
+    """``MATE search <text>`` ([X] RG5): one line per module, with the version installed by
+    default."""
+    try:
+        found = registry.search(args.text)
+    except registry.RegistryError as exc:
+        _err(str(exc))
+        return 1
+    for url in registry.registry_urls():
+        age = registry.cache_age(url)
+        if age is not None and age >= 86400:
+            _out(f"(registry {url}: cache from {age / 86400:.1f} day(s) ago, offline or not "
+                 f"updated)")
+    for e in found:
+        latest = e.latest()
+        version = latest.version if latest is not None else "withdrawn"
+        for m in e.modules:
+            organs = ", ".join(f"{k}: {v}" for k, v in m.organs.items())
+            owner = f" ({e.distribution})" if m.name != e.name else ""
+            _out(f"{m.kind:<7} {m.name:<20} {version:<12} {e.summary}{owner}"
+                 + (f"  [{organs}]" if organs else ""))
+    if not found:
+        _out(f"no module matches {args.text!r}")
+    return 0
+
+
+def cmd_install(args: argparse.Namespace) -> int:
+    """``MATE install <name>...`` ([X] RG6): pip, then the software check of the modules."""
+    status = 0
+    for name in args.names:
+        try:
+            done = registry.install(name)
+        except registry.RegistryError as exc:
+            _err(str(exc))
+            status = 1
+            continue
+        wanted = {canonicalize_name(d) for d in done.distributions}
+        refs = [ModuleRef(e.kind, e.name) for e in _modules()
+                if canonicalize_name(e.distribution) in wanted]
+        if not refs:
+            _out(f"installed {done.target}; it declares no MATE module")
+            continue
+        report = check_software(refs, None)
+        (_out if report.ok else _err)(render(report))
+        status = status or (0 if report.ok else 1)
+    return status
+
+
+# --- deferred ----------------------------------------------------------------------------------
+
+
+def cmd_replay(args: argparse.Namespace) -> int:
+    """``MATE replay``: refused in MATE 1.0.0 (design §1.3)."""
+    _err(REPLAY_REFUSAL)
+    return 1
+
+
+def cmd_dashboard(args: argparse.Namespace) -> int:
+    """``MATE dashboard``: refused in MATE 1.0.0 (design §1.3)."""
+    _err(DASHBOARD_REFUSAL)
+    return 1
+