From a8b9bf677db73603a69c7fad96eaed0ba42c6fde Mon Sep 17 00:00:00 2001 From: Stefan Hillmich Date: Tue, 23 Jun 2020 12:06:39 +0200 Subject: [PATCH] Updated README.md and made Boost optional - Updated README.md to be more helpful to new users (feedback welcome) - Made Boost ProgramOptions optional (now only required to build the standalone executable) --- README.md | 96 ++++++++++++++++++++++++++------------------- apps/CMakeLists.txt | 19 ++++----- 2 files changed, 66 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 2cc2e523..8a788023 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![codecov](https://codecov.io/gh/iic-jku/ddsim/branch/master/graph/badge.svg)](https://codecov.io/gh/iic-jku/ddsim) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -# DDSIM - A quantum simulator based on decision diagrams written in C++ +# JKQ-DDSIM - A quantum simulator based on decision diagrams written in C++ A tool for quantum circuit simulation by the [Institute for Integrated Circuits](http://iic.jku.at/eda/) at the [Johannes Kepler University Linz](https://jku.at). @@ -12,30 +12,53 @@ The tool builds upon [our quantum functionality representation (QFR)](https://gi For more information, please visit [iic.jku.at/eda/research/quantum_simulation](http://iic.jku.at/eda/research/quantum_simulation). -If you have any questions, feel free to contact us via [iic_quantum@jku.at](mailto:iic_quantum@jku.at) or by creating an issue on GitHub. +If you have any questions, feel free to contact us via [iic-quantum@jku.at](mailto:iic-quantum@jku.at) or by creating an [issue](https://github.com/iic-jku/ddsim/issues) on GitHub. ## Usage This tool can be used for simulating quantum circuits provided in any of the following formats: -* `Real` from [RevLib](http://revlib.org), -* `OpenQASM` used by IBM's [Qiskit](https://github.com/Qiskit/qiskit) (currently, we do not support intermediate measurements!), -* `GRCS` as available on https://github.com/sboixo/GRCS +* `Real` from [RevLib](http://revlib.org/documentation.php) + * [Our set of circuits](https://github.com/iic-jku/quantum_circuits) + * [RevLib](http://revlib.org) +* `OpenQASM` used by IBM's [Qiskit](https://github.com/Qiskit/qiskit) + * [Our set of circuits](https://github.com/iic-jku/quantum_circuits) + * [OpenQASM Repo](https://github.com/Qiskit/openqasm) + * [QUEKO](https://github.com/tbcdebug/QUEKO-benchmark) (focus on mapping though) +* `GRCS` + * [GRCS Repo](https://github.com/sboixo/GRCS) + + The format is automatically detected through the file extension. The following additional algorithms are integrated in [QFR](https://github.com/iic-jku/qfr.git) and hence available in the simulator as well: * Quantum Fourier Transformation -* Grover's search +* Bernstein-Vazirani +* GHZ / Entanglement +* Grover's search (see `--help` for different call options) For details on the available methods we refer to [iic.jku.at/eda/research/quantum_simulation](http://iic.jku.at/eda/research/quantum_simulation). It can either be used as a **standalone executable** with command-line interface, or as a **library** for the incorporation in other projects. - The standalone executable is launched in the following way, showing available options: ```commandline - ddsim_simple --help + $ ./ddsim_simple --help + DDSIM by http://iic.jku.at/eda/ -- Allowed options: + -h [ --help ] produce help message + --seed arg (=0) seed for random number generator (default zero is directly used as seed!) + --simulate_file arg simulate a quantum circuit given by file (detection by the file extension) + --simulate_qft arg simulate Quantum Fourier Transform for given number of qubits + --simulate_grover arg simulate Grover's search for given number of qubits with random oracle + --simulate_grover_emulated arg simulate Grover's search for given number of qubits with random oracle and emulation + --simulate_grover_oracle_emulated arg simulate Grover's search for given number of qubits with given oracle and emulation + --simulate_ghz arg simulate state preparation of GHZ state for given number of qubits + --shots arg (=0) number of measurements on the final quantum state + --display_vector display the state vector + --ps print simulation stats (applied gates, sim. time, and maximal size of the DD) + --benchmark print simulation stats in a single CSV style line (overrides --ps and suppresses most other output) ``` -- The library can be used by including, for example, the```SimpleSimulator.hpp``` header file and +- The library can be used by including, for example, the```QFRSimulator.hpp``` header file and ```c++ std::string file1 = "PATH_TO_FILE_1.EXT"; qc::QuantumComputation qc1(file1); @@ -56,14 +79,15 @@ However, the implementation should be compatible with any current C++ compiler s ### Build and Run For building the library alone the CMake target `ddsim` is available, i.e., ```commandline -mkdir build && cd build -cmake .. -DCMAKE_BUILD_TYPE=Release -cmake --build . --config Release --target ddsim +$ cmake -DCMAKE_BUILD_TYPE=Release -S . -B build +$ cmake --build build --config Release --target ddsim ``` Windows users need to configure CMake by calling -`cmake .. -G "Visual Studio 15 2017" -A x64 -DCMAKE_BUILD_TYPE=Release` +```commandline +$ cmake -G "Visual Studio 15 2017" -A x64 -DCMAKE_BUILD_TYPE=Release -S . -B build +``` instead. @@ -71,16 +95,16 @@ To build the executable simulator, build the `ddsim_simple` CMake target (which The output is JSON-formatted as shown below (with hopefully intuitive naming, the `dummy` object is just for easier handling of trailing commas). ```commandline -# (still in the build directory after building the ddsim target from above) -cmake --build . --config Release --target ddsim_simple -./ddsim_simple --simulate_file entanglement_4.real --display_vector --shots 1000 --ps +$ cmake -DCMAKE_BUILD_TYPE=Release -S . -B build +$ cmake --build build --config Release --target ddsim_simple +$ ./build/ddsim_simple --simulate_ghz 4 --display_vector --shots 1000 --ps { "measurements": { - "0000": 504, - "1111": 496 + "0000": 484, + "1111": 516 }, "state_vector": [ - √½, + +0.707107+0i, 0, 0, 0, @@ -95,37 +119,36 @@ cmake --build . --config Release --target ddsim_simple 0, 0, 0, - √½ + +0.707107+0i ], + "non_zero_entries": 2, "statistics": { - "simulation_time": 0.000147604, - "measurement_time": 0.000715286, + "simulation_time": 0.000104, + "measurement_time": 0.000104, + "benchmark": "", "shots": 1000, - "benchmark": "simple", + "distinct_results": 2, "n_qubits": 4, "applied_gates": 4, "max_nodes": 9, + "path_of_least_resistance": "1111", "seed": 0 - }, - "dummy": 0 + } } - -Process finished with exit code 0 - ``` The repository also includes some (rudimentary) unit tests (using GoogleTest), which aim to ensure the correct behaviour of the tool. They can be built and executed in the following way: ```commandline -cmake --build . --config Release --target ddsim_test -./ddsim_test +$ cmake --build build --config Release --target ddsim_test +$ ./build/ddsim_test +[...] ``` The DDSIM library and tool may be installed on the system by executing ```commandline -mkdir build && cd build -cmake .. -DCMAKE_BUILD_TYPE=Release -cmake --build . --config Release --target install +$ cmake -DCMAKE_BUILD_TYPE=Release -S . -B build +$ cmake --build build --config Release --target install ``` It can then also be included in other projects using the following CMake snippet @@ -137,16 +160,9 @@ target_link_libraries(${TARGET_NAME} PRIVATE JKQ::ddsim) ## Reference -If you use our tool for your research, we will be thankful if you refer to it by citing the following publications: +If you use our tool for your research, we will be thankful if you refer to it by citing the following publication: ```bibtex -@article{zulehner2019package, - title={How to Efficiently Handle Complex Values? Implementing Decision Diagrams for Quantum Computing}, - author={Zulehner, Alwin and Hillmich, Stefan and Wille, Robert}, - journal={International Conference on Computer-Aided Design (ICCAD)}, - year={2019} -} - @article{zulehner2019advanced, title = {Advanced Simulation of Quantum Computations}, author = {Zulehner, Alwin and Wille, Robert}, diff --git a/apps/CMakeLists.txt b/apps/CMakeLists.txt index 46021a83..a44be675 100644 --- a/apps/CMakeLists.txt +++ b/apps/CMakeLists.txt @@ -1,14 +1,11 @@ set(Boost_USE_MULTITHREADED ON) set(Boost_USE_STATIC_RUNTIME OFF) -find_package( Boost 1.50 COMPONENTS program_options REQUIRED ) -message(STATUS "Boost version: ${Boost_VERSION}") +find_package( Boost 1.50 COMPONENTS program_options ) -if(NOT TARGET Boost::program_options) - add_library(Boost::program_options IMPORTED INTERFACE) - set_property(TARGET Boost::program_options PROPERTY - INTERFACE_INCLUDE_DIRECTORIES ${Boost_INCLUDE_DIR}) - set_property(TARGET Boost::program_options PROPERTY - INTERFACE_LINK_LIBRARIES ${Boost_LIBRARIES}) +if(Boost_FOUND) + message(STATUS "Boost version: ${Boost_VERSION}") +else() + message(STATUS "Boost not found. Certain targets may not be available.") endif() include(GNUInstallDirs) @@ -35,5 +32,9 @@ macro(add_sim_executable APPNAME) set_target_properties(${PROJECT_NAME}_${APPNAME} PROPERTIES EXPORT_NAME ${PROJECT_NAME}_${APPNAME}) endmacro() -add_sim_executable(simple Boost::program_options) +if(Boost_FOUND) + add_sim_executable(simple Boost::program_options) +else() + message(STATUS "Did not find Boost! Commandline interface will not be an available target!") +endif() add_sim_executable(benchmark benchmark::benchmark_main) \ No newline at end of file