Skip to content

Commit

Permalink
Updated README.md and made Boost optional
Browse files Browse the repository at this point in the history 
- Updated README.md to be more helpful to new users (feedback welcome)
- Made Boost ProgramOptions optional (now only required to build the standalone executable)
  • Loading branch information
@hillmich
hillmich committed Jun 23, 2020
1 parent 4aca639 commit a8b9bf6
Show file tree
Hide file tree
Showing 2 changed files with 66 additions and 49 deletions.
96 changes: 56 additions & 40 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand All @@ -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);
Expand All @@ -56,31 +79,32 @@ 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.

To build the executable simulator, build the `ddsim_simple` CMake target (which requires `boost/program_options`) and run the resulting executable with options according to your needs.
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,
Expand All @@ -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
Expand All @@ -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},
Expand Down
19 changes: 10 additions & 9 deletions apps/CMakeLists.txt
View file
Original file line number Diff line number Diff line change
@@ -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)
Expand All @@ -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)

0 comments on commit a8b9bf6

Please sign in to comment.