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 -- Fuse same-axis T gates and remove terminal phases.

2. PhasePolynomialPass -- Reduce T count using identities among commuting rotations.

3. RotationSimplificationPass -- Simplify arbitrary-angle Pauli rotations using known stabilizers.

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

These passes are complementary; the default manager runs them in the order shown.

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.PhasePolynomialPass())
pm.add(clifft.RotationSimplificationPass())
pm.add(clifft.StatevectorSqueezePass())
pm.add(clifft.ActiveWidthSchedulePass())

Supply the manager as hir_passes=pm to clifft.compile() to replace the defaults. Omit any pass you want to disable, or use hir_passes=None to skip all HIR optimization.

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 PhasePolynomialPass, RotationSimplificationPass, StatevectorSqueezePass and ActiveWidthSchedulePass.

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.

PhasePolynomialPass¶

Uses TOHPE from Vandaele, Lower T-count with faster algorithms, Algorithm 2 for T-count reduction. Clifft tracks commuting T rotations as a Boolean phase polynomial and uses Pauli constraints from the all-zero input to separate a non-Clifford core from a Clifford correction. TOHPE synthesizes the core; Clifft supplies the state analysis, measurement/noise handling, and exact Clifford correction.

Pauli measurements, expectation-value probes and classically controlled Pauli gates can move before a phase prefix only when their conjugated axes remain Paulis and all required constraints survive. Pauli noise can cross only when its nonzero-probability channels commute with that prefix and preserve those constraints. These must hold on every trajectory and the noiseless reference, so even probability-one noise discards affected constraints. Instruments clear all constraints; postselection supplies none. Use this pass only on complete circuits with an all-zero input; prior scheduling across noise causes it to skip the circuit.

max_variables limits how many independent phase variables the pass analyzes together (default 32, range 0 to 64; zero disables it). Circuits can have more qubits than this limit. Raising it may uncover more simplifications but increases compilation cost. The pass rejects rewrites that increase T count or peak active width; at unchanged width, estimated sampling work must not increase either. Actual sampling speedups depend on the complete optimization pipeline. Equivalent rewrites preserve sampling distributions but can change samples for a fixed random seed.

After a run, input_t_count, output_t_count, blocks_reduced and pauli_pullbacks describe the accepted rewrite; applied reports acceptance.

RotationSimplificationPass¶

Uses the circuit's known all-zero initial state to track stabilizer constraints shared by every trajectory. These constraints let the pass combine equivalent commuting Pauli rotations with arbitrary angles and absorb resulting Clifford operations.

Run this pass on complete circuits before squeezing or scheduling. It skips circuits whose noise has already been rescheduled.

Stabilizer constraints must hold for every measurement outcome and noise trajectory, including the noiseless reference. Every nonrotation operation ends a region; instruments discard the known stabilizers and postselection adds none.

Rewrites must not increase peak active width or estimated sampling work. Equivalent rewrites preserve output distributions but can change samples for a fixed seed.

After a run, regions_examined and regions_capped describe the attempted search. regions_reduced, rotations_removed and applied describe the accepted rewrite.

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.

ActiveWidthSchedulePass¶

Searches legal reorderings of the HIR for one that lowers peak active width first and an estimated dense-work cost second. It accepts a new order when peak width falls, or when peak width is unchanged and estimated dense work falls; otherwise the HIR is left untouched. A deterministic work budget limits search executions, but does not bound classification probes or wall time. Opt in to reduce sampling work at extra compilation cost. Run it after PeepholeFusionPass and StatevectorSqueezePass: reordering across noise can prevent subsequent peephole fusion.

See Compiling Circuits for setup and guidance on when to enable this pass.

The search narrows to one retained candidate at half the execution budget. Ongoing sweeps and replays finish, so the thresholds can be exceeded. This budget does not bound classification probes or wall time: probe counts can grow quadratically on circuits with many independent rotations, and each probe's cost also depends on the qubit count. Budgets must be finite and nonnegative, or None.

After a run, incumbent_peak and result_peak report peak active width before and after scheduling. incumbent_dense_work and result_dense_work estimate work by summing \(2^w\) over operations touching the active array at width \(w\). The pass accepts a lower peak even if that work estimate rises; neither metric measures elapsed time or guarantees a globally optimal schedule.

applied reports whether the order changed. swept_ops counts search executions, including discarded candidates and replays; classification_probes counts checks for expanding operations. These counters exclude graph construction and final analysis. For per-operation widths, use clifft.active_width_trace.

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.