OpenQASM 3 Python AST

Warnings

• breaking OpenQASM 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.
• gotcha The `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.
• deprecated The `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.
• gotcha The `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.
• breaking The 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.

Install

• pip install openqasm3 Base Installation
• pip install openqasm3[parser] Installation with Parser (Recommended)

Imports

• parse
  wrong:

  import openqasm3.parser.parse

  correct:

  from openqasm3.parser import parse

  The `parse` function is the main entry point for parsing OpenQASM 3 strings into an AST `Program` object.
• Program
  wrong:

  import openqasm3.ast.Program

  correct:

  from openqasm3.ast import Program

  Classes representing the Abstract Syntax Tree nodes, such as `Program`, reside in the `openqasm3.ast` module.

Quickstart

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}")