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)

Author: hillmich

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,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,
@@ -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},

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)