QASM TypeScript Documentation

OpenQASM, the low-level programming language for quantum circuit specification, implemented in TypeScript.

QASM-TS 2.0 is an implementation of a compiler frontend for OpenQASM 2.0 and 3.0. It includes a lexer and a parser of the OpenQASM language. The source is parsed into an Intermediate Representation (IR): an Abstract Syntax Tree (AST) that captures program structure including control flow and data flow.

The package is aimed at enabling implementations of verification and validation software (such as semantic and static analyzers), compilers and more. These tools may be instrumental in the formalization of hybrid quantum-classical computing.

Language documentation is provided by IBM here.

Quick Start

Installation

npm install qasm-ts
Copy

Basic Usage

Parse from an OpenQASM string snippet:

import { parseString } from "qasm-ts";

const qasmCode = `
OPENQASM 3.0;
include "stdgates.inc";
qubit[2] q;
h q[0];
cx q[0], q[1];
`;

const ast = parseString(qasmCode);
Copy

Parse from an OpenQASM file:

import { parseFile } from "qasm-ts";

const ast = parseFile("./my-circuit.qasm");

// Specify OpenQASM version explicitly
const ast2 = parseFile("./legacy-circuit.qasm", 2); // OpenQASM 2.0
const ast3 = parseFile("./modern-circuit.qasm", 3); // OpenQASM 3.0
Copy

Working with the AST

// Get verbose output with class names
const verboseAst = parseString(qasmCode, 3, true);

// Get stringified JSON output
const jsonAst = parseString(qasmCode, 3, false, true);

// Both verbose and stringified
const verboseJsonAst = parseString(qasmCode, 3, true, true);
Copy

Example I/O

Input: alignment.qasm (source)

include "stdgates.inc";

stretch g;

qubit[3] q;
barrier q;
cx q[0], q[1];
delay[g] q[2];
U(pi/4, 0, pi/2) q[2];
delay[2*g] q[2];
barrier q;

Copy

Output: Abstract Syntax Tree

[
  Include { filename: '"stdgates.inc"' },
  ClassicalDeclaration {
    classicalType: StretchType {},
    identifier: Identifier { name: 'g' },
    initializer: null,
    isConst: false
  },
  QuantumDeclaration {
    identifier: Identifier { name: 'q' },
    size: IntegerLiteral { value: 3 }
  },
  QuantumBarrier { qubits: [ [Identifier] ] },
  QuantumGateCall {
    quantumGateName: Identifier { name: 'cx' },
    qubits: [ [SubscriptedIdentifier], [SubscriptedIdentifier] ],
    parameters: null,
    modifiers: []
  },
  QuantumDelay {
    duration: Identifier { name: 'g' },
    qubits: [ [SubscriptedIdentifier] ]
  },
  QuantumGateCall {
    quantumGateName: Identifier { name: 'U' },
    qubits: [ [SubscriptedIdentifier] ],
    parameters: Parameters { args: [Array] },
    modifiers: []
  },
  QuantumDelay {
    duration: Arithmetic { op: '*', left: [IntegerLiteral], right: [Identifier] },
    qubits: [ [SubscriptedIdentifier] ]
  },
  QuantumBarrier { qubits: [ [Identifier] ] }
]
Copy

API Documentation Navigation

Core Functions

Start here for the main parsing functions:

• parseString - Parse OpenQASM code from a string
• parseFile - Parse OpenQASM code from a file

Tokenization

Understand the tokenization process and available token types:

• OpenQASM 3.0 Tokens - Modern OpenQASM token set
• OpenQASM 2.0 Tokens - Legacy OpenQASM token set

Lexing

Understand the Lexer:

• OpenQASM 3.0 Lexer - Modern OpenQASM lexer
• OpenQASM 2.0 Lexer - Legacy OpenQASM lexer

AST Structure

Understand the abstract syntax tree nodes:

• OpenQASM 3.0 AST Nodes - Modern OpenQASM syntax tree
• OpenQASM 2.0 AST Nodes - Legacy OpenQASM syntax tree

Parsing

Understand the Parser:

• OpenQASM 3.0 Parser - Modern OpenQASM parser
• OpenQASM 2.0 Parser - Legacy OpenQASM parser

Utilities and Internals

• Error Handling - All error types and their usage
• Version Management - Version detection and handling

Navigate using the sidebar or search functionality to find specific functions and classes.

New In Version 2.0.0

• Support for the OpenQASM 3.0 spec while retaining OpenQASM 2.0 backwards compatibility.

Source Code

Feel free to clone, fork, comment or contribute on GitHub!

References

The original OpenQASM authors:

• Andrew W. Cross, Lev S. Bishop, John A. Smolin, Jay M. Gambetta "Open Quantum Assembly Language" arXiv:1707.03429
• Andrew W. Cross, Ali Javadi-Abhari, Thomas Alexander, Niel de Beaudrap, Lev S. Bishop, Steven Heidel, Colm A. Ryan, Prasahnt Sivarajah, John Smolin, Jay M. Gambetta, Blake R. Johnson "OpenQASM 3: A broader and deeper quantum assembly language" arXiv:2104.14722

Another strongly typed implementation from which this project took some inspiration:

• Adam Kelly's Rust QASM Parser

License

Copyright 2019 Marcus Edwards

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at:

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

How to Cite

If you are using QASM-TS for research we appreciate any citations. Please read and cite our paper published with the Journal of Open Source Software.

@article{Kim[2025,
  doi = {10.21105/joss.08696},
  url = {https://doi.org/10.21105/joss.08696},
  year = {2025},
  publisher = {The Open Journal},
  volume = {10},
  number = {113},
  pages = {8696},
  author = {Kim[, Sean and Edwards[, Marcus},
  title = {Enabling the Verification and Formalization of Hybrid Quantum-Classical Computing with OpenQASM 3.0 compatible QASM-TS 2.0},
  journal = {Journal of Open Source Software}
}
 
Copy