Metadata-Version: 2.4
Name: zcc-verify
Version: 0.2.2
Summary: Independent consistency checker for ZKSF quantum certificates: ZCC-v0.1, ZHF-v0.1, ZCC-Estimate-v0.1/v0.2 and ZQEC-v0.1
Author-email: ZKSF <info@zksf.org>
License: MIT
Project-URL: Homepage, https://zksf.org
Project-URL: Source, https://github.com/official-dvl/zksf-zcc-verify
Project-URL: Issues, https://github.com/official-dvl/zksf-zcc-verify/issues
Project-URL: Specification, https://doi.org/10.5281/zenodo.21851380
Project-URL: Protocol, https://github.com/official-dvl/zksf/blob/main/docs/CERTIFICATION.md
Project-URL: SDK, https://pypi.org/project/qsim-sdk/
Keywords: quantum,quantum computing,quantum circuit simulator,certification,verification,error bounds,reproducibility,ZCC,ZHF,ZQEC,quantum error correction
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# zcc-verify

[![CI](https://github.com/official-dvl/zksf-zcc-verify/actions/workflows/ci.yml/badge.svg)](https://github.com/official-dvl/zksf-zcc-verify/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/zcc-verify.svg?v=2)](https://pypi.org/project/zcc-verify/)
[![Python](https://img.shields.io/pypi/pyversions/zcc-verify.svg?v=2)](https://pypi.org/project/zcc-verify/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.21851380-blue.svg)](https://doi.org/10.5281/zenodo.21851380)
[![Quantum computing mobile app on Google Play](https://img.shields.io/badge/Mobile_app-Google_Play-34A853?logo=googleplay&logoColor=white)](https://play.google.com/store/apps/details?id=com.quantumcomputing.app)

Independent consistency checker for ZKSF certificates: **ZCC-v0.1** and **ZHF-v0.1**
accuracy certificates, **ZCC-Estimate-v0.1/v0.2** estimates and **ZQEC-v0.1**
error-correction certificates.

No dependencies. Python 3.10+.

```bash
pip install zcc-verify
zcc-verify fe529e21d7404ff3
```

```
certificate fe529e21d7404ff3 (ZCC-v0.1)
  [ok  ] required fields present
  [ok  ] protocol recognised: ZCC-v0.1
  [ok  ] carries no account or circuit data
  [ok  ] circuit identified by SHA-256
  [ok  ] issued-at timestamp parses: 2026-07-09T13:20:03+00:00
  [ok  ] shot count: 512
  [ok  ] measured outcomes: 2 outcomes, 512 shots shown
  [ok  ] bound is a probability: 2.1073424255447017e-08
  [ok  ] bound recomputed from the measurement: sqrt(2 x 2.22045e-16) = 2.10734e-08
  [ok  ] converged flag consistent with the bound: True
  consistent: the stated bound follows from the stated measurement
```

Exit status is 0 when every check passes and 1 when any fails, so it drops into CI.

## Why this exists

Classical simulation of quantum circuits is exact only in a narrow regime. Exact
statevector methods terminate near 30 to 32 qubits, because state size grows as `2^n`.
Beyond that every practical method is approximate: tensor networks truncate the bond
dimension, Pauli propagation truncates operator weight, and real hardware substitutes
device noise for the ideal distribution.

An approximate result without an error statement is not a measurement, it is an
assertion. **ZCC-v0.1** and **ZHF-v0.1**, and **ZCC-Estimate** and **ZQEC-v0.1** after
them, are small versioned protocols that attach a
machine-checkable accuracy statement to a result. This tool is the checker: it takes a
certificate and confirms the claim it makes follows from the measurement it reports.

The protocols are specified in a citable paper:

> Reporting the Accuracy of Approximate Quantum Circuit Simulation: A Machine-Checkable
> Certificate Format. [doi.org/10.5281/zenodo.21851380](https://doi.org/10.5281/zenodo.21851380)

## What this establishes

The load-bearing check recomputes the declared bound from the measured quantity the
certificate itself reports, and requires the two to agree:

| Method | Reported quantity | Bound must equal |
|---|---|---|
| Matrix product state | discarded SVD weight `eps` | `min(1, sqrt(2 * eps))` |
| Pauli propagation | discarded coefficient mass | the mass itself (additive) |
| Exact / stabilizer | nothing discarded | zero |
| Hardware (ZHF-v0.1) | Hellinger fidelity vs. the exact ideal | within `[0, 1]`, or explicitly declined |
| Photonic hardware (ZHF-v0.1) | shots that detected every photon | the coincidence share, `events / shots` to six places |
| Neural ground state (ZCC-Estimate-v0.2) | energy `E`, its standard error and variance | ceiling `E + 5 * stderr`; floor at or below `E - 5 * stderr - sqrt(variance)` (Weinstein) or `E - 5 * stderr` (Temple), and stated as conditional |
| Zero-noise extrapolation (ZCC-Estimate) | extrapolated value and its uncertainty | no bound to recompute: marked uncertified, uncertainty at one sigma and not negative |
| Error correction (ZQEC-v0.1) | failures and shots at each code distance | each rate's Wilson 95% interval; the least-squares suppression factor and prefactor; its joint 95% range |

It also checks that the record is well formed, that the `converged` flag agrees with the
bound (the two methods use different thresholds), that outcome counts do not exceed the
shot count, and that no account data or circuit source is present.

A certificate whose stated bound does not follow from its own stated inputs fails here,
whoever issued it.

## What this does not establish

**It does not establish that the measurement was honest.** The discarded weight in a
tensor-network certificate, and the coefficient mass in a Pauli one, are produced by
whoever ran the simulation. No arithmetic on the record can confirm that the number
reported is the number that was measured. The same holds for the failure counts in an
error-correction certificate and the energy in a neural one.

Verifying a certificate is not the same as trusting the issuer. What it gives you is
narrower and still worth having: the claim is well formed, self-consistent, and stated
in a form somebody else can check.

## Use as a library

```python
from zcc_verify import fetch, verify

report = verify(fetch("df1d4c698a954051"))
print(report.ok)                          # True
print([c.name for c in report.failures])  # []
```

`fetch()` reads the public record at `https://api.zksf.org/certify/<id>/json`. It needs
no authentication and no account. `verify()` takes a plain dict, so a record from any
source, including a local file or a different issuer, can be checked:

```bash
zcc-verify ./certificate.json
```

Live certificates to try, one for every kind of statement the four protocols make:

| Certificate | Protocol | Run |
|---|---|---|
| `d904e28af0b441e0` | ZCC-v0.1 | 3-qubit GHZ, exact stabilizer simulation |
| `fe529e21d7404ff3` | ZCC-v0.1 | 12-qubit GHZ, tensor network, measured bound of 2.11e-08 |
| `5b8b2c4309d44d41` | ZCC-v0.1 | 192-qubit GHZ, Pauli propagation |
| `df1d4c698a954051` | ZHF-v0.1 | Bell state on IonQ Forte-1 hardware, 0.977 fidelity |
| `063a6fcb82a9464a` | ZHF-v0.1 | Two photons on photonic hardware, 0.967 fidelity conditioned on detecting both |
| `b358005dc6724273` | ZQEC-v0.1 | Surface code at distance 5, 4 failures in 20,000 shots |
| `881ba3500ed94538` | ZQEC-v0.1 | Surface code at distances 3, 5 and 7, suppression factor 7.26 fitted, 95% range 3.46 to 15.2 |
| `66e9fabc9e784425` | ZCC-Estimate-v0.2 | 8-spin Ising ring, neural ground state, ceiling -10.2499758 |
| `9dcf796bd99648a0` | ZCC-Estimate-v0.2 | Zero-noise extrapolation, mitigated value with a one-sigma uncertainty |

## On the limits of the bound

The certified bound is an empirical result rather than a theorem. It held across 334
runs at sizes where the exact answer is computable, 290 of them constructed specifically
to break it, approaching at closest 49 percent of its value. Above 20 qubits it cannot
be checked by direct comparison and no such evidence exists. Where a hard ceiling is
required, use an exact or stabilizer engine.

The paper is explicit about the case in which the motivating derivation does not extend:
in deep sequential circuits the accumulated truncation weight has been measured
understating the true infidelity by up to a factor of seven. It also shows, by explicit
counterexample, that a natural tightening of the bound is unsound.

## Where these certificates come from

[ZKSF (Zero Kelvin Simulation Foundry)](https://zksf.org) runs quantum circuits on
classical simulators, GPU accelerators, or real quantum processors, and attaches one of
these accuracy statements to every approximate result.

- **Python SDK** — [`qsim-sdk`](https://pypi.org/project/qsim-sdk/) on PyPI, source at
  [official-dvl/zksf](https://github.com/official-dvl/zksf), DOI
  [10.5281/zenodo.21836619](https://doi.org/10.5281/zenodo.21836619). Accepts Qiskit
  circuits directly, and Cirq, PennyLane, pyQuil or Braket circuits via an optional
  transpiler.
- **Try it without an account** — the
  [Colab quickstart](https://colab.research.google.com/github/official-dvl/zksf/blob/main/examples/quickstart.ipynb)
  reads real completed certificates from the public API before it asks you for anything.
- **Android app** — submit a circuit and read the result from a phone, including runs on
  real quantum hardware:
  [Google Play](https://play.google.com/store/apps/details?id=com.quantumcomputing.app).
- **Protocol reference** —
  [CERTIFICATION.md](https://github.com/official-dvl/zksf/blob/main/docs/CERTIFICATION.md)
- **Documentation** — [zksf.org/docs](https://zksf.org/docs)

This checker is deliberately independent of all of the above: it has no dependency on
the SDK, needs no account, and will check a certificate issued by anyone who emits the
format.

## Licence

MIT.
