The Pipeline

When you call transpile(), your circuit passes through seven sequential transformation passes. Each pass receives the output of the previous one. This page walks through each pass in order, including what it does, why it exists, and what changes in the circuit as a result.

The full pipeline:

BasisTranslation → DenseLayout → SwapRouter → BasisTranslation → RemoveBarriers → CancelAdjacent → MergeRotations

Pass 1: Basis Translation

The first thing Tessera does is decompose every gate in your circuit into the target backend's supported gate set. Different hardware supports different native gates IBM supports cx, rz, sx, x, u; IonQ supports rx, ry, rz, cx; Rigetti supports rx, rz, cz. Any gate that isn't in the backend's basis set gets replaced with an equivalent sequence of gates that are.

This pass is single-pass. It walks the instruction list once and substitutes each non-basis gate using the backend's decomposition map. Decomposition map entries must produce only basis gate instructions, so no second pass is needed here.

Gates that are already in the basis set pass through unchanged. Measurements and barriers also pass through unchanged.

Pass 2: Dense Layout

Your circuit is written in logical qubit space with qubit 0, qubit 1, qubit 2. Real hardware has a fixed topology where only certain qubit pairs are physically connected. DenseLayoutPass maps each logical qubit to a physical qubit on the target device.

The algorithm works in four steps:

1. Count how often each qubit pair interacts in the circuit
2. Sort pairs by interaction frequency, highest first
3. Greedily assign the most frequently interacting pairs to the closest available physical qubits
4. Assign any remaining unplaced logical qubits to leftover physical qubits

The result is stored in TesseraCircuit.layout as a dict mapping logical → physical qubit indices. For example {0: 3, 1: 5, 2: 6} means logical qubit 0 maps to physical qubit 3, and so on. All subsequent passes work in physical qubit space using this mapping.

Pass 3: Swap Router

Even with a good layout, some two-qubit gates may still involve qubits that aren't directly connected on the hardware. BasicSwapRouter resolves this by applying the layout from Pass 2 and inserting SWAP gates to move qubits into adjacent positions before each non-adjacent operation.

The router works in a single pass over the instruction list. For each two-qubit gate it checks whether the two involved physical qubits are connected in the coupling map. If they are, the gate is emitted as-is. If they aren't, the router finds the shortest path between them using BFS (or a custom path-finding function if one was provided), inserts SWAP gates along that path to bring them adjacent, and then emits the gate. The routing state, which tracks which logical qubit is currently at which physical position, is updated after every SWAP so subsequent gates see the correct positions.

Pass 4: Basis Translation (Second Run)

The SWAP gates inserted by Pass 3 are not basis gates on most backends. A SWAP decomposes into three CX gates on IBM, or a longer sequence on Rigetti. This second run of BasisTranslationPass catches those newly introduced SWAPs and decomposes them into backend basis gates exactly the same way Pass 1 did.

Running basis translation a second time rather than baking SWAP decomposition into the router keeps the router simple and backend-agnostic. It only has to think about connectivity, not gate sets.

Pass 5: Remove Barriers

Barriers are structural hints that prevent gate reordering during circuit construction. They have no physical effect on hardware. Before the optimization passes run, RemoveBarriersPass strips all barrier instructions from the circuit so that CancelAdjacentPass and MergeRotationsPass can see across them and find cancellation and merging opportunities they would otherwise miss.

Pass 6: Cancel Adjacent

Some gates are self-inverse. Applying the same gate twice returns the qubit to its original state, so the pair can be removed entirely. CancelAdjacentPass finds and removes these pairs.

The supported self-inverse gates are: x, cx, y, h, cz, swap.

This pass operates in two modes controlled by the strict parameter:

• Strict mode (default): only cancels gates that are directly adjacent in the instruction list. X(q0) X(q0) cancels; X(q0) H(q1) X(q0) does not.
• Commutative mode: cancels gates separated by instructions on non-overlapping qubits, since those instructions commute freely. H(q0) X(q1) H(q0) cancels the H gates because nothing between them touches q0.

Pass 7: Merge Rotations

Consecutive rotation gates on the same qubit can be combined into a single rotation since rotation is additive: Rz(a)·Rz(b) = Rz(a+b). MergeRotationsPass finds these pairs and collapses them. If the merged angle is smaller than epsilon (default 1e-9), the gate is dropped entirely since it has negligible effect.

The supported mergeable gates are: rz, rx, ry.

Like CancelAdjacentPass, this pass operates in two modes:

• Strict mode (default): only merges gates that are directly adjacent. Note that three consecutive rotation gates will leave one unmerged in a single pass. This is a known limitation of the single-pass design.
• Commutative mode: merges gates separated by instructions on non-overlapping qubits. Rz(0.3, q0) Rx(0.5, q1) Rz(0.5, q0) becomes Rz(0.8, q0) Rx(0.5, q1).