OpenQASM 3 Python Reference

The openqasm3 package contains the reference abstract syntax tree (AST) for representing OpenQASM 3 programs, tools to parse text into this AST, and tools to manipulate the AST.

The AST is intended to help with writing compiler passes for OpenQASM 3 in Python. It aims to have no dependencies for users who consume the Python tree structure, and minimal dependencies for parsing a string to this tree structure. The AST is simpler than a Concrete Syntax Tree (CST) which preserves comments, spacing, etc for use by editor plugins.

The package consists of the modules:

• openqasm3.ast: The AST nodes.

• openqasm3.parser: A parser based on an ANTLR grammar and reference parser also found in this repo. It walks the ANTLR parse tree to generate the AST.

• openqasm3.visitor: A base AST visitor and transformer.

• tests: A set of unit tests.

Note: this reference Python package is currently in the early stages of development, and no parts of the API should be considered stable at this time. The AST itself will be subject to change in backwards-incompatible ways, mirroring the development of the OpenQASM 3 languge itself.

Installation

The package can be installed from PyPI (pip) with the command

python -m pip install openqasm3

If you want to use the parser, you will need to install the extra parsing, and to run the tests you need the extra tests, for example pip install openqasm3[tests]. All extras can be installed with the target openqasm3[all].

Development Environment

To work on development, you will need to have a complete ANTLR installation (not just the runtime), and the ANTLR grammar files from the main OpenQASM repository.

Setting up ANTLR

You can most likely get a copy of ANTLR using your system package manager if you are on Linux, or from Homebrew (brew) on macOS. Otherwise, you can follow these instructions. Make a note of the exact version of ANTLR you have installed, because you will need to ensure your version of antlr4-python3-runtime matches exactly. The package in its current form expects ANTLR 4.9.2.

Once you have ANTLR installed, change to the directory where the qasm3.g4 file is located (for example, openqasm/source/grammar), and run

<antlr command> -o /path/to/openqasm3/antlr -Dlanguage=Python3 -visitor qasm3.g4

For example, if this repository is cloned to ~/openqasm and the command to run ANTLR is antlr4, then you should run

cd ~/openqasm/source/grammar
antlr4 -o ~/openqasm/source/openqasm/openqasm3/antlr -Dlanguage=Python3 -visitor qasm3.g4

Developer tools

Install the rest of the Python development environment with

python -m pip install -r requirements.txt -r requirements-dev.txt

ensuring that the version of antlr4-python3-runtime exactly matches the version of ANTLR you have.

Install the Python package in editable mode with

python -m pip install -e .

The project is configured to use the code formatter black, linter pylint and tester pytest. The commands to run these are, respectively:

black .
pylint .
pytest