TVD Certificate Verification — 12-Qubit Exact Reference

12 qubits  ·  Depth 4  ·  KLT MPS vs exact statevector  ·  Certificate is always a safe upper bound

What this benchmark tests

Every Qumulator result includes a TVD accuracy certificate — an analytically derived upper bound on the total variation distance between the engine's output distribution and the ideal quantum output. This certificate requires no exact reference simulation and scales to circuits far too large to simulate exactly.

This benchmark verifies the certificate on a 12-qubit depth-4 circuit where the exact statevector result is computable. We compare the certified bound against the true measured TVD. The result confirms a key property: the certificate is always a safe conservative upper bound — the engine is 25% more accurate than the certificate claims.

Predicted vs measured TVD

Full result summary

Reproduce this result

Run the KLT engine and the exact statevector engine on the same circuit, then compute the TVD between the two output probability distributions. The certificate bound is in result.tvd_bound on the KLT result.

pip install qumulator-sdk

import os
import numpy as np
from qumulator import QumulatorClient

client = QumulatorClient(
    api_url=os.environ["QUMULATOR_API_URL"],
    api_key=os.environ["QUMULATOR_API_KEY"],
)

# 12-qubit circuit: 4 layers of random CX + Ry rotations
N = 12
rng = np.random.default_rng(7)
instructions = []
for d in range(4):
    for q in range(N):
        instructions.append({"gate": "ry", "qubits": q, "params": [rng.uniform(0, 2*np.pi)]})
    for q in range(0, N-1, 2):
        instructions.append({"gate": "cx", "qubits": [q, q+1]})
    for q in range(1, N-1, 2):
        instructions.append({"gate": "cx", "qubits": [q, q+1]})

SHOTS = 16384  # enough shots for accurate TVD estimate

# Run KLT MPS engine — gets the certificate
r_klt = client.circuit.run(
    n_qubits=N, instructions=instructions,
    mode="klt_mps", bond_dim=32,
    shots=SHOTS, seed=0, return_entropy_map=True,
)

# Run exact statevector engine — ground truth
r_exact = client.circuit.run(
    n_qubits=N, instructions=instructions,
    mode="statevector",
    shots=SHOTS, seed=0,
)

# Compute empirical TVD from shot histograms
def shots_to_probs(counts, n_qubits):
    probs = np.zeros(2**n_qubits)
    for bits, cnt in counts.items():
        probs[int(bits, 2)] = cnt
    return probs / probs.sum()

p_klt   = shots_to_probs(r_klt.counts,   N)
p_exact = shots_to_probs(r_exact.counts, N)
tvd     = 0.5 * np.sum(np.abs(p_klt - p_exact))

print(f"Certified bound : TVD ≤ {r_klt.tvd_bound:.3f}")  # → 0.132
print(f"Measured TVD    : {tvd:.3f}")                     # → 0.100
print(f"Certificate OK  : {tvd <= r_klt.tvd_bound}")      # → True
print(f"Margin          : {(r_klt.tvd_bound - tvd) / r_klt.tvd_bound * 100:.0f}% better than certified")
# → 25%

Why TVD is the right accuracy metric

Total variation distance measures the maximum probability any event could be assigned differently between two distributions: TVD = max_S|P(S) − Q(S)|. For quantum circuit sampling this directly answers: "how wrong could my sampled frequencies be?"

A TVD of 0.10 means that for any subset of bitstrings, the KLT output assigns at most 10% more or less probability than the exact quantum output. For most applications — including variational algorithms, optimization, and randomness generation — a TVD below 0.15 is sufficient for correct results.