Quantum++

Version 1.0-rc2 - 6 September 2017

Build status: Master

Quantum++ is a modern C++11 general purpose quantum computing library, composed solely of template header files. Quantum++ is written in standard C++11 and has very low external dependencies, using only the Eigen 3 linear algebra header-only template library and, if available, the OpenMP multi-processing library.

Quantum++ is not restricted to qubit systems or specific quantum information processing tasks, being capable of simulating arbitrary quantum processes. The main design factors taken in consideration were the ease of use, high portability, and high performance. The library's simulation capabilities are only restricted by the amount of available physical memory. On a typical machine (Intel i5 8Gb RAM) Quantum++ can successfully simulate the evolution of 25 qubits in a pure state or of 12 qubits in a mixed state reasonably fast.

To report any bugs or ask for additional features/enhancements, please submit an issue with an appropriate label.

If you are interesting in contributing to this project, feel free to contact me. Alternatively, create a custom branch, add your contribution, then finally create a pull request. If I accept the pull request, I will merge your custom branch with the latest development branch. The latter will eventually be merged into a future release version. To contribute, you need to have a solid knowledge of C++ (preferably C++11), including templates and the standard library, a basic knowledge of quantum computing and linear algebra, and working experience with Eigen 3.

For additional Eigen 3 documentation see http://eigen.tuxfamily.org/dox/. For a simple Eigen 3 quick ASCII reference see http://eigen.tuxfamily.org/dox/AsciiQuickReference.txt.

Quantum++ is licensed under the MIT license, see COPYING for the full terms and conditions of the license.

Building instructions for POSIX-compliant platforms

Configuration

Compiler: g++ version 5.0 or later (for good C++11 support)
Eigen 3 linear algebra library. I assume here that the library is installed in $HOME/eigen, although the location may vary, e.g. if the libary was installed using a package manager.
Quantum++ library located in $HOME/qpp

Optional

CMake version 3.0 or later, highly recommended
MATLAB compiler include header files: /Applications/MATLAB_R2016a.app/extern/include
MATLAB compiler shared library files: /Applications/MATLAB_R2016a.app/bin/maci64

Building using CMake (version 3.0 or later)

The current version of the repository has a ./CMakeLists.txt configuration file for building examples using CMake. To build an example using CMake, I recommend an out-of-source build, i.e., from the root of the project (where ./include is located), type

mkdir ./build
cd ./build
cmake ..
make

The commands above build the release version (default) executable qpp, from the source file ./examples/minimal.cpp, without MATLAB support (default), inside the directory ./build.

If the location of Eigen 3 is not detected automatically by the CMake build script, then the build script will fail (with an error message). In this case the location of Eigen 3 needs to be specified manually in the CMake build command line by passing the -DEIGEN3_INCLUDE_DIR=path_to_eigen3 flag, e.g.

cmake .. -DEIGEN3_INCLUDE_DIR=/usr/local/eigen3

To build a different configuration, e.g. the debug version with MATLAB support, type from the root of the project

cd ./build
rm -rf *
cmake -DCMAKE_BUILD_TYPE=Debug -DWITH_MATLAB=ON ..
make

Or, to disable OpenMP support (enabled by default), type

cd ./build
rm -rf *
cmake -DWITH_OPENMP=OFF ..
make

To change the name of the example file or the location of MATLAB installation, edit the ./CMakeLists.txt file. Inspect also ./CMakeLists.txt for additional fine-tuning options. Do not forget to clean the ./build directory before a fresh build!

Building without an automatic build system

Example file: $HOME/qpp/examples/minimal.cpp
Output executable: $HOME/qpp/examples/minimal
You must run the commands below from inside the directory $HOME/qpp/examples

Release version (without MATLAB support)

g++ -pedantic -std=c++11 -Wall -Wextra -Weffc++ -fopenmp \
     -O3 -DNDEBUG -DEIGEN_NO_DEBUG \
     -isystem $HOME/eigen -I $HOME/qpp/include \
     minimal.cpp -o minimal

Debug version (without MATLAB support)

g++ -pedantic -std=c++11 -Wall -Wextra -Weffc++ -fopenmp \
     -g3 -DDEBUG \
     -isystem $HOME/eigen -I $HOME/qpp/include \
      minimal.cpp -o minimal

Release version (with MATLAB support)

g++ -pedantic -std=c++11 -Wall -Wextra -Weffc++ -fopenmp \
     -O3 -DNDEBUG -DEIGEN_NO_DEBUG \
     -isystem $HOME/eigen -I $HOME/qpp/include \
     -I/Applications/MATLAB_R2016a.app/extern/include \
     -L/Applications/MATLAB_R2016a.app/bin/maci64 \
     -lmx -lmat minimal.cpp -o minimal

Debug version (with MATLAB support)

g++ -pedantic -std=c++11 -Wall -Wextra -Weffc++ -fopenmp \
     -g3 -DDEBUG \
     -isystem $HOME/eigen -I $HOME/qpp/include \
     -I /Applications/MATLAB_R2016a.app/extern/include \
     -L /Applications/MATLAB_R2016a.app/bin/maci64 \
     -lmx -lmat minimal.cpp -o minimal

Additional building instructions for particular platforms

Windows via Cygwin

Some earlier versions of Cygwin had a bug related to lack of support for some C++11 math functions, see http://stackoverflow.com/questions/28997206/cygwin-support-for-c11-in-g4-9-2 for more details. Quick fix: patch the standard library header file <cmath> using the provided patch ./cmath_cygwin.patch. Later Cygwin versions seem to have fixed the issue (as of Nov. 2016).

Windows via Visual Studio

Quantum++ contains a full Visual Studio 2017 solution under the folder ./VisualStudio. The solution expects Eigen 3 to be installed under C:\eigen. Use this solution at first to get you started.
Visual Studio versions preceeding version 2015 do not have full C++11 support. If you decide to use Visual Studio make sure you install version 2015 or later. I recommend using Visual Studio 2017.
Visual Studio 2015/2017 only supports OpenMP 2.0. Quantum++ uses features from OpenMP 3.0, hence Quantum++ will not compile on Visual Studio 2015/2017 if you enable OpenMP (disabled by default) in

Project/Properties/Configuration Properties/C_C++/Language/Open MP Support

and #define WITH_OPENMP_ in your source file.

OS X/macOS

If you want to compile with clang++ version 3.7 or later, I highly recommend to install it via macports.
If you run the program with MATLAB support, make sure that the environment variable DYLD_LIBRARY_PATH is set to point to the MATLAB compiler library location, see the run_mac_MATLAB script. Otherwise, you get a runtime error similar to

dyld: Library not loaded: @rpath/libmat.dylib.
- I recommend running via a script, as otherwise setting the DYLD_LIBRARY_PATH globally may interfere with macports' CMake installation (in case you use CMake from macports). If you use a script, then the environment variable is local to the script and does not interfere with the rest of the system.
- Example of script, assumed to be located in the root directory of Quantum++
```
   #!/bin/sh
   
   MATLAB=/Applications/MATLAB_R2016a.app
   export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$MATLAB/bin/maci64
   
   ./build/qpp
```
If you build a debug version with g++ and use gdb to step inside template functions you may want to add -fno-weak compiler flag. See http://stackoverflow.com/questions/23330641/gnu-gdb-can-not-step-into-template-functions-os-x-mavericks for more details about this problem.

Unit testing

Quantum++ was extensively tested under multiple flavours of Linux, OS X/macOS, Windows XP/7/10, Solaris 11.x via a suite of unit tests constructed with Google Test 1.8.0 (included with the project in ./unit_tests/lib/gtest-1.8.0). The source code of the unit tests is provided under ./unit_tests/tests. To build and run the unit tests, I strongly recommend to use CMake version 3.0 or later. Assuming you do use CMake, switch to the
./unit_tests directory, create a build directory inside it, then from the newly created ./unit_tests/build type

cmake ..
make

The commands above build ./unit_tests/build/tests/qpp_testing, which you then may run. Note that qpp::Timer tests or tests related to random functions such as qpp::rand() may sometime (very rarely) fail, due to timing imprecision or statistical errors. Such behaviour is perfectly normal.

Note

The CMake configuration file ./unit_tests/CMakeLists.txt defines the same building options and default choices as the main ./CMakeLists.txt of Quantum++. Therefore you can use the same flags as the ones mentioned at the beginning of this document when customizing the build. You should modify ./unit_tests/CMakeLists.txt accordingly in case your Eigen 3 library or MATLAB include/library files are in a different location than the one assumed in this document.

Additional remarks

If you use clang++ version 3.7 or later and want to use OpenMP (enabled by default), make sure to modify CLANG_LIBOMP and CLANG_LIBOMP_INCLUDE in CMakeLists.txt so they point to the correct location of the OpenMP library, as otherwise clang++ will not find <omp.h> and the libomp shared library.

gitter-badger / qpp Goto Github PK

qpp's Introduction