Optimization Passes¶

Clifft's public optimization passes operate on the Heisenberg IR before active-coordinate planning and executable-plan preparation.

Default Pipeline¶

The default HIR pipeline:

1. PeepholeFusionPass -- Algebraic T-gate fusion and terminal-phase elimination.

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

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

import clifft

pm = clifft.HirPassManager()
pm.add(clifft.PeepholeFusionPass())
pm.add(clifft.StatevectorSqueezePass())

Optimization passes end at the HIR boundary; SamplingPlan is not a second public pass pipeline. See Software Architecture for the private planning and executable-preparation stages that follow.

Trajectory Safety Metadata¶

Some workflows require measurements to remain in their original order, including hidden measurements introduced by the compiler. In particular, clifft.noncomp.sample may force the result of a hidden trace-out measurement when it resumes a trapped transition. Moving another measurement across that collapse can change quantum correlations.

clifft.noncomp.sample therefore applies only passes that are enabled by default, preserve measurement-record order, and preserve instrument prefixes. Its HIR pipeline uses PeepholeFusionPass but omits StatevectorSqueezePass.

Record-order preservation is necessary but does not by itself make a continuation compatible with an already-running executor. Trajectory passes must also opt in to instrument-prefix stability: changing the circuit after an instrument may not change optimized output through that instrument. The runtime checks each recompiled prefix before resuming. For this reason, clifft.noncomp.sample uses a fixed internal pipeline and does not currently accept custom pass managers. See Leakage and Loss for how continuations are compiled and resumed.

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. Phase rotations within an absolute tolerance of 1e-12 half-turns of supported Clifford or T angles are canonicalized. It also removes a T gate or Pauli phase rotation when a later same-axis measurement consumes the phase; intervening Pauli noise is left in place.

StatevectorSqueezePass¶

Attempts to reduce peak_active_width 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, bypassing other commuting expansions when that exposes a movable non-expanding operation. This prevents a blocked expansion from keeping a later movable expansion live across a measurement. Measurements reduce active width 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.