MATE-runtime 1.0.0__py3-none-any.whl

MATE/cli/workdir.py

@@ -0,0 +1,571 @@
+"""Readers of a workdir and of its run directories, for the command line.
+
+``MATE status``, ``verify`` and ``runs`` read the run table ([C] R21.4, R19.8); ``MATE diff``
+compares blueprints ([C] R21.5); ``MATE show`` summarises run databases (design §1.2);
+:func:`branch_protocol` builds the protocol of ``MATE branch`` ([C] R21.3). Each reader
+returns the text the command prints, or raises :class:`WorkdirError`.
+"""
+
+import sqlite3
+import tomllib
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Literal
+
+from MATE.config import canonical
+from MATE.config.invariance import Violation, default_hold, shared_branch_mismatches, verify
+from MATE.config.model import Value, designates
+from MATE.config.runtable import PlannedRun, RunTable
+from MATE.errors import MATEError
+from MATE.launch import run_state
+from MATE.provenance import Provenance, read_provenance
+from MATE.storage import codec
+from MATE.storage.checkpoint import find_addressable
+from MATE.storage.lease import live_lease, read_lease, running
+from MATE.storage.rundir import RunDirectory
+
+__all__ = ["WorkdirError", "status", "verify_workdir", "runs", "diff", "show",
+           "branch_protocol"]
+
+
+class WorkdirError(MATEError):
+    """A workdir command cannot proceed.
+
+    Parameters
+    ----------
+    message : str
+    exit_status : int, default 3
+        1 for a refusal (an invariant violated, a best without a total order), 3 for a
+        usage error (no run table, an ambiguous protocol).
+    """
+
+    message: str
+    exit_status: int
+
+    def __init__(self, message: str, exit_status: int = 3) -> None:
+        self.message = message
+        self.exit_status = exit_status
+        super().__init__(message)
+
+
+# --- the run table ---------------------------------------------------------------------------
+
+
+def _table(workdir: Path) -> RunTable:
+    """The run table of a workdir; a usage error without one."""
+    path = Path(workdir)
+    if path.exists() and not path.is_dir():
+        if path.suffix == ".toml":
+            raise WorkdirError(f"{workdir}: a protocol file, not a workdir; give the directory "
+                               f"its launch wrote ([execution] workdir)")
+        raise WorkdirError(f"{workdir}: a file, not a workdir")
+    try:
+        table = RunTable.load(path)
+    except ValueError as exc:
+        raise WorkdirError(str(exc), 1) from None
+    if table is None:
+        raise WorkdirError(f"{workdir}: no run table (not a workdir)")
+    return table
+
+
+def _protocol(table: RunTable, protocol: str | None, required: bool) -> str | None:
+    """The protocol aggregated: given, implied by a single one, or mandatory (R18.9)."""
+    if protocol is not None:
+        if protocol not in table.protocols:
+            raise WorkdirError(f"protocol '{protocol}' is not in the run table (found: "
+                               f"{', '.join(table.protocols) or 'none'})")
+        return protocol
+    if len(table.protocols) == 1:
+        return next(iter(table.protocols))
+    if required and table.protocols:
+        raise WorkdirError(f"the workdir holds several protocols ({', '.join(table.protocols)});"
+                           f" name one with --protocol")
+    return None
+
+
+def _missing_state(row: PlannedRun, table: RunTable, workdir: Path) -> str | None:
+    """The R17.18 message of a chained run whose designated state will not exist."""
+    if row.parent is None:
+        return None
+    parent_ref, generation = row.parent
+    parent = table.find(parent_ref)
+    if parent is None:
+        return None
+    parent_dir = RunDirectory(Path(workdir) / parent.directory)
+    state, cause = run_state(parent_dir.path)
+    if state not in ("done", "failed") or find_addressable(parent_dir, generation) is not None:
+        return None
+    head = f"state {parent.directory}@{generation} missing"
+    if cause is None:
+        return f"{head}: parent did not run"
+    reason = cause.kind + (f": {cause.detail}" if cause.detail else "")
+    at = f" at generation {cause.generation}" if cause.generation is not None else ""
+    return f"{head}: parent stopped{at} ({reason})"
+
+
+def _state(row: PlannedRun, table: RunTable, workdir: Path) -> tuple[str, str]:
+    """``(state label, detail)`` of a row."""
+    directory = Path(workdir) / row.directory
+    missing = _missing_state(row, table, workdir)
+    if not directory.is_dir():
+        return ("missing state", missing) if missing else ("not started", "")
+    holder = live_lease(directory)
+    if holder is not None:
+        return "running", holder.describe()
+    state, cause = run_state(directory)
+    if cause is not None and cause.kind == "missing_state":
+        return "missing state", cause.detail
+    if state == "new" and missing:
+        return "missing state", missing
+    labels = {"new": "not started", "interrupted": "interrupted", "running": "running",
+              "done": "done", "failed": "failed"}
+    detail = ""
+    if cause is not None:
+        detail = cause.kind + (f": {cause.detail}" if cause.detail else "")
+        if cause.generation is not None:
+            detail += f" (generation {cause.generation})"
+    elif state == "interrupted" and (stale := read_lease(directory)) is not None:
+        detail = f"lease left behind: {stale.describe()}"   # killed without ending
+    return labels[state], detail
+
+
+def status(workdir: Path, protocol: str | None = None) -> str:
+    """Report the progress of a workdir's runs ([C] R21.4).
+
+    Parameters
+    ----------
+    workdir : Path
+    protocol : str, optional
+        Restrict to one protocol's rows; default every row.
+
+    Returns
+    -------
+    str
+        One line per run (state and stop cause; host, pid and age of the last beat for a
+        running run), then the counts per state; missing states are reported with their
+        cause (R17.18).
+
+    Raises
+    ------
+    WorkdirError
+        Without a run table, or for an unknown protocol.
+    """
+    table = _table(workdir)
+    name = _protocol(table, protocol, required=False) if protocol is not None else None
+    rows = table.rows(name)
+    counts: dict[str, int] = {}
+    lines = [f"workdir {workdir}" + (f", protocol {name}" if name else "")]
+    for row in rows:
+        label, detail = _state(row, table, workdir)
+        counts[label] = counts.get(label, 0) + 1
+        lines.append(f"  {row.directory:<10} {label:<13} {detail}".rstrip())
+    summary = ", ".join(f"{n} {label}" for label, n in counts.items())
+    lines.append(f"{len(rows)} run(s)" + (f": {summary}" if summary else ""))
+    return "\n".join(lines)
+
+
+# --- invariance --------------------------------------------------------------------------------
+
+
+def _hold(rows: Sequence[PlannedRun], workdir: Path,
+          provenances: Mapping[str, Provenance]) -> tuple[str, ...]:
+    """The held keys: ``[invariant] hold`` of the launch's protocol files, else the default."""
+    for row in rows:
+        sources = Path(workdir) / row.directory / "sources"
+        chain = [sources / "protocol.toml"]
+        chain += sorted(sources.glob("extends-*.toml"), key=lambda p: int(p.stem.split("-")[1]))
+        if not chain[0].is_file():
+            continue
+        for path in chain:
+            try:
+                with open(path, "rb") as handle:
+                    table = tomllib.load(handle)
+            except (OSError, tomllib.TOMLDecodeError):
+                break
+            hold = table.get("invariant", {}).get("hold")
+            if isinstance(hold, list):
+                return tuple(hold)
+        break
+    owns_loop = bool(provenances) and all(
+        not any(m.kind == "method" for m in p.modules) for p in provenances.values())
+    return default_hold(owns_loop)
+
+
+def _provenances(rows: Sequence[PlannedRun], workdir: Path) -> dict[str, Provenance]:
+    """Run directory -> provenance, for the runs that have one."""
+    out: dict[str, Provenance] = {}
+    for row in rows:
+        try:
+            out[row.directory] = read_provenance(Path(workdir) / row.directory)
+        except (OSError, ValueError):
+            continue
+    return out
+
+
+def _violation_lines(violations: Sequence[Violation]) -> list[str]:
+    """One block per violation: key, subject, each value with its runs."""
+    lines: list[str] = []
+    for v in violations:
+        lines.append(f"  {v.key} ({v.subject}) takes {len(v.found)} values:")
+        for value, dirs in v.found.items():
+            lines.append(f"    {value}: {', '.join(dirs)}")
+    return lines
+
+
+def _violations(workdir: Path, protocol: str | None
+                ) -> tuple[str | None, list[PlannedRun], tuple[str, ...], list[Violation]]:
+    """The protocol aggregated, its rows, the held keys and every violation."""
+    table = _table(workdir)
+    name = _protocol(table, protocol, required=True)
+    rows = table.rows(name)
+    provenances = _provenances(rows, workdir)
+    hold = _hold(rows, workdir, provenances)
+    found = verify(hold, provenances) + shared_branch_mismatches(rows, workdir)
+    return name, rows, hold, found
+
+
+def verify_workdir(workdir: Path, protocol: str | None = None) -> tuple[str, bool]:
+    """Check the held invariants over one protocol's runs ([C] R19.8).
+
+    Parameters
+    ----------
+    workdir : Path
+    protocol : str, optional
+        Mandatory when the workdir holds several protocols (R18.9).
+
+    Returns
+    -------
+    tuple
+        ``(report, ok)``: every violation (key, subject, each value with its runs) and the
+        shared-branch mismatches; ``ok`` is ``False`` when there is any.
+
+    Raises
+    ------
+    WorkdirError
+        Without a run table, or for a missing or unknown protocol.
+
+    Notes
+    -----
+    The held keys are those of ``[invariant] hold`` in the protocol files copied into the
+    first run's ``sources/``, else the default set (R19.5).
+    """
+    name, rows, hold, found = _violations(workdir, protocol)
+    head = f"protocol {name}: " if name else ""
+    if not found:
+        return f"{head}{len(rows)} run(s), no violation (held: {', '.join(hold)})", True
+    lines = [f"{head}{len(found)} violation(s)"] + _violation_lines(found)
+    return "\n".join(lines), False
+
+
+def _axis(value: Value) -> str:
+    """An axis value as written in a report."""
+    return codec.to_json(canonical.thaw(value))
+
+
+def runs(workdir: Path, protocol: str | None = None) -> str:
+    """Return the run table of one protocol: blueprint -> runs, axis values ([C] R21.4).
+
+    Parameters
+    ----------
+    workdir : Path
+    protocol : str, optional
+        Mandatory when the workdir holds several protocols.
+
+    Returns
+    -------
+    str
+        One line per run: directory, stage, short fingerprint, replicate, seed, state, axes.
+
+    Raises
+    ------
+    WorkdirError
+        On any invariant violation (exit status 1, R19.8), without a run table, or for a
+        missing or unknown protocol.
+    """
+    name, rows, _, found = _violations(workdir, protocol)
+    if found:
+        raise WorkdirError("\n".join([f"protocol {name}: invariants violated, no aggregation"]
+                                     + _violation_lines(found)), 1)
+    table = _table(workdir)
+    lines = [f"{'run':<10} {'stage':<10} {'blueprint':<12} {'rep':>4}  {'state':<13} "
+             f"{'seed':<40} axes"]
+    for row in rows:
+        label, _ = _state(row, table, workdir)
+        axes = ", ".join(f"{k} = {_axis(v)}" for k, v in row.axes.items())
+        lines.append(f"{row.directory:<10} {row.stage or '-':<10} "
+                     f"{row.identity.fingerprint[:12]:<12} {row.replicate:>4}  {label:<13} "
+                     f"{row.identity.seed!s:<40} {axes}".rstrip())
+    return "\n".join(lines)
+
+
+# --- diff --------------------------------------------------------------------------------------
+
+
+def _blueprints(path: Path) -> list[dict[str, Value]]:
+    """The flat blueprints of a run directory (one) or of a workdir (each, not superseded)."""
+    path = Path(path)
+    if (path / "blueprint.toml").is_file():
+        return [RunDirectory(path).read_blueprint()[0]]
+    table = _table(path)
+    seen: dict[str, dict[str, Value]] = {}
+    for row in table.rows(None):
+        fp = row.identity.fingerprint
+        file = path / row.directory / "blueprint.toml"
+        if fp not in seen and file.is_file():
+            seen[fp] = RunDirectory(path / row.directory).read_blueprint()[0]
+    if not seen:
+        raise WorkdirError(f"{path}: no recorded blueprint")
+    return list(seen.values())
+
+
+def _values(blueprints: Sequence[Mapping[str, Value]], key: str) -> list[str]:
+    """The distinct values of a path over blueprints, in order of first appearance."""
+    out: list[str] = []
+    for b in blueprints:
+        if key in b and (v := _axis(b[key])) not in out:
+            out.append(v)
+    return out
+
+
+def diff(a: Path, b: Path) -> str:
+    """Compare the blueprints of two run directories or workdirs ([C] R21.5).
+
+    Parameters
+    ----------
+    a, b : Path
+        Each a run directory or a workdir.
+
+    Returns
+    -------
+    str
+        The flat paths constant within each side whose value differs between the sides,
+        then (with a workdir) the paths that vary within a side with their value sets, then
+        the paths present on one side only. Sides with identical blueprints give
+        ``no difference``.
+
+    Raises
+    ------
+    WorkdirError
+        For a path that is neither a run directory nor a workdir.
+    """
+    left, right = _blueprints(a), _blueprints(b)
+    keys_l = list(dict.fromkeys(k for bp in left for k in bp))
+    keys_r = list(dict.fromkeys(k for bp in right for k in bp))
+    both = [k for k in keys_l if k in keys_r]
+    differ, vary = [], []
+    for k in both:
+        vl, vr = _values(left, k), _values(right, k)
+        full = all(k in bp for bp in left) and all(k in bp for bp in right)
+        if len(vl) == 1 and len(vr) == 1 and full:
+            if vl != vr:
+                differ.append(f"  {k}: {vl[0]} | {vr[0]}")
+        elif vl != vr or len(vl) > 1:
+            vary.append(f"  {k}: {{{', '.join(vl)}}} | {{{', '.join(vr)}}}")
+    only_l = [f"  {k} = {', '.join(_values(left, k))}" for k in keys_l if k not in keys_r]
+    only_r = [f"  {k} = {', '.join(_values(right, k))}" for k in keys_r if k not in keys_l]
+    lines: list[str] = [f"--- {a}", f"+++ {b}"]
+    for title, block in ((f"differ ({a} | {b}):", differ),
+                         ("vary within a side:", vary),
+                         (f"only in {a}:", only_l),
+                         (f"only in {b}:", only_r)):
+        if block:
+            lines.append(title)
+            lines.extend(block)
+    if len(lines) == 2:
+        lines.append("no difference")
+    return "\n".join(lines)
+
+
+# --- show --------------------------------------------------------------------------------------
+
+
+def _query(db: Path, sql: str, params: Sequence[object] = ()) -> list[tuple]:
+    """Run one read-only query on a run database."""
+    connection = sqlite3.connect(f"file:{db}?mode=ro", uri=True)
+    try:
+        return connection.execute(sql, tuple(params)).fetchall()
+    finally:
+        connection.close()
+
+
+def _number(x: object) -> str:
+    """A number as shown in a summary."""
+    return "-" if x is None else f"{x:.6g}" if isinstance(x, float) else str(x)
+
+
+def _show_run(directory: Path, objective: str | None, subpop: str | None) -> list[str]:
+    """The summary of one run."""
+    rundir = RunDirectory(directory)
+    db = rundir.database
+    if not db.is_file():
+        return [f"{rundir.name}: no database (not started)"]
+    lines = [f"{rundir.name}"]
+    try:
+        _, identity, stage = rundir.read_blueprint()
+        lines.append(f"  blueprint   {identity.fingerprint[:12]}, seed {identity.seed}"
+                     + (f", stage {stage}" if stage else ""))
+    except (OSError, ValueError):
+        pass
+    outcome = _query(db, "SELECT status, kind, detail, run_generation FROM outcome "
+                         "ORDER BY seq DESC LIMIT 1")
+    holder = live_lease(directory)
+    if holder is not None:
+        lines.append(f"  status      {running(holder)}")
+    elif outcome:
+        st, kind, detail, g = outcome[0]
+        at = f" at generation {g}" if g is not None else ""
+        lines.append(f"  status      {st}: {kind}" + (f" ({detail})" if detail else "") + at)
+    else:
+        lines.append("  status      no outcome recorded (interrupted)")
+    gens = _query(db, "SELECT run_generation, spent_episodes, spent_steps FROM generations "
+                      "ORDER BY run_generation DESC LIMIT 1")
+    if gens:
+        lines.append(f"  generations {gens[0][0] + 1}")
+        lines.append(f"  consumption {_number(gens[0][1])} episodes, {_number(gens[0][2])} steps")
+    try:
+        prov = read_provenance(directory)
+        modules = ", ".join(f"{m.kind} {m.name} {m.version}" for m in prov.modules)
+        lines.append(f"  versions    runtime {prov.runtime_version}, contract "
+                     f"{prov.contract_version}" + (f", {modules}" if modules else ""))
+    except (OSError, ValueError):
+        pass
+
+    paths = [p for (p,) in _query(db, "SELECT path FROM subpops ORDER BY seq")]
+    paths = list(dict.fromkeys(paths))
+    if subpop is not None:
+        chosen = [p for p in paths if designates(subpop, p)]
+        if not chosen:
+            raise WorkdirError(f"{rundir.name}: no subpopulation '{subpop}' (found: "
+                               f"{', '.join(paths) or 'none'})")
+    elif len(paths) > 1:
+        raise WorkdirError(f"{rundir.name}: several subpopulations ({', '.join(paths)}); "
+                           f"name one with --subpop", 1)
+    else:
+        chosen = paths
+    for path in chosen:
+        lines.extend(_show_subpop(db, rundir.name, path, objective))
+    return lines
+
+
+def _show_subpop(db: Path, run: str, path: str, objective: str | None) -> list[str]:
+    """Series per generation and best individual of one subpopulation."""
+    stats = _query(db, "SELECT run_generation, objective, best, mean FROM statistics "
+                       "WHERE subpop = ? ORDER BY seq", (path,))
+    objectives = list(dict.fromkeys(o for _, o, _, _ in stats))
+    if objective is not None and objective not in objectives:
+        raise WorkdirError(f"{run}: no objective '{objective}' (found: "
+                           f"{', '.join(objectives) or 'none'})")
+    if objective is None and len(objectives) >= 2:
+        raise WorkdirError(f"{run}: {len(objectives)} objectives ({', '.join(objectives)}): "
+                           f"the best individual has no total order; name one with "
+                           f"--objective", 1)
+    lines = [f"  subpopulation {path}"]
+    for name in objectives:
+        lines.append(f"    performance.{name}: generation, best, mean")
+        for g, o, best, mean in stats:
+            if o == name:
+                lines.append(f"      {g:>6}  {_number(best):>12}  {_number(mean):>12}")
+    if not objectives:
+        lines.append("    no performance statistics recorded")
+        return lines
+    name = objective if objective is not None else objectives[0]
+    index = objectives.index(name)
+    rows = _query(db, "SELECT e.genome_id, e.run_generation, e.objectives FROM evaluations e "
+                      "WHERE e.subpop = ? AND e.done = 1 AND e.objectives IS NOT NULL AND "
+                      "e.genome_id IN (SELECT genome_id FROM fronts WHERE scope = 'run' AND "
+                      "subpop = ?) ORDER BY e.rank", (path, path))
+    if not rows:
+        rows = _query(db, "SELECT genome_id, run_generation, objectives FROM evaluations "
+                          "WHERE subpop = ? AND done = 1 AND objectives IS NOT NULL "
+                          "ORDER BY rank", (path,))
+    best: tuple[float, str, object, list] | None = None
+    for gid, g, text in rows:
+        values = codec.from_json(text)
+        if index < len(values) and (best is None or values[index] > best[0]):
+            best = (values[index], gid, g, values)
+    if best is None:
+        lines.append(f"    best ({name}): no completed evaluation")
+    else:
+        shown = ", ".join(_number(v) for v in best[3])
+        lines.append(f"    best ({name}): genome {best[1]}, generation {best[2]}, "
+                     f"objectives ({shown})")
+    return lines
+
+
+def show(path: Path, objective: str | None = None, subpop: str | None = None) -> str:
+    """Summarise a run, or every run of a workdir (design §1.2).
+
+    Parameters
+    ----------
+    path : Path
+        A run directory or a workdir.
+    objective : str, optional
+        The objective by which the best individual is chosen; mandatory with K >= 2
+        ([X] ST4).
+    subpop : str, optional
+        The subpopulation shown; mandatory with several ([X] SQ1).
+
+    Returns
+    -------
+    str
+        Per run: stop cause (or who runs it), generations, consumption, versions, then per
+        subpopulation the performance statistics per generation and the best individual
+        (objectives are maximised).
+
+    Raises
+    ------
+    WorkdirError
+        Exit status 1 for a best without total order or several subpopulations unnamed;
+        3 for a path that is neither a run directory nor a workdir.
+    """
+    path = Path(path)
+    if (path / "blueprint.toml").is_file() or (path / "run.sqlite").is_file():
+        return "\n".join(_show_run(path, objective, subpop))
+    table = _table(path)
+    out: list[str] = []
+    for row in table.rows(None):
+        out.extend(_show_run(path / row.directory, objective, subpop))
+    return "\n".join(out) if out else f"{path}: no run"
+
+
+# --- branch ------------------------------------------------------------------------------------
+
+
+def branch_protocol(run_dir: Path, generation: int | Literal["end"], count: int,
+                    root_seed: int | Literal["fresh"]) -> dict:
+    """Build the protocol of ``MATE branch <run>@<generation>`` ([C] R21.3).
+
+    Parameters
+    ----------
+    run_dir : Path
+        The recorded run.
+    generation : int or "end"
+    count : int
+        ``[replicates] count``.
+    root_seed : int or "fresh"
+        ``[replicates] root_seed``.
+
+    Returns
+    -------
+    dict
+        The run's resolved blueprint as a raw protocol table, with ``[start] kind =
+        "from_run"``, ``run`` (the absolute run directory) and ``generation``, the
+        replicates, and ``[protocol] name = "<run directory name>@<generation>"``. No
+        ``[execution]`` table: the command line supplies it.
+
+    Raises
+    ------
+    WorkdirError
+        For a directory without ``blueprint.toml``.
+    """
+    rundir = RunDirectory(Path(run_dir).resolve())
+    try:
+        flat, _, _ = rundir.read_blueprint()
+    except (OSError, ValueError) as exc:
+        raise WorkdirError(f"{run_dir}: not a recorded run ({exc})") from None
+    raw = canonical.thaw(canonical.unflatten(flat))
+    assert isinstance(raw, dict)
+    raw["start"] = {"kind": "from_run", "run": str(rundir.path), "generation": generation}
+    raw["replicates"] = {**raw.get("replicates", {}), "count": count, "root_seed": root_seed}
+    raw["protocol"] = {"name": f"{rundir.name}@{generation}"}
+    return raw

MATE/compat/__init__.py

@@ -0,0 +1 @@
+"""Interface compatibility: the test between a system's specs and a method's requirements."""