Python toolkit providing an OpenQASM 3 semantic analyzer and utilities for program analysis and compilation.
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.
PyQASM requires Python 3.10 or greater, and can be installed with pip as follows:
pip install pyqasmPyQASM offers optional extras such as -
cli: command-line interface (CLI) functionalityvisualization: for program visualizationpulse: pulse/calibration features (in progress)
To install these features along with the core package, you can use the following command:
pip install 'pyqasm[cli,pulse,visualization]'You can also install them individually. For example, to install the CLI features only, you can run:
pip install 'pyqasm[cli]' 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 .You can view the version of pyqasm you have installed within a Python shell as follows:
>>> import pyqasm
>>> pyqasm.__version__PyQASM offers robust support for the extensive grammar of OpenQASM 3, including custom gates, subroutines, loops, conditionals, classical control, and more. Its core utilities allow you to validate programs for semantic correctness and unroll (flatten) all high-level constructs into a linear sequence of basic quantum operations, ready for execution or further compilation.
-
Comprehensive Grammar Support: PyQASM supports the full breadth of OpenQASM 3 operations, and backward compatibility with OpenQASM 2, including:
- Classical and quantum registers
- Loops (
for,while) - Conditionals (
if,else) - Parameterized and custom gates
- Subroutine inlining
- Switch statements
- Classical expressions and assignments
- Variables and arrays
- Type casting and conversions
- Built-in and user-defined constants
- Quantum-classical interaction (
measurement,reset, etc.) - Inclusion of standard libraries (
stdgates.inc, etc.)
-
Unrolling:
Expands all custom gates, loops, subroutines, branches, etc. into a flat, hardware-ready sequence of instructions. -
Validation:
Performs semantic analysis to ensure programs are correct and conform to the OpenQASM 3 specification.
Below is an example demonstrating PyQASM's efficacy on a non-trivial OpenQASM 3 program. This program uses custom gates, loops, and classical control, and is fully unrolled and validated by PyQASM:
from pyqasm import loads, dumps
qasm = """
OPENQASM 3;
include "stdgates.inc";
gate h2 a, b { h a; h b; }
def parity_flip(qubit[4] q) {
for int i in [0:3] {
if (i % 2 == 0) {
x q[i];
}
}
}
qubit[4] q;
bit[4] c;
h2 q[0], q[1];
parity_flip(q);
for int i in [0:3] {
measure q[i] -> c[i];
}
"""
module = loads(qasm) # Parse and build the program
module.validate() # Check for semantic errors
module.unroll() # Flatten all gates, loops, and subroutines
print(dumps(module)) # Output the fully unrolled QASMOutput (fully unrolled QASM):
OPENQASM 3.0;
include "stdgates.inc";
qubit[4] q;
bit[4] c;
h q[0];
h q[1];
x q[0];
x q[2];
c[0] = measure q[0];
c[1] = measure q[1];
c[2] = measure q[2];
c[3] = measure q[3];PyQASM ensures your OpenQASM programs are semantically correct and hardware-ready, supporting the language's most advanced features with ease.
- API Reference: Developer documentation.
- Usage Examples: Scripts and Markdown examples demonstrating core functionality.
- Supported Operations: OpenQASM language features supported, in progress, and planned for future support.
- 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
QCSE
with the
pyqasmtag. - By participating, you are expected to uphold our code of conduct.