gbskernels 0.2.0__py3-none-any.whl

bench/accuracy_permanent.py

@@ -0,0 +1,169 @@
+"""Accuracy characterization for the permanent (FP64 vs mpmath reference).
+
+The CPU-runnable, throughput-free half of docs/DESIGN.md §9: relative error vs matrix
+size and vs the Glynn condition number ``kappa``, measured against the
+independent arbitrary-precision reference. This is the "measured boundary" of
+docs/DESIGN.md §6 -- the thing that tells a user exactly when FP64 suffices and when
+the (GPU) double-double tier is required.
+
+Writes a timestamped, self-describing JSON artifact to ``results/accuracy/``
+(append-only). **No timing is recorded here** -- throughput numbers come only
+from scripted rented-GPU sessions (docs/DESIGN.md §8 CI policy).
+
+    uv run python -m bench.accuracy_permanent --sizes 2-12 --seeds 8 --dps 60
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import platform
+import subprocess
+from datetime import datetime, timezone
+from importlib.metadata import version
+from pathlib import Path
+from typing import Any
+
+import mpmath
+import numpy as np
+
+from cpu_ref import cancellation_ratio, permanent_glynn
+from cpu_ref.permanent import permanent_glynn_dd
+from highprec_ref import permanent_mp
+
+from ._inputs import make_cancellation_matrix, random_complex
+
+DEFAULT_OUT = Path(__file__).resolve().parent.parent / "results" / "accuracy"
+CANCELLATION_DELTAS = [1e-1, 1e-2, 1e-4, 1e-6, 1e-8, 1e-10, 1e-12, 1e-14]
+
+
+def _git_commit() -> str | None:
+    try:
+        out = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],
+            capture_output=True, text=True, cwd=Path(__file__).parent,
+        )
+        return out.stdout.strip() or None
+    except Exception:
+        return None
+
+
+def _rel_err_mp(approx: complex, exact_mp: Any, dps: int) -> float:
+    """Relative error of an FP64 result vs the mpmath reference, computed in
+    mpmath so the reference's full precision is used (not truncated to FP64)."""
+    with mpmath.workdps(dps):
+        a = mpmath.mpc(approx.real, approx.imag)
+        return float(abs(a - exact_mp) / abs(exact_mp))
+
+
+def run(
+    sizes: list[int],
+    seeds_per_size: int,
+    dps: int = 60,
+    out_dir: Path | None = None,
+    tag: str = "",
+) -> tuple[dict[str, Any], Path]:
+    """Run the accuracy sweeps and write one append-only artifact. Returns it."""
+    size_sweep = []
+    for n in sizes:
+        rel_errs, kappas = [], []
+        for seed in range(seeds_per_size):
+            A = random_complex(n, seed=1000 * n + seed)
+            exact_mp = permanent_mp(A, dps=dps)
+            approx = permanent_glynn(A)
+            rel_errs.append(_rel_err_mp(approx, exact_mp, dps))
+            kappas.append(cancellation_ratio(A, perm_value=complex(exact_mp)))
+        size_sweep.append(
+            {
+                "n": n,
+                "rel_err_median": float(np.median(rel_errs)),
+                "rel_err_max": float(np.max(rel_errs)),
+                "kappa_median": float(np.median(kappas)),
+                "rel_errs": [float(x) for x in rel_errs],
+                "kappas": [float(x) for x in kappas],
+            }
+        )
+
+    # Conditioning axis: drive kappa with the cancellation knob at fixed n.
+    cancellation_sweep = []
+    cancel_dps = max(dps, 80)
+    for delta in CANCELLATION_DELTAS:
+        A = make_cancellation_matrix(6, delta=delta, seed=1)
+        exact_mp = permanent_mp(A, dps=cancel_dps)
+        cancellation_sweep.append(
+            {
+                "n": 6,
+                "delta": delta,
+                "kappa": cancellation_ratio(A, perm_value=complex(exact_mp)),
+                "rel_err_fp64": _rel_err_mp(permanent_glynn(A), exact_mp, cancel_dps),
+                "rel_err_dd": _rel_err_mp(permanent_glynn_dd(A), exact_mp, cancel_dps),
+            }
+        )
+
+    artifact = {
+        "kind": "accuracy_permanent",
+        "created_utc": datetime.now(timezone.utc).isoformat(),
+        "env": {
+            "python": platform.python_version(),
+            "platform": platform.platform(),
+            "numpy": version("numpy"),
+            "mpmath": version("mpmath"),
+            "git_commit": _git_commit(),
+        },
+        "params": {
+            "sizes": sizes,
+            "seeds_per_size": seeds_per_size,
+            "dps": dps,
+            "dtype": "complex128",
+            "input_family": "random_complex (size sweep) / cancellation block (kappa sweep)",
+        },
+        "size_sweep": size_sweep,
+        "cancellation_sweep": cancellation_sweep,
+    }
+
+    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")
+    suffix = f"_{tag}" if tag else ""
+    path = out_dir / f"accuracy_permanent_{stamp}{suffix}.json"
+    path.write_text(json.dumps(artifact, indent=2))
+    return artifact, path
+
+
+def _print_summary(artifact: dict[str, Any], path: Path) -> None:
+    print(f"# accuracy_permanent  ->  {path}")
+    print(f"#   env: py {artifact['env']['python']}, numpy {artifact['env']['numpy']}, "
+          f"mpmath {artifact['env']['mpmath']}, commit {artifact['env']['git_commit']}")
+    print("\n  size sweep (FP64 vs mpmath, random complex):")
+    print(f"  {'n':>3}  {'rel_err median':>15}  {'rel_err max':>13}  {'kappa median':>13}")
+    for row in artifact["size_sweep"]:
+        print(f"  {row['n']:>3}  {row['rel_err_median']:>15.2e}  "
+              f"{row['rel_err_max']:>13.2e}  {row['kappa_median']:>13.2e}")
+    print("\n  conditioning sweep (the measured FP64<->DD boundary, n=6):")
+    print(f"  {'delta':>8}  {'kappa':>11}  {'rel_err FP64':>13}  {'rel_err DD':>13}")
+    for row in artifact["cancellation_sweep"]:
+        print(f"  {row['delta']:>8.0e}  {row['kappa']:>11.2e}  "
+              f"{row['rel_err_fp64']:>13.2e}  {row['rel_err_dd']:>13.2e}")
+
+
+def _parse_sizes(s: str) -> list[int]:
+    if "-" 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("--sizes", type=_parse_sizes, default=_parse_sizes("2-12"))
+    p.add_argument("--seeds", type=int, default=8)
+    p.add_argument("--dps", type=int, default=60)
+    p.add_argument("--out", type=Path, default=None)
+    p.add_argument("--tag", type=str, default="")
+    args = p.parse_args()
+    artifact, path = run(args.sizes, args.seeds, args.dps, args.out, args.tag)
+    _print_summary(artifact, path)
+
+
+if __name__ == "__main__":
+    main()

bench/calibrate_auto.py

@@ -0,0 +1,159 @@
+"""Calibrate precision="auto": is kappa a trustworthy FP64-risk indicator? (docs/DESIGN.md §6)
+
+``precision="auto"`` trusts the FP64 result when the cancellation indicator
+``kappa = sum|terms| / |result|`` (``cpu_ref.summation_condition_number``) is below
+``_AUTO_KAPPA_MAX`` (1e8), and reruns in the high-precision tier otherwise. ``kappa`` is a
+**heuristic**, NOT a rigorous error certificate: the model is ``rel_err_fp64 ~ kappa * eps``,
+but ``kappa`` is itself formed from the (FP64-inexact) computed ``|result|``, so under extreme
+cancellation it can mis-estimate. So we MEASURE the relationship on physical / loss /
+adversarial ensembles and calibrate the threshold rather than assume it:
+
+* per ``(func, regime, size)``: ``kappa``, the actual FP64 relative error vs the mpmath
+  ground truth, and whether ``auto`` would trust FP64 (``kappa < threshold``);
+* a calibration summary: the **worst FP64 error among the TRUSTED cases** (the accuracy
+  ``auto`` actually delivers), the **false-trust count** (``kappa < threshold`` yet the error
+  is large), and the kappa-vs-error correlation.
+
+The headline a truthful claim can make: on these ensembles, ``kappa < 1e8`` keeps the FP64
+error below ``max_rel_err_when_trusted`` with ``false_trust_count`` exceptions -- a calibrated
+heuristic, stated with its measured failure rate, not a guarantee.
+
+    uv run python -m bench.calibrate_auto --dps 60
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import platform
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import mpmath
+import numpy as np
+
+import cpu_ref
+import gbskernels
+import highprec_ref
+from bench import _inputs, _provenance
+
+DEFAULT_OUT = Path(__file__).resolve().parent.parent / "results" / "accuracy"
+
+_MP = {"perm": highprec_ref.permanent_mp, "haf": highprec_ref.hafnian_mp,
+       "lhaf": highprec_ref.loop_hafnian_mp, "tor": highprec_ref.torontonian_mp}
+_FN = {"perm": gbskernels.perm, "haf": gbskernels.haf, "lhaf": gbskernels.lhaf, "tor": gbskernels.tor}
+_EPS = float(np.finfo(np.float64).eps)
+_SIZES = {"perm": [6, 8], "haf": [6, 8], "lhaf": [6, 8], "tor": [6, 8]}  # tor dim = 2*modes
+
+
+def _pearson(pts: list[tuple[float, float]]) -> float | None:
+    n = len(pts)
+    if n < 2:
+        return None
+    xs = [p[0] for p in pts]; ys = [p[1] for p in pts]
+    mx, my = sum(xs) / n, sum(ys) / n
+    num = sum((x - mx) * (y - my) for x, y in pts)
+    dx = math.sqrt(sum((x - mx) ** 2 for x in xs)); dy = math.sqrt(sum((y - my) ** 2 for y in ys))
+    return float(num / (dx * dy)) if dx > 0 and dy > 0 else None
+
+
+def _eval(func: str, A, backend: str, threshold: float):
+    """(FP64 value, kappa, trusted) for one input on ``backend``. On the GPU backend the kappa
+    comes from the on-device ``*_kappa`` kernel and the FP64 value from the GPU FP64 path -- so
+    the calibration measures the GPU AUTO decision (not a CPU proxy); ``trusted`` == auto would
+    keep FP64 (tier 'fp64'). On CPU it uses cpu_ref + summation_condition_number."""
+    if backend == "gpu":
+        _val, diag = _FN[func](A, precision="auto", backend="gpu", return_diagnostics=True)
+        kappa = float(diag["cancellation"])
+        fp = complex(_FN[func](A, precision="fp64", backend="gpu"))
+        return fp, kappa, (diag["tier"] == "fp64")
+    fp = complex(_FN[func](A, precision="fp64", backend="cpu"))
+    kappa = float(cpu_ref.summation_condition_number(func, A, fp))
+    return fp, kappa, (kappa < threshold)
+
+
+def run(dps: int = 60, seeds: int = 5, threshold: float | None = None,
+        backend: str | None = None, out_dir: Path | None = None) -> tuple[dict[str, Any], Path]:
+    threshold = gbskernels._AUTO_KAPPA_MAX if threshold is None else threshold
+    # Calibrate the REAL path the claim is used for: the GPU auto path when the extension is
+    # importable (its kappa comes from the device *_kappa kernels), else CPU.
+    if backend is None:
+        backend = "gpu" if gbskernels.gpu_available() else "cpu"
+    rows: list[dict[str, Any]] = []
+    for func in ("perm", "haf", "lhaf", "tor"):
+        for regime in _inputs.BENCH_REGIMES:
+            for dim in _SIZES[func]:
+                for s in range(seeds):
+                    A = _inputs.bench_batch(func, dim, 1, regime, 1000 + dim + s)[0]
+                    fp, kappa, trusted = _eval(func, A, backend, threshold)
+                    with mpmath.workdps(dps):
+                        exact = _MP[func](A, dps=dps)
+                        rel = float(abs(mpmath.mpc(fp) - exact) / max(abs(exact), mpmath.mpf("1e-300")))
+                    rows.append({"func": func, "regime": regime, "dim": dim, "seed": s,
+                                 "kappa": kappa, "rel_err_fp64": rel, "trusted": trusted})
+
+    trusted = [r for r in rows if r["trusted"]]
+    per_regime = {}
+    for regime in _inputs.BENCH_REGIMES:
+        rr = [r for r in rows if r["regime"] == regime]
+        tr = [r for r in rr if r["trusted"]]
+        per_regime[regime] = {
+            "n": len(rr), "n_trusted": len(tr),
+            "max_kappa": max(r["kappa"] for r in rr),
+            "max_rel_err_when_trusted": max((r["rel_err_fp64"] for r in tr), default=0.0),
+        }
+    summary = {
+        "threshold": threshold, "eps": _EPS,
+        "n_total": len(rows), "n_trusted": len(trusted),
+        "max_rel_err_when_trusted": max((r["rel_err_fp64"] for r in trusted), default=0.0),
+        "false_trust_count": sum(1 for r in trusted if r["rel_err_fp64"] > 1e-6),
+        "log_kappa_vs_log_relerr_corr": _pearson(
+            [(math.log10(max(r["kappa"], 1.0)), math.log10(max(r["rel_err_fp64"], 1e-300))) for r in rows]),
+        "per_regime": per_regime,
+    }
+    artifact = {
+        "kind": "auto_calibration",
+        "created_utc": datetime.now(timezone.utc).isoformat(),
+        **_provenance.provenance(),
+        "indicator": "kappa = sum|terms| / |result| (a-posteriori; a HEURISTIC indicator, "
+                     "NOT a rigorous error certificate)",
+        "model": "rel_err_fp64 ~ kappa * eps",
+        "backend": backend,                              # the path calibrated (gpu kappa kernels or cpu)
+        "gpu_backend": gbskernels.gpu_backend_kind(),    # real device vs host-shim (honest provenance)
+        "params": {"dps": dps, "seeds": seeds, "backend": backend},
+        "env": {"platform": platform.platform()},
+        "summary": summary,
+        "rows": rows,
+    }
+    out = Path(out_dir) if out_dir is not None else DEFAULT_OUT
+    out.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    path = out / f"auto_calibration_{stamp}.json"
+    path.write_text(json.dumps(artifact, indent=2))
+    return artifact, path
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--dps", type=int, default=60)
+    p.add_argument("--seeds", type=int, default=5)
+    p.add_argument("--backend", choices=["gpu", "cpu"], default=None,
+                   help="path to calibrate (default: gpu if the extension is importable)")
+    p.add_argument("--out", type=Path, default=None)
+    args = p.parse_args()
+    art, path = run(dps=args.dps, seeds=args.seeds, backend=args.backend, out_dir=args.out)
+    s = art["summary"]
+    print(f"# precision='auto' calibration ({art['backend']} path / {art['gpu_backend']}) -> {path}")
+    print(f"#   commit {art['commit']}; trust when kappa < {s['threshold']:.0e}; eps = {s['eps']:.2e}")
+    print(f"  trusted {s['n_trusted']}/{s['n_total']}; worst FP64 rel.err when trusted = "
+          f"{s['max_rel_err_when_trusted']:.2e}; false-trust (>1e-6) = {s['false_trust_count']}")
+    print(f"  log(kappa) vs log(rel.err) correlation = {s['log_kappa_vs_log_relerr_corr']}")
+    for regime, r in s["per_regime"].items():
+        print(f"  {regime:>11}: max kappa {r['max_kappa']:.1e}; "
+              f"worst rel.err when trusted {r['max_rel_err_when_trusted']:.1e}")
+
+
+if __name__ == "__main__":
+    main()

bench/crossover.py

@@ -0,0 +1,195 @@
+"""Batch-size sweep + accuracy-normalized GPU/CPU/Walrus crossover (docs/DESIGN.md §9).
+
+Sweeps the public-path end-to-end throughput over a range of batch sizes and records, per
+(function, matrix size), the GPU per-eval rate at each batch against two ~flat baselines on
+the **same shared workload** (bench._inputs.bench_batch): our CPU reference, and the
+**same-instance The Walrus** (measured once -- Walrus is one-at-a-time, so its per-eval rate
+is batch-independent). At small batch the GPU's fixed H2D/launch/D2H overhead loses; as the
+batch grows the GPU's batched throughput overtakes. The **crossover batch** -- the smallest
+batch where the GPU median overtakes a baseline -- is the headline of the batched-throughput
+thesis, reported separately vs the CPU and vs The Walrus.
+
+To find the *actual* crossover (not just "the smallest batch we tried"), the sweep must include
+**low** batches -- the default starts at 1 -- so the GPU genuinely loses at the small end.
+
+Evidence discipline (docs/DESIGN.md §9): the artifact retains **median + IQR + the raw repetitions**
+for GPU/CPU at every batch and for the Walrus baseline (not just medians); each series is tagged
+with the **achieved FP64 error** (vs mpmath) and its **precision tier**; and an **official** run
+(``strict=True``) is **fatal** if e2e reports a GPU/CPU public-path checksum disagreement at any
+batch, or if the same-instance Walrus baseline is unavailable -- so no crossover is published
+past a backend mismatch or without its baseline.
+
+    uv run python -m bench.crossover --batches 1,4,16,64,256,1024,4096,16384 --repeats 7
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+import gbskernels
+from bench import _inputs, _provenance, throughput_end_to_end as e2e, walrus_baseline
+
+DEFAULT_OUT = Path(__file__).resolve().parent.parent / "results" / "throughput"
+DEFAULT_BATCHES = [1, 4, 16, 64, 256, 1024, 4096, 16384]
+
+_MP = {"perm": "permanent_mp", "haf": "hafnian_mp",
+       "lhaf": "loop_hafnian_mp", "tor": "torontonian_mp"}
+
+
+def _achieved_error(func: str, dim: int, regime: str, n: int, dps: int) -> float | None:
+    """Max relative error of the public FP64 GPU path vs the mpmath ground truth on ``n``
+    elements of the shared workload -- the accuracy the throughput is bought at. The SAME
+    matrices the sweep timed (seed convention ``1000+dim``). ``n<=0`` or ``dps<=0`` disables."""
+    if n <= 0 or dps <= 0:
+        return None
+    import highprec_ref
+    stack = _inputs.bench_batch(func, dim, n, regime, 1000 + dim)
+    fp = np.asarray(getattr(gbskernels, f"{func}_batched")(stack, backend="gpu", precision="fp64"))
+    mp_fn = getattr(highprec_ref, _MP[func])
+    rel = 0.0
+    for k in range(n):
+        ref = complex(mp_fn(stack[k], dps=dps))
+        rel = max(rel, abs(complex(fp[k]) - ref) / max(abs(ref), 1e-300))
+    return rel
+
+
+def _pull(summary, raw, func, dim, backend):
+    """(median, iqr, raw evals/sec list) for (func, dim, backend) from an e2e artifact --
+    so the crossover keeps the dispersion + raw repetitions, not just the median."""
+    row = next((r for r in summary if r["func"] == func and r["matrix_dim"] == dim), {})
+    sub = row.get(backend, {})
+    rawlist = [r["evals_per_sec"] for r in raw
+               if r["backend"] == backend and r["func"] == func and r["matrix_dim"] == dim]
+    return sub.get("evals_per_sec_median"), sub.get("evals_per_sec_iqr"), rawlist
+
+
+def run(batches: list[int], repeats: int = 7, seed: int = 0, warmup: int = 2,
+        regime: str = "physical", error_n: int = 2, error_dps: int = 30,
+        strict: bool = True, out_dir: Path | None = None) -> tuple[dict[str, Any], Path]:
+    base = Path(out_dir) if out_dir is not None else DEFAULT_OUT
+    tmp = base / "_sweep_tmp"
+
+    # GPU + CPU per-eval median/IQR/raw at each batch (same shared workload as the Walrus
+    # baseline). An e2e GPU/CPU checksum disagreement is FATAL for an official (strict) run.
+    curves: dict[tuple[str, int], list[dict[str, Any]]] = {}
+    for b in sorted(set(batches)):
+        art, _ = e2e.run(batch=b, repeats=repeats, seed=seed, warmup=warmup,
+                         regime=regime, out_dir=tmp)
+        if strict and not art["all_backends_agree"]:
+            bad = [f"{r['func']}/d{r['matrix_dim']}" for r in art["summary"] if not r["backends_agree"]]
+            raise RuntimeError(
+                f"crossover ABORT: e2e GPU/CPU public-path checksum disagreement at batch {b} "
+                f"(regime {regime}) on {bad} -- no official crossover from a backend mismatch.")
+        for row in art["summary"]:
+            func, dim = row["func"], row["matrix_dim"]
+            gm, gi, gr = _pull(art["summary"], art["raw"], func, dim, "gpu")
+            cm, ci, cr = _pull(art["summary"], art["raw"], func, dim, "cpu")
+            curves.setdefault((func, dim), []).append({
+                "batch": b, "gpu_median": gm, "gpu_iqr": gi, "gpu_raw": gr,
+                "cpu_median": cm, "cpu_iqr": ci, "cpu_raw": cr})
+
+    # The Walrus per-eval rate is batch-independent (one-at-a-time) -> measure it ONCE on the
+    # same workload, keeping median + IQR + raw. Unavailable Walrus is FATAL for a strict run.
+    walrus: dict[tuple[str, int], dict[str, Any]] = {}
+    walrus_meta: dict[str, Any]
+    try:
+        wb_batch = max(min(max(batches), 128), 8)
+        wart, _ = walrus_baseline.run(batch=wb_batch, repeats=repeats, seed=seed,
+                                      warmup=warmup, regime=regime, out_dir=tmp)
+        for r in wart["rows"]:
+            rraw = [x["evals_per_sec"] for x in wart["raw"]
+                    if x["func"] == r["func"] and x["matrix_dim"] == r["matrix_dim"]]
+            walrus[(r["func"], r["matrix_dim"])] = {
+                "median": r["evals_per_sec_median"], "iqr": r["evals_per_sec_iqr"], "raw": rraw}
+        walrus_meta = {"library_version": wart["library_version"], "batch": wb_batch}
+    except Exception as e:  # pragma: no cover - depends on the box
+        walrus_meta = {"skipped": str(e)}
+    if strict and "skipped" in walrus_meta:
+        raise RuntimeError(
+            f"crossover ABORT: the same-instance The Walrus baseline is unavailable "
+            f"({walrus_meta['skipped']}) -- an official crossover requires it.")
+
+    series = []
+    for (func, dim), pts in sorted(curves.items()):
+        pts.sort(key=lambda p: p["batch"])
+        wb = walrus.get((func, dim), {})
+        wmed = wb.get("median")
+
+        def _gt(p, beat):
+            return p["gpu_median"] is not None and beat is not None and p["gpu_median"] > beat
+
+        x_cpu = next((p["batch"] for p in pts if _gt(p, p["cpu_median"])), None)
+        x_wal = next((p["batch"] for p in pts if _gt(p, wmed)), None)
+        x_best = next((p["batch"] for p in pts
+                       if p["gpu_median"] is not None
+                       and any(v is not None for v in (p["cpu_median"], wmed))
+                       and p["gpu_median"] > max(v for v in (p["cpu_median"], wmed) if v is not None)),
+                      None)
+        series.append({
+            "func": func, "matrix_dim": dim, "precision_tier": "fp64",
+            "achieved_rel_err_fp64": _achieved_error(func, dim, regime, error_n, error_dps),
+            "walrus_median": wmed, "walrus_iqr": wb.get("iqr"), "walrus_raw": wb.get("raw"),
+            "crossover_batch_vs_cpu": x_cpu,
+            "crossover_batch_vs_walrus": x_wal,
+            "crossover_batch_vs_best": x_best,
+            "points": pts,
+        })
+
+    artifact = {
+        "kind": "crossover_batch_sweep",
+        "created_utc": datetime.now(timezone.utc).isoformat(),
+        **_provenance.provenance(),
+        "gpu_backend": gbskernels.gpu_backend_kind(),
+        "metric": "per-eval evals/sec (public path) vs batch; GPU rises, CPU & same-instance "
+                  "Walrus are ~flat baselines on the same workload; crossover = smallest batch "
+                  "where GPU median > baseline; median+IQR+raw retained; achieved FP64 error per series",
+        "params": {"batches": sorted(set(batches)), "repeats": repeats, "warmup": warmup,
+                   "regime": regime, "seed": seed, "strict": strict,
+                   "error_n": error_n, "error_dps": error_dps},
+        "walrus": walrus_meta,
+        "series": series,
+    }
+    base.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    path = base / f"crossover_{stamp}.json"
+    path.write_text(json.dumps(artifact, indent=2))
+    return artifact, path
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--batches", default=",".join(map(str, DEFAULT_BATCHES)),
+                   help="comma-separated batch sizes to sweep (start low to find the real crossover)")
+    p.add_argument("--repeats", type=int, default=7)
+    p.add_argument("--warmup", type=int, default=2)
+    p.add_argument("--seed", type=int, default=0)
+    p.add_argument("--regime", default="physical", choices=list(_inputs.BENCH_REGIMES))
+    p.add_argument("--error-n", type=int, default=2, help="elements checked vs mpmath (0=off)")
+    p.add_argument("--error-dps", type=int, default=30, help="mpmath precision for the error check")
+    p.add_argument("--no-strict", dest="strict", action="store_false",
+                   help="do NOT fail on e2e disagreement / missing Walrus (non-official run)")
+    p.add_argument("--out", type=Path, default=None)
+    args = p.parse_args()
+    batches = [int(x) for x in args.batches.split(",")]
+    artifact, path = run(batches, args.repeats, seed=args.seed, warmup=args.warmup, regime=args.regime,
+                         error_n=args.error_n, error_dps=args.error_dps, strict=args.strict, out_dir=args.out)
+    w = artifact["walrus"]
+    print(f"# batch-size sweep / crossover ({artifact['gpu_backend']}) -> {path}")
+    print(f"#   commit {artifact['commit']}; container {artifact['container_digest']}; "
+          f"regime={args.regime}; strict={args.strict}; batches={batches}")
+    print(f"#   walrus baseline: {w.get('library_version', 'SKIPPED: ' + str(w.get('skipped')))}")
+    print(f"  {'func':>5} {'dim':>4}  {'fp64 rel.err':>12}  {'x vs cpu':>9} {'x vs walrus':>11}")
+    for s in artifact["series"]:
+        err = s["achieved_rel_err_fp64"]
+        print(f"  {s['func']:>5} {s['matrix_dim']:>4}  {('%.2e' % err) if err is not None else 'n/a':>12}  "
+              f"{str(s['crossover_batch_vs_cpu']):>9} {str(s['crossover_batch_vs_walrus']):>11}")
+
+
+if __name__ == "__main__":
+    main()

bench/kernel_footprint.py

@@ -0,0 +1,120 @@
+"""Static per-thread local-memory footprint of the one-eval-per-thread kernels.
+
+This is the *static* half of "profile register spills / local-memory traffic"
+(perf research item 5): it accounts, from the kernel sources, the per-thread local
+arrays each kernel declares -- the quantity that drives register spilling and the
+local-memory (off-chip) traffic that bounds the hard kernels. The *dynamic* half
+(ncu/nvprof spill counts, achieved occupancy, DRAM throughput) needs a real device
+and is run in a GPU session.
+
+Why this matters, and why it is NOT optimization-by-analogy: the measured cooperative
+results map exactly onto the footprint below. The permanent's per-thread state is a
+single length-n vector (sub-KB -> lives in registers, no spill), so its bottleneck is
+the *serial 2^(n-1) Glynn chain* and splitting that across a group wins ~5x. The
+hafnian / loop hafnian / torontonian instead carry several n x n matrices per thread
+(tens of KB -> spills to local/off-chip memory), so they are memory-bound on the
+*per-subset* work; splitting their (short, 2^(N/2)) subset sum cannot help and adds
+launch + global-partials overhead -- which is exactly what was measured (haf 0.6x,
+lhaf 0.5x, tor 1.2x). The lever for the hard kernels is the per-thread footprint.
+
+    uv run python -m bench.kernel_footprint
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+CPLX = 16  # bytes per cuDoubleComplex (2 x double)
+DBL = 8
+
+# Per-thread local arrays each one-eval-per-thread kernel declares, as
+# (name, element_bytes, size_expr(maxdim)). maxdim is the kernel's compile-time cap
+# (HAF_MAX_N etc.); the arrays are sized for it REGARDLESS of the actual matrix size,
+# which is the core inefficiency for small inputs. Transcribed from core/*.cu.
+_KERNELS: dict[str, dict[str, Any]] = {
+    "permanent": {
+        "cap": 28, "cap_name": "PERM_MAX_N",
+        "buffers": [("rowsum", CPLX, lambda M: M)],
+    },
+    "hafnian": {
+        "cap": 20, "cap_name": "HAF_MAX_N",
+        "buffers": [("BX", CPLX, lambda M: M * M), ("P", CPLX, lambda M: M * M),
+                    ("T", CPLX, lambda M: M * M), ("p", CPLX, lambda M: M + 1),
+                    ("e", CPLX, lambda M: M + 1), ("pidx", 4, lambda M: M // 2)],
+    },
+    "loop_hafnian": {
+        "cap": 20, "cap_name": "LHAF_MAX_N",
+        "buffers": [("C", CPLX, lambda M: M * M), ("P", CPLX, lambda M: M * M),
+                    ("Q", CPLX, lambda M: M * M), ("T", CPLX, lambda M: M * M),
+                    ("d", CPLX, lambda M: M), ("w", CPLX, lambda M: M),
+                    ("kg", CPLX, lambda M: M + 1), ("e", CPLX, lambda M: M + 1),
+                    ("pidx", 4, lambda M: M // 2)],
+    },
+    "torontonian": {
+        "cap": 24, "cap_name": "TOR_MAX_DIM",
+        "buffers": [("sub", CPLX, lambda M: M * M), ("idx", 4, lambda M: M)],
+    },
+}
+
+# A 64 KB/thread guideline: above this, an SM (with e.g. 64-99 KB usable as registers
+# + L1) cannot hold even a handful of threads' working sets, so the per-thread arrays
+# spill to off-chip local memory. The practical spill cliff for these kernels is well
+# below: the register file is 256 KB/SM = 1 KB / thread at full occupancy, so anything
+# past ~1 KB already starts spilling. We report both the footprint and the implied
+# occupancy ceiling so the GPU session knows what to confirm with ncu.
+_REGFILE_PER_SM = 256 * 1024  # bytes (Ampere/Ada: 64K 32-bit registers)
+
+
+def footprint(kernel: str, dim: int) -> int:
+    """Per-thread local-array bytes for `kernel` if its buffers were sized to `dim`."""
+    return sum(eb * sz(dim) for _, eb, sz in _KERNELS[kernel]["buffers"])
+
+
+def report() -> dict[str, Any]:
+    rows = []
+    for name, spec in _KERNELS.items():
+        cap = spec["cap"]
+        at_cap = footprint(name, cap)
+        # threads/SM the register file can hold before spilling (rough occupancy ceiling)
+        threads = _REGFILE_PER_SM // max(at_cap, 1)
+        # for the hard kernels the matrices are usually small; show a small/typical size
+        small = 8 if name != "torontonian" else 8  # dim 8 (haf/lhaf N=8; tor 2n=8)
+        rows.append({
+            "kernel": name, "cap_name": spec["cap_name"], "cap": cap,
+            "bytes_at_cap": at_cap, "kb_at_cap": round(at_cap / 1024, 1),
+            "bytes_at_dim8": footprint(name, small),
+            "kb_at_dim8": round(footprint(name, small) / 1024, 2),
+            "occupancy_threads_per_sm_at_cap": threads,
+            "n_nxn_buffers": sum(1 for nm, _, sz in spec["buffers"] if sz(10) == 100),
+        })
+    return {"kind": "kernel_footprint", "regfile_per_sm_bytes": _REGFILE_PER_SM, "rows": rows}
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--json", type=Path, default=None, help="also write the report as JSON")
+    args = p.parse_args()
+    rep = report()
+    print("# per-thread local-memory footprint (static; the spill source)")
+    print(f"#   register file/SM = {_REGFILE_PER_SM // 1024} KB "
+          f"(~1 KB/thread at full occupancy -> anything past that spills)")
+    print(f"  {'kernel':>13} {'cap':>14} {'KB@cap':>7} {'KB@dim8':>8} {'nxn bufs':>9} "
+          f"{'occ thr/SM@cap':>15}")
+    for r in rep["rows"]:
+        print(f"  {r['kernel']:>13} {r['cap_name']+'='+str(r['cap']):>14} "
+              f"{r['kb_at_cap']:>7} {r['kb_at_dim8']:>8} {r['n_nxn_buffers']:>9} "
+              f"{r['occupancy_threads_per_sm_at_cap']:>15}")
+    print("\n#  Reading: the permanent's <1 KB lives in registers (no spill); the hard")
+    print("#  kernels carry several n x n matrices (tens of KB) -> spill -> memory-bound")
+    print("#  on the per-subset work. Sizing buffers to the ACTUAL dim (size specialization)")
+    print("#  is the lever -- e.g. hafnian at dim 8 is ~6x smaller than at the cap.")
+    if args.json:
+        args.json.write_text(json.dumps(rep, indent=2))
+        print(f"\n# wrote {args.json}")
+
+
+if __name__ == "__main__":
+    main()