.. _debug:

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.

#. The functions ``qexpr::exitAtCompile`` and ``qexpr::exitAtRuntime`` (see
   :ref:`exiting`) should be used liberally to catch improper inputs to quantum
   kernel expression functions.

#. 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 :ref:`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 :ref:`compilation-overview`), which may not always align with
   their intuition.

#. If a large quantum kernel expression contains a bug, the function
   ``qexpr::printQuantumLogic()`` (see :ref:`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 :cite:p:`PSIW23`, 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.

#. ``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.

#. 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 :ref:`bind`) 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.

#. 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.

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

#. 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.
   (:ref:`compilation-overview`).

#. 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
   :ref:`compilation-overview` for details.

#. As discussed in :ref:`classical`, 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.

#. 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 :ref:`fleq_support`.
   This feedback is vital to shape FLEQ and maximize its utility for quantum applications developers
   and researchers.