Optimization Passes¶

Clifft optimizes at two distinct IR levels, each with its own pass manager. HIR passes operate on the Heisenberg IR before bytecode emission. Bytecode passes operate on the finalized bytecode after the back-end has lowered the HIR.

Default Pipeline¶

The default HIR pipeline:

1. PeepholeFusionPass -- Algebraic T-gate cancellation and fusion.

2. StatevectorSqueezePass -- Minimizes peak active dimension by reordering HIR operations.

The default bytecode pipeline:

1. NoiseBlockPass -- Coalesces contiguous noise instructions into blocks.

2. MultiGatePass -- Fuses star-graph CNOT/CZ patterns into single array sweeps.

3. ExpandTPass -- Fuses EXPAND + T-phase into a single array pass.

4. ExpandRotPass -- Fuses EXPAND + continuous rotation into a single array pass.

5. SwapMeasPass -- Fuses SWAP + measurement into one operation.

6. TileAxisFusionPass -- Fuses 2-qubit tile sequences into precomputed 4x4 unitaries.

7. SingleAxisFusionPass -- Fuses single-axis operation chains into precomputed 2x2 unitaries.

Use clifft.default_hir_pass_manager() and clifft.default_bytecode_pass_manager() to get these defaults, or build a custom pipeline:

import clifft

# Custom HIR pipeline
pm = clifft.HirPassManager()
pm.add(clifft.PeepholeFusionPass())
pm.add(clifft.StatevectorSqueezePass())

# Custom bytecode pipeline
bpm = clifft.BytecodePassManager()
bpm.add(clifft.NoiseBlockPass())
bpm.add(clifft.MultiGatePass())

HIR Passes¶

PeepholeFusionPass¶

Scans the HIR to cancel or fuse T/T_dag gates acting on the same virtual Pauli axis using the symplectic inner product as a commutation check. T+T fuses to S, T+T_dag cancels to identity.

StatevectorSqueezePass¶

Attempts to reduce peak_rank by compacting qubit lifetimes. Sweep 1 (leftward) bubbles MEASURE ops as early as possible. Sweep 2 (rightward) bubbles T_GATE and PHASE_ROTATION ops as late as possible. Measurements free active dimensions sooner, and non-Clifford expansions are deferred.

RemoveNoisePass¶

Removes all stochastic noise and readout noise ops, and clears the noise_sites, readout_noise side-tables and source_map. Not included in the default pipeline. Used internally by compute_reference_syndrome() to produce a noiseless circuit copy for reference-shot extraction.

DropNonUnitaryPass¶

Removes MEASURE, CONDITIONAL_PAULI, NOISE, READOUT_NOISE, DETECTOR, OBSERVABLE, and EXP_VAL ops and clears the matching metadata. Not included in the default pipeline and not semantics-preserving; use only when intentionally querying a unitary-only circuit skeleton.

Bytecode Passes¶

NoiseBlockPass¶

Collapses contiguous OP_NOISE instructions with consecutive site indices into single OP_NOISE_BLOCK instructions. The VM's exponential gap-sampling already skips silent noise sites in O(1), but without this pass the dispatch loop still individually fetches and decodes each OP_NOISE.

MultiGatePass¶

Fuses contiguous ARRAY_CNOT instructions sharing a target axis into OP_ARRAY_MULTI_CNOT, and contiguous ARRAY_CZ sharing a control axis into OP_ARRAY_MULTI_CZ. These star-graph patterns arise from the backend's Pauli localization pass. The fused instruction processes all controls/targets in one O(2^k) array pass using popcount-based parity.

ExpandTPass¶

Fuses contiguous OP_EXPAND + OP_ARRAY_T (or T_DAG) pairs into single OP_EXPAND_T (or OP_EXPAND_T_DAG) instructions. The separate instructions cause two array passes; the fused instruction performs both in one loop: arr[i+half] = arr[i] * exp(+/-i*pi/4).

ExpandRotPass¶

Fuses contiguous OP_EXPAND + OP_ARRAY_ROT pairs into single OP_EXPAND_ROT instructions, eliminating the two-pass penalty of separate expand and phase-rotate operations.

SwapMeasPass¶

Fuses contiguous OP_ARRAY_SWAP + OP_MEAS_ACTIVE_INTERFERE pairs into single OP_SWAP_MEAS_INTERFERE instructions. The backend emits a SWAP to route the measurement axis to position k-1, followed by the interfere measurement. The fused instruction eliminates the separate O(2^k) ARRAY_SWAP memory pass.

TileAxisFusionPass¶

Fuses consecutive 2-qubit operations on a fixed axis pair {a, b} into single OP_ARRAY_U4 instructions with precomputed 4x4 unitary matrices. Pre-computes 16 matrices (one per incoming Pauli frame state on the two axes) and stores them in the ConstantPool. A run is only fused if it contains at least 3 array-touching operations. Runs before SingleAxisFusionPass so it operates on raw primitives.

SingleAxisFusionPass¶

Fuses consecutive single-axis operations (ARRAY_H, ARRAY_S, ARRAY_T, ARRAY_ROT, etc.) on the same virtual axis into a single OP_ARRAY_U2 instruction. Pre-computes 2x2 unitary matrices for all 4 possible incoming Pauli frame states (I, X, Z, Y). A run is fused if it contains at least 3 array-touching operations, or at least 2 when one is a continuous rotation.