gbskernels 0.2.0__py3-none-any.whl

bench/throughput_end_to_end.py

@@ -0,0 +1,204 @@
+"""End-to-end (public-API) throughput: the GPU binding path vs the CPU backend.
+
+This measures the **public** call path -- `gbskernels.X_batched(stack,
+backend=...)` -- which for the GPU backend includes the numpy -> host_api ->
+H2D -> launch -> sync -> D2H -> numpy round trip on *every* call (the binding has
+no device-resident workspace; see the README "Known limitations"). It is
+deliberately separate from the kernel-only timing in `core/bench_kernels.cu`:
+together they bound how much of the cost is data movement vs compute.
+
+Benchmark hygiene (docs/DESIGN.md §9): n>=repeats timed runs per cell reported as
+median + IQR; **randomized execution order** across (backend, func, size) cells;
+a post-call **checksum honesty guard** that also cross-checks the GPU and CPU
+backends agree; raw data appended to `results/throughput/`; no composite score.
+
+Runs wherever the GPU extension is importable -- on a CUDA box it times the real
+device, on a host-shim build it times the CPU emulation (the timing is then only
+indicative, but the harness and the GPU/CPU agreement are validated). The
+accuracy-normalized vs-The-Walrus comparison lives in `bench/throughput.py`.
+
+    uv run python -m bench.throughput_end_to_end --batch 1024 --repeats 7
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import platform
+import random
+import sys
+import time
+from datetime import datetime, timezone
+from importlib.metadata import version
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+import gbskernels
+from bench import _inputs, _provenance
+
+DEFAULT_OUT = Path(__file__).resolve().parent.parent / "results" / "throughput"
+
+# func -> (batched fn, matrix sizes within the GPU kernels' caps). The matrices come from
+# the SINGLE shared workload generator (bench._inputs.bench_batch) so the GPU, CPU, and the
+# same-instance The Walrus baseline are all timed on the *same input* per (func, dim, regime)
+# -- an apples-to-apples, accuracy-normalizable comparison (docs/DESIGN.md §9). For the
+# torontonian the matrix dim is 2*modes.
+_SPECS = {
+    "perm": (gbskernels.perm_batched, [8, 12, 16]),
+    "haf": (gbskernels.haf_batched, [8, 12, 16]),
+    "lhaf": (gbskernels.lhaf_batched, [8, 12]),
+    "tor": (gbskernels.tor_batched, [8, 12, 16]),
+}
+
+
+def _checksum(v: np.ndarray) -> float:
+    """Order-independent magnitude checksum (the post-sync honesty guard)."""
+    return float(np.sum(np.abs(np.asarray(v, dtype=np.complex128))))
+
+
+def _quantile(sorted_vals: list[float], q: float) -> float:
+    x = q * (len(sorted_vals) - 1)
+    lo = int(x)
+    frac = x - lo
+    return (sorted_vals[lo] * (1 - frac) + sorted_vals[lo + 1] * frac
+            if lo + 1 < len(sorted_vals) else sorted_vals[lo])
+
+
+
+
+def run(batch: int, repeats: int, seed: int = 0, warmup: int = 2,
+        regime: str = "physical", out_dir: Path | None = None) -> tuple[dict[str, Any], Path]:
+    if not gbskernels.gpu_available():
+        raise RuntimeError(
+            "GPU extension not importable; build bindings/ (or the host-shim) first."
+        )
+    backends = ["gpu", "cpu"]
+    cells = [(eng, func, d, rep)
+             for eng in backends for func, (_, sizes) in _SPECS.items()
+             for d in sizes for rep in range(repeats)]
+    random.Random(seed).shuffle(cells)
+
+    # one shared workload per (func, dim) from bench._inputs (regime-aware): GPU, CPU, and
+    # the Walrus baseline all consume the SAME matrices -> same-input comparison.
+    stacks = {(func, d): _inputs.bench_batch(func, d, batch, regime, 1000 + d)
+              for func, (_, sizes) in _SPECS.items() for d in sizes}
+
+    # The CPU backend loops the Python reference, so it is timed on a capped
+    # sub-batch; evals/sec is per-eval and stays comparable to the GPU full batch.
+    cpu_cap = 128
+
+    # Warm-up policy (docs/DESIGN.md §9): each (backend, func, size) cell is run `warmup` times
+    # UNTIMED before any timed run, to reach steady-state GPU clocks and prime caches /
+    # the kernel JIT. The cold first run is never a headline number -- this is what
+    # tames the large cold-start IQRs. Warm-up runs are discarded.
+    for eng, func, d in {(e, f, dd) for e, f, dd, _ in cells}:
+        fn, n = _SPECS[func][0], (batch if eng == "gpu" else min(batch, cpu_cap))
+        for _ in range(warmup):
+            fn(stacks[(func, d)][:n], backend=eng)
+
+    raw: list[dict[str, Any]] = []
+    for eng, func, d, rep in cells:
+        fn = _SPECS[func][0]
+        n = batch if eng == "gpu" else min(batch, cpu_cap)
+        A = stacks[(func, d)][:n]
+        t0 = time.perf_counter()
+        out = fn(A, backend=eng)
+        elapsed = time.perf_counter() - t0  # GPU path syncs inside host_api
+        # checksum over the first cpu_cap results (the same matrices both backends
+        # compute) so GPU and CPU are comparable despite different timed batch sizes.
+        raw.append({"backend": eng, "func": func, "matrix_dim": d, "repeat": rep,
+                    "batch_timed": n, "seconds": elapsed,
+                    "evals_per_sec": n / elapsed if elapsed else float("inf"),
+                    "checksum": _checksum(out[:min(batch, cpu_cap)])})
+
+    summary = _summarize(raw)
+    # The public-path honesty gate: on a real device the GPU and CPU backends must agree to
+    # FP64 tolerance on every well-conditioned (physical) cell. A single disagreement means a
+    # kernel/binding bug, and NO timing from this run is publishable -- the caller (main / the
+    # GPU session) turns this into a non-zero exit. (Adversarial inputs may legitimately
+    # diverge; gate on the physical regime.)
+    all_agree = all(r["backends_agree"] for r in summary)
+    artifact = {
+        "kind": "throughput_end_to_end",
+        "created_utc": datetime.now(timezone.utc).isoformat(),
+        **_provenance.provenance(),  # commit + container_digest + hostname
+        "path": "public gbskernels.*_batched(backend=...) incl. H2D/launch/sync/D2H",
+        # build-flag provenance, not host OS: a no-GPU runner is "host-shim".
+        "gpu_backend": gbskernels.gpu_backend_kind(),
+        "env": {"platform": platform.platform(), "numpy": version("numpy")},
+        "params": {"batch": batch, "repeats": repeats, "warmup": warmup, "precision": "fp64",
+                   "regime": regime, "seed": seed,
+                   "metric": "evals/sec median + IQR; randomized cell order; "
+                             "warm-up discarded; checksum guard"},
+        "all_backends_agree": all_agree,
+        "summary": summary,
+        "raw": raw,
+    }
+    out_dir = Path(out_dir) if out_dir is not None else DEFAULT_OUT
+    out_dir.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    path = out_dir / f"throughput_e2e_{stamp}.json"
+    path.write_text(json.dumps(artifact, indent=2))
+    return artifact, path
+
+
+def _summarize(raw: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    rows = []
+    keys = sorted({(r["func"], r["matrix_dim"]) for r in raw})
+    for func, d in keys:
+        row: dict[str, Any] = {"func": func, "matrix_dim": d}
+        checks = {}
+        for eng in ("gpu", "cpu"):
+            eps = sorted(r["evals_per_sec"] for r in raw
+                         if r["backend"] == eng and r["func"] == func and r["matrix_dim"] == d)
+            cs = [r["checksum"] for r in raw
+                  if r["backend"] == eng and r["func"] == func and r["matrix_dim"] == d]
+            checks[eng] = cs[0] if cs else None
+            if eps:
+                row[eng] = {"evals_per_sec_median": _quantile(eps, 0.5),
+                            "evals_per_sec_iqr": _quantile(eps, 0.75) - _quantile(eps, 0.25)}
+        # GPU vs CPU agree to FP64 tolerance -- NOT bit-exact: the two backends use
+        # different determinant/linear-algebra routines, so mildly-conditioned
+        # inputs legitimately differ at ~1e-11 (a strict string check would flag it).
+        g, c = checks.get("gpu"), checks.get("cpu")
+        row["backends_agree"] = (g is not None and c is not None
+                                 and abs(g - c) <= 1e-7 * max(abs(c), 1e-300))
+        row["checksum_gpu"], row["checksum_cpu"] = g, c
+        rows.append(row)
+    return rows
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--batch", type=int, default=1024)
+    p.add_argument("--repeats", type=int, default=7)
+    p.add_argument("--seed", type=int, default=0)
+    p.add_argument("--out", type=Path, default=None)
+    p.add_argument("--warmup", type=int, default=2, help="untimed warm-up runs per cell")
+    p.add_argument("--regime", default="physical", choices=list(_inputs.BENCH_REGIMES),
+                   help="shared input family for every (func,dim) cell")
+    args = p.parse_args()
+    artifact, path = run(args.batch, args.repeats, args.seed, args.warmup,
+                         regime=args.regime, out_dir=args.out)
+    print(f"# end-to-end throughput ({artifact['gpu_backend']}) -> {path}")
+    print(f"#   public binding path; commit {artifact['commit']}; digest "
+          f"{artifact['container_digest']}; batch={args.batch} repeats={args.repeats} "
+          f"warmup={args.warmup} regime={args.regime}")
+    print(f"  {'func':>5} {'dim':>4}  {'gpu med':>12} {'cpu med':>12}  agree")
+    for r in artifact["summary"]:
+        gm = r.get("gpu", {}).get("evals_per_sec_median", float("nan"))
+        cm = r.get("cpu", {}).get("evals_per_sec_median", float("nan"))
+        print(f"  {r['func']:>5} {r['matrix_dim']:>4}  {gm:>12.3e} {cm:>12.3e}  "
+              f"{'ok' if r['backends_agree'] else 'MISMATCH'}")
+    # P0.8: a public-path checksum disagreement fails the run (non-zero exit), so the GPU
+    # session aborts instead of publishing a number from a backend mismatch.
+    if not artifact["all_backends_agree"]:
+        print("\n[FAIL] GPU and CPU disagree on a public-path cell -- no timing from this run "
+              "is publishable. Investigate the kernel; rerun on the physical regime.")
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

bench/throughput_gpu.py

@@ -0,0 +1,126 @@
+"""GPU throughput driver — runs the compiled CUDA timing harness with provenance.
+
+Thin wrapper (docs/DESIGN.md §9/sec.10) around ``core/build/bench_kernels`` (built by
+CMake under nvcc in a rented-GPU session). It runs the harness, captures the
+per-(func, size) evals/sec + honesty checksums it emits, attaches GPU/driver/clock
+provenance from ``nvidia-smi``, and writes an append-only artifact to
+``results/throughput/``. No composite "winner" number; raw data retained.
+
+This module does **not** compile or run anything on a GPU by itself — it requires
+that ``core/build/bench_kernels`` already exists (the session's manifest builds
+it). Invoked as ``python -m bench.throughput_gpu`` from ``scripts/session.py``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import platform
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from bench import _provenance
+
+REPO = Path(__file__).resolve().parent.parent
+DEFAULT_BIN = REPO / "core" / "build" / "bench_kernels"
+DEFAULT_OUT = REPO / "results" / "throughput"
+
+
+def _nvidia_smi() -> dict[str, Any]:
+    """GPU name, driver, and clocks for provenance (empty dict if unavailable)."""
+    q = ("name,driver_version,memory.total,memory.used,temperature.gpu,"
+         "clocks.sm,clocks.mem,clocks.max.sm,power.draw")
+    try:
+        out = subprocess.run(
+            ["nvidia-smi", f"--query-gpu={q}", "--format=csv,noheader"],
+            capture_output=True, text=True, check=True,
+        ).stdout.strip()
+        fields = [f.strip() for f in out.split(",")]
+        keys = ["name", "driver_version", "memory_total", "memory_used", "temperature_c",
+                "clock_sm", "clock_mem", "clock_sm_max", "power_draw"]
+        return dict(zip(keys, fields))
+    except Exception:
+        return {}
+
+
+def run(bench_bin: Path, batch: int, repeats: int, out_dir: Path) -> tuple[dict[str, Any], Path]:
+    if not bench_bin.exists():
+        raise FileNotFoundError(
+            f"{bench_bin} not found — build it first (cmake --build core/build) in the "
+            "rented-GPU session; this driver only runs the compiled harness."
+        )
+    proc = subprocess.run(
+        [str(bench_bin), str(batch), str(repeats)],
+        capture_output=True, text=True, check=True,
+    )
+
+    def _parse(line: str) -> dict[str, Any]:
+        # C printf emits bare nan/inf; rewrite to the JSON tokens json accepts so
+        # an anomalous row is recorded (as NaN/inf) rather than crashing the run.
+        import re
+        line = re.sub(r":\s*-inf\b", ": -Infinity", line)
+        line = re.sub(r":\s*inf\b", ": Infinity", line)
+        line = re.sub(r":\s*nan\b", ": NaN", line)
+        return json.loads(line)
+
+    rows = [_parse(line) for line in proc.stdout.splitlines() if line.strip().startswith("{")]
+
+    artifact = {
+        "kind": "throughput",
+        "tier": "gpu",
+        "created_utc": datetime.now(timezone.utc).isoformat(),
+        **_provenance.provenance(),  # commit + container_digest + hostname
+        "gpu": _nvidia_smi(),  # name/driver/memory + temperature & live clocks at run time
+        "host": {"platform": platform.platform()},
+        "params": {"batch": batch, "repeats": repeats, "precision": "fp64+dd",
+                   "metric": "evals_per_sec median + IQR over repeats; bench_kernels.cu "
+                             "warms each cell before timing; post-sync checksum/row"},
+        "methodology_caveats": (
+            "Toward docs/DESIGN.md §9 bar: the container digest + commit are now recorded and "
+            "the kernel timing is warmed up. Still single-instance per run (sweep the 4090 "
+            "AND a datacenter GPU across runs); the on-the-same-instance The Walrus "
+            "comparison runs in the GPU session (bench.walrus_baseline)."
+        ),
+        "rows": rows,
+    }
+    out_dir.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    gpu_tag = (artifact["gpu"].get("name", "gpu") or "gpu").replace(" ", "_")
+    path = out_dir / f"throughput_{gpu_tag}_{stamp}.json"
+    path.write_text(json.dumps(artifact, indent=2))
+    return artifact, path
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--bin", type=Path, default=DEFAULT_BIN)
+    p.add_argument("--batch", type=int, default=4096)
+    p.add_argument("--repeats", type=int, default=7)
+    p.add_argument("--out", type=Path, default=DEFAULT_OUT)
+    # accepted for manifest-compatibility with the CPU harness; the compiled
+    # binary fixes its own size grid, so these are informational here.
+    p.add_argument("--func", default=None)
+    p.add_argument("--sizes", default=None)
+    args = p.parse_args()
+
+    artifact, path = run(args.bin, args.batch, args.repeats, args.out)
+    print(f"# gpu throughput -> {path}")
+    g = artifact["gpu"]
+    print(f"#   GPU: {g.get('name','?')} | driver {g.get('driver_version','?')} | "
+          f"{g.get('temperature_c','?')}C | clk {g.get('clock_sm','?')}")
+    print(f"#   commit {artifact.get('commit')} | container {artifact.get('container_digest')} | "
+          f"batch={args.batch} repeats={args.repeats}")
+    print(f"  {'func':>9}  {'matrix_dim':>10}  {'evals/sec median':>17}  {'IQR':>11}")
+    for r in artifact["rows"]:
+        med = r.get("evals_per_sec_median", r.get("evals_per_sec_best", float("nan")))
+        iqr = r.get("evals_per_sec_iqr", float("nan"))
+        # the cooperative permanent rows carry a "groups" width; surface it so the
+        # perm-vs-perm_coop crossover is legible (raw rows keep the field regardless).
+        label = r["func"] + (f"/g{r['groups']}" if "groups" in r else "")
+        print(f"  {label:>9}  {r['matrix_dim']:>10}  {med:>17.3e}  {iqr:>11.2e}")
+
+
+if __name__ == "__main__":
+    main()

bench/tightness.py

@@ -0,0 +1,174 @@
+"""Certified-bound tightness distributions -- the numerics figure.
+
+For a CS/numerics reviewer, "the enclosure is always safe" is table stakes; the
+question is *how tight*. This measures, across ensembles rather than single
+worst cases, the distribution of three quantities for each certified function:
+
+  rel_bound  = bound / |value|           -- what the certificate PROMISES (≈ κ·u)
+  rel_err    = |value − exact| / |value|  -- what actually happened (vs mpmath)
+  tightness  = bound / max(|value−exact|, u·|value|)
+                                          -- the bound's slack over the true
+                                             error, floored at the fp64 ulp
+                                             (you cannot resolve error below u·|v|)
+
+The hard invariant (`rel_err ≤ rel_bound` on every sample -- the enclosure) is
+checked here too and must never fail. The story the distribution tells: on the
+physical ensemble the bound is tight (small, bounded tightness) and on the
+adversarial cancellation families it widens *correctly* -- because those inputs
+are genuinely ill-conditioned, and the certificate reports that honestly rather
+than hiding it. That is the difference between a rigorous certificate and a
+heuristic κ.
+
+    uv run python -m bench.tightness --samples 150 [--plot]
+
+Writes results/tightness/tightness_<utc>.json (per function×regime distribution
+stats + enclosure check) and, with --plot, results/tightness/tightness.png.
+CPU-only; references are mpmath. Sizes are kept modest so the reference is
+affordable -- the point is the distribution shape, not large N.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import time
+from pathlib import Path
+from typing import Any, Callable
+
+import numpy as np
+
+import cpu_ref
+import highprec_ref as href
+from bench import _inputs as inp
+from bench._provenance import provenance
+
+RESULTS = Path(__file__).resolve().parent.parent / "results" / "tightness"
+U = 2.0 ** -53
+
+# func -> (mpmath reference, {regime: sampler(seed) -> matrix})
+_CASES: dict[str, tuple[Callable, dict[str, Callable]]] = {
+    "perm": (href.permanent_mp, {
+        "physical": lambda s: inp.physical_permanent(10, s),
+        "adversarial": lambda s: inp.pm1_matrix(10, s),            # ±1: heavy cancellation
+    }),
+    "haf": (href.hafnian_mp, {
+        "physical": lambda s: inp.physical_hafnian(10, s),
+        "adversarial": lambda s: inp.cancellation_hafnian(10.0 ** -(3 + s % 9), s),
+    }),
+    "lhaf": (href.loop_hafnian_mp, {
+        "physical": lambda s: inp.physical_loop_hafnian(10, s),
+        "adversarial": lambda s: inp.cancellation_loop_hafnian(10.0 ** -(3 + s % 9), s),
+    }),
+    "tor": (href.torontonian_mp, {
+        "physical": lambda s: np.real(inp.physical_torontonian(4, s)),
+        "adversarial": lambda s: inp.cancellation_torontonian(10.0 ** -(1 + s % 6)),
+    }),
+}
+
+
+def _quantiles(x: np.ndarray) -> dict[str, float]:
+    q = np.quantile(x, [0.05, 0.25, 0.5, 0.75, 0.95])
+    return {"q05": float(q[0]), "q25": float(q[1]), "median": float(q[2]),
+            "q75": float(q[3]), "q95": float(q[4]), "max": float(x.max()),
+            "min": float(x.min())}
+
+
+def _collect(func: str, regime: str, gen: Callable, ref: Callable,
+             samples: int) -> dict[str, Any]:
+    rel_bound, rel_err, tight = [], [], []
+    enclosure_fails = 0
+    for s in range(samples):
+        A = gen(s)
+        value, bound = cpu_ref.certified(func, A)
+        av = abs(value)
+        if av == 0.0 or not np.isfinite(bound):
+            continue
+        exact = complex(ref(A, dps=50))
+        err = abs(complex(value) - exact)
+        rb, re = bound / av, err / av
+        if re > rb * (1 + 1e-9):           # the enclosure invariant -- must hold
+            enclosure_fails += 1
+        rel_bound.append(rb)
+        rel_err.append(re)
+        tight.append(bound / max(err, U * av))
+    return {"n": len(tight), "enclosure_fails": enclosure_fails,
+            "rel_bound": _quantiles(np.array(rel_bound)),
+            "rel_err": _quantiles(np.array(rel_err)),
+            "tightness": _quantiles(np.array(tight)),
+            "_raw_tightness": [float(x) for x in tight],
+            "_raw_rel_bound": [float(x) for x in rel_bound]}
+
+
+def run(samples: int) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    print(f"{'func/regime':>18} {'N':>4} {'encl':>5} "
+          f"{'rel_bound med':>14} {'rel_err med':>12} {'tightness med (q95)':>22}")
+    for func, (ref, regimes) in _CASES.items():
+        out[func] = {}
+        for regime, gen in regimes.items():
+            d = _collect(func, regime, gen, ref, samples)
+            out[func][regime] = d
+            t = d["tightness"]
+            print(f"{func + '/' + regime:>18} {d['n']:>4} {d['enclosure_fails']:>5} "
+                  f"{d['rel_bound']['median']:>14.2e} {d['rel_err']['median']:>12.2e} "
+                  f"{t['median']:>10.1f} ({t['q95']:.1f})")
+    total_fails = sum(out[f][r]["enclosure_fails"]
+                      for f in out for r in out[f])
+    print(f"\nenclosure violations across all ensembles: {total_fails} "
+          f"(MUST be 0 -- the certificate is only meaningful if it never under-claims)")
+    return {"kind": "certified_tightness", **provenance(),
+            "params": {"samples": samples, "sizes": "perm/haf/lhaf n=10, tor 2n=8"},
+            "enclosure_violations_total": total_fails, "by_function": out}
+
+
+def plot(art: dict[str, Any], path: Path) -> None:
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    funcs = list(art["by_function"])
+    fig, ax = plt.subplots(figsize=(9, 5))
+    positions, data, colors, labels = [], [], [], []
+    pos = 0
+    for func in funcs:
+        for regime, col in (("physical", "#2a7"), ("adversarial", "#d63")):
+            raw = art["by_function"][func][regime].get("_raw_tightness", [])
+            if raw:
+                positions.append(pos)
+                data.append(np.log10(np.maximum(raw, 1.0)))
+                colors.append(col)
+                labels.append(f"{func}\n{regime}")
+                pos += 1
+        pos += 0.6
+    parts = ax.violinplot(data, positions=positions, showmedians=True, widths=0.8)
+    for pc, c in zip(parts["bodies"], colors):
+        pc.set_facecolor(c)
+        pc.set_alpha(0.6)
+    ax.set_xticks(positions)
+    ax.set_xticklabels(labels, fontsize=8)
+    ax.set_ylabel(r"$\log_{10}$ tightness  =  bound / max(actual error, $u\,|v|$)")
+    ax.set_title("Certified-bound tightness distribution (rigorous, never < 1)\n"
+                 "physical ensembles tight; adversarial families widen honestly")
+    ax.axhline(0, color="k", lw=0.5, ls=":")
+    fig.tight_layout()
+    fig.savefig(path, dpi=140)
+    print(f"-> {path}")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--samples", type=int, default=150)
+    ap.add_argument("--plot", action="store_true")
+    args = ap.parse_args()
+    art = run(args.samples)
+    RESULTS.mkdir(parents=True, exist_ok=True)
+    stamp = time.strftime("%Y%m%dT%H%M%SZ", time.gmtime())
+    out = RESULTS / f"tightness_{stamp}.json"
+    out.write_text(json.dumps(art, indent=1))
+    print(f"-> {out}")
+    if args.plot:
+        plot(art, RESULTS / "tightness.png")
+
+
+if __name__ == "__main__":
+    main()

bench/walrus_baseline.py

@@ -0,0 +1,148 @@
+"""Same-instance The Walrus baseline (docs/DESIGN.md §9 / the reproducibility contract).
+
+Times Xanadu's The Walrus (the canonical CPU reference) for the four functions on the
+**same GPU instance** that ran our kernels, with the same hygiene -- warm-up, median +
+IQR over repeats, randomized cell order, the shared provenance block -- so the
+GPU-vs-The-Walrus comparison is apples-to-apples on one machine (not our GPU on a
+rented box vs The Walrus on a laptop). The crossover analysis (`bench.crossover`) pairs
+this artifact with the kernel throughput artifact from the same session.
+
+The Walrus is one-evaluation-at-a-time, so each cell loops a small batch and reports
+per-eval evals/sec, directly comparable to our batched per-eval rate. Runs wherever
+``thewalrus`` is importable (the GPU session installs it); skips with a clear error
+otherwise.
+
+    uv run python -m bench.walrus_baseline --batch 64 --repeats 7
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import platform
+import random
+import time
+from datetime import datetime, timezone
+from importlib.metadata import version
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from bench import _inputs, _provenance
+
+# The Walrus's high-level paths use np.find_common_type (removed in NumPy 2.0); the
+# low-level perm/hafnian/tor used here do not, but apply the NumPy-2.0 compat shim
+# defensively so the import + any internal use is safe.
+if not hasattr(np, "find_common_type"):
+    np.find_common_type = lambda a, s: np.result_type(*a, *s)
+
+DEFAULT_OUT = Path(__file__).resolve().parent.parent / "results" / "throughput"
+
+# func -> (The Walrus call, matrix sizes). The matrices come from the SAME shared generator
+# (bench._inputs.bench_batch) and the SAME seed convention as bench.throughput_end_to_end, so
+# The Walrus is timed on the *identical inputs* as our GPU/CPU path -- a same-input baseline
+# (docs/DESIGN.md §9). For the torontonian the matrix dim is 2*modes (so [8,12,16] = 4..8 modes).
+_SPECS: dict[str, Any] = {
+    "perm": (lambda tw, M: tw.perm(M), [8, 12, 16]),
+    "haf": (lambda tw, M: tw.hafnian(M), [8, 12, 16]),
+    "lhaf": (lambda tw, M: tw.hafnian(M, loop=True), [8, 12]),
+    "tor": (lambda tw, M: tw.tor(np.real(M)), [8, 12, 16]),
+}
+
+
+def _quantile(xs: list[float], q: float) -> float:
+    s = sorted(xs)
+    x = q * (len(s) - 1)
+    lo = int(x); frac = x - lo
+    return s[lo] * (1 - frac) + s[lo + 1] * frac if lo + 1 < len(s) else s[lo]
+
+
+def run(batch: int, repeats: int, seed: int = 0, warmup: int = 2,
+        regime: str = "physical", out_dir: Path | None = None) -> tuple[dict[str, Any], Path]:
+    try:
+        import thewalrus as tw
+    except Exception as e:  # pragma: no cover - depends on the box
+        raise RuntimeError(
+            "thewalrus is not importable; install it on the instance to record the "
+            "same-instance baseline (the GPU session does this)."
+        ) from e
+
+    cells = [(func, d, rep) for func, (_, sizes) in _SPECS.items()
+             for d in sizes for rep in range(repeats)]
+    random.Random(seed).shuffle(cells)
+
+    # the SAME shared workload (and seed convention 1000+d) as throughput_end_to_end, so the
+    # Walrus baseline is timed on the identical matrices our GPU/CPU path is.
+    mats = {(func, d): list(_inputs.bench_batch(func, d, batch, regime, 1000 + d))
+            for func, (_, sizes) in _SPECS.items() for d in sizes}
+
+    call = {func: _SPECS[func][0] for func in _SPECS}
+    # warm-up (untimed) per distinct cell -- steady state before timing
+    for func, d in {(f, dd) for f, dd, _ in cells}:
+        for _ in range(warmup):
+            for M in mats[(func, d)][: min(batch, 8)]:
+                call[func](tw, M)
+
+    raw: list[dict[str, Any]] = []
+    for func, d, rep in cells:
+        batch_mats = mats[(func, d)]
+        t0 = time.perf_counter()
+        s = 0.0
+        for M in batch_mats:
+            s += abs(complex(call[func](tw, M)))
+        elapsed = time.perf_counter() - t0
+        raw.append({"func": func, "matrix_dim": d, "repeat": rep, "batch": batch,
+                    "seconds": elapsed, "evals_per_sec": batch / elapsed if elapsed else float("inf"),
+                    "checksum": s})
+
+    rows = []
+    for func, (_, sizes) in _SPECS.items():
+        for d in sizes:
+            eps = [r["evals_per_sec"] for r in raw if r["func"] == func and r["matrix_dim"] == d]
+            rows.append({"func": func, "matrix_dim": d,
+                         "evals_per_sec_median": _quantile(eps, 0.5),
+                         "evals_per_sec_iqr": _quantile(eps, 0.75) - _quantile(eps, 0.25)})
+
+    artifact = {
+        "kind": "walrus_baseline",
+        "created_utc": datetime.now(timezone.utc).isoformat(),
+        **_provenance.provenance(),
+        "library": "thewalrus", "library_version": version("thewalrus"),
+        "metric": "per-eval evals/sec (The Walrus, one-at-a-time, looped over a batch); "
+                  "median + IQR; randomized cell order; warm-up discarded",
+        "params": {"batch": batch, "repeats": repeats, "warmup": warmup, "precision": "fp64",
+                   "regime": regime, "seed": seed},
+        "env": {"platform": platform.platform(), "numpy": version("numpy")},
+        "rows": rows, "raw": raw,
+    }
+    out_dir = Path(out_dir) if out_dir is not None else DEFAULT_OUT
+    out_dir.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    path = out_dir / f"walrus_baseline_{stamp}.json"
+    path.write_text(json.dumps(artifact, indent=2))
+    return artifact, path
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--batch", type=int, default=64)
+    p.add_argument("--repeats", type=int, default=7)
+    p.add_argument("--warmup", type=int, default=2)
+    p.add_argument("--regime", default="physical", choices=list(_inputs.BENCH_REGIMES),
+                   help="shared input family (same generator as throughput_end_to_end)")
+    p.add_argument("--out", type=Path, default=None)
+    args = p.parse_args()
+    artifact, path = run(args.batch, args.repeats, warmup=args.warmup,
+                         regime=args.regime, out_dir=args.out)
+    print(f"# The Walrus baseline (same instance) -> {path}")
+    print(f"#   thewalrus {artifact['library_version']}; commit {artifact['commit']}; "
+          f"container {artifact['container_digest']}")
+    print(f"  {'func':>5} {'dim':>4}  {'evals/sec median':>17}  {'IQR':>11}")
+    for r in artifact["rows"]:
+        print(f"  {r['func']:>5} {r['matrix_dim']:>4}  {r['evals_per_sec_median']:>17.3e}  "
+              f"{r['evals_per_sec_iqr']:>11.2e}")
+
+
+if __name__ == "__main__":
+    main()