openqasm3

library1.0.1pypypiunverified

The `openqasm3` library provides a reference Python implementation of the OpenQASM 3 Abstract Syntax Tree (AST). It enables parsing OpenQASM 3 programs into an AST and offers tools for manipulating this AST, facilitating the development of OpenQASM 3 compiler passes and analysis tools. The library, currently at version 1.0.1, actively supports the OpenQASM 3.1.0 specification, with releases often coinciding with updates to the OpenQASM specification.

data

pip install openqasm3

github ↗package ↗

INSTALL

IMPORT

SIG · OPENQASM3

openqasm3

datapythonv1.0.1

Install

2.0s avg

Import

402ms

Disk

24MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.940 runs

installs and imports cleanly · install 0.0s · import 0.414s · 24.5MB

glibc

py 3.10–3.940 runs

installs and imports cleanly · install 2.0s · import 0.391s · 25MB

24MB installed

● package 24MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ from openqasm3 import parse

✗ from openqasm3 import parse

This example demonstrates how to parse a simple OpenQASM 3 program string into its Abstract Syntax Tree representation using the `openqasm3.parser.parse` function. The resulting `Program` object can then be inspected or traversed for further processing.

from openqasm3 import parser from openqasm3 import ast # For type hinting or direct AST node creation qasm_code = ''' OPENQASM 3; qubit q; h q; measure q -> bit b; ''' # Parse the OpenQASM 3 string into an AST Program object program_ast = parser.parse(qasm_code) # The __str__ method of the Program object provides a basic representation print(program_ast) # You can also iterate through the statements print("\nStatements in AST:") for statement in program_ast.statements: print(f"- {type(statement).__name__}: {statement}")

Debug

Known issues

breakingOpenQASM 3.0 introduced significant breaking changes compared to OpenQASM 2.0, including new keywords, classical control flow, explicit timing, and gate modifiers. This library specifically targets OpenQASM 3.x and is not compatible with OpenQASM 2.0 syntax.

fix

Ensure your quantum programs adhere to the OpenQASM 3 specification. Consult the OpenQASM 3 specification for syntax and feature differences.

affects: All versions of `openqasm3` (as it's for OQASM 3.x only) when used with OQASM 2.x code.

gotchaThe `openqasm3` package relies on `antlr4-python3-runtime` for parsing. Compatibility is maintained across minor versions of ANTLR where possible through a dynamic import system. However, specific minor version mismatches (e.g., using `antlr4-python3-runtime==4.10.x` with `openqasm3` built for `4.11.x`) can lead to parsing errors or runtime issues.

fix

Install `openqasm3` with the `[parser]` extra (`pip install openqasm3[parser]`) to ensure the correct `antlr4-python3-runtime` version is installed. If encountering issues, check the `antlr4-python3-runtime` version and `openqasm3`'s `ANTLR_VERSIONS.txt` on GitHub for supported ranges.

affects: All versions

deprecatedThe `qreg` and `creg` keywords, fundamental in OpenQASM 2.0 for declaring quantum and classical registers, are not explicitly supported in the OpenQASM 3 specification and may cause issues or be fully removed in future specification versions. OpenQASM 3 primarily uses `qubit[N] q;` and `bit[N] c;`.

fix

Migrate from `qreg`/`creg` to `qubit[N]` and `bit[N]` declarations for future compatibility with OpenQASM 3.

affects: OpenQASM 3.x specification and consequently `openqasm3` library versions supporting it.

gotchaThe `openqasm3` library serves as a *reference AST* and parser for OpenQASM 3. It is not a full quantum compiler, simulator, or execution environment. Its primary purpose is to provide an in-memory representation for developing compiler passes and static analysis tools.

fix

Understand that this library processes the OpenQASM 3 language structure. For execution or simulation, integrate with a compatible quantum SDK or platform (e.g., Qiskit, Amazon Braket) that supports OpenQASM 3.

affects: All versions

breakingThe API of the `openqasm3` Python package, including the AST structure, is explicitly stated to be in early development and subject to change in backwards-incompatible ways, mirroring the ongoing evolution of the OpenQASM 3 language itself.

fix

Pin the exact version of `openqasm3` in your `requirements.txt` (`openqasm3==X.Y.Z`) and be prepared for potential API changes when upgrading. Regularly review release notes for breaking changes.

affects: All versions, especially between minor or patch releases that align with specification updates.

Upgrade

Version history

1.0.1latest on PyPI · released Feb 19, 2025

Audit

Dependencies

antlr4-python3-runtimeoptionalRequired for parsing OpenQASM 3 code into the AST. The library includes a dynamic import system to ensure compatibility with different minor versions of this runtime.

Agent activity

16 hits · last 30 days

node

Resources

githubhttps://github.com/openqasm/openqasm ↗

packagehttps://pypi.org/project/openqasm3/ ↗