General

Quantum Exact Simulation Toolkit, abbreviated as QuEST, is an exact quantum simulator supporting OpenMP multithreading, MPI distribution, and GPU acceleration, allowing efficient simulation on supercomputing infrastructure.

Project Website

Official website - https://quest.qtechtheory.org
Tutorials and Examples- https://quest.qtechtheory.org/docs/
Documentation - https://quest-kit.github.io/QuEST/modules.html
GitHub - https://github.com/QuEST-Kit/QuEST

Authors

Quantum Technologies group, University of Oxford - https://quest.qtechtheory.org/team/

License

MIT License

Current version / Version supported by LRZ

v3.7.0

Supported HPC Systems

SuperMUC-NG

Installation / HPC Deployment

This section describes the deployment of QuEST on the aforementioned supported HPC Systems. QuEST does not require a formal installation and can be utilised as a header-only library. The QuEST repository can be cloned from the GitHub project to a local directory on the HPC system. To run quantum simulations, one only needs to compile source files and run the generated executables. This process is described below with an example. This documentation assumes the user is working on a SuperMUC-NG login node.

Requirements

Source files must be provided in either C or C++. Although both GNU C and C++ compilers will suffice, the default compilers on SNG are LLVM C/C++ compilers clang /clang ++ provided by Intel, hence we suggest building QuEST source code using those compilers. This documentation uses the clang++ compiler to illustrate source code compilation. To ensure that clang++ is available, the following intel module must be loaded.

module load intel-oneapi-compilers/2021.4.0

Further, cmake and make functionalities are required for the compilation of QuEST scripts. cmake needs to be loaded using:

module load cmake

Cloning from GitHub

QuEST can be directly cloned from the official GitHub, in any directory within the user's home directory. Follow:

Cloning QuEST

cd desired/directory/
git clone https://github.com/QuEST-Kit/QuEST.git

Run test suite

QuEST comes with an extensive test suite. Run it to verify all tests pass

Run test suite

cd QuEST
mkdir build
cd build
cmake .. -DTESTING=ON
make
ctest

Usage Examples

Following a successful cloning and environment variable declaration, the functioning of the simulator can be tested through the provided built-in examples. Here, the steps to run Grover's search algorithm, which is provided as an example within the QuEST repository, are illustrated.

Basic Compilation

Basic compilation can be tested by examples provided with QuEST. The compilation of source files can be hindered by pre-existing cmake output files, from the test suite compilation. Clearing these files is recommended before proceeding with new compilations:

cd QuEST
cd build 
ls				# note the cmake files to be removed 
CMakeCache.txt  CMakeFiles  CTestTestfile.cmake  DartConfiguration.tcl  Makefile  QuEST  Testing  cmake_install.cmake  tests
rm -rf CMake*

After cloning QuEST from GitHub, Grover's search algorithm can be compiled and executed within the QuEST clone, as follows. The folder build is created in the QuEST clone to store the build process results, including the executable.

cd QuEST
mkdir build
cd build
cmake .. -DUSER_SOURCE=../examples/grovers_search.c -DOUTPUT_EXE=example_grover
make

The executable example_grover will now be created in the build directory. Running executables on the SNG login nodes is not recommended. Instead, a simple SLURM test job should be created, as detailed in the SNG documentation.

Simple Execution Job

#!/bin/bash
#SBATCH --time=00:05:00
#SBATCH --account=<project name>
#SBATCH --partition=test
#SBATCH --ntasks=1
./example_grover

This SLURM job file can be submitted as:

sbatch simple_execution_job.sh

Compilation outside the cloned QuEST directory

Executables can be compiled outside the cloned QuEST directory. In this case, an absolute path to the QuEST functionalities must be provided to cmake.

Upon cloning QuEST from GitHub, another directory, also named QuEST/, is created within the cloned repository. This directory contains all the QuEST functionalities. Hence, for the compilation of executables directly in an external directory, it may be convenient to set the absolute path to the cloned QuEST directory as an environment variable.

Export QuEST as an environment variable

cd QuEST
ls            # ensure you receive the following output to ls before calling export
AUTHORS.txt  CMakeLists.txt  LICENCE.txt  QuEST  README.md doxyconfig  examples tests
 
export QUEST_DIR=$PWD

Now, to simply compile the provided Grover's search source code, at a desired location, as a single-threaded executable without MPI acceleration, follow:

Compile executables using QuEST from generic directory

mkdir desired/location/build_exe_dir
cd desired/location/build_exe_dir
cmake $QUEST_DIR -DUSER_SOURCE="$QUEST_DIR/examples/grover_search.c" -DOUTPUT_EXE="example_grover" -DCMAKE_C_COMPILER=clang
make

The executable example_grover will now be created in the build directory, and can be executed through the simple execution job as detailed above.

Additional CMake Flags

QuEST uses cmake to compile source code, and hence a vast array of flags are available to exploit the supercomputing infrastructure during compilation.

Switching compilers - GNU C/C++

By default, QuEST uses GCC or G++ as its compilers. However, clang or clang++ are the preferred compilers on the HPC infrastructure.

In case your code needs to be built using GNU C/C++ compilers, you need to unload the default load compilers and load the necessary module for gcc as follows:

module unload intel-oneapi-compilers
module load gcc

To ensure the use of gcc (or g++) as the compiler, the flag -DCMAKE_C_COMPILER (or -DCMAKE_CXX_COMPILER) is necessary in line with the cmake command above. In addition, if certain functions require a specific version of the compiler, the additional flag DCMAKE_C_FLAGS_INIT (-or DCMAKE_CXX_FLAGS_INIT) is also required.

Set clang/clang++ as compiler

-DCMAKE_C_COMPILER=gcc													# flag to use gcc as compiler  
-DCMAKE_CXX_COMPILER=g++ -DCMAKE_CXX_FLAGS_INIT='-std=gnu++20'			# flag to use g++ as compiler, for a C++20 source file

now the following lines will be a part of the cmake compilation log.

...
The C compiler identification is GNU 11.2.0
The CXX compiler identification is GNU 11.2.0
...

Multithreading

As QuEST supports OpenMP multithreading, i.e. parallelism on multi-core or multi-CPU systems, this can be invoked during compilation compile adding the following flag:

Multithreading compilation

-DMULTITHREADED=1

If N = 16 threads are desired on one computation node, the SLURM job submission file contains the following:

Multithreading execution

#!/bin/bash
#SBATCH --time=00:05:00
#SBATCH --account=<project name>
#SBATCH --partition=test
#SBATCH --ntasks=1

export OMP_NUM_THREADS=16
./myExecutable

Distributed Systems

To compile on distributed or networked systems, such as multiple distinct nodes, include the flag

Distributed compilation

 -DDISTRIBUTED=1

The OpenMPI command mpirun should be used in the SLURM job submission file.

Distributed execution

#!/bin/bash
#SBATCH --time=00:05:00
#SBATCH --account=<project name>
#SBATCH --partition=test
#SBATCH --ntasks=1

export N_MPI_TASKS=<N>
mpirun -np $N_MPI_TASKS ./myExecutable

Consequently, a hybrid multithreaded and distributed compilation is possible, by setting both -DDISTRIBUTED and -DMULTITHREADED flag to one. Here, set N_MPI_TASKS as the number of distinct compute nodes (which don't share memory), and set OMP_NUM_THREADS , as above, to assign the number of threads used on each compute node.

Multithreaded + Distributed execution

export OMP_NUM_THREADS=16
export N_MPI_TASKS=<N>	
mpirun -np $N_MPI_TASKS ./myExecutable

Multiple Source Files

Multiple source files can be compiled into one executable by separating the source files by semicolons.

 -DUSER_SOURCE="source_file1.c;source_file2.cpp"