Python toolkit for OpenQASM program analysis, validation and compilation.

​
Motivation

OpenQASM is a powerful language for expressing hybrid quantum-classical programs, but it lacks a comprehensive tool supporting the full capabilities of the language. PyQASM aims to fill this gap by building upon the openqasm3.parser, and providing support for semantic analysis and utilities for program compilation.

​
Installation

PyQASM requires Python 3.10 or greater, and can be installed with pip as follows:

pip install pyqasm

​
Optional dependencies

PyQASM offers integrations that require extra (optional) dependencies, which can be installed as follows:

For using the CLI tool, install the cli extra:

pip install 'pyqasm[cli]'

​
Install from source

You can also install from source by cloning this repository and running a pip install command in the root directory of the repository:

git clone https://github.com/qBraid/pyqasm.git
cd pyqasm
pip install .

To include optional dependencies when installing from source, use the same “extras_require” format, e.g.

pip install '.[cli]'

​
Check version

You can view the version of pyqasm you have installed within a Python shell as follows:

In [1]: import pyqasm

In [2]: pyqasm.__version__

​
Using PyQASM

We will use simple QASM strings for demonstrating the core functionalities of pyqasm API.

A detailed overview of the supported QASM features can be found in the Usage Examples section.

​
load and dump

The load and dump functions are used to read QASM code from a file and write QASM code to a file, respectively.

  • load: Reads QASM code from a file and returns a QasmModule object.
  • dump: Writes QASM code from a QasmModule object to a file.
import pyqasm

# ensure that the file exists and the path is correct
file_path = "example.qasm"

# Load QASM code from the file into a QasmModule object
module = pyqasm.load(file_path)

# Write QASM code from a QasmModule object to a file
pyqasm.dump(module, "output.qasm")

​
loads and dumps

The loads and dumps functions are used to read QASM code from a string and write QASM code to a string, respectively.

  • loads: Reads QASM code from a string and returns a QasmModule object.
  • dumps: Writes QASM code from a QasmModule object to a string.

​
The QasmModule object

The QasmModule object is the main data structure used to represent a QASM program. The two important methods of the QasmModule object are validate and unroll -

  • validate : Used to check the semantic validity of the QASM program represented by the QasmModule object.

Raises an exception if the program is not semantically valid and points out the error in the program.

  • unroll : Used to unroll the QASM program represented by the QasmModule object. Also performs semantic validation while unrolling the program.

A useful argument for the method is external_gates that takes in a list of gate names considered external to the program. Only the number of parameters and qubit arguments must be declared for validation but the body of the gate is not required in the program.

For more details about the QasmModule and its features, please refer to our API Reference.

​
The CLI tool

This feature is still in active development and may not be stable for production use

To provide a more interactive experience for developers, PyQASM offers a command-line interface (CLI) tool. The CLI tool can be installed as an extra dependency by running the following command:

pip install "pyqasm[cli]"

Users can then verify their installation by running the following command:

The validate functionality can be used to check QASM files. You can provide the path to the QASM file or a directory as an argument to the validate command. The tool will then check the semantic validity of the file(s) and return the results.

Currently Supported Operations for OpenQASM language features supported, in progress, and planned for future support.

​
Contributing

​
Citation

If you use PyQASM in your research, we kindly request that you cite it appropriately. The BibTeX entry below is aligned with the latest stable release. For the most up-to-date citation details, please refer to CITATION.cff.

@software{Gupta_PyQASM_Python_package_2024,
author = {Gupta, Harshit and Hill, Ryan James},
license = {GPL-3.0},
month = november,
title = {{PyQASM: Python toolkit for OpenQASM program analysis and compilation.}},
url = {https://github.com/qBraid/pyqasm},
version = {0.0.3},
year = {2024}
}

​
License

GNU General Public License v3.0

Usage Examples