Passes Reference

This page documents each pass individually. For the high-level flow of how passes chain together, see The Pipeline. For how to write your own pass, see Adding a Pass.

BasisTranslationPass

Constructor

BasisTranslationPass(backend="IBM")

What it does

Walks the circuit instruction by instruction. If a gate is already in the backend's basis set, it passes through unchanged. If it isn't, the pass looks it up in the backend's decomposition map and substitutes it with the decomposed sequence, remapping qubit indices appropriately. Measurements and barriers always pass through unchanged.

Architecture note: This pass is single-pass. It walks the instruction list exactly once with no recursion. Decomposition map entries must produce only basis gate instructions. Entries that produce intermediate gates which themselves need further decomposition will not be caught.

Normalization: The gate name cnot is normalized to cx before any lookup, so circuits using either name are handled correctly.

DenseLayoutPass

Constructor

DenseLayoutPass(coupling_map)

What it does

Analyzes the interaction frequency between qubit pairs in the circuit and greedily assigns logical qubits to physical positions that minimize routing overhead. The algorithm runs in four steps:

1. Count how often each qubit pair interacts across all two-qubit gates
2. Sort pairs by interaction count, highest first
3. For each pair, assign both qubits to the closest available physical positions. if one qubit is already placed, find the closest free physical qubit to its current position; if neither is placed, find the closest free physical pair on the device
4. Assign any remaining unplaced logical qubits to leftover physical positions in order

The resulting mapping is written to TesseraCircuit.layout as a dict[int, int] (logical → physical). No instructions are modified. only the layout field is set.

BasicSwapRouter

Constructor

BasicSwapRouter(coupling_map, path_finder=None)

What it does

Applies the layout from DenseLayoutPassand routes the circuit to be compatible with the hardware's physical connectivity constraints. It maintains two tracking dicts: current_positions (logical → physical) and inverse_positions (physical → logical): which start equal to the initial layout and are updated every time a SWAP is inserted.

For each instruction:

• Single-qubit gates and measurements are emitted with their qubit index translated to the current physical position
• Two-qubit gates whose physical qubits are directly connected are emitted as-is
• Two-qubit gates whose physical qubits are not connected trigger SWAP insertion: the router finds the shortest path between them, inserts SWAPs along all but the last edge of the path to bring the qubits adjacent, updates both tracking dicts after each SWAP, then emits the gate at the final two adjacent positions

Custom path-finder interface: If provided, path_finder must be a callable with signature (start: int, end: int) -> list[int] that returns a list of physical qubit indices representing the path from start to end inclusive.

RemoveBarriersPass

Constructor

RemoveBarriersPass()

No parameters.

What it does

Strips all instructions with name "barrier" from the circuit. Everything else passes through unchanged. The layout is preserved.

This pass exists because barriers prevent the optimization passes from seeing cancellation and merging opportunities across their boundaries. Since barriers have no physical effect on hardware, removing them before optimization is always safe.

CancelAdjacentPass

Constructor

CancelAdjacentPass(strict=True)

Supported self-inverse gates: x, cx, y, h, cz, swap

Strict mode

Scans the instruction list for pairs of identical self-inverse gates on the same qubits that are directly adjacent. Both gates are removed.

X(q0)  X(q0)           → (removed)
H(q0)  X(q1)  H(q0)   → H(q0)  X(q1)  H(q0)   (no cancellation; not adjacent)

Commutative mode

Extends cancellation to gates separated by instructions on non-overlapping qubits. When a self-inverse gate is found, the pass scans forward until it hits an instruction that shares a qubit with it. If that instruction is the same gate on the same qubits, both cancel. If it's a different gate on a shared qubit, cancellation stops.

H(q0)  X(q1)  H(q0)   → X(q1)   (H gates cancel because nothing between them touches q0)
H(q0)  X(q0)  H(q0)   → X(q0)   (no cancellation because X(q0) is on a shared qubit)

MergeRotationsPass

Constructor

MergeRotationsPass(strict=True, epsilon=1e-9)

Supported mergeable gates: rz, rx, ry

Strict mode

Scans for pairs of identical rotation gates on the same qubit that are directly adjacent. Merges their angles additively. If the merged angle is within epsilon of zero, the gate is dropped entirely.

Rz(0.3, q0)  Rz(0.5, q0)              → Rz(0.8, q0)
Rz(0.5, q0)  Rz(-0.5, q0)             → (dropped)
Rz(0.3, q0)  Rx(0.5, q1)  Rz(0.5, q0) → Rz(0.3, q0)  Rx(0.5, q1)  Rz(0.5, q0)  (no merge; not adjacent)

Known limitation: Three or more consecutive rotation gates of the same type will leave one unmerged in a single pass. Rz(a) Rz(b) Rz(c) becomes Rz(a+b) Rz(c). The third gate is not merged because the pass only looks one step ahead at a time.

Commutative mode

Extends merging to rotation gates separated by instructions on non-overlapping qubits. When a rotation gate is found, the pass scans forward until it hits an instruction on a shared qubit. If that instruction is the same rotation gate on the same qubit, their angles are merged.

Rz(0.3, q0)  Rx(0.5, q1)  Rz(0.5, q0) → Rz(0.8, q0)  Rx(0.5, q1)