Circuit library

Circuits, drawn the way we think about them.

Four worked examples, from a two-qubit Bell pair to a surface-code patch. Each one shows the circuit, the state or observable it produces, and the routine that builds it. Hover a gate to light it up.

single-qubit gate two-qubit / control phase rotation measurement
EXAMPLE 01

Bell pair

|ψ⟩ = (|00⟩ + |11⟩)/√2
bell_pair.qv2 qubits · depth 2
maximally entangled pair q₀q₁ |0⟩|0⟩ H measure → bits ⟨Z₀ ⊗ Z₁⟩ = +1
Build
from quantuva import Circuit, Observable

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

obs = Observable("Z(0) @ Z(1)")
result = qc.run(shots=2048)
print(result.expectation(obs))
Readout
The Bell state is the simplest entangled state: a single Hadamard plus one CNOT, and the two qubits are maximally entangled — measuring one fixes the other.
|00⟩
|11⟩
|01⟩
|10⟩
outcome distribution · illustrative, no noise
EXAMPLE 02

GHZ state

|ψ⟩ = (|000⟩ + |111⟩)/√2
ghz_state.qv3 qubits · depth 6
three-qubit entanglement q₀q₁q₂ |0⟩|0⟩|0⟩ H measure → bits ⟨Z₀ ⊗ Z₁⟩ = ⟨Z₁ ⊗ Z₂⟩ = +1
Build
qc = Circuit(3)
qc.h(0)
qc.cx(0, 1)
qc.cx(0, 2)
qc.measure_all()

# both stabilizers should be +1
for obs in ["Z(0) @ Z(1)", "Z(1) @ Z(2)"]:
    print(qc.run(2048).expectation(Observable(obs)))
Readout
The GHZ state spreads one qubit's superposition across three. Its defining feature is the pair of stabilizers that hold it together — each two-point correlator is exactly +1.
|000⟩
|111⟩
outcome distribution · illustrative, no noise
EXAMPLE 03

Quantum Fourier transform

4 qubits · controlled phase rotations
qft4.qv4 qubits · depth 11
QFT₄ — R_k = diag(1, e^{2πi/2^k}) q₀q₁q₂q₃ |x₀⟩|x₁⟩|x₂⟩|x₃⟩ H H H H R₂ R₃ R₄ R₂ R₃ R₂ swap
Build
qc = Circuit(4)
for i in range(4):
    qc.h(i)
    for j in range(i + 1, 4):
        qc.cp(2 * math.pi / 2**(j - i + 1), i, j)
# un-reverse the bit order
qc.swap(0, 3)
qc.swap(1, 2)
Readout
The QFT is a Hadamard followed by a staircase of controlled phase rotations, then a bit-reversal. It's the workhorse behind phase estimation and Shor's algorithm — and a good stress test for a transpiler's SWAP routing.
each controlled rotation angle: π / 2^(k-1)
EXAMPLE 04

Surface-code patch

stabilizer geometry · not a gate circuit
surface_patch.qvdata + ancilla qubits
distance-3 patch · ○ data qubit · X / Z stabilizer faces ZZZZ XXXX stabilizers are measured repeatedly; a changed syndrome flags an error
Note
# the surface code is geometry, not a gate list.
# data qubits sit on vertices; ancilla qubits sit
# inside each face and read out a stabilizer.
from quantuva.codes import SurfaceCode

code = SurfaceCode(d=3)
syndrome = code.measure_round()
Readout
The surface code arranges data and ancilla qubits on a grid so that errors show up as a change in a measured stabilizer. An X error flips adjacent Z checks; a Z error flips adjacent X checks. The decoder reads that syndrome and corrects it.
distance d sets how many errors the patch tolerates