12 releases (7 breaking)
0.7.0 | Oct 30, 2024 |
---|---|
0.6.0 | May 3, 2024 |
0.5.0 | Mar 26, 2024 |
0.4.0 | Mar 1, 2024 |
0.0.7 | Jan 31, 2024 |
#1464 in Parser implementations
8,201 downloads per month
635KB
15K
SLoC
OpenQASM 3 Parser
This project provides a compiler front end for OpenQASM 3 language (OQ3).
In this document, this parser is referred to as openqasm3_parser
.
Why is this important?
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_parser
is much more performant. A crude test with large source files showed parse time reduced by a factor of 80. openqasm3_parser
performs semantic analysis. In particular diagnostics and error reporting are much better.
Contributing
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.
Crates (roughly one installable library per crate)
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_lexer
and outputs a concrete syntax tree. - oq3_syntax -- Ingests output of
oq3_parser
and 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.
Warning !
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.
Using this front end
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.qasm
Replace scratch1.qasm
with some file found in ./crates/oq3_semantics/examples/qasm/.
Search path
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.
Design
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
Notes
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 <bors@rust-lang.org>
Date: Wed Aug 2 14:28:41 2023 +0000
Auto merge of #15380 - HKalbasi:mir, r=HKalbasi
Fix unsized struct problems in mir eval
Dependencies
~5.5MB
~103K SLoC