QASM2 Parser

This project is a QASM2 (Quantum Assembly Language 2) parser implemented using ANTLR4 for lexing and parsing. This parser follow the standard grammer and syntax from orignal Open Quantum Assembly Language.

The parser translates QASM2 code into an Abstract Syntax Tree (AST) for further processing. This parser includes the external source file or standard header such as qelib1.inc.

Getting Started

Prerequisites

CMake 3.5 or higher
Java 11 or higher
C++ compiler supporting C++14
Universally Unique IDs (uuid-dev)
```
sudo apt-get install uuid-dev
```

Building the project

Clone the repository:

git clone <repository-url>
cd qasm2-parser

Generate the build files using CMake:
```
mkdir build
cd build
cmake ..
```
Highly recommend using Ninja Build for compilation speed up
Build the project:
```
make
```
Run the Parser:
```
./run_qasm2 <path-to-qasm-file>
```
Run Test
```
./run_test
```

Project structure

.
├── cmake
│   └── ExternalAntlr4Cpp.cmake   # CMake script to handle external ANTLR4 dependencies
├── CMakeLists.txt                # CMake configuration file
├── gen_files.sh                  # Script to generate file_contents.txt
├── grammar
│   ├── QASM2Lexer.g4             # ANTLR4 grammar for QASM2 lexer
│   └── QASM2Parser.g4            # ANTLR4 grammar for QASM2 parser
├── main.cpp                      # Main entry point for the QASM2 parser
├── README.md                     # Project documentation
├── src
│   ├── include
│   │   ├── AST.h                 # Header for Abstract Syntax Tree
│   │   ├── Expr.h                # Header for expressions
│   │   ├── Register.h            # Header for quantum register
│   │   ├── SymbolTable.h         # Header for symbol table
│   │   └── Visitor.h             # Header for visitor pattern
│   └── lib
│       ├── AST.cpp               # Implementation of AST
│       ├── Expr.cpp              # Implementation of expressions
│       ├── Register.cpp          # Implementation of quantum register
│       ├── SymbolTable.cpp       # Implementation of symbol table
│       └── Visitor.cpp           # Implementation of visitor pattern
└── thirdparty
    ├── antlr
    │   └── antlr-4.7-complete.jar # ANTLR4 tool
    └── qplayer                    # QPlayer integration

AST usage

AST nodes are generated by walking through the parse tree. program is QASMNode that obtains the statement nodes. You can traverse that statements for furture process such code generation or execution.

...
    QASM2Visitor visitor;
    visitor.visit(tree);
    auto program = visitor.getProgram();
...

While traverse the parse tree, it performs semantic analysis to generate Symbol Table. All registers (Qubit and CBit) and user-defined gates are stored in Symbol Table. The user-defined gates is the gate that user defines or it's may from qelib1.inc.

    auto gateDefines = visitor.getSymbolTable().gateDefines;
    auto regDefines = visitor.getSymbolTable().qubitRegisters;
    auto cregDefines = visitor.getSymbolTable().cbitRegisters;

Example of link with simulator

We will support simulator as backend to execute circuit. This shows how QPlayer built with our parser.

Example of link library with QPlayer

Clone simulator

cd ./thirdparty
git clone https://github.com/eQuantumOS/QPlayer.git qplayer

Include the qplayer in main.cpp

#include <antlr4-runtime.h>
#include "QASM2Parser.h"
#include "QASM2Lexer.h"
#include "Visitor.h"
#include "AST.h"

#include "qplayer.h"
. . .
int main(int argc, const char* argv[]) {

    // Create one of QRegister from QPlayer
    QRegister QReg = new QRegister(12);
    cout << "QReg: " << QReg.getNumQubits() << endl;
    . . . 
}

Build with QPlayer

cd ../build
cmake .. -DBUILD_QPLAYER=ON 
make;

Run the Parser

./run_qasm2 ../test/circuits/adder_n4_cus.qasm

expected result

QReg: 12
...

For more details on link the library to used in here, check in CMakeLists.txt

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

ANTLR4

For more details on the usage and contribution guidelines, refer to the CONTRIBUTING.md file.

QCL-PKNU/QASM2-Parser