QuEST/README.md

The Quantum Exact Simulation Toolkit is a high performance simulator of quantum circuits, state-vectors and density matrices. QuEST uses multithreading, GPU acceleration and distribution to run lightning first on laptops, desktops and networked supercomputers. QuEST just works; it is stand-alone, requires no installation, and is trivial to compile and run. QuEST hybridises OpenMP and MPI with huge compiler support to run on all sorts of multicore, multi-CPU and distributed hardware, uses HIP to run on AMD GPUs, integrates cuQuantum and Thrust for cutting-edge performance on modern NVIDIA GPUs, and has a custom kernel backend to run on older CUDA-compatible GPUs. And it hides these deployment modes behind a single, seamless interface.

QuEST is developed by the QTechTheory group at the University of Oxford, and these authors. To learn more:

• see the tutorial
• view the documentation
• visit the website
• see some examples
• read the whitepaper, which featured in Scientific Report's Top 100 in Physics 🏆

---

🎉  Introduction

QuEST has a simple interface, which is agnostic to its runtime environment, between CPUs, GPUs and over networks.

hadamard(qubits, 0);

controlledRotateX(qubits, 0, 1, angle);

double prob = calcProbOfOutcome(qubits, 0, outcome);

Yet, it is flexible

Vector v;
v.x = 1; v.y = .5; v.z = 0;
rotateAroundAxis(qubits, 0, angle, v);

ComplexMatrix2 u = {
    .real = {{.5, .5}, { .5,.5}},
    .imag = {{.5,-.5}, {-.5,.5}}};
unitary(qubits, 0, u);

mixDepolarising(qubits, 0, prob);

and extremely powerful

ComplexMatrixN u = createComplexMatrixN(5);
int ctrls[] = {0, 1, 2};
int targs[] = {5, 20, 15, 10, 25};
multiControlledMultiQubitUnitary(qubits, ctrls, 3, targs, 5, u);

ComplexMatrixN k1, k2, k3 = ...
mixMultiQubitKrausMap(qubits, targs, 5, {k1, k2, k3}, 3);

double val = calcExpecPauliHamil(qubits, hamiltonian, workspace);

applyTrotterCircuit(qubits, hamiltonian, time, order, repetitions);

---

✅  Features

QuEST supports:

• ☑️   density matrices for precise simulation of noisy quantum computers
• ☑️   general unitaries with any number of control and target qubits
• ☑️   general decoherence channels of any dimension
• ☑️   general Hermitian operators in the Pauli basis
• ☑️   many many operators, including even Pauli gadgets, analytic phase functions and Trotter circuits
• ☑️   many tools to analyse quantum states, such as calculations of probability, fidelity, and expected value
• ☑️   variable precision through a qreal numerical type which can use single, double or quad precision
• ☑️   QASM output to verify simulated circuits
• ☑️   direct access to amplitudes for rapid custom modification of the quantum state
• ☑️   native compilation on MacOS, Linux and Windows, through Clang, GNU, Intel, and MSVC compilers

---

📖  Documentation

• The tutorial includes instructions for
  • compiling QuEST
  • running QuEST locally and on supercomputers
  • testing QuEST using the comprehensive unit tests
    
    
• The documentation is divided into the following modules (collated here)
  • data structures
  • initialisations
  • unitaries
  • gates
  • decoherence
  • operators
  • calculations
  • QASM
    
    
• Additional utilities for debugging and testing are documented below
  • debugging
  • unit tests
  • testing utilities

For developers: QuEST's doc is automatically regenerated when the master branch is updated via Github Actions. To locally regenerate the doc, run doxygen doxyconfig/config in the root directory, which generates html documentation in Doxygen_doc/html.

---

🚀  Getting started

To rocket right in, download QuEST with git at the terminal

git clone https://github.com/quest-kit/QuEST.git
cd QuEST

Compile the tutorial example (source) using cmake and make

mkdir build
cd build
cmake ..
make

then run it with

./demo

Windows users should install Build Tools for Visual Studio, and CMake, and run the above commmands in the Developer Command Prompt for VS, though using build commands

cmake .. -G "NMake Makefiles"
nmake

If using MSVC and NMake in this way fails, users can forego GPU acceleration, download MinGW-w64, and compile via

cmake .. -G "MinGW Makefiles"
make

---

❤️  Acknowledgements

We sincerely thank the following external contributors to QuEST.

• Jakub Adamski for optimising distributed communication of max-size messages.
• Bruno Villasenor Alvarez of AMD for porting the GPU backend to HIP, for compatibility with AMD GPUs.
• HQS Quantum simulations for contributing mixDamping on CPU.
• Kshitij Chhabra for patching some validation bugs.
• Drew Silcock for patching the multithreaded build on MacOS.
• Zach van Rijn for patching the multithreading code for GCC-9 OpenMP-5 compatibility.
• SchineCompton for patching the GPU CMake release build.
• Christopher J. Anders for patching the multithreading (when default off) and GPU builds (revising min cmake).
• Gleb Struchalin for patching the cmake standalone build.
• Milos Prokop for serial prototyping of initDiagonalOpFromPauliHamil.

QuEST uses the mt19937ar Mersenne Twister algorithm for random number generation, under the BSD licence. QuEST optionally (by additionally importing QuEST_complex.h) integrates the language agnostic complex type by Randy Meyers and Dr. Thomas Plum

---

📰  Related projects

• QuESTlink
  a Mathematica package enabling symbolic circuit manipulation, analytic simulation, visualisation and high performance simulation with remote accelerated hardware.

• pyQuEST
  a python interface to QuEST, based on Cython, developed within the QTechTheory group. Please note, pyQuEST is currently in the alpha stage.

• PyQuEST-cffi
  a python interface to QuEST based on cffi developed by HQS Quantum Simulations. Please note, PyQuEST-cffi is currently in the alpha stage and not an official QuEST project.