Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/itsubaki/qasm-playground/llms.txt

Use this file to discover all available pages before exploring further.

Grover’s algorithm provides a quadratic speedup for searching an unstructured database of N entries for M marked solutions. While a classical search needs O(N) queries on average, Grover’s algorithm finds a solution in O(√(N/M)) iterations with high probability. This example searches a 4-bit state space representing a 2×2 binary grid, looking for assignments r=[a,b,c,d] where all adjacent cells differ — a constraint-satisfaction problem that has exactly two solutions.

Code

// Grover's Algorithm
//
// Searches a 4-bit state space (2x2 binary grid) using Grover iterations,
// where r = [a, b, c, d].
//
// The oracle marks the two valid solutions satisfying the constraints:
// a != b, c != d, a != c, and b != d.
// The solutions are [1,0,0,1] and [0,1,1,0].

OPENQASM 3.0;

gate x q { U(pi, 0, pi) q; }
gate h q { U(pi/2.0, 0, pi) q; }
gate cx q0, q1 { ctrl @ U(pi, 0, pi) q0, q1; }
gate xor q0, q1, q2 { cx q0, q2; cx q1, q2; }
gate cccz c0, c1, c2, t { ctrl(3) @ U(0, 0, pi) c0, c1, c2, t; }
gate ccccx c0, c1, c2, c3, t { ctrl(4) @ U(pi, 0, pi) c0, c1, c2, c3, t; }

def oracle(qubit[4] r, qubit[4] s, qubit a) {
    xor r[0], r[1], s[0];
    xor r[2], r[3], s[1];
    xor r[0], r[2], s[2];
    xor r[1], r[3], s[3];

    ccccx s[0], s[1], s[2], s[3], a;

    xor r[1], r[3], s[3];
    xor r[0], r[2], s[2];
    xor r[2], r[3], s[1];
    xor r[0], r[1], s[0];
}

def diffuser(qubit[4] r) {
    h r;
    x r;
    cccz r[0], r[1], r[2], r[3];
    x r;
    h r;
}

def G(qubit[4] r, qubit[4] s, qubit a) {
    oracle(r, s, a);
    diffuser(r);
}

const int n = 4;
qubit[n] r;
qubit[4] s;
qubit a;

reset r;
reset s;
reset a;

h r;
x a;
h a;

int N = 2**n;
int M = 2;
int R = int(pi/4 * sqrt(float(N)/float(M)));

for int i in [0:R-1] {
    G(r, s, a);
}

measure s;
measure a;

Step-by-step explanation

Gate definitions
  • x and h: Standard NOT and Hadamard gates.
  • cx: CNOT gate used inside the xor gate.
  • xor q0, q1, q2: Computes q2 ⊕= q0 ⊕ q1 using two CNOTs. This is the key building block for evaluating inequality constraints without measurement.
  • cccz: Three-controlled Z gate — flips the phase of |1111⟩ state. Uses ctrl(3) @ syntax.
  • ccccx: Four-controlled X gate — flips the ancilla only when all four scratch bits are 1. Uses ctrl(4) @ syntax.
The oracle The oracle checks four constraints on the search register r = [a, b, c, d]:
xor r[0], r[1], s[0]   →  s[0] = a XOR b  (is a ≠ b ?)
xor r[2], r[3], s[1]   →  s[1] = c XOR d  (is c ≠ d ?)
xor r[0], r[2], s[2]   →  s[2] = a XOR c  (is a ≠ c ?)
xor r[1], r[3], s[3]   →  s[3] = b XOR d  (is b ≠ d ?)
Each scratch bit in s is 1 if and only if its pair differs. The ccccx gate then flips the ancilla a only when all four scratch bits are 1 — meaning all four constraints are satisfied simultaneously. The second block of xor gates uncomputes s back to |0000⟩, leaving the ancilla as the only changed qubit. Phase kickback via the ancilla The ancilla a is initialized in |−⟩ = (|0⟩ − |1⟩)/√2 via x a; h a. When ccccx flips a, phase kickback applies a factor of −1 to the amplitude of the marked states in the superposition of r, turning an amplitude-flip into a phase-flip. The ancilla returns to |−⟩ and is unaffected by subsequent iterations. The diffuser (Grover diffusion operator) The diffuser amplifies the probability of marked states by reflecting all amplitudes about their mean:
h r     →  transform to uniform superposition basis
x r     →  flip so |11...1⟩ is the state to phase-flip
cccz    →  apply −1 phase to |1111⟩ only
x r     →  undo the flip
h r     →  transform back
The net effect is: each amplitude aᵢ → 2⟨a⟩ − aᵢ, where ⟨a⟩ is the mean amplitude. Marked states (with negative phase from the oracle) are amplified; all others are suppressed. Iteration count
N = 2^4 = 16   (search space size)
M = 2          (number of solutions)
R = floor(pi/4 * sqrt(N/M)) = floor(pi/4 * sqrt(8)) ≈ floor(2.22) = 2
Two Grover iterations are optimal for this instance. Applying more iterations would overshoot and reduce the success probability.

Expected output

After 2 iterations, the amplitudes concentrate on the two valid solutions. Measuring r gives:
Outcome (r[3]r[2]r[1]r[0])MeaningProbability
1001[1,0,0,1]~50%
0110[0,1,1,0]~50%
All other 14 states have near-zero probability. The scratch register s and ancilla a return to |0000⟩ and |−⟩ respectively, confirming the oracle correctly uncomputed its intermediate results.
Both solutions [1,0,0,1] and [0,1,1,0] represent valid 2-colorings of a 2×2 grid where no two adjacent cells share the same color. Visually, they are the two checkerboard patterns on a 2×2 board.

Quantum mechanics concepts

Phase oracle — Grover’s algorithm requires a phase oracle: a unitary that maps |x⟩ → −|x⟩ for marked states and leaves all others unchanged. This circuit constructs the phase oracle by combining a computational oracle (that flips an ancilla for marked states) with an ancilla in |−⟩ to convert amplitude flips into phase flips via phase kickback. Grover iteration — Each iteration consists of oracle application followed by the diffusion operator. The rotation angle in state space is arcsin(√(M/N)) ≈ 0.354 radians per iteration for this problem. After R ≈ π/(4·arcsin(√(M/N))) iterations, the quantum state aligns closely with the superposition of marked states. Amplitude amplification — Grover’s algorithm is a special case of amplitude amplification, a general technique for boosting the probability of a “good” outcome in any quantum computation. The diffusion operator reflects amplitudes around their mean, systematically transferring probability from unmarked to marked states. Uncomputation — The oracle must uncompute all scratch qubits (register s) before returning, ensuring they return to |0000⟩. If scratch qubits retained information about which state was evaluated, they would become entangled with the search register and destroy the interference needed for amplitude amplification.

Build docs developers (and LLMs) love