New features of the Qiskit Trebugger

By Harshit Gupta, Qiskit Advocate

The Qiskit Transpiler is an essential tool that allows us to map any arbitrary quantum circuit into a circuit that is both physically runnable and compatible with the properties of its target quantum backend. Qiskit’s transpiler has built-in logging and callback mechanisms to help users understand transpilation, but, many users don’t know about these methods, nor do they have sufficient knowledge about using them. That’s where we come in.

The process we use Qiskit’s transpiler for is called quantum circuit
transpilation. It includes important tasks like expanding a circuit to the backend’s qubit count, breaking down higher-level quantum operations in terms of the supported basis set, routing qubits according to the chip connectivity, and optimizing the final circuit. Users often find it difficult to visualize these tasks, however. That’s why we decided to build Qiskit Trebugger (transpiler-debugger), a tool that provides a visual representation of the transpilation process. Originally debuting on the Qiskit blog in early 2022 in the form of a Jupyter widget, we’re pleased to share that Qiskit Trebugger is now also available as a lightweight command-line interface (CLI) as well.

Qiskit Trebugger was developed as an interactive tool with multiple views catering to the needs of different users. Available as a Python package on PyPI, it can be used as a Jupyter widget or a lightweight CLI tool to understand how a circuit goes through the Qiskit transpiler. Below, we’ll take a closer look at this new CLI functionality and its key features.

Command Line View

The command line view for the debugger is a recent development. Built using the ncurses and tabulate packages, it is a lightweight alternative to the Jupyter view. It has minimal overhead for loading and gives users the ability to debug circuits in a familiar terminal environment.

The CLI view is also interactive, with action keys for navigation and a status bar. Users can index into the pass list to see the details of each pass and toggle through different views. The CLI supports most features that are provided by the Jupyter view. However, users should note that they can only render the CLI view in the terminal, not a Jupyter notebook.

Installing the package is as simple as running the following command —

pip install qiskit-trebugger

To test the package, users can run a Python file with the given code —

from qiskit.providers.fake_provider import FakeCasablanca
from qiskit.circuit.random import random_circuit 
from qiskit_trebugger import Debugger
import warnings

warnings.simplefilter('ignore')
debugger = Debugger(view_type = "cli")
backend = FakeCasablanca()
circuit = random_circuit(num_qubits = 4, depth = 5 , seed = 44)

# replace qiskit's transpile call 
debugger.debug(circuit, optimization_level = 2, backend = backend)

This will render a view describing the transpilation process of the Qiskit transpiler.

Components

• Overview Panel: The overview consists of the header and the transpilation overview panels. The transpilation overview panel highlights crucial information about the workings of the transpiler. It consists of the total number of transpiler passes executed, the total runtime of the transpiler, and a comparison of the different statistics for the original and final circuits.

Overview

• Global Transpilation Panel: Provides the details about which passes were executed during transpilation and in which order. Key details such as pass type, runtime for the pass, and circuit statistics post-execution of each pass are highlighted in a tabular format. Passes that change at least one property of the circuit are highlighted as well.

Global Transpilation Table

• Interaction Bar: The CLI tool is interactive and can take in user input to modify its state. This input is taken through ‘hot keys’ listed in the interaction bar at the bottom of the terminal. The commands are listed below :

1. Arrow Keys: Scroll horizontally or vertically
2. U: Page Up
3. D: Page Down
4. H: Toggle the overview panel
5. I: Index into any transpiler pass
6. N: Move to Next
7. P: Previous pass while viewing pass details
8. B: Move back to the initial view
9. Q: Quit

Note: After pressing I, the user can enter the index of any transpiler pass and the pass level details will be rendered for the same.

Initial View

Input from User

Indexed View

• Pass Level Panels: These panels display a more granular level of detail. The user indexes into a particular pass by pressing ‘I’ followed by the index of the transpiler pass. This renders a new panel where users can see the state and properties of the circuit after this pass is executed. Trebugger highlights circuit statistics and property set for the given pass. Moreover, it also expands properties like the layout and original qubit indices, providing an insight into the detailed mapping of the circuit’s virtual to the physical qubits of the quantum backend. Lastly, circuit diagrams, documentation, and logs are displayed for an easier lookup.

Circuit Statistics and Pass Information

Property Set

Qubit Layout

Circuit Diagram

Documentation and Logs

Future Work

The project's development is ongoing with more upcoming features in both the CLI and the Jupyter view on the way. These include expanding different elements in the property set in the CLI view and introducing new elements in the jupyter widget such as the backend coupling maps, timeline drawer for the qiskit pulse schedule, and routing maps for the qubits. We encourage anyone interested in contributing to the project to do so via the GitHub repository linked below.

Sincere thanks to Unitary Fund for supporting this project through their Microgrant Program and facilitating the opportunity to work on it. Thanks as well to the Qiskit team for their support in the Qiskit Advocate Mentorship Program, and to mentors Kevin Krsulich and Matthew Treinish for their constant guidance and feedback.

Reference Links :

Qiskit Blog Post | GitHub Repository | Python Package | Demo Video