diff --git a/Makefile b/Makefile index ad3a535e..1960a790 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,23 @@ +UNAME_S := $(shell uname -s) + +# Default target on Linux +ifeq ($(UNAME_S), Linux) +RELEASE_TARGET := build-g++ +DEBUG_TARGET := debug-g++ +endif + +# Default target on macOS (Darwin) +ifeq ($(UNAME_S), Darwin) +RELEASE_TARGET := build-clang++ +DEBUG_TARGET := debug-clang++ +endif + all: build -build: - cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=1 -DCMAKE_BUILD_TYPE=Release +build: $(RELEASE_TARGET) + +build-g++: + cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=1 -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=$(shell which g++) $(MAKE) -C build # force macos to use the clang++ installed by brew instead of the default one @@ -14,8 +30,10 @@ build-clang++: build-docker: docker build -f docker/dev.Dockerfile -t qsyn-local . -debug: - cmake -S . -B debug -DCMAKE_EXPORT_COMPILE_COMMANDS=1 -DCMAKE_BUILD_TYPE=Debug +debug: $(DEBUG_TARGET) + +debug-g++: + cmake -S . -B debug -DCMAKE_EXPORT_COMPILE_COMMANDS=1 -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_COMPILER=$(shell which g++) $(MAKE) -C debug # force macos to use the clang++ installed by brew instead of the default one @@ -54,9 +72,13 @@ clean: rm -rf build rm -f qsyn +clean-debug: + rm -rf debug + rm -f qsyn-debug + clean-docker: docker container prune -f docker rmi qsyn-test-gcc -f docker rmi qsyn-test-clang -f -.PHONY: all build build-clang++ debug debug-clang++ test test-docker test-update lint publish clean clean-docker +.PHONY: all build build-g++ build-clang++ debug debug-g++ debug-clang++ test test-docker test-update lint publish clean clean-debug clean-docker diff --git a/README.md b/README.md index a93a5b13..82559d03 100644 --- a/README.md +++ b/README.md @@ -10,24 +10,24 @@ ![](https://i.imgur.com/wKg5cQO.jpg) - + ## Overview Qsyn is a developer-friendly `C++`-based Quantum Circuit Compilation framework to aid further development in this field. The main contributions of Qsyn are: -* Providing a unified and user-friendly developing environment so researchers and developers can efficiently prototype, implement, and thoroughly evaluate their QCS algorithms with standardized tools, language, and data structures. -* Assisting the developers with a robust and intuitive interface that can access low-level data directly to provide developers with unique insights into the behavior of their algorithms during runtime. -* Inforcing robust quality-assurance practices, such as regression tests, continuous integration-and-continuous delivery (CI/CD) flows, linting, etc. These methodologies ensure that we provide reliable and efficient functionalities and that new features adhere to the same quality we strive for. +- Providing a unified and user-friendly developing environment so researchers and developers can efficiently prototype, implement, and thoroughly evaluate their QCS algorithms with standardized tools, language, and data structures. +- Assisting the developers with a robust and intuitive interface that can access low-level data directly to provide developers with unique insights into the behavior of their algorithms during runtime. +- Inforcing robust quality-assurance practices, such as regression tests, continuous integration-and-continuous delivery (CI/CD) flows, linting, etc. These methodologies ensure that we provide reliable and efficient functionalities and that new features adhere to the same quality we strive for. ![](https://i.imgur.com/DjqGlU5.png) Some of the future work for Qsyn includes: -* Improving high-level synthesis: A well-designed high-level synthesis algorithm can yield efficient high-level circuits and adapt to the qubit resource constraint, simplifying the subsequent synthesis steps. -* More flexible gate-level synthesis: We aim to optimize multiple metrics simultaneously and characterize the trade-off between them. Device-aware synthesis strategies are also promising for further compacting the resulting circuits. -* Beyond NISQ devices: Fault-tolerant quantum architectures require decomposing the Clifford+T gate set and introducing new Clifford gate models. Distributed devices are also a common theme for realizing quantum advantage, necessitating -algorithms targeting specifically for these devices. + +- Improving high-level synthesis: A well-designed high-level synthesis algorithm can yield efficient high-level circuits and adapt to the qubit resource constraint, simplifying the subsequent synthesis steps. +- More flexible gate-level synthesis: We aim to optimize multiple metrics simultaneously and characterize the trade-off between them. Device-aware synthesis strategies are also promising for further compacting the resulting circuits. +- Beyond NISQ devices: Fault-tolerant quantum architectures require decomposing the Clifford+T gate set and introducing new Clifford gate models. Distributed devices are also a common theme for realizing quantum advantage, necessitating + algorithms targeting specifically for these devices. ## Getting Started @@ -39,19 +39,21 @@ algorithms targeting specifically for these devices. Clone the repository to your local machine by running -```shell! +```sh git clone https://github.com/DVLab-NTU/qsyn.git cd qsyn ``` Then, follow the instructions below to install the dependencies and build `qsyn`. -Or you can try out `qsyn` in a containerized environment by running +Alternatively, you can try out `qsyn` in a containerized environment by running -```shell! +```sh docker run -it --rm dvlab/qsyn:latest ``` +if you have Docker installed on your machine. + ### Optional Dependencies for Visualization Visualization functionalities of `qsyn` depend at runtime on the following dependencies. Please refer to the linked pages for installation instructions of these dependencies: @@ -67,58 +69,83 @@ Visualization functionalities of `qsyn` depend at runtime on the following depen ### Compilation -`qsyn` uses CMake to manage the build process. To build `qsyn`, follow the instructions below: +To build `qsyn`, follow the instructions below: -1. Run `cmake` to build dependencies and generate Makefiles, if this step fails, you might have to install external dependencies `blas`, `lapack` or `xtensor` yourself. +
+For Linux Users + +You'll probably need to install `OpenBLAS` and `LAPACK` libraries. For Ubuntu, you can install them by running + +```sh +sudo apt install libopenblas-dev +sudo apt install liblapack-dev +``` - ```sh - cmake -B build -S . - ``` +If you are tech-savvy enough to be using a different Linux distribution, we're confident that you can figure out how to install these libraries 😉 - **Note for Mac Users:** Since we use some C++20 features that are not yet supported by Apple Clang, you'll need to install another compiler yourself. We recommend installing the `llvm` toolchain with `clang++` by running +Then, run the following commands to build `qsyn`: - ```sh - brew install llvm - ``` +```sh +make -j8 +``` - Then, run the following command to force `cmake` to use the new `clang++` you installed. +which triggers our suggested CMake build process. Alternatively, use `make build-g++` or `make build-clang++` to manually specify the compiler. - ```sh - cmake -DCMAKE_CXX_COMPILER=$(which clang++) -B build -S . - ``` +
-2. Build the executable. You would want to crank up the number of threads to speed up the compilation process: +
+For MacOS Users + +Since Qsyn uses some C++20 features that are not yet supported by Apple Clang, you'll need to install another compiler yourself. We recommend installing the `llvm` toolchain with the `brew` package manager. +```sh +brew install llvm +``` - ```sh - cmake --build build -j 8 - ``` +After installation, `brew` will guide you to configure your environment to use LLVM `clang++` and its associated libraries. - You can now execute `qsyn` by running +You would probably want to install `OpenBLAS` by running - ```sh - ./qsyn - ``` +```sh +brew install openblas +``` - You can also build `qsyn` in a containerized environment by running +Finally, run the following commands to build `qsyn`: - ```sh - make build-docker - ``` +```sh +make -j8 +``` - And run that executable by running +which triggers our suggested CMake build process. Alternatively, use `make build-g++` or `make build-clang++` to manually specify the compiler. - ```sh - make run-docker - ``` +
+ +
+Docker Builds + +You can also build `qsyn` in a containerized environment by running + +```sh +make build-docker +``` + +And run that executable by running + +```sh +make run-docker +``` + +Of course, this requires you to have Docker installed on your machine. + +
### Run -- After successful compilation, open the command-line interface of `qsyn` by running +- After successful compilation, run `./qsyn` and enter Qsyn's command-line interface: ```sh - ❯ ./qsyn + ./qsyn qsyn v0.7.0 - Copyright © 2022-2024, DVLab NTUEE. - Licensed under Apache 2.0 License. + Licensed under Apache 2.0 License. Release build. qsyn> ``` @@ -128,25 +155,26 @@ Visualization functionalities of `qsyn` depend at runtime on the following depen qsyn> help ``` -- To see the help message of a specific command, type ` -h` or ` --help`. +- To see the help message of a specific command, type ` -h` or ` --help`. ```sh qsyn> qcir read -h ``` -- You can also let `qsyn` to execute a sequence of commands by passing a DOFILE to `qsyn`: +- You can also let `qsyn` to execute a sequence of commands by passing a script to `qsyn`: ```sh - ❯ ./qsyn -v examples/synth.dof - qsyn v0.7.0 - DVLab NTUEE. - Licensed under Apache 2.0 License. - qsyn> qcir read benchmark/zx/tof3.zx + ./qsyn -v examples/synth.dof + qsyn v0.7.0 - Copyright © 2022-2024, DVLab NTUEE. + Licensed under Apache 2.0 License. Release build. + qsyn> qcir read benchmark/SABRE/large/adr4_197.qasm + # further executing commands... ``` - Some example DOFILEs are provided under `examples/`. You can also write your own DOFILEs to automate your workflow. + Some example scripts are provided under `examples/`. You can also write your own scripts to automate your workflow. - `qsyn` also supports reading commands from scripts. For example, we also provided a ZX-calculus-based optimization flow - by executing the following script in the project folder examples/zxopt.qsyn . + by executing the following script in the project folder `examples/zxopt.qsyn`: ```sh //!ARGS INPUT @@ -162,13 +190,14 @@ Visualization functionalities of `qsyn` depend at runtime on the following depen ``` To run the commands in the above file, supply the script’s file path and arguments after ./qsyn : - + ```sh - ❯ ./qsyn examples/zxopt.qsyn \ benchmark/SABRE/large/adr4_197.qasm + ./qsyn examples/zxopt.qsyn benchmark/SABRE/large/adr4_197.qasm ``` - This runs the ZX-calculus-based synthesis on the circuit in benchmark/SABRE/large/adr4_197.qasm. -- If you're new to `qsyn`, you will be prompted to run the command `create-qsynrc` to create a configuration file for `qsyn`. This file will be stored under `~/.config/qsynrc` and can be used to store your aliases, variables, etc. + This runs the ZX-calculus-based synthesis on the circuit in `benchmark/SABRE/large/adr4_197.qasm`. + +- If you're using `qsyn` for the first time, a config file will be created under `~/.config/qsynrc` and can be used to store your aliases, variables, etc. If you lost this file, you can use the command `create-qsynrc` to recreate it. - For more options, please refer to the help message of `qsyn` by running @@ -178,21 +207,21 @@ Visualization functionalities of `qsyn` depend at runtime on the following depen ### Testing -We have provided some DOFILEs, i.e., a sequence of commands, to serve as functionality checks as well as demonstration of use. DOFILEs are Located under `tests/
//dof/`. +We have provided some test scripts as integrated tests as well as demonstration of use. These scripts are Located under `tests/
//dof/`. -- To run a DOFILE and compare the result to the reference, type +- To run a test script and compare the result to the reference, type ```sh ./scripts/RUN_TESTS -d ``` -- To update the reference to a dofile, type +- To update the reference to a test script, type ```sh ./scripts/RUN_TESTS -u ``` -- You may also run all DOFILEs by running +- You may also run all test scripts by running ```sh make test @@ -204,85 +233,86 @@ We have provided some DOFILEs, i.e., a sequence of commands, to serve as functio make test-docker ``` - Notice that if you use a different BLAS or LAPACK implementation to build `qsyn`, some of the DOFILEs may produce different results, which is expected. + Notice that if you use a different BLAS or LAPACK implementation to build `qsyn`, be expect that some of the test scripts may produce different results. ## Functionalities ### Software architecture - The core interaction with `qsyn` is facilitated through its command-line interface (CLI), which processes user input, handles command execution, and manages error reporting. Developers can add additional commands and integrate into the CLI. New strategy can be added without compromising to existing data structure, as all modifications are funneled through well-defined public interfaces. +The core interaction with `qsyn` is facilitated through its command-line interface (CLI), which processes user input, handles command execution, and manages error reporting. Developers can add additional commands and integrate into the CLI. New strategy can be added without compromising to existing data structure, as all modifications are funneled through well-defined public interfaces. - `qsyn` supports real time storage of multiple quantum circuits and intermediate representations by the `
` checkout command. Users can take snapshots at any time in the synthesis process and switch to an arbitrary version of stored data. +`qsyn` supports real time storage of multiple quantum circuits and intermediate representations by the `
` checkout command. Users can take snapshots at any time in the synthesis process and switch to an arbitrary version of stored data. - This architecture is central to qsyn’s flexibility and extensibility. It segregates responsibilities and simplifies command implementations while enhancing its capability as a research tool in quantum circuit synthesis. +This architecture is central to qsyn’s flexibility and extensibility. It segregates responsibilities and simplifies command implementations while enhancing its capability as a research tool in quantum circuit synthesis. ### High-level Synthesis - - `qsyn` can process various specifications for quantum circuits by supporting syntheses from Boolean oracles and unitary matrices. - | Command | Description | - | :----- | :---- | - | qcir oracle | ROS Boolean oracle synthesis flow | - | convert ts qc | Gray-code unitary matrix synthesis | +`qsyn` can process various specifications for quantum circuits by supporting syntheses from Boolean oracles and unitary matrices. + +| Command | Description | +| :------------ | :--------------------------------- | +| qcir oracle | ROS Boolean oracle synthesis flow | +| convert ts qc | Gray-code unitary matrix synthesis | ### Gate-level Synthesis - `qsyn` also adapt to different optimization targets by providing different routes to synthesize low-level quantum circuits. + +`qsyn` also adapt to different optimization targets by providing different routes to synthesize low-level quantum circuits. #### Via ZX-calculus - | Command | Description | - | :----- | :---- | - | qzq | ZX-calculus-based synth routine | - | convert qc zx | convert quantum circuit to ZX-diagram | - | zx opt | fully reduce ZX diagram | - | convert zx qc | convert ZX-diagram to quantum circuit | - | qc opt | basic optimization passes | + +| Command | Description | +| :------------ | :------------------------------------ | +| qzq | ZX-calculus-based synth routine | +| convert qc zx | convert quantum circuit to ZX-diagram | +| zx opt | fully reduce ZX diagram | +| convert zx qc | convert ZX-diagram to quantum circuit | +| qc opt | basic optimization passes | #### Via Tableau - | Command | Description | - | :----- | :---- | - | qtablq | tableau-based synth routine | - | convert qc tabl | convert quantum circuit to tableau | - | tabl opt full | iteratively apply the following three | - | tabl opt tmerge | phase-merging optimization | - | tabl opt hopt | internal H-gate optimization | - | tabl opt ph todd | TODD optimization | - | convert tabl qc | convert tableau to quantum circuit | + +| Command | Description | +| :--------------- | :------------------------------------ | +| qtablq | tableau-based synth routine | +| convert qc tabl | convert quantum circuit to tableau | +| tabl opt full | iteratively apply the following three | +| tabl opt tmerge | phase-merging optimization | +| tabl opt hopt | internal H-gate optimization | +| tabl opt ph todd | TODD optimization | +| convert tabl qc | convert tableau to quantum circuit | ### Device Mapping - `qsyn` can target a wide variety of quantum devices by addressing their available gate sets and topological constraints. - | Command | Description | - | :----- | :---- | - | device read | read info about a quantum device | - | qc translate | library-based technology mapping | - | qc opt -t | technology-aware optimization passes | - | duostra | Duostra qubit mapping for depth or #SWAPs | +`qsyn` can target a wide variety of quantum devices by addressing their available gate sets and topological constraints. +| Command | Description | +| :----- | :---- | +| device read | read info about a quantum device | +| qc translate | library-based technology mapping | +| qc opt -t | technology-aware optimization passes | +| duostra | Duostra qubit mapping for depth or #SWAPs | ### Data Access and Utilities - `qsyn` provides various data representations for quantum logic. `
` stands for any data representation type, including quantum circuits, ZX diagrams, Tableau, etc. - | Command | Description | - | :----- | :---- | - | `
` list | list all `
`s | - | `
` checkout | switch focus between `
`s | - | `
` print | print `
` information | - | `
` | add a new/delete a `
` | - | `
` | read and write `
` | - | `
` equiv | verify equivalence of two `
`s | - | `
` draw | render visualization of `
` | - | convert `` `` | convert from `` to `` | - - There are also some extra utilities: - | Command | Description | - | :----- | :---- | - | alias | set or unset aliases | - | help | display helps to commands | - | history | show or export command history | - | logger | control log levels | - | set | set or unset variables | - | usage | show time/memory usage | - - +`qsyn` provides various data representations for quantum logic. `
` stands for any data representation type, including quantum circuits, ZX diagrams, Tableau, etc. +| Command | Description | +| :----- | :---- | +| `
` list | list all `
`s | +| `
` checkout | switch focus between `
`s | + | `
` print | print `
` information | +| `
` | add a new/delete a `
` | +| `
` | read and write `
` | +| `
` equiv | verify equivalence of two `
`s | +| `
` draw | render visualization of `
` | +| convert `` `` | convert from `` to `` | + +There are also some extra utilities: +| Command | Description | +| :----- | :---- | +| alias | set or unset aliases | +| help | display helps to commands | +| history | show or export command history | +| logger | control log levels | +| set | set or unset variables | +| usage | show time/memory usage | ## License @@ -290,4 +320,15 @@ We have provided some DOFILEs, i.e., a sequence of commands, to serve as functio [Apache License 2.0](https://github.com/DVLab-NTU/qsyn/blob/main/LICENSE). Certain functions of `qsyn` is enabled by a series of third-party libraries. For a list of these libraries, as well as their license information, please refer to [this document](/vendor/README.md). - + +## Reference +If you are using Qsyn for your research, it will be greatly appreciated if you cite this publication: + +``` +@misc{Lau_Qsyn_2024, +Author = {Mu-Te Lau and Chin-Yi Cheng and Cheng-Hua Lu and Chia-Hsu Chuang and Yi-Hsiang Kuo and Hsiang-Chun Yang and Chien-Tung Kuo and Hsin-Yu Chen and Chen-Ying Tung and Cheng-En Tsai and Guan-Hao Chen and Leng-Kai Lin and Ching-Huan Wang and Tzu-Hsu Wang and Chung-Yang Ric Huang}, +Title = {Qsyn: A Developer-Friendly Quantum Circuit Synthesis Framework for NISQ Era and Beyond}, +Year = {2024}, +Eprint = {arXiv:2405.07197}, +} +```