Awesome
<!-- This README avoids relative paths since it is also used as Doxygen's mainpage --> <!-- banner --> <!-- temporarily hiding Github Actions badges (pending aesthetic customisation) [![Ubuntu unit](https://github.com/QuEST-Kit/QuEST/workflows/Ubuntu%20unit/badge.svg?branch=develop)](https://github.com/QuEST-Kit/QuEST/actions) [![macOS unit](https://github.com/QuEST-Kit/QuEST/workflows/macOS%20unit/badge.svg)](https://github.com/QuEST-Kit/QuEST/actions) [![LLVM](https://github.com/QuEST-Kit/QuEST/workflows/LLVM%20asan/badge.svg)](https://github.com/QuEST-Kit/QuEST/actions) --> <!-- temporarily hiding incorrect coverage statistics (currently only considers serial CPU; needs also GPU and distributed test contributions) [![codecov](https://codecov.io/gh/QuEST-Kit/QuEST/branch/develop/graph/badge.svg)](https://codecov.io/gh/QuEST-Kit/QuEST) --> <!-- action-badges has broken and is incorrectly showing build failure. temporarily forcing badge to show the correct pass while replacement is sought (that isn't Github's hideous default CI badge) [![unit tests](https://action-badges.now.sh/QuEST-Kit/QuEST)](https://github.com/QuEST-Kit/QuEST/actions) -->
<!-- forgive my sins (see above) -->
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 :trophy:
:tada: 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);
:white_check_mark: Features
QuEST supports:
- :ballot_box_with_check: density matrices for precise simulation of noisy quantum computers
- :ballot_box_with_check: general unitaries with any number of control and target qubits
- :ballot_box_with_check: general decoherence channels of any dimension
- :ballot_box_with_check: general Hermitian operators in the Pauli basis
- :ballot_box_with_check: many many operators, including even Pauli gadgets, analytic phase functions and Trotter circuits
- :ballot_box_with_check: many tools to analyse quantum states, such as calculations of probability, fidelity, and expected value
- :ballot_box_with_check: variable precision through a
qreal
numerical type which can use single, double or quad precision - :ballot_box_with_check: QASM output to verify simulated circuits
- :ballot_box_with_check: direct access to amplitudes for rapid custom modification of the quantum state
- :ballot_box_with_check: native compilation on MacOS, Linux and Windows, through Clang, GNU, Intel, and MSVC compilers
:book: Documentation
- The tutorial includes instructions for
- compiling QuEST
- running QuEST locally and on supercomputers
- testing QuEST using the comprehensive unit tests <br><br>
- The documentation is divided into the following modules (collated here)
- Additional utilities for debugging and testing are documented below
For developers: QuEST's doc is automatically regenerated when the
master
branch is updated via Github Actions. To locally regenerate the doc, rundoxygen doxyconfig/config
in the root directory, which generates html documentation inDoxygen_doc/html
.
:rocket: 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
<br>
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
:heart: 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
:newspaper: Related projects
-
QuESTlink <br> a Mathematica package enabling symbolic circuit manipulation, analytic simulation, visualisation and high performance simulation with remote accelerated hardware.
-
pyQuEST <br> a python interface to QuEST, based on Cython, developed within the QTechTheory group. Please note, pyQuEST is currently in the alpha stage.
-
PyQuEST-cffi <br> 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.