pyqasm 1.0.2

Python toolkit providing an OpenQASM 3 semantic analyzer and utilities for program analysis and compilation.

Python toolkit providing an OpenQASM 3 semantic analyzer and utilities for program analysis 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 optional extras such as -

1. cli : command-line interface (CLI) functionality
2. visualization: for program visualization
3. pulse : 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]'      

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 .

Check version

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

>>> import pyqasm
>>> pyqasm.__version__

Key Features: Unroll & Validate OpenQASM 3 Programs

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.

Highlights

• 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.

---

Example: Unroll and Validate a Complex QASM Program

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 QASM

Output (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.

Resources

• 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.
• Gate Decompositions: Detailed decomposition diagrams and explanations for quantum gates.

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 QCSE with the pyqasm tag.
• By participating, you are expected to uphold our code of conduct.

License

Apache-2.0 License