labnotes 0.0.117__tar.gz → 0.0.119__tar.gz

{labnotes-0.0.117 → labnotes-0.0.119}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labnotes
-Version: 0.0.117
+Version: 0.0.119
 Summary: Browse experiment designs, notes, and run data from a folder.
 Project-URL: Repository, https://github.com/thekevinscott/labnotes
 Author-email: Kevin Scott <me@thekevinscott.com>
@@ -120,6 +120,8 @@ line per event instead.
 
 - `--concurrency N` runs N at a time (default 1).
 - `-e PATH` reads another file instead of `experiment.toml`.
+- `--PARAM=VALUE` runs only the cells where that param has that value, like
+  `--model=small`.
 - With runs going, Ctrl-C asks first. Enter (or a second Ctrl-C) leaves them
   running. `s` stops the running scripts and records their end, then kills any
   still going 5 seconds later. Escape goes back. SIGTERM stops them like `s`.

{labnotes-0.0.117 → labnotes-0.0.119}/README.md

@@ -95,6 +95,8 @@ line per event instead.
 
 - `--concurrency N` runs N at a time (default 1).
 - `-e PATH` reads another file instead of `experiment.toml`.
+- `--PARAM=VALUE` runs only the cells where that param has that value, like
+  `--model=small`.
 - With runs going, Ctrl-C asks first. Enter (or a second Ctrl-C) leaves them
   running. `s` stops the running scripts and records their end, then kills any
   still going 5 seconds later. Escape goes back. SIGTERM stops them like `s`.

{labnotes-0.0.117 → labnotes-0.0.119}/src/labnotes/context.md

@@ -151,6 +151,14 @@ going. Elsewhere, it prints a line per event instead.
   in `experiment.toml` sets it, then `concurrency` under `[experiments]` in
   `.labnotes.toml`, then 1.
 - `-e PATH` reads another file instead of `experiment.toml`.
+- `--PARAM=VALUE` runs only the cells where that param has that value, e.g.
+  `labnotes experiments NAME run --model=small`. PARAM must be a key in
+  `[params]` and VALUE one of its values, written as it shows in `runs`
+  (`true`, `2`); anything else is an error. One value per param; give several
+  params to narrow further (`--model=small --lang=en`). It changes only what
+  this `run` starts: counts, progress and `repeats` still cover the full
+  matrix, so a later plain `run` fills in the rest. Use it instead of editing
+  `experiment.toml` to run a slice.
 - `--timeout SECONDS` stops any one run still going after that many seconds:
   SIGTERM, then SIGKILL 5 seconds later. Its
   `run.json` gets `"error": "timed out after ..."` and `"ended_by": "timeout"`
@@ -180,4 +188,4 @@ going. Elsewhere, it prints a line per event instead.
   was retried counts as retried, not failed. If it can't
   start or reach the daemon, it prints the cause on one line and exits 1.
 
-`uvx labnotes server` serves the experiments, their markdown files and their runs as a local site, read from the same `.labnotes.toml`. An experiment's page shows its `experiment.toml` on one line, then a Runs tab with a table of its runs and a Notebooks tab with one tab per markdown file. Clicking a run opens its `stdout.log` and `stderr.log` together, followed as they're written until the run ends.
+`uvx labnotes server` serves the experiments, their markdown files and their runs as a local site, read from the same `.labnotes.toml`. An experiment's page shows its `experiment.toml` on one line, then a Runs tab with a table of its runs and a Notebooks tab with one tab per markdown file. For a matrix experiment, the Runs tab also has a grid (`?view=grid`): one cell per combination of the params that vary, with how many runs count toward `repeats`. Clicking a run opens its `stdout.log` and `stderr.log` together, followed as they're written until the run ends.

{labnotes-0.0.117 → labnotes-0.0.119}/src/labnotes/daemon/daemon_app.py

@@ -78,6 +78,7 @@ def daemon_app(config: LabnotesConfig) -> Starlette:
                 name,
                 None if path is None else Path(str(path)),
                 body.get("concurrency"),  # type: ignore[arg-type]
+                body.get("only"),  # type: ignore[arg-type]
             )
         except ValueError as error:
             return refuse(400, str(error))
@@ -103,6 +104,7 @@ def daemon_app(config: LabnotesConfig) -> Starlette:
                     lambda event: record({**event, "experiment": name}),
                     listen,
                     body.get("timeout"),  # type: ignore[arg-type]
+                    only=body.get("only"),  # type: ignore[arg-type]
                 )
             # Clients hear why the session ended; the daemon keeps serving.
             except Exception as failure:  # noqa: BLE001

{labnotes-0.0.117 → labnotes-0.0.119}/src/labnotes/daemon/remote_start.py

@@ -16,6 +16,7 @@ def remote_start(
     experiment_config: Path | None,
     concurrency: int | None,
     timeout: float | None = None,
+    only: dict[str, str] | None = None,
 ) -> Start:
     async def start(report: Report, listen: Listen) -> list[dict[str, object]]:
         try:
@@ -46,6 +47,7 @@ def remote_start(
                     else str(experiment_config.resolve()),
                     "concurrency": concurrency,
                     "timeout": timeout,
+                    "only": only,
                 },
             )
             if reply.status_code != 202:

{labnotes-0.0.117 → labnotes-0.0.119}/src/labnotes/experiments.py

@@ -8,6 +8,7 @@ from labnotes.create_experiment import create_experiment
 from labnotes.daemon.remote_start import remote_start
 from labnotes.utils.format_bytes import format_bytes
 from labnotes.load_config import load_config
+from labnotes.parse_subset import parse_subset
 from labnotes.print_rows import print_rows
 from labnotes.read_config import CONFIG_FILE
 from labnotes.runner.run_headless import run_headless
@@ -20,7 +21,9 @@ BYTES = ("memory", "size")
 
 @click.command(
     help="List experiments, show one, list its runs, or run it."
-    " `new [NAME]` creates one."
+    " `new [NAME]` creates one. With run, --PARAM=VALUE runs only the"
+    " matrix cells where that param has that value.",
+    context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
 )
 @click.argument("name", required=False)
 @click.argument("action", required=False, metavar="[runs|run]")
@@ -74,7 +77,13 @@ def experiments(
             click.echo(f"Created {path / 'experiment.toml'}")
             return
         case str(), "run":
-            start = remote_start(config, name, experiment_config, concurrency, timeout)
+            try:
+                only = parse_subset(ctx.args)
+            except ValueError as error:
+                raise click.UsageError(str(error)) from error
+            start = remote_start(
+                config, name, experiment_config, concurrency, timeout, only
+            )
             try:
                 if sys.stdout.isatty() and sys.stderr.isatty():
                     results = run_tui(start, name)
@@ -92,6 +101,8 @@ def experiments(
             passed = len(results) - failed - retried
             click.echo(f"{passed} passed, {failed} failed.{again}")
             return
+    if ctx.args:
+        raise click.UsageError(f"Unexpected {ctx.args[0]}. --PARAM=VALUE needs run.")
     if action not in (None, "runs"):
         raise click.UsageError(f"Unknown action {action}. Use runs or run.")
     if output_format is None and sys.stdout.isatty() and sys.stderr.isatty():

labnotes-0.0.119/src/labnotes/grid_cell.py

@@ -0,0 +1,21 @@
+from typing import TypedDict
+from urllib.parse import urlencode
+
+from labnotes.format_value import format_value
+
+
+class Cell(TypedDict):
+    values: dict[str, object]
+    runs: object
+    completed: object
+    href: str
+
+
+def grid_cell(values: dict[str, object], counts: dict[str, object]) -> Cell:
+    filters = [(f"f.{key}", format_value(value)) for key, value in values.items()]
+    return {
+        "values": values,
+        "runs": counts.get("runs", 0),
+        "completed": counts.get("completed", 0),
+        "href": f"?{urlencode(filters)}#runs",
+    }

{labnotes-0.0.117 → labnotes-0.0.119}/src/labnotes/load_experiment.py

@@ -17,6 +17,7 @@ from labnotes.list_runs import list_runs
 from labnotes.models import QueryParams
 from labnotes.nests_runs import nests_runs
 from labnotes.parse_run_view import parse_run_view
+from labnotes.pivot_runs import pivot_runs
 from labnotes.python_blocks import python_blocks
 from labnotes.render_markdown import render_markdown
 from labnotes.runs_view_command import runs_view_command
@@ -65,6 +66,19 @@ async def load_experiment(
         if nested
         else None
     )
+    matrix = summary["mode"] == "matrix"
+    gridded = matrix and params.getlist("view")[-1:] == ["grid"]
+    axes = {key: varies[key] for key in choices if len(varies[key]) > 1}
+    grid = (
+        pivot_runs(
+            axes,
+            await count_runs(
+                tables, source, str(summary["completed_run"]), group_by=list(axes)
+            ),
+        )
+        if gridded
+        else None
+    )
     return {
         "name": row["name"],
         "display_name": row["display_name"],
@@ -86,6 +100,7 @@ async def load_experiment(
         "runs_list": runs,
         "runs_live": await daemon_running(root),
         "run_groups": groups,
+        "run_grid": grid,
         "run_columns": shown,
         "run_view": view,
         "run_choices": choices,

labnotes-0.0.119/src/labnotes/parse_subset.py

@@ -0,0 +1,10 @@
+def parse_subset(args: list[str]) -> dict[str, str]:
+    only: dict[str, str] = {}
+    for arg in args:
+        param, equals, value = arg.removeprefix("--").partition("=")
+        if not arg.startswith("--") or not equals or not param:
+            raise ValueError(f"Unexpected {arg}. Pick params with --PARAM=VALUE.")
+        if param in only:
+            raise ValueError(f"--{param} given twice. Pass one value per param.")
+        only[param] = value
+    return only

labnotes-0.0.119/src/labnotes/pivot_runs.py

@@ -0,0 +1,43 @@
+from itertools import product
+from typing import TypedDict
+
+from labnotes.grid_cell import Cell, grid_cell
+
+
+class Row(TypedDict):
+    labels: list[object]
+    cells: list[Cell]
+
+
+class Grid(TypedDict):
+    row_keys: list[str]
+    column_key: str | None
+    columns: list[object]
+    rows: list[Row]
+
+
+def _key(value: object) -> object:
+    return int(value) if isinstance(value, bool) else value
+
+
+def pivot_runs(axes: dict[str, list[object]], counts: list[dict[str, object]]) -> Grid:
+    by_cell = {tuple(_key(row[key]) for key in axes): row for row in counts}
+    row_keys = [*axes]
+    column_key = row_keys.pop() if row_keys else None
+    columns: list[object] = [None] if column_key is None else axes[column_key]
+    rows: list[Row] = []
+    for labels in product(*(axes[key] for key in row_keys)):
+        cells = []
+        for column in columns:
+            values: dict[str, object] = dict(zip(row_keys, labels))
+            if column_key is not None:
+                values[column_key] = column
+            found = by_cell.get(tuple(_key(values[key]) for key in axes), {})
+            cells.append(grid_cell(values, found))
+        rows.append({"labels": list(labels), "cells": cells})
+    return {
+        "row_keys": row_keys,
+        "column_key": column_key,
+        "columns": columns,
+        "rows": rows,
+    }

labnotes-0.0.119/src/labnotes/runner/check_subset.py

@@ -0,0 +1,13 @@
+from labnotes.format_value import format_value
+
+
+def check_subset(params: dict[str, list[object]], only: dict[str, str]) -> None:
+    for param, value in only.items():
+        if param not in params:
+            declared = ", ".join(params) or "none"
+            raise ValueError(f"No param {param}. Params: {declared}.")
+        values = [format_value(option) for option in params[param]]
+        if value not in values:
+            raise ValueError(
+                f"No value {value} for {param}. Values: {', '.join(values)}."
+            )

labnotes-0.0.119/src/labnotes/runner/in_subset.py

@@ -0,0 +1,5 @@
+from labnotes.format_value import format_value
+
+
+def in_subset(cell: dict[str, object], only: dict[str, str]) -> bool:
+    return all(format_value(cell[param]) == value for param, value in only.items())

{labnotes-0.0.117 → labnotes-0.0.119}/src/labnotes/runner/prepare_experiment.py

@@ -1,6 +1,7 @@
 from pathlib import Path
 
 from labnotes.models import ExperimentConfig, LabnotesConfig
+from labnotes.runner.check_subset import check_subset
 from labnotes.runner.read_experiment_config import read_experiment_config
 from labnotes.tables.file_text import file_text
 
@@ -10,6 +11,7 @@ async def prepare_experiment(
     name: str,
     experiment_config: Path | None,
     concurrency: int | None,
+    only: dict[str, str] | None = None,
 ) -> tuple[ExperimentConfig, int]:
     if config.experiment not in (None, name):
         raise ValueError(
@@ -29,4 +31,6 @@ async def prepare_experiment(
         config.retries,
         config.defaults,
     )
+    if only:
+        check_subset(experiment.params, only)
     return experiment, experiment.concurrency if concurrency is None else concurrency

{labnotes-0.0.117 → labnotes-0.0.119}/src/labnotes/runner/run_experiment.py

@@ -13,6 +13,7 @@ from labnotes.models import (
 )
 from labnotes.retries import RETRY_EXIT_CODE, RETRY_SECONDS
 from labnotes.runner.execute_run import execute_run
+from labnotes.runner.in_subset import in_subset
 from labnotes.runner.invocation_meta import invocation_meta
 from labnotes.runner.new_param_run_id import new_param_run_id
 from labnotes.runner.new_stamped_run_id import new_stamped_run_id
@@ -36,6 +37,7 @@ async def run_experiment(
     listen: Listen,
     timeout: float | None = None,
     retry_seconds: float = RETRY_SECONDS,
+    only: dict[str, str] | None = None,
 ) -> list[dict[str, object]]:
     meta = None
     if experiment.meta is not None:
@@ -52,7 +54,10 @@ async def run_experiment(
     def taken(run: str) -> bool:
         return run in planned or run in existing
 
-    cells = plan_runs(param_grid(experiment.params), experiment.repeats, finished)
+    grid = [
+        cell for cell in param_grid(experiment.params) if in_subset(cell, only or {})
+    ]
+    cells = plan_runs(grid, experiment.repeats, finished)
     group = None
     match experiment.mode:
         case "adhoc" if len(cells) > 1:

{labnotes-0.0.117 → labnotes-0.0.119}/src/labnotes/static/labnotes.css

@@ -217,6 +217,22 @@ h3 {
 .new-note { font: inherit; color: var(--ink-2); background: none; border: 0; padding: 0 0.2rem; cursor: pointer; }
 .new-note:hover { color: var(--ink); }
 
+/* Runs grid: counted runs per combination of the params that vary. */
+.runs-grid { border-collapse: separate; border-spacing: 3px; font-size: 0.86rem; }
+.runs-grid th { font-family: var(--mono); font-size: 0.8rem; font-weight: 500; color: var(--ink-2); text-align: left; white-space: nowrap; padding: 0 0.75rem 0.3rem; }
+.runs-grid thead th { vertical-align: bottom; }
+.runs-grid th.label { color: var(--ink-3); }
+.runs-grid th.axis { font-family: var(--sans); font-size: 0.68rem; font-weight: 600; letter-spacing: 0.08em; text-transform: uppercase; color: var(--ink-3); border-bottom: 1px solid var(--rule); }
+.grid-cell { min-width: 6rem; padding: 0; background: var(--surface); border: 1px solid var(--rule); border-radius: 7px; }
+.grid-cell a { display: block; padding: 0.5rem 0.7rem 0.6rem; color: var(--ink); text-decoration: none; }
+.grid-cell:hover { border-color: var(--rule-strong); }
+.grid-cell .num { display: block; margin-bottom: 0.4rem; }
+.grid-cell .of { color: var(--ink-3); }
+.grid-cell.empty .num { color: var(--ink-3); }
+.grid-cell.done { border-color: color-mix(in srgb, var(--accent) 35%, var(--rule)); }
+.grid-cell .meter { display: block; height: 4px; border-radius: 2px; background: var(--track); overflow: hidden; }
+.grid-cell .meter-fill { display: block; height: 100%; background: var(--accent); }
+
 /* Runs table */
 .narrowed { color: var(--ink-2); font-size: 0.88rem; margin: 0 0 0.75rem; }
 .narrowed .clear { margin-left: 0.8rem; color: var(--ink-3); }
@@ -390,6 +406,12 @@ h3 {
 }
 .view-toggle button + button { border-left: 1px solid var(--rule-strong); }
 .view-toggle button[aria-pressed="true"] { background: var(--accent-soft); color: var(--ink); }
+#runs .view-toggle { display: flex; width: fit-content; float: none; margin: 0 0 0.75rem auto; }
+.view-toggle a { display: flex; padding: 0.3rem 0.55rem; background: var(--surface); color: var(--ink-3); }
+.view-toggle a + a { border-left: 1px solid var(--rule-strong); }
+.view-toggle a:hover { color: var(--ink); }
+.view-toggle a[aria-current="page"] { background: var(--accent-soft); color: var(--ink); }
+.view-toggle svg { width: 16px; height: 16px; fill: none; stroke: currentColor; stroke-width: 1.5; stroke-linecap: round; }
 
 /* Index as cards: the same table, laid out as a grid. */
 .ledger[data-view="cards"] { display: block; background: none; border: 0; border-radius: 0; overflow: visible; }

{labnotes-0.0.117 → labnotes-0.0.119}/src/labnotes/templates/experiment.html

@@ -51,6 +51,45 @@
   {% set nested = e.run_groups is not none %}
   {% set width = e.run_columns | length + (2 if nested else 1) %}
   {% set narrowed = view.status or view.filters or view.picked %}
+  {% set grid = e.run_grid %}
+  {% if e.mode == 'matrix' and e.runs %}
+  <nav class="view-toggle" aria-label="Runs view">
+    <a href="?#runs" title="Table" aria-label="Table"{% if not grid %} aria-current="page"{% endif %}><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M2 3.5h12M2 8h12M2 12.5h12"/></svg></a>
+    <a href="?view=grid#runs" title="Grid" aria-label="Grid"{% if grid %} aria-current="page"{% endif %}><svg viewBox="0 0 16 16" aria-hidden="true"><rect x="2" y="2" width="5" height="5" rx="1"/><rect x="9" y="2" width="5" height="5" rx="1"/><rect x="2" y="9" width="5" height="5" rx="1"/><rect x="9" y="9" width="5" height="5" rx="1"/></svg></a>
+  </nav>
+  {% endif %}
+  {% if grid %}
+  <div class="scroll">
+  <table class="runs-grid">
+    <thead>
+      {% if grid.column_key is not none %}
+      <tr class="axis-row">
+        {% if grid.row_keys %}<td colspan="{{ grid.row_keys | length }}"></td>{% endif %}
+        <th scope="colgroup" colspan="{{ grid.columns | length }}" class="axis">{{ grid.column_key }}</th>
+      </tr>
+      <tr>
+        {% for key in grid.row_keys %}<th scope="col" class="label">{{ key }}</th>{% endfor %}
+        {% for column in grid.columns %}<th scope="col">{{ column | value }}</th>{% endfor %}
+      </tr>
+      {% endif %}
+    </thead>
+    <tbody>
+      {% for row in grid.rows %}
+      <tr>
+        {% for label in row.labels %}<th scope="row">{{ label | value }}</th>{% endfor %}
+        {% for cell in row.cells %}
+        {% set goal = e.runs_per_cell or 1 %}
+        <td class="grid-cell{{ ' done' if cell.completed >= goal }}{{ ' empty' if not cell.runs }}" title="{% for key, value in cell['values'].items() %}{{ key }} = {{ value | value }}{{ ', ' if not loop.last }}{% endfor %}{{ ': ' if cell['values'] }}{{ cell.completed }} complete of {{ cell.runs }} recorded">
+          <a href="{{ cell.href }}"><span class="num">{{ cell.completed }}<span class="of">/{{ goal }}</span></span>
+          <span class="meter"><span class="meter-fill" style="width: {{ [cell.completed / goal * 100, 100] | min }}%"></span></span></a>
+        </td>
+        {% endfor %}
+      </tr>
+      {% endfor %}
+    </tbody>
+  </table>
+  </div>
+  {% else %}
   {% if narrowed %}<p class="narrowed"><span class="num">{{ e.runs_list | length }}</span> of <span class="num">{{ e.runs }}</span> <a class="clear" href="{{ '?sort=' ~ (view.sort | urlencode) ~ ('&order=desc' if view.descending else '') if view.sort else '?' }}#runs">Clear filters</a></p>{% endif %}
   {% if e.runs %}
   <form id="run-filters" method="get" action="#runs">
@@ -117,6 +156,7 @@
   {% else %}
   <p class="empty">No runs recorded yet.</p>
   {% endif %}
+  {% endif %}
 </section>
 {% endif %}
 <script src="{{ asset('experiment.js') }}" defer></script>

{labnotes-0.0.117 → labnotes-0.0.119}/testing-conventions.toml

@@ -13,7 +13,7 @@ reason = "last_stream is always the same str object taken from STREAMS, so is eq
 [[python.exempt]]
 path = "src/labnotes/load_experiment.py"
 rules = ["mutation"]
-lines = [61]
+lines = [61, 69]
 reason = "summarize_config returns mode matrix or adhoc; \"matrix\" <= \"adhoc\" is false like ==, and both are interned literals so is equals =="
 
 [[python.exempt]]
@@ -25,13 +25,13 @@ reason = "quiet counts up by one from zero, so it reaches IDLE_EXIT_SECONDS befo
 [[python.exempt]]
 path = "src/labnotes/daemon/daemon_app.py"
 rules = ["mutation"]
-lines = [132]
+lines = [134]
 reason = "start answers 202, 400, 409 or 500, so every status but 202 is above it: != equals >"
 
 [[python.exempt]]
 path = "src/labnotes/daemon/remote_start.py"
 rules = ["mutation"]
-lines = [49]
+lines = [51]
 reason = "the daemon answers a run with 202, 400, 409 or 500, so every status but 202 is above it: != equals >"
 
 [[python.exempt]]
@@ -67,7 +67,7 @@ reason = "WorkerState members are singletons, so is equals =="
 [[python.exempt]]
 path = "src/labnotes/runner/run_experiment.py"
 rules = ["mutation"]
-lines = [188, 269]
+lines = [193, 274]
 reason = "a retry is only scheduled below the budget and each one adds one, so tried never passes retries: >= equals ==; both sides are small ints, which CPython caches, so is equals =="
 
 [[python.exempt]]
@@ -79,5 +79,5 @@ reason = "exit_code is non-negative here; when bit 7 is set, - 128 equals ^ 128,
 [[python.exempt]]
 path = "src/labnotes/experiments.py"
 rules = ["mutation"]
-lines = [109]
+lines = [120]
 reason = "click hands back the \"json\" choice literal itself, so is not equals !="