qstack: Fault-Tolerant Quantum Compiler Framework

• qstack is a compiler framework for fault-tolerant quantum programs that uses a purely quantum intermediate representation with opaque callbacks for classical logic.
• It composes transformation passes for quantum error correction, enabling techniques like bit-flip, phase-flip, and concatenated codes in a seamless manner.
• The design preserves semantic measurement structure while allowing efficient integration of decoders and hardware-native gate translations for robust quantum execution.

Searching arXiv for the specified paper and related uses of the term "qstack". qstack is a compiler framework for fault-tolerant quantum programs that treats compilation as a compositional transformation across multiple abstraction layers, from high-level logical gates through quantum error-corrected encodings to hardware-native instructions (Paz et al., 15 May 2026). Its distinguishing design choice is a purely quantum intermediate representation in which classical logic is not represented directly in the IR, but is instead accessed only through opaque callbacks written in a host language such as Python. This design targets the central difficulty of fault-tolerant compilation: quantum error correction turns purely quantum programs into hybrid quantum-classical programs, because syndrome measurements, decoders, and conditional corrections introduce classical feedback at runtime (Paz et al., 15 May 2026).

1. Problem setting and design rationale

Fault-tolerant compilation must preserve the semantics of programs in which intermediate measurements produce classical bits that drive subsequent quantum operations. The motivating examples stated for qstack are teleportation fix-ups, $T$-gate injections, and quantum error-correction syndrome decoding. At compile time, each layer of quantum error correction inserts its own measurement-decode-correction cycle, so the amount of classical feedback compounds as passes are composed (Paz et al., 15 May 2026).

The framework is positioned against two established implementation patterns. In one pattern, quantum and classical control are interleaved in a single IR, which forces every compiler pass to reason about both. In the other, classical host code is treated separately, which requires manual re-wiring of decoders at each quantum error-correction layer. qstack’s central claim is that neither strategy is necessary if the compiler sees only quantum structure—“allocate, gate, measure, invoke callback”—while all classical logic remains hidden behind opaque callbacks (Paz et al., 15 May 2026).

A common misconception is that a purely quantum IR removes classical computation from the execution model. qstack does not do so. Rather, it relocates classical logic behind an interface boundary. This suggests a strict separation between semantic preservation of measurement structure and implementation freedom for the decoder or runtime controller.

2. Intermediate representation and runtime semantics

The framework defines a program as $(\text{GateSet}, \text{Kernel})$ together with a set of callback identifiers. The GateSet specifies the available unitaries $\{U_1,U_2,\ldots\}$, while the Kernel is a tree of instructions with strict LIFO qubit allocation. Each allocate q: ... measure cb block allocates exactly one qubit, executes gates or nested Kernels, measures it, and invokes callback cb (Paz et al., 15 May 2026).

At runtime, an evaluation engine maintains a Kernel stack and a Measurement stack. Each measurement pushes one bit onto the Measurement stack, and a callback may pop bits and optionally return a new Kernel to continue execution. This execution model makes dynamic control explicit without embedding classical control flow directly into the IR (Paz et al., 15 May 2026).

The formal IR is given as a set of pairs

$IR = \{(U_i, C_i)\mid i=1\ldots n\},$

where $U_i$ is a purely quantum operation or nested Kernel and $C_i$ is an opaque callback identifier. Compiler passes act pointwise on these pairs:

$P : (U, C) \mapsto (U', C').$

Here $U'$ is the transformed quantum subprogram, while $C'$ is a wrapped callback that preserves the expected measurement interface after the quantum transformation (Paz et al., 15 May 2026).

This representation is deliberately narrow. Kernels may nest, but nested structure remains another instance of the same $(U,C)$ abstraction. That uniformity is what enables later claims of pass composability.

3. Callback wrapping as the core mechanism

The central technique in qstack is callback wrapping. It addresses the case where a pass changes the number or structure of measurements. The canonical example is an encoding pass that replaces one logical qubit by $(\text{GateSet}, \text{Kernel})$0 physical qubits. The original callback expects one logical measurement bit, but the transformed program produces $(\text{GateSet}, \text{Kernel})$1 physical bits (Paz et al., 15 May 2026).

For a pass $(\text{GateSet}, \text{Kernel})$2, the generated wrapper $(\text{GateSet}, \text{Kernel})$3 performs three operations. First, it runs a decoder that pops exactly those $(\text{GateSet}, \text{Kernel})$4 physical bits and pushes back a single logical bit. Second, it invokes the original callback on the restored Measurement stack. Third, if the callback returns a Kernel written in the source gate set, the wrapper recompiles that Kernel by re-applying $(\text{GateSet}, \text{Kernel})$5, so dynamically generated kernels re-enter the same pipeline (Paz et al., 15 May 2026).

The formal definition given for one callback is:

$(\text{GateSet}, \text{Kernel})$6

Define $(\text{GateSet}, \text{Kernel})$7 by

$(\text{GateSet}, \text{Kernel})$8

$(\text{GateSet}, \text{Kernel})$9

$\{U_1,U_2,\ldots\}$0

$\{U_1,U_2,\ldots\}$1

The stated consequence is that the measurement flow restores the stack exactly so that the original callback sees the same shape of bits it was written for (Paz et al., 15 May 2026).

This mechanism is stronger than a simple decoder insertion pass. Because returned kernels are recursively recompiled, runtime-generated quantum continuations remain closed under the same compiler transformation.

4. Compositional passes and code concatenation

qstack presents quantum error correction and ISA translation as compiler passes with a shared structure, rather than as special-purpose end stages. Sequential composition of two passes is defined as

$\{U_1,U_2,\ldots\}$2

At runtime, callbacks become layered wrappers: the outermost wrapper applies $\{U_1,U_2,\ldots\}$3, then invokes the inner wrapper for $\{U_1,U_2,\ldots\}$4, then finally invokes the original callback. If the original callback returns a Kernel, it is first compiled by $\{U_1,U_2,\ldots\}$5 and then by $\{U_1,U_2,\ldots\}$6 (Paz et al., 15 May 2026).

The framework uses this structure to express code concatenation. For the 3-bit bit-flip repetition pass $\{U_1,U_2,\ldots\}$7 and the 3-bit phase-flip repetition pass $\{U_1,U_2,\ldots\}$8, the Shor code pass is simply

$\{U_1,U_2,\ldots\}$9

At each measurement site, $IR = \{(U_i, C_i)\mid i=1\ldots n\},$0 pops 3 phase-syndrome bits and pushes a logical measurement, then $IR = \{(U_i, C_i)\mid i=1\ldots n\},$1 pops 3 bit-flip syndrome bits and pushes another logical measurement, after which the original callback runs (Paz et al., 15 May 2026).

The same section states that concatenating a pass with itself doubles distance, so $IR = \{(U_i, C_i)\mid i=1\ldots n\},$2 yields a 9-distance repetition code. The importance of this observation is methodological rather than merely algebraic: higher-level codes can be obtained by composing existing passes, rather than by constructing monolithic new back ends.

5. End-to-end compilation pipeline and worked example

The demonstration begins with a three-qubit Toy program containing the gates mix, entangle, and Flip, together with a fix callback that returns Kernel([Flip(q)]). qstack then composes five stages: Toy$IR = \{(U_i, C_i)\mid i=1\ldots n\},$3Cliffords, Cliffords$IR = \{(U_i, C_i)\mid i=1\ldots n\},$4Rep-3 (bit), Rep-3 (bit)$IR = \{(U_i, C_i)\mid i=1\ldots n\},$5Rep-3 (phase), Shor$IR = \{(U_i, C_i)\mid i=1\ldots n\},$6Steane, and Steane$IR = \{(U_i, C_i)\mid i=1\ldots n\},$7Trapped-Ion Native (Paz et al., 15 May 2026).

In the Toy$IR = \{(U_i, C_i)\mid i=1\ldots n\},$8Cliffords stage, handlers map mix↦H, entangle↦CX, and Flip↦X. Because measurement structure does not change, decode is the identity, and the fix callback’s returned kernel [Flip(q)] is recompiled to [X(q)]. In the bit-flip repetition stage, each logical qubit $IR = \{(U_i, C_i)\mid i=1\ldots n\},$9 expands to physical qubits $U_i$0, gate handlers duplicate operations or interleave syndrome ancilla allocations and measurements, and the decoder majority-votes three physical bits to one logical bit before invoking the inner callback. In the phase-flip repetition stage, the same wrapper structure is applied for $U_i$1-error protection, giving the Shor code by composition rather than by a separate ad hoc construction (Paz et al., 15 May 2026).

The Steane pass inserts a 7-qubit Hamming encoding for each logical qubit and preserves the Clifford gate set; decode_Steane implements syndrome lookup for the $U_i$2 code. The final native pass maps each logical Clifford gate $U_i$3 to sequences of trapped-ion native gates $U_i$4 and does not change measurement structure, so its decoder is again the identity (Paz et al., 15 May 2026).

The resource growth reported for the worked pipeline is summarized below.

Stage	Effect per logical qubit	Physical qubits
Rep-3 bit	bit-flip repetition	3
Shor	Rep-3 bit + Rep-3 phase	9
Shor + Steane	concatenated encoding	63
Trapped-Ion translation	native decomposition only	63

After each stage, the implementation was validated by 1,000 runs on the qstack state-vector emulator, and the logical outcome distribution was reported to remain unchanged. The trapped-ion translation adds no extra qubits; it adds only native gate decompositions (Paz et al., 15 May 2026).

6. Experimental properties, comparison to Qiskit, and extensibility

The reported experimental results emphasize three properties. First, semantic preservation: output distributions after each pass, from Toy through Clifford rewriting, quantum error-correction layers, and hardware targeting, match to statistical tolerance over 1,000 simulator runs. Second, composability: the Shor code was obtained by simply chaining the two repetition-3 passes, with no new code or manual wiring. Third, implementation economy: each pass required only approximately 70–230 lines of Python for handlers and decode, the shared Compiler base class is approximately 71 lines, and the full prototype is approximately 1,500 lines including emulator and Jupyter support (Paz et al., 15 May 2026).

The comparison drawn with Qiskit is specific. Qiskit provides classical primitives such as if_test and switch to inline decoders, but composing multiple quantum error-correction layers requires hand-written recursion into every control-flow construct and careful remapping of classical registers; a missing case can break correctness silently. By contrast, qstack’s opaque-callback boundary means that no pass inspects another pass’s logic, and composition is described as fully automatic (Paz et al., 15 May 2026).

The framework also claims broader decoder expressivity at the callback boundary. Because callbacks can call external libraries, they can implement arbitrary decoders, including MWPM for surface codes, whereas in-circuit QASM conditionals cannot express unbounded or graph-algorithmic decoding. Extensibility is correspondingly localized: adding a new gate set, such as superconducting CZ-based hardware, or a new quantum error-correction code, such as a surface code, requires only new gate handlers and a decoder, while the compositional machinery remains unchanged (Paz et al., 15 May 2026).

7. Terminological scope and related uses of “qstack”

Within arXiv literature, “qstack” is not a unique designation. The term refers here to the compositional compiler framework for fault-tolerant quantum programs (Paz et al., 15 May 2026), but closely related naming appears in several other contexts.

In quantum systems software, “Quantum Accelerator Stack” denotes a layered accelerator architecture spanning OpenQL, cQASM, eQASM, a quantum operating system, micro-architecture, mapping and routing, and simulator or hardware layers (Bertels et al., 2021). “Full Quantum Stack: Ket Platform” describes a high-level Python interface, multi-stage compilation, hardware-aware mapping, native gate translation, and pulse-level calibration for superconducting processors (Rosa et al., 18 Sep 2025). “A Full Stack Framework for High Performance Quantum-Classical Computing” uses LLVM IR and QIR, a Quantum Interface Library, MPI plus SLURM dispatch, and adaptive circuit knitting in an HPC–QC environment (Zhan et al., 23 Oct 2025).

Outside quantum compilation, “QStack” has been used for a user-space network stack that targets CPU efficiency and low tail latency in front-end datacenter servers (Zhang et al., 2022). In concurrent data structures, “qstack” denotes a wait-free, read/write-only, set-linearizable relaxed stack with multiplicity (Castañeda et al., 2020). In automata theory, “quantum stack machines” designate quantum generalizations of stack-machine models in which a family of unitaries acts on a finite control register while stack operations are interleaved classically (Qiu, 21 Nov 2025).

This terminological overlap makes context essential. In current fault-tolerant quantum compilation, qstack specifically denotes the callback-wrapping compiler architecture built around a purely quantum IR and compositional pass structure (Paz et al., 15 May 2026).