MATE-runtime 1.0.0__py3-none-any.whl

MATE/__init__.py

@@ -0,0 +1,22 @@
+"""MATE runtime: runs, records and replays artificial evolution experiments.
+
+``import MATE`` re-exports the contract types, so that users need not tell ``MATE`` and
+``MATE_contract`` apart, and adds the Python form of a protocol (design §2.4). Every other
+runtime name is imported from its module (``MATE.conformance``, ``MATE.observation.records``,
+...).
+"""
+
+import importlib.metadata
+
+from MATE_contract import *  # noqa: F403
+from MATE_contract import __all__ as _contract_names
+
+from MATE.config.builders import Protocol, loops, method, protocol, replicates, sample, stop, system
+from MATE.errors import ProtocolRefused
+from MATE.run.plan import LaunchResult
+from MATE.run.run import Run
+
+__version__ = importlib.metadata.version("MATE-runtime")
+
+__all__ = [*_contract_names, "protocol", "method", "system", "loops", "stop", "replicates",
+           "sample", "Protocol", "ProtocolRefused", "Run", "LaunchResult"]

MATE/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m MATE``: the ``MATE`` command line."""
+
+import sys
+
+from MATE.cli import main
+
+sys.exit(main())

MATE/cli/__init__.py

@@ -0,0 +1,181 @@
+"""The ``MATE`` command line ([X] §24, [C] §21, design §3.14).
+
+:func:`main` parses the arguments and dispatches to :mod:`MATE.cli.commands`. Exit status:
+0 success, 1 refusal (software, interface, preconditions, deferred feature), 2 run
+failures, 3 usage error.
+"""
+
+import argparse
+import sys
+from importlib.metadata import version
+from typing import NoReturn
+
+from MATE.cli import commands
+
+__all__ = ["main", "build_parser"]
+
+_USAGE = 3
+_EXECUTORS = ("serial", "thread", "process", "vectorised", "accelerator")
+_VERBOSITIES = ("quiet", "normal", "verbose", "debug")
+
+
+class _Usage(Exception):
+    """An argument error, reported with exit status 3."""
+
+
+class _Parser(argparse.ArgumentParser):
+    """An argument parser whose errors give exit status 3 instead of exiting with 2."""
+
+    def error(self, message: str) -> NoReturn:
+        self.print_usage(sys.stderr)
+        raise _Usage(f"{self.prog}: error: {message}")
+
+
+def _execution(p: argparse.ArgumentParser, *, retention: bool = False) -> None:
+    """The ``[execution]`` overrides ([C] R21.1)."""
+    p.add_argument("--workers", type=int, help="number of workers")
+    p.add_argument("--executor", choices=_EXECUTORS, help="executor")
+    p.add_argument("--scheduler", choices=("slurm",), help="submit to a Slurm cluster")
+    p.add_argument("--verbosity", choices=_VERBOSITIES, help="terminal verbosity")
+    p.add_argument("--workdir", help="working directory of the runs")
+    p.add_argument("--sinks", help="comma-separated sink names, replacing [execution] sinks")
+    p.add_argument("--debug", action="store_true", help="debug mode: fail at the first error")
+    p.add_argument("--dry-run", action="store_true",
+                   help="prepare the workdir (and Slurm scripts) and run nothing")
+    if retention:
+        p.add_argument("--retention", choices=("minimal", "lineage", "full"))
+        p.add_argument("--checkpoint-every", type=int, dest="checkpoint_every")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser of the ``MATE`` command.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        One sub-command per command of [X] §24 and design §3.14; ``exec-run`` is hidden.
+    """
+    parser = _Parser(
+        prog="MATE",
+        description="MATE, the Modular Algorithmic Toolkit for Evolution.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"MATE-runtime {version('MATE-runtime')} (MATE-contract {version('MATE-contract')})",
+    )
+    sub = parser.add_subparsers(dest="command", metavar="<command>", parser_class=_Parser)
+
+    p = sub.add_parser("launch", help="launch a protocol")
+    p.add_argument("protocol", help="the protocol file")
+    _execution(p)
+    p.add_argument("--sweep", action="append", metavar="PATH=V1,V2",
+                   help="add an axis (repeatable)")
+    p.add_argument("--dashboard", action="store_true", help=argparse.SUPPRESS)
+    p.set_defaults(func=commands.cmd_launch)
+
+    for name, text, func in (("status", "progress and missing runs", commands.cmd_status),
+                             ("verify", "check the held invariants", commands.cmd_verify),
+                             ("runs", "blueprints -> runs, for analysis", commands.cmd_runs)):
+        p = sub.add_parser(name, help=text)
+        p.add_argument("workdir")
+        p.add_argument("--protocol", help="the protocol aggregated (several in the workdir)")
+        p.set_defaults(func=func)
+
+    p = sub.add_parser("diff", help="what differs between two blueprints")
+    p.add_argument("a", help="a run directory or a workdir")
+    p.add_argument("b", help="a run directory or a workdir")
+    p.set_defaults(func=commands.cmd_diff)
+
+    p = sub.add_parser("show", help="summary, series, best individual")
+    p.add_argument("path", help="a run directory or a workdir")
+    p.add_argument("--objective", help="objective of the best individual (K >= 2)")
+    p.add_argument("--subpop", help="subpopulation shown (several subpopulations)")
+    p.set_defaults(func=commands.cmd_show)
+
+    p = sub.add_parser("branch", help="branch from a recorded run")
+    p.add_argument("target", metavar="RUN@GENERATION")
+    p.add_argument("--count", type=int, required=True, help="number of replicates")
+    p.add_argument("--root-seed", required=True, dest="root_seed",
+                   help="root seed (an integer or 'fresh')")
+    _execution(p, retention=True)
+    p.set_defaults(func=commands.cmd_branch)
+
+    p = sub.add_parser("control", help="control a running run")
+    p.add_argument("run", help="the run directory")
+    p.add_argument("command_name", metavar="command",
+                   choices=("stop", "suspend", "resume", "checkpoint", "verbosity"))
+    p.add_argument("value", nargs="?", help="the verbosity, for 'verbosity'")
+    p.set_defaults(func=commands.cmd_control)
+
+    p = sub.add_parser("list", help="installed modules and their status")
+    p.set_defaults(func=commands.cmd_list)
+
+    p = sub.add_parser("matrix", help="compatibility table of methods x systems")
+    p.add_argument("--smoke", action="store_true", help="two real generations per pair")
+    p.set_defaults(func=commands.cmd_matrix)
+
+    p = sub.add_parser("check", help="conformance suite of a module")
+    p.add_argument("module")
+    p.add_argument("--kind", choices=("method", "system"),
+                   help="the module's kind, when a method and a system share its name")
+    p.add_argument("--system", help="system a method is checked against")
+    p.add_argument("--method", help="method a system's resume test runs with")
+    p.add_argument("--set", action="append", metavar="KEY=VALUE",
+                   help="a setting of the module (repeatable)")
+    p.add_argument("--tolerance", type=float, default=0.0)
+    p.set_defaults(func=commands.cmd_check)
+
+    p = sub.add_parser("search", help="search the module registry")
+    p.add_argument("text")
+    p.set_defaults(func=commands.cmd_search)
+
+    p = sub.add_parser("install", help="install modules from the registry")
+    p.add_argument("names", nargs="+", metavar="name",
+                   help="a registered name, optionally name==version, or a git+ URL")
+    p.set_defaults(func=commands.cmd_install)
+
+    p = sub.add_parser("replay", help="visual replay (not available in MATE 1.0.0)")
+    p.add_argument("args", nargs=argparse.REMAINDER)
+    p.set_defaults(func=commands.cmd_replay)
+
+    p = sub.add_parser("dashboard", help="terminal dashboard (not available in MATE 1.0.0)")
+    p.add_argument("args", nargs=argparse.REMAINDER)
+    p.set_defaults(func=commands.cmd_dashboard)
+
+    p = sub.add_parser("exec-run")   # hidden: no help, not listed ([X] SC4)
+    p.add_argument("directory")
+    p.add_argument("--debug", action="store_true")
+    p.set_defaults(func=commands.cmd_exec_run)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the ``MATE`` command line.
+
+    Parameters
+    ----------
+    argv : list of str, optional
+        The arguments; default ``sys.argv[1:]``.
+
+    Returns
+    -------
+    int
+        The exit status: 0 success, 1 refusal, 2 run failures, 3 usage error.
+    """
+    parser = build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except _Usage as exc:
+        print(exc, file=sys.stderr)
+        return _USAGE
+    except SystemExit as exc:   # --version, --help
+        return exc.code if isinstance(exc.code, int) else 0
+    if args.command is None:
+        parser.print_help()
+        return 0
+    try:
+        return args.func(args)
+    except commands.UsageError as exc:
+        print(f"MATE {args.command}: error: {exc}", file=sys.stderr)
+        return _USAGE