qstack: Compositional End-to-End Compilation for Fault-Tolerant Quantum Programs

Abstract: Compiling quantum programs for fault-tolerant execution requires transforming high-level operations through multiple abstraction layers: from logical gates to error-corrected encodings to hardware-native instructions. A key challenge is that quantum error correction turns purely quantum programs into hybrid quantum-classical programs, where classical feedback from syndrome measurements drives quantum corrections at runtime. Existing compilation frameworks handle these quantum and classical components separately, requiring manual adaptation of classical logic at each compilation stage, all while preserving program semantics. We present qstack, a compiler framework built around a purely quantum intermediate representation in which classical logic is accessed only through opaque callbacks, written in any classical language. The framework's central mechanism, callback wrapping, enables compositional compilation: each compiler pass automatically adapts both quantum operations and their associated classical callbacks, and any kernel dynamically generated by a callback is compiled through the full pipeline. This allows ISA translation and quantum error correction to be expressed as composable compiler passes, including concatenation of error-correcting codes, without manual intervention. We demonstrate end-to-end compilation from a high-level gate set through Clifford gates to trapped-ion native operations, with bit-flip and phase-flip repetition codes, the Steane code, and the Shor code obtained by composing two repetition passes.

• The paper introduces qstack with automated callback wrapping to seamlessly propagate classical control and error correction across compilation layers.
• The paper demonstrates that a uniform quantum IR enables modular gate set translations and recursive kernel generation for scalable fault-tolerant quantum operations.
• The paper validates the approach through simulations showing consistent measurement distributions, confirming semantic equivalence pre- and post-compilation.

qstack: Compositional Compiler Infrastructure for Fault-Tolerant Quantum Programs

Introduction

The challenge of compiling fault-tolerant quantum programs lies in correctly transforming hybrid quantum-classical control while propagating quantum error correction (QEC) logic through multiple abstraction layers. Traditional compilation pipelines require explicit threading of classical feedback, forcing manual rewrites of decoder logic and classical control as programs evolve through layering of error-correcting codes and instruction set translation. The paper "qstack: Compositional End-to-End Compilation for Fault-Tolerant Quantum Programs" (2605.16595) introduces the qstack framework, which centralizes a purely quantum intermediate representation (IR) and composes quantum and classical program semantics via callback wrapping. This paradigm both unifies all compilation layers and automates adaptation of classical logic, including dynamically generated quantum kernels.

Uniform Quantum IR and Kernel Model

qstack's IR is structured around stack-disciplined quantum kernels, each consisting of qubit allocation, an instruction sequence (gates or nested kernels), and termination via measurement with a classical callback. Each kernel maintains strict LIFO discipline over qubit management, and measurement outcomes are pushed onto a classical measurement stack. The IR is free of explicit classical control or data, delegating all classical computation to external opaque callbacks.

Gate sets are also abstracted: kernels explicitly indicate which gate set they use, and each compiler pass operates by translating between source and target gate sets. This modularity, with explicit kernel and gate set designations, enables injection of QEC and ISA translation as orthogonal, composable passes, and maintains a uniform syntax throughout the entire pipeline.

Callback Wrapping and Compositional Compilation

The core technical contribution is the automated wrapping of classical callbacks during compilation passes. Whenever a pass modifies the measurement structure—such as expanding a single logical measurement into multiple physical qubit measurements for a QEC code—the compiler synthesizes an adapter: prior to invoking the original callback, it decodes the physical measurement outcomes and reconstructs the logical bit sequence expected by the callback. This restoration is crucial for semantic correctness of measurement-driven feedback and mid-circuit correction.

Furthermore, if a callback generates a new kernel (such as implementing conditional correction or a repeat-until-success loop), the wrapper re-compiles the returned kernel through the same chain of compiler passes. This recursive, dynamically-resolved pipeline enables full runtime adaptation; every dynamically created kernel reflects all prior compilation transformations without manual intervention. The wrapped callback chain composes automatically over multiple layers of passes, with each pass’s decoder and compiler applied in the correct sequence at runtime.

The efficacy of this mechanism is illustrated in the context of classic measurement-driven loops (e.g., repeat-until-success):

Figure 1: Distribution of measurement outcomes from 1000 simulation runs of the repeat-until-success program. Bitstrings of length $n$ occur with probability $1/2^{n}$, confirming the expected geometric decay.

This histogram not only validates the semantic preservation across compilation layers but showcases the correspondence between original and QEC-compiled programs via measurement stack emulation.

Gate Compilation and QEC Passes

Each compiler pass implements per-gate handlers that map source instructions to target instructions or, for QEC, to sub-kernels encoding logical operations in physical gates and ancillae. For instance, a repetition-3 bit-flip code returns a kernel distributing a logical $X$ across three physical qubits and orchestrates syndrome extraction and decoding purely via kernel expansion in the IR. Decoders, invoked as part of callback wrapping, restore logical measurement bits via majority vote or syndrome-based logic.

Because QEC passes do not alter the logical gate set (e.g., Cliffords $\to$ Cliffords), error-correcting codes can be concatenated or composed arbitrarily, including standard concatenated codes (e.g., Shor via rep-3 bit + rep-3 phase; Steane code with arbitrary concatenation). The chaining of callback wrappers ensures that all decoder logic is composed automatically, regardless of the number or type of QEC layers.

Implementation and Evaluation

The reference implementation (∼1,500 lines Python) realizes the full qstack pipeline: high-level toy and Clifford ISAs, QEC passes for repetition and Steane codes, hardware-native targeting for trapped-ion and neutral-atom devices, and a state-vector emulator with noise models. The compilation graph enables arbitrary sequences of hardware targeting and code concatenation with no manual adaptation of classical logic.

Correctness is established by comparing measurement distributions on logical outputs (pre- and post-compilation) over 1,000 simulation runs, demonstrating semantic equivalence across all pipelines. The callback wrapping paradigm shows strong numerical equivalence and eliminates measurement stack mismatches, even across deeply nested code concatenations and dynamically generated kernels.

Comparison with Qiskit and Alternative Frameworks

qstack’s approach contrasts with existing frameworks (Qiskit, Cirq, OpenQASM 3, Q#) which either intermingle quantum and classical logic in the host language or else require in-language classical control that restricts decoder expressivity and complicates composition. For instance, in Qiskit, composition of QEC layers demands manual inlining of decoders and careful recursion through all control blocks, with high risks of semantic drift if the classical-to-quantum mapping is not meticulously managed.

OpenQASM 3 partially addresses this via external (extern) classical functions, but has no canonical algorithm for recursive decoder composition, kernel adaptation, or cross-layer semantic preservation. qstack’s callback-based abstraction instead externalizes all classical logic, allowing arbitrary computational complexity (e.g., MWPM decoders), and delegates all stack translation and kernel re-compilation to the compiler pass infrastructure.

Moreover, the kernel/callback boundary in qstack provides a transparent insertion point for future constraints on classical expressiveness or integration with static analysis—should needs for termination, execution time bounds, or hardware-specific control codification arise.

Theoretical and Practical Implications

The qstack architecture demonstrates that a minimalistic quantum IR with opaque classical interfaces, together with recursive wrapping and compilation semantics, enables full compositionality of ISA translation, QEC, and hardware mapping with maximal code reuse and no semantic leakage between layers. From a theoretical perspective, this structure is well-suited to formal verification, allowing modular proofs of semantics for individual passes and invariant propagation along the callback chain. The framework sets a foundation for formally verified quantum compilers analogous to SQIR [sqir] or related work.

Practically, the elimination of manual classical adaptation drastically reduces developer burden for scalable, fault-tolerant compilation and supports rapid insertion of new codes or hardware platforms. This makes the approach advantageous for next-generation hardware deployments and scalable QEC designs, particularly as logical-qubit layers and real-time decoding requirements become more demanding.

Future Directions

Potential directions include:

• Extending qstack to more complex topological codes (surface/LDPC, color codes) with adaptive, algorithmic decoders.
• Integration with hardware-specific control stacks, mapping kernel/callback operations to real control processors with timing/resource constraints.
• Formal verification of semantic preservation under arbitrary code concatenations and dynamic kernel generation.
• Realization of qstack’s compilation model atop established IRs such as OpenQASM 3, leveraging def/extern constructs and translation to widely adopted backend representations.

Conclusion

qstack introduces a uniform, kernel- and callback-based IR and automatic callback wrapping, supporting end-to-end, compositional compilation for fault-tolerant quantum programs (2605.16595). By decoupling quantum and classical semantics at the IR boundary and automating adaptation and compilation over arbitrary compositions of QEC and ISA passes, it achieves strong semantic guarantees and scalable, hardware-agnostic expressivity. These results inform both the theory of quantum compilation and the engineering of next-generation, hybrid quantum-classical software stacks.