Compiler IR Reference¶

This page documents two internal semantic representations used by the Clifft compiler: the Heisenberg IR (HIR) produced by the front end and the Sampling Plan actions produced by coordinate planning.

These names and text formats support inspection and debugging. They are not a serialized program format, bytecode, or stable public ABI. User code should compile circuits into a Program and use the public sampling and exact-query APIs rather than depend on plan-action layout.

The same data powers the hover tooltips in the Playground.

HIR Operation Types¶

The Heisenberg IR is the intermediate representation produced by the front-end. Clifford gates are absorbed into the offline Clifford frame \(U_C\) and do not appear in the HIR. What remains are non-Clifford operations, measurements, noise, feedback, and output metadata.

Non-Clifford¶

T¶

T_DAG¶

T or T-dagger gate: pi/8 phase rotation on a Pauli product.

The primary non-Clifford operation. Applies exp(ipi/8 * P) where P is the Pauli product shown (e.g. +X0Z1). T_DAG applies the conjugate rotation. These cannot be absorbed into the offline Clifford frame U_C and remain explicit through sampling-plan preparation.

PHASE_ROTATION¶

Continuous Z-rotation by angle alpha (half-turns) on a Pauli product.

Applies exp(-ialphapi/2 * P) where P is the rewound Pauli product and alpha is in half-turn units. The front-end factors out the global phase e^{-ialphapi/2} into global_weight. All single-qubit rotations and multi-qubit Pauli rotations are reduced to this HIR type via Clifford absorption.

Measurement¶

MEASURE¶

Destructive measurement of a Pauli observable.

Measures the Pauli product shown (e.g. +X0, -Z0*Z1) and stores the outcome in the measurement record. The Pauli is the effective observable after the Heisenberg mapping U_C^dag P U_C -- it may differ from the original circuit's measurement basis.

EXP_VAL¶

Non-destructive expectation value of a rewound Pauli product.

Evaluates

for the rewound Pauli product P at the point in the circuit where the probe appears. Does not collapse the state, mutate the Pauli frame, or affect measurement, detector, or observable records.

Instrument¶

INSTRUMENT¶

State-dependent jump site: a transition instrument on one qubit.

Carries the rewound source observable Z_q and references an InstrumentSite side table with per-source fire probabilities and computational-destination splits. Instruments are optimization fences so a recompiled continuation preserves the prefix consumed by an already-running executor.

Feedback¶

IF¶

THEN¶

Classical feedback: apply Pauli correction conditioned on a measurement.

If the referenced measurement record entry is 1, applies the shown Pauli product to the frame. Implements feed-forward operations like teleportation corrections and QEC feedback.

Noise¶

NOISE¶

Stochastic Pauli noise channel.

Represents a noise process (depolarizing, dephasing, etc.) that may randomly apply a Pauli operator. References a NoiseSite side-table with the channel probabilities.

READOUT_NOISE¶

Classical bit-flip noise on a measurement result.

Models measurement readout errors as a classical bit-flip probability applied to the measurement record after the quantum measurement.

QEC¶

DETECTOR¶

Detector: parity check over measurement records.

Defines a parity check (XOR) over a set of measurement record entries. In error correction, detectors flag syndrome changes between rounds.

OBSERVABLE¶

Logical observable accumulator.

Accumulates measurement record parities into a logical observable for error correction tracking.

Sampling Plan Actions¶

The planner compiles optimized HIR into a target-independent SamplingPlan: a fixed sequence of semantic actions in which every Clifford has been absorbed and every stochastic event appears as a Boolean symbol. The Playground's Sampling Plan panel displays this representation. Before repeated sampling, Clifft prepares a target-specific ExecutablePlan containing the compact descriptors, dependency tables, fused actions, and kernel selections consumed by the executor.

See Software Architecture for the responsibilities of HIR, SamplingPlan, ExecutablePlan, and the executor.

Reading a plan line¶

w1->0 MEASURE_ACTIVE Z0 pivot=0 branch=s3 outcome=s0^s1^s3 record=r0 passes=2

• w<k> / w<k>-><k'> — the active width before (and, when it changes, after) the action. The dense coefficient state holds \(2^k\) amplitudes for the currently active stabilizer coordinates.
• Pauli products such as Z0 or X0*Z1 are written over active stabilizer coordinates, not physical qubits. The planner's coordinate frame tracks the mapping between physical qubits and those packed coordinates.
• Affine expressions such as 1^s0^s3 are XORs of Boolean symbols, with a leading 1 for the affine constant. Symbols are sampled noise outcomes, measurement branches, or derived parities. The Playground's compact view truncates long expressions and reports the omitted count as ...(+N).
• Typed ids name output slots: r measurement records, d detectors, o observables, v expectation values, and s symbols.
• passes=<n> estimates full traversals of the dense coefficient state before executable preparation combines or specializes operations. It is a diagnostic cost estimate, not an execution ABI or a guarantee of the final kernel count; actions without it require no dense-state traversal on their own.

Semantic action types¶

Rotation¶

ROTATE_ACTIVE¶

Rotation about a Pauli product on the active coordinates.

Applies exp(-ipihalf_turns/2 * P) where P is the Pauli product shown over active stabilizer coordinates. This traverses the dense 2^k coefficient state. When the per-shot sign expression evaluates true the rotation direction is reversed; this is how earlier stochastic events such as noise and measurement branches steer later physics without re-planning.

Operands: Pauli product, half_turns, sign

ROTATE_PHASE¶

Sign-conditioned global phase from a rotation whose Pauli reduced to the identity.

A rotation whose Pauli product reduced to the identity during planning. It multiplies the global scalar by a phase determined by the per-shot sign expression and does not traverse the coefficient state. The phase is retained so exact statevector reconstruction preserves the program's global phase; it does not affect sampling, later interference, basis probabilities, record probabilities, or expectation values.

Operands: half_turns, sign

PROMOTE_DORMANT¶

Grows the active state by one coordinate and applies the rotation that introduced it.

A non-Clifford rotation on a coordinate that was stabilizer-only until now. The active width increases by one, doubling the coefficient state, and the promoting rotation is applied in the same pass. Later operations were already rewritten into the new basis during planning. The sign expression conditions the rotation direction per shot.

Operands: half_turns, sign

Measurement¶

MEASURE_ACTIVE¶

Measures a Pauli product on the active coordinates, collapsing the coefficient state.

Samples the branch symbol from the coefficient amplitudes and collapses onto the selected eigenspace. The pivot coordinate is removed afterwards, so the active width decreases by one and the coefficient state halves. The record bit is the raw branch XORed with the outcome expression's corrections from earlier stochastic events.

Operands: Pauli product, pivot, branch, outcome, record

MEASURE_DORMANT¶

Measures a random-outcome Pauli outside the active coefficient state.

The measured observable anticommutes with a dormant stabilizer, so the outcome is an unbiased coin flip handled algebraically: the branch symbol is sampled, the dormant stabilizer at the pivot is replaced, and the coefficient state is untouched. The record bit combines the branch with the outcome expression's corrections.

Operands: pivot, branch, outcome, record

Classical¶

RECORD_CLASSICAL¶

Writes a deterministic expression to the measurement record.

Used when a measurement outcome is fully determined by the initial state and earlier symbols, such as a stabilizer measurement whose value follows from the frame. No state work is needed: the record bit is the affine expression, an XOR of earlier symbols and an optional constant.

Operands: outcome, record

DEFINE_SYMBOL¶

Names an affine expression as a reusable symbol without writing a record.

Gives a parity of previously available symbols its own symbol id so later actions can reference it compactly. Pure bookkeeping: no record slot is written and no state is touched.

Operands: symbol, value

READOUT_NOISE¶

Samples whether a completed measurement record flips.

Classical readout error applied after a record is written. The flip probability may depend on the record's value before the flip (p01 versus p10), so the flip symbol is defined at this circuit position instead of being presampled before the shot. The record slot is updated in place.

Operands: flip, source, record, p01, p10

Output¶

WRITE_DETECTOR¶

Writes a detector parity; with postselect, a nonzero parity rejects the shot.

The outcome expression already includes the noiseless reference parity, so the written bit is 1 exactly when the detector fired. When marked postselect, a nonzero value aborts the shot immediately.

Operands: outcome, detector

WRITE_OBSERVABLE¶

Writes one fully accumulated logical observable bit.

The outcome expression combines every contributing measurement record and the noiseless reference parity, so the written bit is 1 exactly when the logical observable flipped.

Operands: outcome, observable

WRITE_EXPECTATION¶

Records a non-destructive Pauli expectation value of the current state.

Probes the expectation of a Pauli observable without collapsing anything. When an active projection is shown, one pass over the coefficient state computes it, with the sign expression conditioning its overall sign per shot. The zero marker means planning already proved the expectation vanishes because the transformed observable has X or Y support outside the active coordinates.

Operands: Pauli product or zero, sign, exp_val

Instrument¶

APPLY_INSTRUMENT¶

Evaluates a state-dependent transition site such as leakage, loss, or relaxation.

The transition fires with a probability that depends on which computational level the qubit occupies, so the source projector is evaluated against the live state. The mode records how the source enters the coefficient state: as a pure sign (classical), on existing active coordinates (active), by adding one coordinate (activate), or as a dormant-random trap resolved by a continuation. The flip symbol is true exactly when the sampled computational destination differs from its source.

Operands: Pauli product (omitted for identity sources), site, mode, sign, flip

INSTRUMENT_BOUNDARY¶

Marks where a continuation may resume after an instrument traps.

Divides the plan into ahead-of-time execution segments. A continuation resumes at this marker with the live coefficients, active-coordinate meaning and order, symbol and record values, and RNG position preserved, then samples only the replacement suffix's remaining presampled noise.

Operands: site, next_noise_site, symbol_prefix_size