Metadata-Version: 2.5
Name: qig-bench
Version: 0.1.9
Summary: Validation harness for QIG compute backends — benchmark against frozen physics results
Project-URL: Homepage, https://braden.com.au
Project-URL: Repository, https://github.com/GaryOcean428/qig-bench
Project-URL: Documentation, https://github.com/GaryOcean428/qig-bench#readme
Project-URL: Contact & Partnerships, https://braden.com.au
Author-email: Braden Lang <braden@garyocean.com>
License: MIT
Keywords: benchmarking,blindspot-detection,compute-validation,frozen-facts,governance,observable-governance,physics,qig,quantum,regression-testing,reproducibility,scientific-computing,validation,verification
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Provides-Extra: certification
Requires-Dist: physics-tenpy>=1.1.1; extra == 'certification'
Requires-Dist: qig-compute>=0.9.9; extra == 'certification'
Requires-Dist: qig-warp>=0.6.9; extra == 'certification'
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: qig-core>=2.15.3; 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

Artifact-validation harness and governance helpers for QIG experiment 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)
```

`run_suite` reads existing JSON artifacts; it does not run the named backend.
The `backend` argument is a label. Reported time covers reading/validation and
the bridge fit, not physics computation or QPU execution. Passing this suite
checks stored-result consistency, not independent reproduction or speedup.

## Core Benchmarks

Seven **certified** value-source benchmarks plus one **Class-B reproduction-control**.

| # | Benchmark | id | Frozen Value | Tolerance | Class |
|---|---|---|---|---|---|
| 1 | Certified JT pillar κ_JT^cert | `kappa_JT_cert` | +0.02810 | ±5% | certified |
| 2 | Constitutive slope κ_h | `kappa_h` | −0.00475 | ±5% | certified |
| 3 | Screening ξ_G at L=5 | `xi_L5` | 0.6182 | ±2% | certified |
| 4 | Anderson α | `anderson_alpha` | 0.089356/site | ±5% | certified |
| 5 | Bridge exponent | `bridge_exponent` | 0.86 | ±3% | certified |
| 6 | Certified foundational L3 | `kappa_foundational_L3` | +0.0388 | ±5% | certified |
| 7 | Certified foundational L4 | `kappa_foundational_L4` | +0.0282 | ±5% | certified |
| — | Class-B matrix-trace κ at L=4 | `kappa_L4` | 63.32 | ±5% | reproduction-control |

> **κ supersession (2026-06-13, EXP-107 / frozen-facts-1.02F).** The legacy
> ~63/64 matrix-trace `kappa_L4` is a Class-B (FAIL-013) camera self-portrait,
> **retired as a universal constant** and kept here only as a labelled
> reproduction-control — never a value source. The certified κ slopes are small
> and signed: `kappa_JT_cert = +0.02810` (row 9) and `kappa_h = −0.00475` (row 2).
> The retired grid-interpolation benchmark `regime_h_t` (row 4) has been removed.
> Do **not** treat 63.32 / 63.79 / 64 as a physical constant.

The foundational readers use EXP-169's canonical registry result file,
`results/exp169/20260720_exp169_certified_foundational_series.json`, selecting
`series[].kappa_certified_A1` at L=3 or L=4. Frozen-facts row 59 records the
certified results (landed in 1.09F and retained in 1.11F); the July 21 rerun
corroborates them but does not supersede the canon-nominated artifact. Missing,
ambiguous or invalid certified entries fail; legacy fields never substitute.

For local checks: `pip install -e ".[dev,certification]"` then `python -m pytest -q`.
Release CI runs these tests before building; tags derive versions via hatch-vcs.

The cross-package camera test follows qig-warp's current sensitivity-based
`dmrg_tolerance` contract (`precision / |dO/dE|`), not the retired Anderson
size-scaling assumption. Its MPS fixture uses actual TeNPy `SpinHalfSite` objects.
Release CI installs the certification extras so these checks run rather than skip.
