Compile (transpile): levels, basis gates, topology
A real device cannot run arbitrary gates on arbitrary qubit pairs. Transpiling rewrites your circuit into the device's native gates (basis) and its qubit connectivity (coupling map), then optimizes it.
Transpiler stages
The Qiskit preset pass manager runs these stages: init → layout → routing → translation → optimization → scheduling.
| Stage | What it does |
|---|---|
| Layout | Chooses which physical qubit holds each logical qubit. Good layouts put interacting qubits next to each other and prefer qubits with low error and long T1/T2. |
| Routing | Inserts SWAP gates so every two-qubit gate acts on neighbouring physical qubits. Each SWAP costs three CNOTs. |
| Translation | Rewrites gates into the basis set, e.g. H → RZ(π/2)·√X·RZ(π/2). |
| Optimization | Cancels inverse pairs, merges single-qubit rotations, removes gates that commute to the end, re-synthesizes blocks. |
Optimization levels 0–3
| Level | Meaning | When |
|---|---|---|
| 0 | No optimization. Trivial layout (logical i → physical i), basic routing, plain translation. | Debugging; seeing the raw cost of your circuit. |
| 1 | Light: inverse-gate cancellation and 1-qubit gate merging. Qiskit's default. | Fast everyday compiling. |
| 2 | Medium: smarter layout (VF2 + SABRE), commutation analysis, more cancellation. | Good trade-off for hardware runs. |
| 3 | Heavy: everything in 2 plus unitary re-synthesis of 2-qubit blocks and many SABRE trials. | Slowest, usually the smallest circuit. Use before spending IBM minutes. |
Topology and SWAPs
Topology (coupling map). IBM Eagle (127 qubits) and Heron (133–156 qubits) processors use a heavy-hex lattice: every qubit has 2 or 3 neighbours. A 4-qubit GHZ chain fits on a line, but a 4-qubit all-to-all circuit needs SWAPs. The Levels tab shows layout, physical qubits and the SWAP count for each level.
Depth is the number of time steps when gates on different qubits run in parallel; it is the main driver of decoherence error (see T1/T2 below). Two-qubit gate count is the main driver of gate error. Smaller is better for both.
In QubitLab, Compile (in the bar above the circuit) transpiles once for your target and shows the mapped circuit, the exact statevector and an explanation. The Levels tab (Submit with 'Compare levels') runs all four levels as a job and charts them.