QuEST

The Quantum Exact Simulation Toolkit (QuEST) is a high-performance simulator of quantum statevectors and density matrices. It hybridises multithreading, GPU acceleration and distribution to run lightning fast on laptops, desktops and supercomputers, parallelising over multiple cores, CPUs and GPUs. Behind the scenes, QuEST leverages OpenMP, MPI, CUDA, HIP, Thrust, cuQuantum and GPUDirect for cutting-edge performance on modern multi-GPU clusters, and compatibility with older NVIDIA and AMD GPUs. These deployments can be combined in any combination, or automatically decided at runtime, yet are abstracted behind a single, seamless interface, accessible by both C and C++ and all the major compilers (detailed here).

As of v4.2, QuEST development is led by the EPCC team at the University of Edinburgh, with support and former development by the QTechTheory group at the University of Oxford. QuEST has also received contributions and support from the below organisations. In particular, QuEST v4.0 was made possible through the support of the UK National Quantum Computing centre (NQCC200921) and the UKRI SEEQA project.

To learn more:

• view the documentation
• visit the website
• read the whitepaper, which featured in Scientific Report's Top 100 in Physics :trophy:

🎉  Introduction

QuEST has a simple interface which is agnostic to whether it's running on CPUs, GPUs or a networked supercomputer.

Qureg qureg = createQureg(30);
initRandomPureState(qureg);

applyHadamard(qureg, 0);
applyControlledRotateX(qureg, 0, 1, angle);
applyFullQuantumFourierTransform(qureg);

reportQureg(qureg);

qreal prob  = calcProbOfQubitOutcome(qureg, 0, outcome);
qreal expec = calcExpecPauliStr(qureg, getPauliStr("XYZ"));

Yet, it is flexible

mixDepolarising(qureg, targ, prob);
mixKrausMap(qureg, targs, ntargs, krausmap);

applyQubitMeasurement(qureg, targ);
applyMultiQubitProjector(qureg, targs, outcomes, ntargs);

applyControlledPauliGadget(qureg, ctrl, paulistr, angle);
applyMultiStateControlledSwap(qureg, ctrls, states, nctrls, targ1, targ2);

leftapplyCompMatr1(qureg, targ, getInlineCompMatr1( {{1,2i},{3i,4}} ));
leftapplyDiagMatrPower(qureg, targs, ntargs, diagmatr, exponent);

and extremely powerful

setFullStateDiagMatrFromMultiVarFunc(fullmatr, myfunc, ntargsPerVar, nvars);
applyFullStateDiagMatrPower(qureg, fullmatr, exponent);

CompMatr matr = createCompMatr(10);
setCompMatr(matr, ...);
applyCompMatr(qureg, targs, 10, matr);

PauliStrSum observ = createInlinePauliStrSum(R"(
    0.123 XXIXX
    1.23i XYZXZ
    -1-6i IIZII
)");
applyTrotterizedPauliStrSumGadget(qureg, observ, time, order, nreps);

Qureg reduce = calcPartialTrace(qureg, targs, ntargs);
qreal expec1 = calcExpecPauliStrSum(reduce, observ);
qreal expec2 = calcExpecFullStateDiagMatr(qureg, fullmatr);

✅  Features

QuEST supports:

• ☑️   density matrices for precise simulation of noisy quantum computers
• ☑️   general unitaries with any number of control, control-states, and target qubits
• ☑️   general decoherence channels of any dimension
• ☑️   general observables in the Pauli or diagonal-Z bases
• ☑️   many many operators, including Pauli gadgets, trotterised time evolutions, and projectors
• ☑️   many tools to analyse quantum states, such as calculations of probability, fidelity, expectation value, distances and partial traces
• ☑️   variable precision through qreal and qcomp numerical types which can use single, double or quad precision
• ☑️   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
• ☑️   hybridisation of multithreading, GPU-acceleration, distribution and GPU-distribution
• ☑️   optimisation using NVLink'd GPUs, cuQuantum, and CUDA-aware MPI
• ☑️   automatic deployment of a Qureg to the optimal hardware at runtime
• ☑️   hardware probing to determine how many qubits can be simulated at runtime
• ☑️   bespoke algorithms to optimally simulate a wide variety of esoteric operations

📖  Documentation

[!IMPORTANT] QuEST v4's documentation is still under construction!

Visit the docs for guides and tutorials, or the API which is divided into:

• calculations
• channels
• debug
• decoherence
• environment
• initialisations
• matrices
• modes
• operations
• paulis
• precision
• qureg
• types
• tests

🚀  Getting started

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

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

We recommend working in a build directory:

mkdir build
cd build

Compile the minimum example using cmake:

cmake .. 
make

then run it with

./min_example

See the docs for enabling acceleration and running the unit tests.

❤  Acknowledgements

In addition to QuEST's authors, we sincerely thank the following external contributors to QuEST.

• Diogo Pratas Maia for implementing non-unitary Pauli gadgets (unitaryHACK 2025 #594).
• Mai Đức Khang for implementing a RAM probe (unitaryHACK 2025 #600).
• James Richings for patching a v4 overflow bug.
• Luc Jaulmes for patching v4's CMake installation.
• Jakub Adamski for optimising distributed communication of max-size messages.
• Bruno Villasenor Alvarez of AMD for porting the v3 GPU backend to HIP, for compatibility with AMD GPUs.
• HQS Quantum simulations for prototyping v3 mixDamping.
• Kshitij Chhabra for patching some v3 validation bugs.
• Drew Silcock for patching the v3 multithreaded build on MacOS.
• Zach van Rijn for patching the v3 multithreading code for GCC-9 OpenMP-5 compatibility.
• SchineCompton for patching the v3 GPU CMake release build.
• Christopher J. Anders for patching the v3 multithreading (when default off) and GPU builds (revising min cmake).
• Gleb Struchalin for patching the v3 cmake standalone build.
• Milos Prokop for serial prototyping of v3's initDiagonalOpFromPauliHamil.

📰  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 by Richard Meister within the QTechTheory group.

• QuEST.jl a Julia interface to QuEST, developed by Jonathan Miller.

• qoqo-quest a Rust interface to QuEST, developed by HQS Quantum Simulations.

• PyQuEST-cffi a python interface to QuEST developed by HQS Quantum Simulations.