New Debugger Takes You Under The Hood of Qiskit’s Transpiler

Published in

Qiskit

6 min readFeb 3, 2022

By Aboulkhair Foda (Qiskit Advocate) and Harshit Gupta (Qiskit Advocate)

Quantum circuit transpilation is the process of rewriting high-level quantum circuits into equivalent circuits which are compatible with a specific quantum backend. Qiskit uses a tool called the qiskit transpiler for achieving this transformation. Though important for realizing physically runnable circuits, its methods remain hidden from the general user. We developed TreBugger, a Qiskit Timeline Debugger, to address this underlying issue.

We developed the Qiskit Timeline Debugger as a mentorship project during the Qiskit Advocate Mentorship Program Fall ’21, under the guidance of Kevin Krsulich. Built as a jupyter widget, it tries to make the transpilation process more transparent and accessible, regardless of a user’s background.

How? Let us find out!

Why the need?

The ability to play around with a concept can be an important way to learn about it. But, the transpiler currently stands almost as a black box tool. While there are some methods to see its inner workings, they are accessible to the users more proficient in programming.
A quantum computer can only run a discrete set of quantum gates. This decomposition of arbitrary quantum gates to the basic gate set can sometimes be expensive in the terms of the final number of operations required to model them. Identifying and optimizing such operations can allow us to better adapt our circuits for today’s noisy, intermediate-scale quantum backends.
Finally, there exists a need for better error handling in the transpilation process. Trace backs in code may bewilder a user when a transpiler runs into an error. A structured way to understand these problems is necessary.

The Debugger

We present a lightweight Jupyter widget in the form of a debugger. It is built with the python ipywidgetsmodule and aims to address all the issues we hope to resolve. With an in-depth analysis of different transpilation stages and a simple, easy to use user interface, any user can quickly set up a debugger instance with as little as 4 lines of code. In the remainder of this section, it is assumed that the reader is familiar with python environments and using Qiskit. If not — get started with Qiskit here!

You can download the debugger via pip using —

pip install -i https://test.pypi.org/simple/ --extra-index https://pypi.org/simple/ qiskit-trebugger

The following code fires up the debugger in the python environment where it was installed. Simply replacing the call to the transpile method with the debug method of Debugger —

from qiskit import QuantumCircuit
from qiskit.test.mock import FakeCasablanca
from qiskit_trebugger import Debuggerdebugger = Debugger()
backend = FakeCasablanca()circuit = QuantumCircuit(3)
circuit.h(0)
circuit.cx(0,1)
circuit.cx(1,2)
circuit.measure_all()# replace transpile call 
# circ = transpile(circuit, backend = backend)
# with debug methoddebugger.debug(circuit, backend = backend)

Taking a small overhead of visual rendering, it quickly loads up the transpilation sequence of the circuit as it goes through different passes of the transpiler. As you can see, the widget is divided into three broad components which are —

Description of the circuit, backend and transpiler arguments provided during transpilation.
Transpilation Overview for the final circuit which provides a quick summary of the complete process.
Main Passes of the transpiler, where each component contains a description of circuit state (depth < 300), properties, logs of pass and documentation.

Let us unwrap its features and design.

Features

1. Visual diff for quantum circuits

Inspired by the git diff command for highlighting changes in two versions of a file, we built a custom feature called visual diffs which highlights the changes made to quantum circuits.
We built the visual diff feature using the DAG representation of circuits and the qiskit matplotlib drawer, allowing users to visually see what changed between two quantum circuits during transpilation. Realizing what exactly changed after each transpiler pass will allow users to get more familiar with the transpiler.

Circuit diff of above two circuits being highlighted in orange.

For the more curious readers, visual diff uses something called the Longest Common Subsequences (LCS) over the DAG of quantum circuits. Treating DAG as a string of one-depth circuits, the LCS contains what is common in two circuits. Everything else is just the diff !
Currently, our debugger supports this functionality for ≤2000 depth circuits and for easy exporting, circuits are available in different formats such as png , qasm and qpy.

2. Log based analysis and documentation

The qiskit transpiler is not a perfect black box after all, it just takes a lot of work to fully understand. It does have a built-in logging functionality which allows anyone to see the steps it takes while processing circuits.
Logs are just text-based messages or records that define what a particular software is doing. The transpiler publishes these messages at each stage, allowing us to look under its hood. TreBugger publishes this information as a separate panel in the pass tabs.

Logs being displayed according to level of severity

Each log record has a level of severity, which defines the kind of information it contains. In our debugger, we color code each log according to this severity level thus, adding a greater level of granularity for the whole process.
Each pass panel is further coupled with a Help tab which contains the docstring of the transpiler pass. This allows the user to easily see what the aim of a particular pass was and the target return value.

3. Circuit statistics and Property set

The debugger presents a lot of important information at the first glance, such as circuit size, depth, number of operations and time taken to run the particular transpiler pass.

The debugger lets a user easily identify the passes which highly affect the final gate count or are particularly time-consuming. Isolation of such passes would help in targeted research towards specific transpiler optimizations.

Contributions and future work

We have built the debugger using jupyter widgets along with some basic web development tools (HTML and CSS). Anyone comfortable with python, web development and having a working knowledge of quantum computing concepts is more than welcome to contribute to our project.

Since our project uses the MVC architecture, we would love to also see a command line version of the debugger. This view would purely be based upon python and use text-based logs and properties to allow users see how a circuit evolves.

Another need for the Trebugger is UI testing. Frameworks like Cypress and SeleniumBase were decided but the tests are yet to be formulated. Once completed, the project would directly be available to be installed from the actual python packaging index, PyPi.

If you would like to contribute or be up to date with the progress of our project be sure to check out the Qiskit Timeline Debugger GitHub repo. We hope that this project opens up the workings of qiskit transpiler to the general public and makes it a more accessible tool for qiskit users.

This project is part of the Qiskit Advocate Mentorship Program Fall 21 cohort. If you are interested in joining the Qiskit Advocate program, please check out the application guide. You can also fill this form to get an email update when the new application round opens later this year.