All gates, with the math
Every gate in the palette, its matrix, what it does to a state, and when to use it. Matrices act on column vectors (|0⟩ = (1,0)ᵀ, |1⟩ = (0,1)ᵀ).
Single-qubit Clifford gates
id q[0];Does nothing to the state. On hardware it is a wait of one gate time, during which T1/T2 noise still acts.
When to use: Padding to line up timing, noise experiments (watch the fidelity drop in Debug mode with a fake backend), placeholders in templates.
h q[0];Maps |0⟩ → (|0⟩+|1⟩)/√2 and |1⟩ → (|0⟩−|1⟩)/√2: creates an equal superposition. Swaps the X and Z axes of the Bloch sphere.
When to use: Start of almost every algorithm; before and after oracles (Deutsch–Jozsa, Grover, Bernstein–Vazirani).
x q[0];Bit flip: |0⟩ ↔ |1⟩. A rotation of π about the X axis.
When to use: Prepare |1⟩ inputs, build oracles, the target of CNOT is an X controlled by another qubit.
y q[0];Bit flip plus phase: |0⟩ → i|1⟩, |1⟩ → −i|0⟩. Rotation of π about Y. Y = iXZ.
When to use: Rare on its own; appears in Pauli observables and error models.
z q[0];Phase flip: leaves |0⟩, multiplies |1⟩ by −1. Invisible in Z-basis probabilities, visible after an H.
When to use: Marks states in Grover; measurement observables (⟨Z⟩) in cutting and VQE.
sx q[0];Half of an X: a π/2 rotation about X. Applying it twice gives X.
When to use: Native gate on IBM hardware; every single-qubit gate is compiled into RZ and √X.
Phase gates
s q[0];Adds a phase of π/2 to |1⟩. S·S = Z.
When to use: Changes between the X and Y bases; part of the Clifford group used in error correction.
sdg q[0];Inverse of S: phase −π/2 on |1⟩.
When to use: Undo an S; measure in the Y basis with S†·H before measuring.
t q[0];Phase π/4 on |1⟩. T·T = S. It is not a Clifford gate, which is what makes universal computation possible.
When to use: Toffoli decompositions, fault-tolerant algorithms (T-count is a cost metric).
tdg q[0];Inverse of T: phase −π/4.
When to use: Appears with T in Toffoli decompositions.
Rotation gates (parameterized)
rx(pi/2) q[0];Rotates the Bloch vector by θ about the X axis. RX(π) = X up to a global phase.
When to use: QAOA mixers, variational ansätze, preparing arbitrary real superpositions.
ry(0.6) q[0];Rotation about Y. Keeps amplitudes real, so RY(θ)|0⟩ = cos(θ/2)|0⟩ + sin(θ/2)|1⟩.
When to use: The workhorse of VQE and W-state preparation; set θ to control the probability of 1 exactly: p(1) = sin²(θ/2).
rz(pi/4) q[0];Rotation about Z: a relative phase e^{iφ} between |0⟩ and |1⟩. Does not change Z-basis probabilities.
When to use: Native and virtually free on IBM hardware (implemented as a frame change, zero duration, no error).
p(pi/8) q[0];Phase gate: multiplies |1⟩ by e^{iλ}. P(π) = Z, P(π/2) = S, P(π/4) = T. Equal to RZ(λ) up to global phase.
When to use: Controlled versions (CP) build the quantum Fourier transform.
U(pi/2, 0, pi) q[0];The most general single-qubit gate: every 1-qubit unitary is a U up to a global phase. H = U(π/2, 0, π), X = U(π, 0, π), RZ(φ) ≈ U(0, 0, φ).
When to use: Variational circuits (VQE, QAOA) where the angles are the parameters you optimise; the OpenQASM 3 built-in gate every other gate is defined from.
Multi-qubit gates
cx q[0], q[1];Flips the target when the control is |1⟩: |c,t⟩ → |c, t⊕c⟩. With H on the control first it creates the Bell state.
When to use: The standard entangling gate. On hardware it costs about 10× more error than a single-qubit gate, so the transpiler counts it.
cz q[0], q[1];Adds a −1 phase only to |11⟩. Symmetric: it does not matter which qubit is the control. CZ = (I⊗H)·CX·(I⊗H).
When to use: Grover's oracle for |11⟩; native two-qubit gate on some IBM Heron processors.
cy q[0], q[1];Applies Y to the target when the control is |1⟩.
When to use: Pauli-controlled operations in error-correction and oracle constructions.
ch q[0], q[1];Puts the target in superposition only when the control is |1⟩.
When to use: Building W states and controlled state preparation.
cp(pi/2) q[0], q[1];Adds the phase e^{iλ} only to |11⟩. CP(π) = CZ. Symmetric: either qubit can be called the control.
When to use: The rotations R_k of the quantum Fourier transform; phase kickback.
cry(pi/4) q[0], q[1];Controlled rotations: the target rotates by θ about X, Y or Z only when the control is |1⟩.
When to use: Quantum phase estimation (CRZ), amplitude encoding of data (CRY), hardware-efficient ansätze.
cu(pi/2, 0, pi, 0) q[0], q[1];The general controlled single-qubit gate; γ adds a phase to the controlled branch.
When to use: Any controlled unitary in one gate: phase kickback demonstrations, controlled-Rk in the QFT.
swap q[0], q[1];Exchanges two qubit states. Costs three CNOTs, which is why routing on hardware is expensive.
When to use: Inserted by the transpiler when two qubits that must interact are not neighbours on the chip. The Compile tab counts them.
ccx q[0], q[1], q[2];Flips the target when both controls are |1⟩: a reversible AND gate. Decomposes into 6 CNOTs and 7 T/T† gates.
When to use: Classical arithmetic (adders), oracles, error correction.
cswap q[0], q[1], q[2];Swaps the two targets when the control is |1⟩.
When to use: The SWAP test for comparing two states, reversible classical logic.
Non-unitary operations
c[0] = measure q[0];Projects the qubit onto |0⟩ or |1⟩ and writes the result to a classical bit. Irreversible.
When to use: End of every circuit you want counts from. Simulators add it automatically if you forget.
reset q[0];Forces the qubit back to |0⟩ regardless of its state (measure, then flip if 1).
When to use: Reusing ancilla qubits mid-circuit.
barrier q;Does nothing to the state. It is a fence for the transpiler: gates are not moved or merged across it.
When to use: Keep a state-preparation block separate from an oracle so the drawing stays readable.