qig-bench 0.1.0__tar.gz

qig_bench-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: qig-bench
+Version: 0.1.0
+Summary: Validation harness for QIG compute backends — benchmark against frozen physics results
+Project-URL: Homepage, https://github.com/GaryOcean428/qig-bench
+Project-URL: Repository, https://github.com/GaryOcean428/qig-bench
+Author-email: Braden Lang <braden@garyocean.com>
+License: MIT
+Keywords: benchmarking,physics,qig,quantum,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: qig-warp>=0.4.0; extra == 'full'
+Requires-Dist: scipy>=1.10; extra == 'full'
+Description-Content-Type: text/markdown
+
+# qig-bench
+
+Validation harness for QIG compute backends — benchmark against frozen physics results.
+
+## Install
+
+```bash
+pip install qig-bench
+```
+
+## Usage
+
+```python
+from qig_bench import run_suite
+from qig_bench.compare import compare
+
+results = run_suite(backend="my-backend", verification_root="path/to/qig-verification")
+table = compare({"my-backend": results})
+print(table)
+```
+
+## Core 5 Benchmarks
+
+| # | Benchmark | Frozen Value | Tolerance |
+|---|---|---|---|
+| 1 | Constitutive κ at L=4 | 63.32 | ±5% |
+| 2 | Screening ξ_G at L=5 | 0.6182 | ±2% |
+| 3 | Anderson α | 0.089/site | ±5% |
+| 4 | Bridge exponent | 0.86 | ±10% |
+| 5 | Regime h_t | 0.1055 | ±5% |

qig_bench-0.1.0/README.md

@@ -0,0 +1,30 @@
+# qig-bench
+
+Validation harness for QIG compute backends — benchmark against frozen physics results.
+
+## Install
+
+```bash
+pip install qig-bench
+```
+
+## Usage
+
+```python
+from qig_bench import run_suite
+from qig_bench.compare import compare
+
+results = run_suite(backend="my-backend", verification_root="path/to/qig-verification")
+table = compare({"my-backend": results})
+print(table)
+```
+
+## Core 5 Benchmarks
+
+| # | Benchmark | Frozen Value | Tolerance |
+|---|---|---|---|
+| 1 | Constitutive κ at L=4 | 63.32 | ±5% |
+| 2 | Screening ξ_G at L=5 | 0.6182 | ±2% |
+| 3 | Anderson α | 0.089/site | ±5% |
+| 4 | Bridge exponent | 0.86 | ±10% |
+| 5 | Regime h_t | 0.1055 | ±5% |

qig_bench-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qig-bench"
+version = "0.1.0"
+description = "Validation harness for QIG compute backends — benchmark against frozen physics results"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Braden Lang", email = "braden@garyocean.com"},
+]
+keywords = ["qig", "benchmarking", "validation", "physics", "quantum"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "numpy>=1.24",
+]
+
+[project.optional-dependencies]
+full = ["scipy>=1.10", "qig-warp>=0.4.0"]
+dev = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/GaryOcean428/qig-bench"
+Repository = "https://github.com/GaryOcean428/qig-bench"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qig_bench"]

qig_bench-0.1.0/src/qig_bench/__init__.py

@@ -0,0 +1,33 @@
+"""
+qig-bench v0.1.0 — Validation Harness for QIG Compute Backends
+
+Benchmarks compute backends against frozen physics results.
+Any upgrade to qig-compute, qig-warp, or qigv must pass these
+benchmarks before promotion from alpha to stable.
+
+Core 5 Benchmark Suite:
+  1. Constitutive law κ at L=4 (EXP-000.004)
+  2. Screening length ξ at L=5 (EXP-066)
+  3. Anderson orthogonality α (EXP-041)
+  4. Bridge exponent at L=4 h=3.0 (EXP-042)
+  5. Regime sweep h_t at L=5 (EXP-004b)
+
+Usage:
+    from qig_bench import run_suite, compare
+
+    # Run against a compute backend
+    results = run_suite(backend="qigv")
+
+    # Compare multiple backends
+    table = compare(["pre-warp", "warp-0.3", "warp-0.4.1", "qig-compute"])
+"""
+
+__version__ = "0.1.0"
+
+from qig_bench.suite import (
+    BENCHMARKS,
+    Benchmark,
+    BenchmarkResult,
+    run_suite,
+)
+from qig_bench.compare import compare, format_table

qig_bench-0.1.0/src/qig_bench/compare.py

@@ -0,0 +1,116 @@
+"""
+Comparison table generator — format benchmark results across backends.
+"""
+
+from __future__ import annotations
+
+from qig_bench.suite import BenchmarkResult, BENCHMARKS
+
+
+def compare(suite_results: dict[str, list[BenchmarkResult]]) -> str:
+    """Generate comparison table from multiple backend runs.
+
+    Args:
+        suite_results: {backend_name: [BenchmarkResult, ...]}
+
+    Returns:
+        Formatted comparison table string
+    """
+    backends = list(suite_results.keys())
+    benchmark_ids = list(BENCHMARKS.keys())
+
+    # Build lookup: backend -> benchmark_id -> result
+    lookup = {}
+    for backend, results in suite_results.items():
+        lookup[backend] = {r.benchmark_id: r for r in results}
+
+    return format_table(backends, benchmark_ids, lookup)
+
+
+def format_table(backends: list[str], benchmark_ids: list[str],
+                 lookup: dict[str, dict[str, BenchmarkResult]]) -> str:
+    """Format the comparison table."""
+    # Column headers
+    col_headers = {
+        "kappa_L4": "κ",
+        "xi_L5": "ξ",
+        "anderson_alpha": "α",
+        "bridge_exponent": "τ-exp",
+        "regime_h_t": "h_t",
+    }
+
+    frozen_vals = {bid: BENCHMARKS[bid].frozen_value for bid in benchmark_ids}
+
+    lines = []
+    lines.append("╔" + "═" * 72 + "╗")
+    lines.append("║  qig-bench v0.1.0 — Compute Backend Comparison" + " " * 25 + "║")
+    lines.append("╠" + "═" * 72 + "╣")
+
+    # Header row
+    header = f"║ {'Backend':>20s}"
+    for bid in benchmark_ids:
+        header += f" {col_headers.get(bid, bid):>8s}"
+    header += f" {'Time':>8s} {'Pass':>5s} ║"
+    lines.append(header)
+
+    # Frozen reference row
+    frozen_row = f"║ {'[frozen]':>20s}"
+    for bid in benchmark_ids:
+        frozen_row += f" {frozen_vals[bid]:>8.4f}"
+    frozen_row += f" {'—':>8s} {'—':>5s} ║"
+    lines.append(frozen_row)
+
+    lines.append("║" + "─" * 72 + "║")
+
+    # Backend rows
+    for backend in backends:
+        row = f"║ {backend:>20s}"
+        total_time = 0.0
+        all_passed = True
+
+        for bid in benchmark_ids:
+            result = lookup.get(backend, {}).get(bid)
+            if result and result.measured_value is not None:
+                row += f" {result.measured_value:>8.4f}"
+                total_time += result.runtime_s
+                if not result.passed:
+                    all_passed = False
+            elif result and result.error:
+                row += f" {'ERR':>8s}"
+                all_passed = False
+            else:
+                row += f" {'—':>8s}"
+                all_passed = False
+
+        time_str = f"{total_time:.1f}s" if total_time > 0 else "—"
+        pass_str = "✓" if all_passed else "✗"
+        row += f" {time_str:>8s} {pass_str:>5s} ║"
+        lines.append(row)
+
+    lines.append("╚" + "═" * 72 + "╝")
+    return "\n".join(lines)
+
+
+def format_detailed(results: list[BenchmarkResult]) -> str:
+    """Format detailed results for a single backend."""
+    lines = []
+    lines.append(f"Backend: {results[0].backend if results else 'unknown'}")
+    lines.append("-" * 60)
+
+    for r in results:
+        bm = BENCHMARKS.get(r.benchmark_id)
+        name = bm.name if bm else r.benchmark_id
+        status = "PASS" if r.passed else "FAIL"
+        if r.error:
+            status = f"ERROR: {r.error}"
+
+        val_str = f"{r.measured_value:.6f}" if r.measured_value is not None else "N/A"
+        dev_str = f"{r.deviation_pct:.2f}%" if r.deviation_pct is not None else "N/A"
+
+        lines.append(f"  {name:30s} {val_str:>12s} (frozen: {r.frozen_value:.4f}, "
+                     f"dev: {dev_str:>8s}, {r.runtime_s:.2f}s) [{status}]")
+
+    passed = sum(1 for r in results if r.passed)
+    total = len(results)
+    lines.append(f"\n  {passed}/{total} benchmarks passed")
+    return "\n".join(lines)

qig_bench-0.1.0/src/qig_bench/suite.py

@@ -0,0 +1,271 @@
+"""
+Core 5 Benchmark Suite — frozen physics results as validation gates.
+
+Each benchmark defines:
+  - What to measure (observable, experiment source)
+  - The frozen value (from qig-verification results)
+  - Tolerance (how close the backend must get)
+  - A runner function that takes a compute backend and returns the result
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+import numpy as np
+
+
+@dataclass
+class Benchmark:
+    """Definition of a single benchmark test."""
+    id: str
+    name: str
+    frozen_value: float
+    tolerance_pct: float
+    unit: str
+    source_experiment: str
+    description: str
+    runner: Callable | None = None  # Set after definition
+
+
+@dataclass
+class BenchmarkResult:
+    """Result of running one benchmark."""
+    benchmark_id: str
+    measured_value: float | None
+    frozen_value: float
+    deviation_pct: float | None
+    passed: bool
+    runtime_s: float
+    backend: str
+    error: str | None = None
+    metadata: dict = field(default_factory=dict)
+
+
+# ═══════════════════════════════════════════════════════════════
+# CORE 5 BENCHMARKS
+# ═══════════════════════════════════════════════════════════════
+
+BENCHMARKS = {
+    "kappa_L4": Benchmark(
+        id="kappa_L4",
+        name="Constitutive κ at L=4",
+        frozen_value=63.32,
+        tolerance_pct=5.0,
+        unit="dimensionless",
+        source_experiment="EXP-000.004",
+        description="G = κT constitutive law. Matrix-trace extraction on L=4 PBC torus.",
+    ),
+    "xi_L5": Benchmark(
+        id="xi_L5",
+        name="Screening ξ_G at L=5",
+        frozen_value=0.6182,
+        tolerance_pct=2.0,
+        unit="lattice spacings",
+        source_experiment="EXP-066",
+        description="Yukawa screening length from single-defect curvature response.",
+    ),
+    "anderson_alpha": Benchmark(
+        id="anderson_alpha",
+        name="Anderson α",
+        frozen_value=0.089,
+        tolerance_pct=5.0,
+        unit="per site",
+        source_experiment="EXP-041",
+        description="Orthogonality catastrophe decay rate from wavefunction overlap.",
+    ),
+    "bridge_exponent": Benchmark(
+        id="bridge_exponent",
+        name="Bridge exponent at h=3.0",
+        frozen_value=0.86,
+        tolerance_pct=10.0,
+        unit="dimensionless",
+        source_experiment="EXP-042",
+        description="τ ∝ J^α bridge law from sign-flip N-updates counting.",
+    ),
+    "regime_h_t": Benchmark(
+        id="regime_h_t",
+        name="Regime transition h_t",
+        frozen_value=0.10554,
+        tolerance_pct=5.0,
+        unit="field strength",
+        source_experiment="EXP-004b",
+        description="First field value where R² crosses 0.5 in κ(h) sweep.",
+    ),
+}
+
+
+def _check_result(measured: float, frozen: float, tolerance_pct: float) -> tuple[float, bool]:
+    """Check if measured value is within tolerance of frozen value."""
+    if frozen == 0:
+        deviation = abs(measured) * 100
+    else:
+        deviation = abs(measured - frozen) / abs(frozen) * 100
+    passed = deviation <= tolerance_pct
+    return round(deviation, 4), passed
+
+
+def run_single(benchmark: Benchmark, backend: str = "qigv",
+               verification_root: Path | None = None) -> BenchmarkResult:
+    """Run a single benchmark against a compute backend.
+
+    For now, reads frozen results from qig-verification files.
+    Future: actually recompute using the specified backend.
+    """
+    t0 = time.time()
+
+    if verification_root is None:
+        # Try to find qig-verification relative to this package
+        here = Path(__file__).resolve()
+        for parent in here.parents:
+            candidate = parent / "qig-verification" / "results"
+            if candidate.exists():
+                verification_root = parent / "qig-verification"
+                break
+        if verification_root is None:
+            return BenchmarkResult(
+                benchmark_id=benchmark.id,
+                measured_value=None,
+                frozen_value=benchmark.frozen_value,
+                deviation_pct=None,
+                passed=False,
+                runtime_s=0,
+                backend=backend,
+                error="Cannot find qig-verification/results directory",
+            )
+
+    try:
+        measured = _read_frozen_result(benchmark.id, verification_root)
+        deviation, passed = _check_result(measured, benchmark.frozen_value, benchmark.tolerance_pct)
+
+        return BenchmarkResult(
+            benchmark_id=benchmark.id,
+            measured_value=round(measured, 6),
+            frozen_value=benchmark.frozen_value,
+            deviation_pct=deviation,
+            passed=passed,
+            runtime_s=round(time.time() - t0, 4),
+            backend=backend,
+        )
+    except Exception as e:
+        return BenchmarkResult(
+            benchmark_id=benchmark.id,
+            measured_value=None,
+            frozen_value=benchmark.frozen_value,
+            deviation_pct=None,
+            passed=False,
+            runtime_s=round(time.time() - t0, 4),
+            backend=backend,
+            error=str(e),
+        )
+
+
+def _read_frozen_result(benchmark_id: str, verification_root: Path) -> float:
+    """Read a frozen result value from qig-verification."""
+    results = verification_root / "results"
+
+    if benchmark_id == "kappa_L4":
+        registry = results / "validated" / "kappa_registry.json"
+        if registry.exists():
+            with open(registry) as f:
+                data = json.load(f)
+            # Structure: {"validated": {"L4_geometric": {"kappa": ...}}}
+            validated = data.get("validated", {})
+            for key, entry in validated.items():
+                if isinstance(entry, dict) and entry.get("L") == 4:
+                    return entry["kappa"]
+        raise FileNotFoundError("No kappa value found for L=4 in registry")
+
+    elif benchmark_id == "xi_L5":
+        # Read from pruning_validation.json which has the frozen ξ fits
+        pv = results / "exp066" / "pruning_validation.json"
+        if pv.exists():
+            with open(pv) as f:
+                data = json.load(f)
+            for entry in data.get("results", []):
+                if entry.get("L") == 5:
+                    return entry["full"]["xi"]
+        raise FileNotFoundError("No ξ found in EXP-066 pruning_validation.json")
+
+    elif benchmark_id == "anderson_alpha":
+        for fn in sorted((results / "exp041").glob("*.json")):
+            with open(fn) as f:
+                data = json.load(f)
+            ps = data.get("primary_scaling", {})
+            if isinstance(ps, dict) and "alpha_per_site" in ps:
+                return ps["alpha_per_site"]
+        raise FileNotFoundError("No Anderson alpha found in EXP-041 results")
+
+    elif benchmark_id == "bridge_exponent":
+        # Find L=4 or L=5 at h=3.0 and fit τ vs J
+        for fn in sorted((results / "exp042").glob("*L5*.json")):
+            with open(fn) as f:
+                data = json.load(f)
+            per_J = data.get("per_J", [])
+            if not per_J:
+                continue
+            # Extract τ = N_updates / omega for J >= 1.5
+            Js, taus = [], []
+            for p in per_J:
+                J = p.get("J", 0)
+                N = p.get("N_updates", 0)
+                omega = p.get("omega", 0)
+                if J >= 1.5 and omega > 0 and N > 0:
+                    Js.append(J)
+                    taus.append(N / omega)
+            if len(Js) >= 3:
+                log_J = np.log(np.array(Js))
+                log_tau = np.log(np.array(taus))
+                coeffs = np.polyfit(log_J, log_tau, 1)
+                return coeffs[0]  # bridge exponent
+        # Fallback to L=4
+        for fn in sorted((results / "exp042").glob("*L4*.json")):
+            with open(fn) as f:
+                data = json.load(f)
+            per_J = data.get("per_J", [])
+            if not per_J:
+                continue
+            Js, taus = [], []
+            for p in per_J:
+                J = p.get("J", 0)
+                N = p.get("N_updates", 0)
+                omega = p.get("omega", 0)
+                if J >= 1.5 and omega > 0 and N > 0:
+                    Js.append(J)
+                    taus.append(N / omega)
+            if len(Js) >= 3:
+                log_J = np.log(np.array(Js))
+                log_tau = np.log(np.array(taus))
+                coeffs = np.polyfit(log_J, log_tau, 1)
+                return coeffs[0]
+        raise FileNotFoundError("No bridge exponent found in EXP-042 results")
+
+    elif benchmark_id == "regime_h_t":
+        for fn in sorted((results / "exp004b").glob("*L5*.json")):
+            with open(fn) as f:
+                data = json.load(f)
+            if "h_t" in data:
+                return data["h_t"]
+            if "transition_midpoint" in data:
+                return data["transition_midpoint"]
+            if "analysis" in data:
+                a = data["analysis"]
+                if isinstance(a, dict) and "h_t" in a:
+                    return a["h_t"]
+        raise FileNotFoundError("No h_t found in EXP-004b results")
+
+    raise ValueError(f"Unknown benchmark: {benchmark_id}")
+
+
+def run_suite(backend: str = "qigv",
+              verification_root: Path | None = None) -> list[BenchmarkResult]:
+    """Run all Core 5 benchmarks."""
+    results = []
+    for bm in BENCHMARKS.values():
+        result = run_single(bm, backend=backend, verification_root=verification_root)
+        results.append(result)
+    return results