QASM TypeScript

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.

New in Version 2.1.0

This release includes several improvements made during the review of the repo by reviewers from the Journal of Open Source Software. These improvements include:

• more examples in documentation
• easier navigation in the documentation
• files like CONTRIBUTING and LICENSE
• fix for the compatibility of the test suite with Windows
• documentation on how to run our benchmarks
• improvements to the README
• etc.

Usage

Import the parse function or parseString function from the package.

import { parseFile, parseString } from 'qasm-ts';

parseFile can be called with a String file path to a .qasm file. It will parse the file and return the abstract syntax tree representation. parseFile can also take 3 optional parameters:

1. version: A number, OpenQASMVersion, or OpenQASMMajorVersion. Specifies whether to use the Qasm 2 or 3 lexer/parser (defaults to version 3).
2. verbose: A Boolean. Whether to return verbose objects that includes an extra key for each node's class name (defaults to false).
3. stringify: A Boolean. Whether to stringify and format the return object (defaults to false).

let ast = parseFile("<file-path>");

parseString should be called with a String of QASM code. It will parse the code and return the abstract syntax tree representation. parseString also takes the same optional arguments as parseFile.

let ast = parseString("<qasm-string>");

The return type for both parseFile and parseString is Array<AstNode>, unless the stringify parameter is true, in which case the return is a String.

The parser is able to recognize and handle 19 distinct types of syntax errors, which are defined and exported in errors.ts. While this is not an advanced semantic or static analysis, it should enable users to basically validate their OpenQASM 2.0 or 3.0 code.

Comprehensive API docs can be found in the docs/ directory, and the docs are hosted online here.

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;

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] ] }
]

To reproduce this output, you could run the following script in the directory where alignment.qasm is located.

import { parseFile } from 'qasm-ts';

const ast = parseFile("./alignment.qasm", 3);

console.log(ast);

To run TypeScript files, you can use any number of compilers, but we recommend ts-node. For more information on ts-node, refer to the docs.

ts-node script.ts

Source code

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

Contributing

To get started contributing to QASM-TS, please see the open issues for a place to start. Alternatively, you are welcome to create any issues which you feel may capture changes, improvements or additions to the package that would be useful. These may be bug reports or enhancement requests. These will be reviewed in a timely manner by a maintainer. If you are able to implement any desired functionality or bug fixes yourself, we also welcome and promise to review any pull requests. Please simply fork the repository and create a branch in your fork with the changes in question. When you create your pull request, make sure to target our repo.

Transpiling

tsc src/*.ts --outDir dist

Installing dependencies

npm install

Run Unit Tests, Conformance Tests

npm test

Run benchmarks

To run benchmarks that compare this package's performance against pre-existing ANTLR and Rust based parsers, see the benchmarking repo and its instructions.

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