gbskernels 0.2.0__py3-none-any.whl

bench/plot_crossover.py

@@ -0,0 +1,94 @@
+"""Render the batch-size crossover curves from a sweep artifact (docs/DESIGN.md §9 figures).
+
+Reads a ``crossover_*.json`` (from ``bench.crossover``) and draws, per (function,
+matrix size), GPU vs CPU per-eval rate against batch size on log-log axes, marking the
+crossover batch. These are the paper figures for the batched-throughput thesis.
+
+matplotlib is imported lazily and is **optional** -- without it (or with ``--data-only``)
+the script emits the plot data as CSV so the curves are reproducible regardless. The
+package keeps numpy/mpmath as its only hard deps; matplotlib is a dev/plotting extra.
+
+    uv run python -m bench.plot_crossover results/throughput/crossover_*.json -o fig/
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def _load(path: Path) -> dict[str, Any]:
+    return json.loads(Path(path).read_text())
+
+
+def write_csv(artifact: dict[str, Any], out: Path) -> Path:
+    out.parent.mkdir(parents=True, exist_ok=True)
+    with out.open("w", newline="") as f:
+        w = csv.writer(f)
+        w.writerow(["func", "matrix_dim", "batch", "gpu_median", "gpu_iqr", "cpu_median", "cpu_iqr",
+                    "walrus_median", "crossover_batch_vs_cpu", "crossover_batch_vs_walrus",
+                    "achieved_rel_err_fp64", "precision_tier"])
+        for s in artifact["series"]:
+            for p in s["points"]:
+                w.writerow([s["func"], s["matrix_dim"], p["batch"], p.get("gpu_median"), p.get("gpu_iqr"),
+                            p.get("cpu_median"), p.get("cpu_iqr"), s.get("walrus_median"),
+                            s.get("crossover_batch_vs_cpu"), s.get("crossover_batch_vs_walrus"),
+                            s.get("achieved_rel_err_fp64"), s.get("precision_tier")])
+    return out
+
+
+def plot(artifact: dict[str, Any], out_dir: Path) -> list[Path]:
+    try:
+        import matplotlib
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+    except Exception:
+        print("# matplotlib not available -- emitting CSV only "
+              "(pip install matplotlib, or use the CSV).", file=sys.stderr)
+        return [write_csv(artifact, out_dir / "crossover.csv")]
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    funcs = sorted({s["func"] for s in artifact["series"]})
+    written = []
+    for func in funcs:
+        fig, ax = plt.subplots(figsize=(6, 4))
+        for s in (s for s in artifact["series"] if s["func"] == func):
+            bs = [p["batch"] for p in s["points"]]
+            ax.plot(bs, [p["gpu_median"] for p in s["points"]], "-o", label=f"GPU d={s['matrix_dim']}")
+            ax.plot(bs, [p["cpu_median"] for p in s["points"]], "--s", label=f"CPU d={s['matrix_dim']}")
+            # the same-instance Walrus baseline is batch-independent -> a horizontal line
+            wv = s.get("walrus_median")
+            if wv is not None:
+                ax.axhline(wv, ls="-.", alpha=0.4, label=f"Walrus d={s['matrix_dim']}")
+            if s.get("crossover_batch_vs_cpu"):
+                ax.axvline(s["crossover_batch_vs_cpu"], color="grey", ls=":", alpha=0.5)
+        ax.set_xscale("log"); ax.set_yscale("log")
+        ax.set_xlabel("batch size"); ax.set_ylabel("evals / sec (per eval)")
+        ax.set_title(f"{func} -- GPU vs CPU throughput crossover\n"
+                     f"commit {artifact.get('commit')} | {artifact.get('gpu_backend')}")
+        ax.legend(fontsize=7); ax.grid(True, which="both", alpha=0.3)
+        p = out_dir / f"crossover_{func}.png"
+        fig.tight_layout(); fig.savefig(p, dpi=130); plt.close(fig)
+        written.append(p)
+    written.append(write_csv(artifact, out_dir / "crossover.csv"))  # always emit the data too
+    return written
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("artifact", type=Path, help="a crossover_*.json from bench.crossover")
+    p.add_argument("-o", "--out", type=Path, default=Path("fig"))
+    p.add_argument("--data-only", action="store_true", help="emit CSV only, skip plotting")
+    args = p.parse_args()
+    art = _load(args.artifact)
+    outs = [write_csv(art, args.out / "crossover.csv")] if args.data_only else plot(art, args.out)
+    for o in outs:
+        print(f"wrote {o}")
+
+
+if __name__ == "__main__":
+    main()

bench/repeated_ab.py

@@ -0,0 +1,127 @@
+"""R4 device A/B: the repeated-row sieve kernel vs the expanded hafnian kernel.
+
+Times, on the SAME device through the public path (both pay H2D/launch/D2H),
+the two ways of evaluating the identical workload — a batch of loop hafnians of
+``A`` expanded by collision patterns ``(q, ..., q)``:
+
+* ``gbskernels.lhaf_repeated(A, 0, reps, backend="gpu")`` — the sieve
+  (``core/repeated.cu``), cost ``prod(q+1)`` per element;
+* ``gbskernels.haf_batched(expanded, backend="gpu")`` — the shipped power-trace
+  kernel on the ``N = M*q`` expansion, cost ``2^(N/2)`` — only where ``N`` is
+  within its cap (the rows above the cap are the capability gap the sieve
+  closes, reported as such, not as a timing).
+
+Hygiene per docs/benchmark_protocol.md: warm-up before timing, raw repeats with
+median + IQR, a checksum honesty guard (sieve vs expanded values must agree),
+append-only artifact with full provenance. The MEASURED crossover here decides
+whether the sampler's sieve path defaults on for the GPU chain
+(the finite-difference sieve, measured against the expanded-hafnian kernel).
+
+    python -m bench.repeated_ab --batch 2048 --qs 2,3,4,5,6 --repeats 5
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import time
+from pathlib import Path
+
+import numpy as np
+
+import gbskernels
+from bench._provenance import provenance
+
+RESULTS = Path(__file__).resolve().parent.parent / "results" / "throughput"
+
+
+def _median_iqr(ts: list[float]) -> dict[str, float]:
+    a = np.sort(np.asarray(ts))
+    return {"median_s": float(np.median(a)),
+            "iqr_s": float(np.percentile(a, 75) - np.percentile(a, 25)),
+            "raw_s": [float(x) for x in a]}
+
+
+def run(modes: int, qs: list[int], batch: int, repeats: int, warmup: int,
+        seed: int) -> dict:
+    M = 2 * modes
+    g = np.random.default_rng(seed)
+    A = g.standard_normal((M, M)) + 1j * g.standard_normal((M, M))
+    A = 0.3 * (A + A.T)                      # modest norm, physical-ish
+    gam = np.zeros(M, dtype=np.complex128)
+
+    rows = []
+    for q in qs:
+        reps = np.full((batch, M), q, dtype=np.int32)
+        N = M * q
+        row: dict = {"q": q, "M": M, "N_expanded": N, "batch": batch,
+                     "sieve_terms": int((q + 1) ** M)}
+
+        # --- sieve kernel ---
+        for _ in range(warmup):
+            gbskernels.lhaf_repeated(A, gam, reps[: max(1, batch // 8)], backend="gpu")
+        ts = []
+        for _ in range(repeats):
+            t0 = time.perf_counter()
+            v_sieve = gbskernels.lhaf_repeated(A, gam, reps, backend="gpu")
+            ts.append(time.perf_counter() - t0)
+        chk = complex(np.sum(v_sieve))       # post-timing checksum (honesty guard)
+        row["sieve"] = _median_iqr(ts) | {"evals_per_s": batch / float(np.median(ts)),
+                                          "checksum": [chk.real, chk.imag]}
+
+        # --- expanded power-trace kernel (only within its cap) ---
+        cap = 20                              # HAF_MAX_N
+        if N <= cap:
+            idx = [i for i in range(M) for _ in range(q)]
+            E = np.ascontiguousarray(A[np.ix_(idx, idx)])
+            stack = np.broadcast_to(E, (batch, N, N)).copy()
+            for _ in range(warmup):
+                gbskernels.haf_batched(stack[: max(1, batch // 8)], backend="gpu")
+            ts = []
+            for _ in range(repeats):
+                t0 = time.perf_counter()
+                v_exp = gbskernels.haf_batched(stack, backend="gpu")
+                ts.append(time.perf_counter() - t0)
+            chk_e = complex(np.sum(v_exp))
+            row["expanded"] = _median_iqr(ts) | {
+                "evals_per_s": batch / float(np.median(ts)),
+                "checksum": [chk_e.real, chk_e.imag]}
+            rel = abs(chk - chk_e) / max(abs(chk_e), 1e-300)
+            row["values_agree_rel"] = float(rel)
+            if not rel <= 1e-8:
+                raise SystemExit(f"HONESTY GATE: sieve vs expanded disagree at q={q}: {rel:.2e}")
+            row["speedup_sieve_over_expanded"] = (
+                row["expanded"]["median_s"] / row["sieve"]["median_s"])
+        else:
+            row["expanded"] = None            # over the expanded kernel's cap:
+            row["note"] = f"N={N} > HAF cap {cap}: the sieve evaluates what the expansion cannot"
+        rows.append(row)
+        print(f"q={q}: sieve {row['sieve']['evals_per_s']:.3g} ev/s"
+              + (f", expanded {row['expanded']['evals_per_s']:.3g} ev/s, "
+                 f"speedup {row['speedup_sieve_over_expanded']:.2f}x"
+                 if row["expanded"] else f"  ({row['note']})"))
+    return {"bench": "repeated_ab", "params": {"modes": modes, "batch": batch,
+            "repeats": repeats, "warmup": warmup, "seed": seed},
+            "gpu_backend_kind": gbskernels.gpu_backend_kind(),
+            "provenance": provenance(), "rows": rows}
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--modes", type=int, default=3)
+    p.add_argument("--qs", type=str, default="2,3,4,5,6")
+    p.add_argument("--batch", type=int, default=2048)
+    p.add_argument("--repeats", type=int, default=5)
+    p.add_argument("--warmup", type=int, default=2)
+    p.add_argument("--seed", type=int, default=0)
+    args = p.parse_args()
+    art = run(args.modes, [int(x) for x in args.qs.split(",")], args.batch,
+              args.repeats, args.warmup, args.seed)
+    RESULTS.mkdir(parents=True, exist_ok=True)
+    out = RESULTS / f"repeated_ab_{time.strftime('%Y%m%dT%H%M%SZ', time.gmtime())}.json"
+    out.write_text(json.dumps(art, indent=1))
+    print(f"-> {out}")
+
+
+if __name__ == "__main__":
+    main()

bench/sampler_throughput.py

@@ -0,0 +1,165 @@
+"""End-to-end GBS sampler throughput -- **samples/sec**, not kernel evals/sec.
+
+The conditional sampler (`sampling.sampler.sample`) draws photon-number samples by
+the reduced-covariance chain rule, routing each mode's conditional-probability
+hafnian batch through one `gbskernels.Workspace` (ragged bucketing + device-buffer
+residency across the whole chain). This measures the headline product metric --
+samples/sec for a real GBS workload -- on the CPU and GPU backends, with the same
+honest provenance as the kernel benchmarks (commit, GPU/host-shim backend).
+
+Runs wherever the GPU extension is importable: a real device times the GPU chain, a
+host-shim build times the CPU emulation (then the GPU number is only indicative, but
+the path and the GPU==CPU sample agreement are validated -- see tests/).
+
+    uv run python -m bench.sampler_throughput --modes 6 --num-samples 2000 --cutoff 6
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import platform
+import subprocess
+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 _provenance
+from sampling import sampler
+
+DEFAULT_OUT = Path(__file__).resolve().parent.parent / "results" / "sampling"
+
+
+def _random_cov(modes: int, seed: int, hbar: float = 2.0) -> np.ndarray:
+    """xxpp covariance of a zero-displacement pure GBS state (squeeze + interferometer),
+    built without third-party deps so the benchmark is self-contained on the box."""
+    g = np.random.default_rng(seed)
+    r = g.uniform(0.3, 0.6, modes)
+    z = (g.standard_normal((modes, modes)) + 1j * g.standard_normal((modes, modes))) / np.sqrt(2.0)
+    U, rr = np.linalg.qr(z); ph = np.diagonal(rr).copy(); ph /= np.abs(ph); U = U * ph
+    sq = np.block([[np.diag(np.exp(-r)), np.zeros((modes, modes))],
+                   [np.zeros((modes, modes)), np.diag(np.exp(r))]])        # xxpp squeezing
+    interf = np.block([[U.real, -U.imag], [U.imag, U.real]])               # xxpp interferometer
+    S = interf @ sq
+    return (hbar / 2.0) * S @ S.T
+
+
+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(modes: int, num_samples: int, cutoff: int, repeats: int = 7, seed: int = 0,
+        out_dir: Path | None = None, repeated_sieve: bool = False) -> tuple[dict[str, Any], Path]:
+    cov = _random_cov(modes, seed)
+    backends = ["cpu"] + (["gpu"] if gbskernels.gpu_available() else [])
+    rows = []
+
+    def _time(backend: str, resident: bool = False, sieve: bool | None = None) -> dict[str, Any]:
+        # warm-up (untimed) then RAW repetitions -> median + IQR (NOT best-of-N, which hides the
+        # spread and biases the headline; the median+IQR matches the kernel/Walrus benches).
+        # The warm-up is also a COST PROBE: if one timed draw-set already exceeds
+        # SLOW_CELL_S, drop to a single measured repetition rather than `repeats`
+        # of them -- the deep-cutoff CPU non-sieve baseline is ~minutes/rep and
+        # timing it 7x (twice: default + explicit nosieve) made the sweep
+        # intractable (it hung a cell ~2h). A slow baseline still gets ONE honest
+        # number; it just does not get the full IQR treatment it cannot afford.
+        SLOW_CELL_S = 20.0
+        import time as _t
+        sampler.sample(cov, max(num_samples // 10, 1), cutoff=cutoff, backend=backend,
+                       resident=resident, seed=seed, repeated_sieve=sieve)
+        _p0 = _t.perf_counter()
+        first = sampler.samples_per_second(cov, num_samples, cutoff=cutoff, backend=backend,
+                                           resident=resident, seed=seed, repeated_sieve=sieve)
+        n_rep = repeats if (_t.perf_counter() - _p0) < SLOW_CELL_S else 1
+        reps = [first] + [sampler.samples_per_second(cov, num_samples, cutoff=cutoff, backend=backend,
+                                           resident=resident, seed=seed + rep,
+                                           repeated_sieve=sieve) for rep in range(1, n_rep)]
+        sps = sorted(r["samples_per_sec"] for r in reps)
+        secs = [r["seconds"] for r in reps]
+        return {"backend": reps[0]["backend"], "num_samples": num_samples, "modes": modes,
+                "cutoff": cutoff, "repeats_requested": repeats, "repeats_timed": len(reps),
+                "repeated_sieve_effective": reps[0].get("repeated_sieve_effective"),
+                "samples_per_sec_median": _quantile(sps, 0.5),
+                "samples_per_sec_iqr": _quantile(sps, 0.75) - _quantile(sps, 0.25),
+                "seconds_median": _quantile(secs, 0.5),
+                "mean_photons": reps[0]["mean_photons"], "raw_samples_per_sec": sps}
+
+    for b in backends:
+        rows.append(_time(b))                # sieve=None: the DEFAULT path, as shipped
+    if repeated_sieve:                       # R4 A/B rows: explicitly pinned paths
+        for b in backends:
+            rows.append(_time(b, sieve=False))
+            rows.append(_time(b, sieve=True))
+    # v3 fully on-device (resident) chain -- the before/after vs the hybrid 'gpu' backend -- when
+    # the extension exposes it and the config is within the hafnian cap (worst-case 2*modes*cutoff).
+    _ext = gbskernels._load_gpu_ext()
+    _cap = getattr(gbskernels, "_GPU_MAX_DIM", {}).get("haf", 20)
+    if (gbskernels.gpu_available() and _ext is not None and hasattr(_ext, "sample_resident")
+            and 2 * modes * cutoff <= _cap):
+        rows.append(_time("gpu", resident=True))
+
+    artifact = {
+        "kind": "sampler_throughput",
+        "created_utc": datetime.now(timezone.utc).isoformat(),
+        **_provenance.provenance(),  # commit + container_digest + hostname
+        "gpu_backend": gbskernels.gpu_backend_kind(),
+        "metric": "end-to-end samples/sec (chain-rule conditional GBS sampler); "
+                  "median + IQR over raw repeats; warm-up discarded; the 'gpu-resident' row is the "
+                  "v3 FULLY on-device chain (before/after vs the hybrid 'gpu' row, where in-cap)",
+        "params": {"modes": modes, "num_samples": num_samples, "cutoff": cutoff,
+                   "repeats": repeats, "seed": seed, "warmup": "1 untimed draw/backend"},
+        "env": {"platform": platform.platform(), "numpy": version("numpy")},
+        "rows": rows,
+    }
+    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"sampler_throughput_{stamp}.json"
+    path.write_text(json.dumps(artifact, indent=2))
+    return artifact, path
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--modes", type=int, default=6)
+    p.add_argument("--num-samples", type=int, default=2000)
+    p.add_argument("--cutoff", type=int, default=6)
+    p.add_argument("--repeats", type=int, default=7)
+    p.add_argument("--out", type=Path, default=None)
+    p.add_argument("--repeated-sieve", action="store_true",
+                   help="also time the sieve-routed chain (cpu+sieve / gpu+sieve rows)")
+    p.add_argument("--sweep", action="store_true",
+                   help="characterization grid: modes x cutoff cells (each its own artifact) "
+                        "instead of the single default cell -- the resident/hybrid/sieve "
+                        "story needs the surface, not one point")
+    args = p.parse_args()
+    if args.sweep:
+        # the characterization surface: shallow->deep collisions, small->mid modes.
+        # Each cell is an independent append-only artifact (same hygiene).
+        for m_, c_ in [(4, 3), (6, 4), (6, 6), (8, 5), (10, 4), (5, 8)]:
+            n_ = max(200, args.num_samples // 4)
+            print(f"--- sweep cell: modes={m_} cutoff={c_} samples={n_} ---")
+            run(m_, n_, c_, max(3, args.repeats // 2), out_dir=args.out,
+                repeated_sieve=args.repeated_sieve)
+        return
+    artifact, path = run(args.modes, args.num_samples, args.cutoff, args.repeats,
+                         out_dir=args.out, repeated_sieve=args.repeated_sieve)
+    print(f"# GBS sampler throughput ({artifact['gpu_backend']}) -> {path}")
+    print(f"#   {args.modes} modes, cutoff {args.cutoff}, {args.num_samples} samples, "
+          f"{args.repeats} repeats; commit {artifact['commit']}")
+    for r in artifact["rows"]:
+        print(f"  {r['backend']:>4}  {r['samples_per_sec_median']:>10.1f} samples/sec median  "
+              f"(IQR {r['samples_per_sec_iqr']:.1f}, {r['seconds_median']:.2f}s, "
+              f"mean photons {r['mean_photons']:.2f})")
+
+
+if __name__ == "__main__":
+    main()

bench/throughput.py

@@ -0,0 +1,229 @@
+"""Throughput benchmark harness (accuracy-normalized, honesty-guarded).
+
+The benchmark claim is **throughput at a stated accuracy**, never raw throughput
+(docs/DESIGN.md §9). This harness measures batched-evaluation throughput (evals/sec)
+for the GBSKernels CPU reference and, where available, The Walrus, at matched
+accuracy, with the hygiene that makes the numbers credible:
+
+* n >= ``repeats`` timed runs per cell, reported as median + IQR (not mean);
+* **randomized execution order** across (engine, size) cells, so thermal/cache
+  drift can't systematically favor one engine;
+* a **benchmark-honesty guard**: every timed call's outputs are reduced to a
+  checksum *after* timing, and the checksum is stored, so no async/early-return
+  can fake a fast time (trivially true on CPU, essential once the GPU path
+  lands);
+* raw per-run data written append-only to ``results/throughput/``; **no composite
+  "winner" number**; CPU single-eval latency where The Walrus honestly wins is
+  reported, not hidden.
+
+This run is a **CPU baseline**. GPU throughput rows are added in a scripted
+rented-GPU session (docs/DESIGN.md §8/sec.10); nothing here runs on a GPU.
+
+    uv run python -m bench.throughput --sizes 4,8,12 --batch 256 --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, Callable
+
+import numpy as np
+
+import gbskernels
+from bench._inputs import random_complex
+
+try:
+    import thewalrus
+
+    _HAVE_WALRUS = True
+except Exception:
+    _HAVE_WALRUS = False
+
+DEFAULT_OUT = Path(__file__).resolve().parent.parent / "results" / "throughput"
+
+
+def _checksum(values: np.ndarray) -> str:
+    """Order-independent magnitude checksum of a result vector (honesty guard)."""
+    v = np.asarray(values, dtype=np.complex128)
+    return f"{float(np.sum(np.abs(v))):.12e}|{len(v)}"
+
+
+def _time_once(fn: Callable[[], np.ndarray]) -> tuple[float, str]:
+    """Run ``fn``, return (elapsed_seconds, checksum-of-result-after-sync)."""
+    t0 = time.perf_counter()
+    out = fn()
+    elapsed = time.perf_counter() - t0
+    # Post-compute checksum: forces materialization of every result *after*
+    # timing so no early-return can fake a fast time (docs/DESIGN.md §8).
+    return elapsed, _checksum(out)
+
+
+def _gbskernels_batched(func: str, batch: list[np.ndarray]) -> Callable[[], np.ndarray]:
+    fn = {"perm": gbskernels.perm_batched, "haf": gbskernels.haf_batched}[func]
+    return lambda: fn(batch, precision="fp64")
+
+
+def _walrus_looped(func: str, batch: list[np.ndarray]) -> Callable[[], np.ndarray]:
+    wfn = {"perm": thewalrus.perm, "haf": thewalrus.hafnian}[func]
+    return lambda: np.array([wfn(A) for A in batch], dtype=np.complex128)
+
+
+def _make_batch(func: str, n: int, batch_size: int, seed: int) -> list[np.ndarray]:
+    out = []
+    for b in range(batch_size):
+        A = random_complex(n, seed=seed + b)
+        if func == "haf":
+            A = A + A.T  # symmetric for the hafnian
+        out.append(A)
+    return out
+
+
+def run(
+    func: str,
+    sizes: list[int],
+    batch_size: int,
+    repeats: int,
+    seed: int = 0,
+    out_dir: Path | None = None,
+) -> tuple[dict[str, Any], Path]:
+    engines = ["gbskernels"]
+    if _HAVE_WALRUS:
+        engines.append("thewalrus")
+
+    # Build the randomized work list: (engine, size, repeat) cells, shuffled.
+    cells = [
+        (engine, n, rep)
+        for engine in engines
+        for n in sizes
+        for rep in range(repeats)
+    ]
+    random.Random(seed).shuffle(cells)
+
+    # Fixed input batch per size (same inputs for both engines -> fair, and the
+    # checksum must agree across engines, a correctness cross-check for free).
+    batches = {n: _make_batch(func, n, batch_size, seed=1000 + n) for n in sizes}
+
+    raw: list[dict[str, Any]] = []
+    for engine, n, rep in cells:
+        batch = batches[n]
+        if engine == "gbskernels":
+            fn = _gbskernels_batched(func, batch)
+        else:
+            fn = _walrus_looped(func, batch)
+        elapsed, checksum = _time_once(fn)
+        raw.append(
+            {
+                "engine": engine,
+                "n": n,
+                "repeat": rep,
+                "seconds": elapsed,
+                "evals_per_sec": batch_size / elapsed if elapsed > 0 else float("inf"),
+                "checksum": checksum,
+            }
+        )
+
+    summary = _summarize(raw, engines, sizes, batch_size)
+    artifact = {
+        "kind": "throughput",
+        "function": func,
+        "created_utc": datetime.now(timezone.utc).isoformat(),
+        "tier": "cpu-baseline",
+        "env": {
+            "python": platform.python_version(),
+            "platform": platform.platform(),
+            "processor": platform.processor(),
+            "numpy": version("numpy"),
+            "thewalrus": version("thewalrus") if _HAVE_WALRUS else None,
+        },
+        "params": {
+            "batch_size": batch_size,
+            "repeats": repeats,
+            "sizes": sizes,
+            "precision": "fp64",
+            "dtype": "complex128",
+            "order": "randomized across (engine, size, repeat)",
+        },
+        "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_{func}_{stamp}_cpu.json"
+    path.write_text(json.dumps(artifact, indent=2))
+    return artifact, path
+
+
+def _summarize(raw, engines, sizes, batch_size) -> list[dict[str, Any]]:
+    rows = []
+    for n in sizes:
+        row: dict[str, Any] = {"n": n}
+        checks = {}
+        for engine in engines:
+            eps = sorted(r["evals_per_sec"] for r in raw if r["engine"] == engine and r["n"] == n)
+            checks[engine] = {r["checksum"] for r in raw if r["engine"] == engine and r["n"] == n}
+            row[engine] = {
+                "evals_per_sec_median": float(np.median(eps)),
+                "evals_per_sec_iqr": float(np.subtract(*np.percentile(eps, [75, 25]))),
+            }
+        # cross-engine correctness: checksums must match (same inputs, same answer)
+        if len(engines) > 1:
+            allchecks = set().union(*checks.values())
+            row["checksums_agree"] = len(allchecks) == 1
+        rows.append(row)
+    return rows
+
+
+def _print_summary(artifact: dict[str, Any], path: Path) -> None:
+    print(f"# throughput [{artifact['function']}, {artifact['tier']}] -> {path}")
+    e = artifact["env"]
+    print(f"#   {e['platform']} | py {e['python']} | numpy {e['numpy']} | "
+          f"thewalrus {e['thewalrus']}")
+    print(f"#   batch={artifact['params']['batch_size']} repeats={artifact['params']['repeats']} "
+          f"(median evals/sec, IQR); randomized order; no composite score")
+    engines = [k for k in ("gbskernels", "thewalrus") if k in artifact["summary"][0]]
+    head = f"  {'n':>3}"
+    for eng in engines:
+        head += f"  {eng + ' med':>16}  {'IQR':>9}"
+    if len(engines) > 1:
+        head += "  checks"
+    print(head)
+    for row in artifact["summary"]:
+        line = f"  {row['n']:>3}"
+        for eng in engines:
+            line += f"  {row[eng]['evals_per_sec_median']:>16.1f}  {row[eng]['evals_per_sec_iqr']:>9.1f}"
+        if len(engines) > 1:
+            line += f"   {'ok' if row['checksums_agree'] else 'MISMATCH'}"
+        print(line)
+
+
+def _parse_sizes(s: str) -> list[int]:
+    if "-" in s and "," not in s:
+        lo, hi = s.split("-")
+        return list(range(int(lo), int(hi) + 1))
+    return [int(x) for x in s.split(",")]
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--func", choices=["perm", "haf"], default="perm")
+    p.add_argument("--sizes", type=_parse_sizes, default=_parse_sizes("4,6,8,10"))
+    p.add_argument("--batch", type=int, default=128)
+    p.add_argument("--repeats", type=int, default=7)
+    p.add_argument("--seed", type=int, default=0)
+    p.add_argument("--out", type=Path, default=None)
+    args = p.parse_args()
+    artifact, path = run(args.func, args.sizes, args.batch, args.repeats, args.seed, args.out)
+    _print_summary(artifact, path)
+
+
+if __name__ == "__main__":
+    main()