Q-Verdict Free Client

Installation

The free client will be available on PyPI. Early access participants can install from the provided distribution file:

pip install q-verdict

Python 3.9 or later is required. The client has no mandatory runtime dependencies beyond your existing framework installation. Install only the adapters you need:

# Qiskit
pip install q-verdict qiskit

# Cirq
pip install q-verdict cirq

# TKET
pip install q-verdict pytket

# Amazon Braket
pip install q-verdict amazon-braket-sdk

# OpenQASM (no additional dependency required)
pip install q-verdict

Quickstart

Pass any supported circuit to QVerdict().analyze(). The client runs its classification locally and returns a result object.

from qverdict import QVerdict
from qiskit.circuit.library import QFT

circuit = QFT(4)
result  = QVerdict().analyze(circuit, shots=2048)

print(result.verdict)
# "noise" | "bug" | "inconclusive"

print(result.reason)
# "Readout error on qubit 1, asymmetric calibration drift." (illustrative example)

print(result.confidence)
# 0.87  (illustrative; actual confidence varies by circuit and shot budget)

print(result.evidence)
# {"error_type": "readout", "qubit": 1, "rate": 0.043, ...}  (illustrative example)

The shots argument controls how many simulated samples the classifier uses internally. Higher shot counts give the classifier more signal and reduce inconclusive verdicts on borderline cases. The default is 1024.

Interpreting results

Noise

The circuit logic is correct. The bad result is consistent with hardware-level error patterns: readout calibration drift, coherent gate error, cross-talk, or decoherence accumulation. The circuit would produce the correct answer on a noiseless device.

Next step: apply error mitigation (zero-noise extrapolation, probabilistic error cancellation), increase shot count, or recalibrate the target qubit(s) before rerunning.

Bug

The circuit contains a logical error that would produce an incorrect result even on a perfect, noiseless device. The error is in the circuit construction, not the hardware. Common causes: incorrect qubit ordering, missing or duplicated gates, phase errors, or discrepancies introduced by a transpiler pass.

Next step: inspect the circuit. Error mitigation will not help; the circuit needs to be corrected first.

Inconclusive

The evidence is insufficient to distinguish hardware error from a circuit bug at this shot count or noise level. result.evidence contains the classifier's working data and identifies what additional information would resolve the classification.

Next step: increase shots and rerun, or submit to the licensed engine for structural verdict analysis, which does not depend on shot count.

Framework adapters

Qiskit

Pass any qiskit.QuantumCircuit directly.

from qverdict import QVerdict
from qiskit import QuantumCircuit

qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()

result = QVerdict().analyze(qc)

Cirq

Pass any cirq.Circuit directly.

from qverdict import QVerdict
import cirq

q0, q1 = cirq.LineQubit.range(2)
circuit = cirq.Circuit([cirq.H(q0), cirq.CNOT(q0, q1), cirq.measure(q0, q1)])

result = QVerdict().analyze(circuit)

TKET

Pass any pytket.Circuit directly.

from qverdict import QVerdict
from pytket import Circuit

circuit = Circuit(2)
circuit.H(0).CX(0, 1).measure_all()

result = QVerdict().analyze(circuit)

Amazon Braket

Pass any braket.circuits.Circuit directly.

from qverdict import QVerdict
from braket.circuits import Circuit

circuit = Circuit().h(0).cnot(0, 1)

result = QVerdict().analyze(circuit)

No AWS account or network connection is required. The adapter operates on the circuit object locally.

OpenQASM

Pass an OpenQASM 3.0 source string. The adapter parses the program and reconstructs the circuit graph before analysis. No intermediate transpilation is performed.

from qverdict import QVerdict

qasm = """
OPENQASM 3.0;
qubit[2] q;
bit[2] c;
h q[0];
cx q[0], q[1];
c = measure q;
"""

result = QVerdict().analyze(qasm)

Result object

QVerdict().analyze() returns a VerdictResult instance with the following properties.

Configuration

Options can be passed at instantiation or per call. Per-call arguments take precedence.

# set defaults at instantiation
qv = QVerdict(shots=4096, verbose=False)

# override per call
result = qv.analyze(circuit, shots=8192)

Limitations

The free client classifies based on statistical signatures. It does not have access to the circuit's full derivation chain or structural properties.

• Verdict quality depends on shot count. Low shot counts produce more inconclusive results, particularly when noise and bug signatures overlap.
• The client cannot distinguish between multiple simultaneous error sources in a single circuit. It identifies the dominant source.
• Photonic and continuous-variable circuits require the licensed engine. The free client will return an error if a photonic circuit is passed.
• Structural verdict (catches what a histogram misses, no reference run needed) requires the licensed engine.

If you are consistently seeing inconclusive verdicts or need structural verdict analysis, the licensed engine addresses both. Apply for enterprise licensing →