OpenQASM: specification, examples, and intermediate representation

What OpenQASM specifies

OpenQASM solves the interchange problem created by quantum programs that need to move between tools, research groups, and execution back ends. Its README describes it as an imperative programming language for describing quantum circuits. The stated scope extends beyond gate lists: it can represent universal quantum computing through the circuit model, the measurement-based model, and near-term quantum computing experiments.

The intended audience includes language designers, compiler developers, framework maintainers, and engineers who need a readable representation of quantum operations. A `.qasm` file can declare qubits and classical bits, include standard gates, define subroutines, apply gates, perform measurements, and contain control flow. This makes OpenQASM useful at an interchange boundary. It is not presented as the software that simulates those operations or sends them to hardware.

The repository identifies version 3.1 as current and links to its live specification. It also points readers to an `implementations.md` list for software supporting OpenQASM 3. That separation matters: this project defines and documents the language, while another tool may parse it, transform it, simulate it, or execute it. Choosing an implementation still requires checking that tool's supported OpenQASM version and feature coverage.

Inside the specification repository

Based on the repository layout, this is a specification-centered project. The `source/` directory is the documentation source, while `spec_releasenotes/` and `releasenotes/` hold release documentation. The README also names a reference grammar, although it does not give that grammar's exact file path in the presented text.

The `examples/` directory is a substantial part of the practical surface. Its filenames include `adder.qasm`, `qft.qasm`, `qpt.qasm`, `teleport.qasm`, `vqe.qasm`, `qec.qasm`, `rb.qasm`, `rus.qasm`, and several inverse-QFT examples. These names indicate coverage for arithmetic circuits, transforms, teleportation, variational examples, error-correction examples, and repeat-until-success logic. The directory also contains `stdgates.inc`, which can be included by OpenQASM source to supply standard gate definitions.

The README says the repository contains tools for the OpenQASM intermediate representation, but it does not document a standalone command for using those tools. That omission makes the intermediate-representation tooling unsuitable for an assumed one-command workflow. A developer should inspect the relevant source and contributor files before depending on a particular entry point.

Although GitHub identifies Python as the repository's primary language, the presented root files do not define a user-facing Python package or installation metadata. Most visible Python files concern documentation and release work, including `convert2pdf.py`, `convert2svg.py`, and `buildPublishable.sh`. Treating the repository as `pip install openqasm` would therefore be a mistake.

How an OpenQASM 3 circuit is structured

An OpenQASM 3 program begins with a version declaration and may include reusable gate definitions. The README example uses `OPENQASM 3;` followed by `include "stdgates.inc";`. It declares individual qubits and sized quantum arrays, declares classical bit arrays, and reserves classical registers for measurement outcomes.

Operations then follow an imperative sequence. The example resets a qubit, applies `h`, invokes a subroutine named `segment`, updates a bit-array flag, and continues while the integer value of that flag is nonzero. The subroutine receives an ancilla array and a data qubit, measures the ancillas into a bit array, and returns those bits to the caller.

This example shows that OpenQASM 3 is more than a linear sequence of gates. Subroutines have typed-looking declarations, parameters, a return clause, access to qubits, and classical control flow. The control condition depends on measurement results rather than on values computed entirely before execution. That distinction is central to measurement-based and near-term circuit descriptions.

The example is not a complete builder-and-run tutorial. It does not specify hardware calibration, shot count, backend scheduling, error mitigation, or a simulator invocation. Those concerns are outside what the README demonstrates. OpenQASM provides circuit semantics and source structure, while execution details depend on the consuming implementation.

Building the documentation and opening the first example

The README does not provide installation steps for OpenQASM as an application or Python package. It directs users to the live language documentation and points to the `examples/` directory. For local documentation work, the repository's `Makefile` defines an `install` target that installs pinned or constrained documentation dependencies. This builds the documentation toolchain, not a circuit runner.

Run the following command from the repository root. It installs the packages listed in `requirements.txt` while applying `constraints.txt`.

make install

The Makefile routes other targets to `sphinx-build`. Its default behavior invokes the help mode because the file includes a comment saying that `make` without an argument acts as `make help`. The variables `SPHINXOPTS`, `SPHINXBUILD`, `SOURCEDIR`, and `BUILDDIR` control the build configuration, with defaults of `sphinx-build`, `source`, and `build`.

For the first real use of the language, open `examples/stdgates.inc` together with one circuit such as `examples/teleport.qasm`. The include file is important because a circuit can rely on external gate definitions rather than declaring every standard operation itself. This pairing helps a new user distinguish core circuit structure from library-provided gates.

The presented repository does not document an exact command for parsing a `.qasm` file, validating one, or running it. The safe first step is therefore to read the specification and examples, then select a parser from `implementations.md` and confirm its supported version.

Version compatibility and upgrade boundaries

The repository records releases for OpenQASM 3.1.0 on 2024-05-15, 3.0.0 on 2023-08-16, and an earlier 3.0 release on 2020-11-11. It also points to a separate branch for OpenQASM 2.0. This version history signals a real migration concern: a source file carrying an OpenQASM declaration should be checked against the grammar and feature set of the parser that will consume it.

The examples use OpenQASM 3 features such as subroutines, arrays, resets, measurement-driven conditions, and includes. A tool that understands an earlier OpenQASM dialect may not accept all of those constructs. Version labels alone are not enough to establish compatibility, because implementations may also differ in their supported gates, include handling, classical expressions, or extension mechanisms.

Changes to the language are accepted through the project's governance process and documented through release notes. That gives contributors defined places to propose and record changes. It does not mean existing consumers will update without work. Generated parsers, simulators, exporters, validation rules, and saved program fixtures may all need review when moving between language revisions.

The last push to the default `main` branch was on 2026-09-02. The repository is not archived, but the dated releases show that specification changes are not continuous. Users should confirm the exact language version in the source declaration rather than assuming every example reflects the newest published specification.

Apache-2.0 scope and adoption limits

OpenQASM is licensed under Apache License 2.0, and the README directs readers to the repository's `LICENSE` file for details. That license applies to the specification, documentation, examples, and other repository content covered by the project. The presence of that license supports reuse of the language material under its stated terms, but it does not grant access to hardware, proprietary back ends, or third-party services named by an implementation.

The project began as a Qiskit project, according to the README, but its current scope is broader than one SDK. A Qiskit-oriented workflow may be appropriate for some users, while users of another implementation need a parser or exporter that supports the relevant OpenQASM version. The repository's `implementations.md` file is the documented starting point for finding software that implements or supports OpenQASM 3.

OpenQASM is also the wrong tool when the requirement is a runtime rather than a representation. The repository does not provide a hardware connection manager, simulator, shot scheduler, or circuit execution API in the presented material. Those needs require a separate implementation. It is similarly insufficient as a standalone quantum application framework, because the examples describe programs but do not provide an application-level service around them.

OpenQASM compared with a circuit-builder API

The clearest alternative is to construct quantum circuits through a software API that directly exposes objects such as qubits, registers, gates, and measurement operations. In that model, a programmer calls framework methods in Python, and the framework maintains circuit state. OpenQASM instead represents the resulting program as source text governed by a published language specification and reference examples.

This difference affects validation and portability. A builder API can tie programs to the framework's object model and supported backend features. OpenQASM is intended to provide a common textual form, but actual portability still depends on the parser or exporter. A consuming implementation may reject unsupported syntax, map gates differently, or offer only partial support for a feature shown in the specification.

The two approaches can be complementary. An API-based tool can export OpenQASM for interchange, while another tool can import the file for simulation or compilation. OpenQASM becomes less suitable when rapid experimentation through a framework's interactive objects matters more than a portable textual artifact. It is more suitable when the circuit needs to be reviewed, stored, versioned, exchanged, or accepted by multiple kinds of tools.

Editorial conclusion

Adopt the OpenQASM repository when your work requires an implementation-neutral source format, reference examples, grammar material, or intermediate-representation tooling. Do not treat it as an execution engine, SDK, or complete Python package. Check the language specification version, target implementation compatibility, circuit semantics, and included gate definitions before integrating a circuit.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. openqasm/openqasm on GitHub
3. Project website
4. README
5. Releases