Debugging

FLEQ enables higher level of abstraction for quantum programming through quantum kernel expressions, conditionals, recursion, DataList DSLs, and more. With this higher level of abstraction however, it becomes more difficult to debug quantum programs that are behaving in unexpected ways. FLEQ supplies several utilities, most of which have already been introduced, to aid in debugging. This section provides an overview of how these utilities can be utilized to debug quantum programs.

  1. The functions qexpr::exitAtCompile and qexpr::exitAtRuntime (see Exiting) should be used liberally to catch improper inputs to quantum kernel expression functions.

  2. If a bug arises from a DataList argument, or if a user wants to determine how far in evaluation of a QExpr the compiler was able to reach, they can use qexpr::printDataList() (see Printing) to act like a print statement during FLEQ evaluation as part of compilation. Users should be aware that such messages are buffered in a print buffer during compile-time, and the order of those messages is based on a topological sort of the FLEQ graph (see Overview of FLEQ compilation), which may not always align with their intuition.

  3. If a large quantum kernel expression contains a bug, the function qexpr::printQuantumLogic() (see Printing) can be used to narrow down the problem to a sub-expression. In particular, qexpr::printQuantumLogic() will display the PCOAST graph generated by a particular quantum kernel expression, even if it occurs within a larger QExpr. The PCOAST representation, described in detail in [PSI+23], is a compact representation of quantum logic, so if a user knows what PCOAST graph should be represented by a certain subcomponent of their QExpr, they can compare the actual output against the expected output.

  4. qexpr::printQuantumLogic() can also be used in conjunction with qexpr::convert<> to display the PCOAST graph associated with a quantum kernel function, even if FLEQ is not being used more broadly.

  5. Barriers in a quantum kernel expression prevent optimization across boundaries. Users may want to replace calls to join in a QExpr with calls to bind (see Barriers and binding) to isolate a problem. After the problem is fixed, they may be able to move back towards using join, which results in a more highly optimized circuit implementation.

  6. The compiler flag -P can be used for debugging quantum kernel expressions in a similar way as for ordinary quantum_kernel functions. The -P flag prints all fully evaluated quantum kernel expressions (as well as all quantum_kernel functions) to either the console, .tex files compatible with LaTeX, or .json files. For quantum kernel expressions, however, only the fully optimized and synthesized versions of the circuits will be displayed.

  7. The compiler flag -v prints out statistics for each evaluated quantum kernel expression and quantum_kernel function.

  8. Users can examine the intermediate LLVM files produced by the compiler by specifying the compiler flag -k. This flag will generate a number of intermediate files with the .ll extension. For the purposes of FLEQ debugging, the user should examine <filename>_lowered.ll, which is the earliest LLVM file generated by -k with results of the FLEQ compilation stage. (Overview of FLEQ compilation).

  9. Ill-formed uses of DataList and QList do not cause the compilation to exit, but do generate warnings which can be seen through the use of command-line flags. See Overview of FLEQ compilation for details.

  10. As discussed in Ordering of classical and quantum operations, if classical code is interwoven with quantum kernel expressions, it is best practice to add the PROTECT attribute to avoid premature inlining. This is especially true if the function introduces local variables.

  11. In the v1.1 release of the Intel® Quantum SDK, FLEQ is still in beta. Please feel free to voice any comments, concerns, questions or suggestions to the URL provided in Support. This feedback is vital to shape FLEQ and maximize its utility for quantum applications developers and researchers.