{"id":6754,"library":"openqasm3","title":"OpenQASM 3 Python AST","description":"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.","status":"active","version":"1.0.1","language":"en","source_language":"en","source_url":"https://github.com/openqasm/openqasm","tags":["quantum","qasm","openqasm","ast","compiler","parser"],"install":[{"cmd":"pip install openqasm3","lang":"bash","label":"Base Installation"},{"cmd":"pip install openqasm3[parser]","lang":"bash","label":"Installation with Parser (Recommended)"}],"dependencies":[{"reason":"Required 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.","package":"antlr4-python3-runtime","optional":true}],"imports":[{"note":"The `parse` function is the main entry point for parsing OpenQASM 3 strings into an AST `Program` object.","wrong":"import openqasm3.parser.parse","symbol":"parse","correct":"from openqasm3.parser import parse"},{"note":"Classes representing the Abstract Syntax Tree nodes, such as `Program`, reside in the `openqasm3.ast` module.","wrong":"import openqasm3.ast.Program","symbol":"Program","correct":"from openqasm3.ast import Program"}],"quickstart":{"code":"from openqasm3 import parser\nfrom openqasm3 import ast # For type hinting or direct AST node creation\n\nqasm_code = '''\nOPENQASM 3;\nqubit q;\nh q;\nmeasure q -> bit b;\n'''\n\n# Parse the OpenQASM 3 string into an AST Program object\nprogram_ast = parser.parse(qasm_code)\n\n# The __str__ method of the Program object provides a basic representation\nprint(program_ast)\n\n# You can also iterate through the statements\nprint(\"\\nStatements in AST:\")\nfor statement in program_ast.statements:\n    print(f\"- {type(statement).__name__}: {statement}\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your quantum programs adhere to the OpenQASM 3 specification. Consult the OpenQASM 3 specification for syntax and feature differences.","message":"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.","severity":"breaking","affected_versions":"All versions of `openqasm3` (as it's for OQASM 3.x only) when used with OQASM 2.x code."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Migrate from `qreg`/`creg` to `qubit[N]` and `bit[N]` declarations for future compatibility with OpenQASM 3.","message":"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;`.","severity":"deprecated","affected_versions":"OpenQASM 3.x specification and consequently `openqasm3` library versions supporting it."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions, especially between minor or patch releases that align with specification updates."}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}