As quantum computing continues to mature, more developers are designing, coding, and simulating quantum circuits. A challenge exists, however, in debugging quantum circuits, particularly as they scale in size and complexity. Given the lack of effective debugging workflows, developers are forced to manually inspect their circuits and analyze various quantum states, which is error-prone and time-consuming. In this research, we present a statistical assertion-based debugging workflow for CUDA-Q. CUDA-Q has gained popularity due to its ability to leverage GPUs to accelerate quantum circuit simulations; this allows circuits to scale to larger depths and widths, where they can be particularly hard to debug by hand. Inspired by and building from prior Qiskit-based debuggers, our work allows CUDA-Q users to verify quantum program correctness with greater ease. Through the insertion of statistical assertions within a quantum circuit, our tool provides valuable insights into the state of qubits at any point within a circuit, tracks their evolution, and helps detect deviations from expected behavior. Furthermore, we improve the reliability and accuracy of the product state assertion by using a combination of Fisher's exact test and the Monte Carlo Method instead of a chi-square test, and examine the impact of CUDA-Q's distinct kernel-based programming model on the design of our debugging tool. This work offers a practical solution to one of CUDA-Q's usability gaps, paving the way for more reliable and efficient quantum software development.
As quantum computing continues to mature, more developers are designing, coding, and simulating quantum circuits. A challenge exists, however, in debugging quantum circuits, particularly as they scale in size and complexity. Given the lack of effective debugging workflows, developers are forced to manually inspect their circuits and analyze various quantum states, which is error-prone and time-consuming. In this research, we present a statistical assertion-based debugging workflow for CUDA-Q. CUDA-Q has gained popularity due to its ability to leverage GPUs to accelerate quantum circuit simulations; this allows circuits to scale to larger depths and widths, where they can be particularly hard to debug by hand. Inspired by and building from prior Qiskit-based debuggers, our work allows CUDA-Q users to verify quantum program correctness with greater ease. Through the insertion of statistical assertions within a quantum circuit, our tool provides valuable insights into the state of qubits at any point within a circuit, tracks their evolution, and helps detect deviations from expected behavior. Furthermore, we improve the reliability and accuracy of the product state assertion by using a combination of Fisher's exact test and the Monte Carlo Method instead of a chi-square test, and examine the impact of CUDA-Q's distinct kernel-based programming model on the design of our debugging tool. This work offers a practical solution to one of CUDA-Q's usability gaps, paving the way for more reliable and efficient quantum software development.
As the scale of quantum programs grows to match that of classical software, the nascent field of quantum software engineering must mature and tools such as debuggers will become increasingly important. However, developing a quantum debugger is challenging due to the nature of a quantum computer; sneaking a peek at the value of a quantum state will cause either partial or complete collapse of the superposition and may destroy the necessary entanglement. As a first step to developing a full quantum circuit debugger, we have designed and implemented a quantum circuit debugging tool. The tool allows the user to divide the circuit vertically or horizontally into smaller chunks known as slices, and manage their simulation or execution for either interactive debugging or automated testing. The tool also enables developers to track gates within the overall circuit and each chunk to understand their behavior better. Feedback on usefulness and usability from early users shows that using the tool to slice and test their circuits has helped make the debugging process more time-efficient for them.
Debugging quantum programs remains challenging due to the nature of quantum measurement. As quantum algorithms and systems scale, it is increasingly crucial to develop rigorous debugging and verification approaches. Statistical assertion-based debugging validates quantum program behavior through repeated circuit execution and statistical hypothesis testing, but existing frameworks treat shot count as a fixed input parameter, leaving the problem of optimal shot allocation across multiple mid-circuit assertions unexplored. To improve debugging efficiency by making better use of given shot counts, this paper proposes and evaluates four shot allocation strategies within the QDB quantum debugger implemented within the CUDA-Q framework. These allocation approaches: equal split, static weight allocation, adaptive entropy routing, and sequential retirement, use statistical approaches to test whether qubits have expected state characteristics at different points in execution. We evaluate these allocation strategies on different circuits, under both noise-free and depolarizing noise conditions. We show how adaptive strategies use shots efficiently by concentrating them on assertions with high uncertainty. This substantially reduces total shot usage while maintaining comparable debugging confidence.
As new advancements in the field of quantum computing lead to the development of increasingly complex programs, approaches to validate and debug these programs are becoming more important. To this end, methods employed in classical debugging, such as assertions for testing specific properties of a program's state, have been adapted for quantum programs. However, to efficiently debug quantum programs, it is key to properly place these assertions. This usually requires a deep understanding of the program's underlying mathematical properties, constituting a time-consuming manual task for developers. To address this problem, this work proposes methods for automatically refining assertions in quantum programs by moving them to more favorable positions in the program or by placing new assertions that help to further narrow down potential error locations. This allows developers to take advantage of rich and expressive assertions that greatly improve the debugging experience without requiring them to place these assertions manually in an otherwise tedious manner. An opensource implementation of the proposed methods is available at https://github.com/cda-tum/mqt-debugger.
Recent advancements in quantum computing software are gradually increasing the scope and size of quantum programs being developed. At the same time, however, these larger programs provide more possibilities for functional errors that are harder to detect and resolve. Meanwhile, debugging tools that could aid developers in resolving these errors are still barely existent and far from what we take for granted in classical design automation and software engineering. As a result, even if one manages to identify the incorrect behavior of a developed quantum program, detecting and resolving the underlying errors in the program remains a time-consuming and tedious task. Moreover, the exponential growth of the state space in quantum programs makes the efficient manual investigation of errors radically difficult even for respectively simple algorithms, and almost impossible as the number of qubits increases. To address this problem, this work proposes a debugging framework, available as an open-source implementation at https://github.com/cda-tum/mqt-debugger. It assists developers in debugging errors in quantum programs, allowing them to efficiently identify the existence of errors and diagnose their causes. Users are given the ability to place assertions in the code that test for the correctness of a given algorithm and are evaluated using classical simulations of the underlying quantum program. Once an assertion fails, the proposed framework employs different diagnostic methods to point towards possible error causes. This way, the debugging workload for quantum programs is drastically reduced.
In support of the growing interest in quantum computing experimentation, programmers need new tools to write quantum algorithms as program code. Compared to debugging classical programs, debugging quantum programs is difficult because programmers have limited ability to probe the internal states of quantum programs; those states are difficult to interpret even when observations exist; and programmers do not yet have guidelines for what to check for when building quantum programs. In this work, we present quantum program assertions based on statistical tests on classical observations. These allow programmers to decide if a quantum program state matches its expected value in one of classical, superposition, or entangled types of states. We extend an existing quantum programming language with the ability to specify quantum assertions, which our tool then checks in a quantum program simulator. We use these assertions to debug three benchmark quantum programs in factoring, search, and chemistry. We share what types of bugs are possible, and lay out a strategy for using quantum programming patterns to place assertions and prevent bugs.
Quantum simulators are a foundational component of the quantum software ecosystem. They are widely used to develop and debug quantum programs, validate compiler transformations, and support empirical claims about correctness and performance. In the absence of large-scale quantum hardware, simulator outputs are often treated as ground truth for algorithm development and system evaluation. However, quantum simulators also introduce unique implementation challenges. They must faithfully emulate quantum behavior while executing on classical hardware, requiring complex representations of quantum state evolution, operator composition, and noise modeling. Yet, we still lack a large-scale and in-depth study of failures in quantum simulators.
To bridge this gap, this work presents a comprehensive empirical study of bugs in widely used open-source quantum simulators. We analyze 394 confirmed bugs from 12 simulators and manually categorize them based on root causes, failure manifestations, affected components, and discovery mechanisms. Our study reveals several key findings. First, bug discovery is largely user-driven, with most crashes, exceptions, and resource-related failures not detected by automated testing and identified after deployment. Second, logical correctness failures are widespread and often silent, producing plausible but incorrect outputs without triggering crashes or explicit error signals. Third, many critical failures originate in classical simulator infrastructure, such as memory management, indexing, configuration, and dependency compatibility, rather than in core quantum execution logic. These findings provide new insights into the reliability challenges of quantum simulators and highlight opportunities to improve testing and validation practices in the quantum software ecosystem.