Overview

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:

To use the CLI tool, install the cli extra:

pip install 'pyqasm[cli]'

To use the circuit drawer tool, install the visualization extra:

pip install 'pyqasm[visualization]'

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,visualization]'

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.

Using loads and dumps

import pyqasm

qasm_code = """
OPENQASM 3.0;
include "stdgates.inc";
qubit[2] q;
bit[2] c;
h q[0];
cx q[0], q[1];
c = measure q;
"""

# Load QASM code from a string into a QasmModule object

module = pyqasm.loads(qasm_code)

# Write QASM code from a QasmModule object to a string

qasm_code = pyqasm.dumps(module)

print(qasm_code)

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.

Using validate method

import pyqasm

qasm_str = """
OPENQASM 3.0;
include "stdgates.inc";
qubit[2] q;
bit[2] c;
h q[0];
cx q[0], q[1];
c = measure q;
"""

module = pyqasm.loads(qasm_str)

module.validate()

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

Using validate method with invalid QASM code

import pyqasm

qasm_str = """
OPENQASM 3.0;
include "stdgates.inc";
qubit[2] q;
bit[2] c;
h q[0];
cx q[0], q[1];
c = measure q[3];
"""

module = pyqasm.loads(qasm_str)

module.validate()

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

Using unroll method

import pyqasm

qasm_str = """
OPENQASM 3.0;
include "stdgates.inc";
qubit[5] q;
bit[5] c;
h q;
cx q[0], q[1];
c = measure q;
"""

module = pyqasm.loads(qasm_str)

module.unroll()

print(pyqasm.dumps(module))

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.

Using external_gates

import pyqasm
qasm_str = """
OPENQASM 3.0;
include "stdgates.inc";
gate custom (p1) q1, q2, q3 {
    // empty body
}
qubit[4] q;
custom(pi / 2) q[0], q[1], q[2];
cx q[1], q[2];
"""
module = pyqasm.loads(qasm_str)
module.unroll(external_gates=["custom"])

print(pyqasm.dumps(module))

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

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

Contributing

• Interested in contributing code, or making a PR? See CONTRIBUTING.md
• For feature requests and bug reports: Submit an issue
• For discussions, and specific questions about pyqasm, or other topics, join our discord community
• For questions that are more suited for a forum, post to Quantum Computing Stack Exchange with the pyqasm tag.

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_2025,
author = {Gupta, Harshit and Hill, Ryan James},
license = {Apache-2.0},
month = mar,
title = {{PyQASM: Python toolkit for OpenQASM program analysis and compilation.}},
url = {https://github.com/qBraid/pyqasm},
version = {0.3.0},
year = {2025}
}

License

Apache-2.0 License