This project provides a compiler front end for OpenQASM 3 language (OQ3).
In this document, this parser is referred to as openqasm3_parser.
There is a lot of interest in using OpenQASM 3 for a number of purposes. For example, for controlling hardware and as an exchange medium for quantum circuits. This project aims to provide a performant, robust front end to compilers and importers. There are no other open source (or public) projects of this kind.
Differences with the OpenQASM reference parser include
- The parser in
openqasm3_parseris much more performant. A crude test with large source files showed parse time reduced by a factor of 80. openqasm3_parserperforms semantic analysis. In particular diagnostics and error reporting are much better.
If you are interested in contributing, browsing the issues is a good place to start. Some of the issues are tagged with the label "Looking for assignee". Issues with the tag include a bit more context than some other issues in order to guide a newcomer. Also, the core developers are not planning on working on these issues in the immediate future. However, this does not mean you can't tackle an issue without this tag if it is a better fit.
There are a few more tips in CONTRIBUTING.md, as well as some later in this README.
The first three crates are based on tools for rust and rust-analyzer.
- oq3_lexer -- A lightly modified version of the
rustc(the rust compiler) lexer. - oq3_parser -- Ingests output of
oq3_lexerand outputs a concrete syntax tree. - oq3_syntax -- Ingests output of
oq3_parserand outputs an abstract syntax tree (AST). The rust-analyzer documentation sometimes refers to this AST by something like "typed AST". This can be confusing. It does not mean that semantic analysis has been performed and OQ3 types have been assigned to all expressions. It means that the rust type system is used to encode syntactic elements, in contrast to some lower representations in the same crate. - oq3_semantics -- Performs semantic analysis and outputs an abstract semantic graph (ASG) There are other names for this structure. But "ASG" is convenient.
- oq3_source_file -- A higher-level interface to the syntactic AST. This sits beetween the syntactic AST and semantic ASG. This crate manages the main source file and incuded source files.
What is a rust "crate"
We talk about rust "crates". A rust library crate is more or less the source for a rust library that is developed, built, and installed with the rust package manager cargo. This single repository contains more than one separately installable crates. In the future, this repository may also be used to generate other artifacts.
Do not run cargo test. Rather use ./run_tests.sh or commands found therein. This is because codegen is implemented via
the test system (you read correctly). If possible, we plan to change this to a more conventional approach.
A reminder: A front end is not of much use unless you have a back end. Examples showing the entry points and how to use them, can be found in ./crates/oq3_semantics/examples/semdemo.rs.
shell> export QASM3_PATH=./crates/semantics/examples/qasm/
shell> cargo run --example semdemo -- semantic scratch1.qasmReplace scratch1.qasm with some file found in ./crates/oq3_semantics/examples/qasm/.
The environment variable QASM_PATH is a colon separated list of paths. Note that the name follows the venerable unix tradition of
ending in PATH rather than PATHS. The code that retrives the paths uses routines std::path which may actually handle
path specifications on other platforms.
Code from rust-analyzer has been borrowed and modified for the lower levels of parsing. The developer documents for rust-analyzer are very relevant as the structure has not been changed in adapting to OQ3.
- Syntax
- Red/Green trees taken from the C# parser.
- Pratt parsing
Some of this code is modified from code found in rust-analyzer. It was taken at this commit:
commit d398ad3326780598bbf1480014f4c59fbf6461a7
Merge: 2f2cf21da 6990d0f26
Author: bors <[email protected]>
Date: Wed Aug 2 14:28:41 2023 +0000
Auto merge of #15380 - HKalbasi:mir, r=HKalbasi
Fix unsized struct problems in mir eval