Qrack

About

The open source vm6502q/qrack library and its associated plugins and projects under the vm6502q organization header comprise a framework for full-stack quantum computing development, via high performance and fundamentally optimized simulation. The intent of "Qrack" is to provide maximum performance for the simulation of an ideal, virtually error-free quantum computer, across the broadest possible set of hardware and operating systems.

Using the C++11 standard, at base, Qrack has an external-dependency-free CPU simulator "engine," as well as a GPU simulator engine that depends only on OpenCL. The QUnit layer provides novel, fundamental optimizations in the simulation algorithm, based on "Schmidt decomposition," transformation of basis, 2 qubit controlled gate buffer caching, the physical nonobservability of arbitrary global phase factors on a state vector, and many other "synergistic" and incidental points of optimization between these approaches and in addition to them. QUnit can be placed "on top" of either CPU, GPU, or hybrid engine types, and an additional QPager layer can sit between these, or in place of QUnit. Optimizations and hardware support are highly configurable, particularly at build time.

A QInterface can be thought of as like simply a one-dimensional array of qubits, within which any qubit has the capacity to directly and fully entangle with any and all others. Bits can be manipulated on by a single bit gate at a time, or gates and higher level quantum instructions can be acted over arbitrary contiguous sets of bits. A qubit start index and a length is specified for parallel operation of gates over bits or for higher level instructions, like arithmetic on arbitrary width registers. Some methods are designed for (bitwise and register-like) interface between quantum and classical bits. See the Doxygen for the purpose of gate-like and register-like functions.

Qrack was originally integrated with a MOS 6502 emulator, demonstrating its originally intended user for developing chip-like quantum computer emulators. (The base 6502 emulator to which Qrack was added for that project is by Marek Karcz, many thanks to Marek! See https://github.com/makarcz/vm6502.)

Qrack compiles like a library. To include in your project:

1. In your source code:

#include "qrack/qfactory.hpp"

2. On the command line, in the project directory

$ mkdir _build && cd _build && cmake .. && make all install

For more information, compile the doxygen.config in the root folder, and then check the doc folder.

Documentation

Live version of the documentation, including API reference, can be obtained at: https://qrack.readthedocs.io/en/latest/

Community

Qrack has a community home at the Advanced Computing Topics server on Discord, at: https://discordapp.com/invite/Gj3CHDy

For help getting started with contributing, see our CONTRIBUTING.md.

Quick start

Firstly, are you looking for the applications promised by quantum computing? Do you want to run tens of thousands of nodes or more of transverse field Ising model (TFIM), or quadratic unconstrained binary optimization (QUBO) in the form of MAXCUT, or the Traveling Salesman Problem (TSP), at quality and scaling performance beyond quantum annealers, VQE, and QAOA, at the scale of a consumer laptop, with "quantum-inspired" heuristics? Then, Qrack will do a lot of things, but you likely want PyQrackIsing for that. Otherwise, we'll tell you how to get started with Qrack.

To get up-and-running most easily with maximum performance, if Python is the appropriate language for what you want to do, just pip install pyqrack. (We also offer the Qook Rust language bindings.) That's it, basically! At minimum, you could stop here: it should just work.

If Qrack tells you, on running any script or program with Qrack, its "default device" is the not the device you actually want to use (i.e. you have a NVIDIA GPU, but Qrack selects an Intel HD device instead) change the default device environment variable setting. If there are any devices at all that you don't want to use in the list Qrack prints whenever you run, this implies that you also needs to set manual device lists for QPager and QUnitMulti (which is explained below in this README). This won't remove them from Qrack's list of detected devices, but it will exclude them from being used. (Qrack will attempt to use all available devices by default, which can actually hurt performance.) If there's only one device you want to use at all (like a single NVIDIA GPU, for example), find its ID in the list Qrack prints at run time, and, if that is ID "0," for example, set environment variables QRACK_QPAGER_DEVICES=0 and QRACK_QUNITMULTI_DEVICES=0.

If you just have a single NVIDIA GPU, but Qrack detects other devices that you don't even want to bother with, you could uninstall all other versions of Qrack and then pip install pyqrack-cuda, but note that OpenCL performance tends to be better than CUDA (despite erroneous "conventional wisdom," even though the CUDA and OpenCL APIs are almost line-by-line equivalent in terms of their implementations in the Qrack library internals).

You could probably squeeze out more performance by following the "power user considerations," and other special considerations might be necessary for approximate simulation techniques or custom builds.

If you're looking for usage examples (of PyQrack), this examples repository covers many common algorithms and cases of claimed "advantage" or "supremacy" that Qrack might be able to challenge.

Power user considerations

1. Run a preliminary round of CPU-only benchmarks (such as on the quantum Fourier transform algorithm) to decide how to tune the PSTRIDEPOW environment variable for best performance (by trial-and-error comparison of timing results). This can make a big difference to CPU-based simulation performance, and be aware that CPU-based and GPU-based algorithms and implementations in Qrack work together to return the best possible performance for even GPU-based benchmarks.
2. Try "precompiling" your OpenCL kernels, to skip the OpenCL JIT compilation step, every time you run. (This doesn't work on all systems.)
3. Consider tuning light-cone optimization qubit threshold and setting manual system resource limit variables (though these are not strictly required and might be recognized accurately by default by Qrack).
4. Set QRACK_DISABLE_QUNIT_FIDELITY_GUARD=1 as environment variable to disengage Qrack's fidelity estimate "limiter," if using approximate simulation. (See the README section on approximate simulation, first.)

Want to challenge "quantum supremacy" and "quantum advantage" benchmarks from hardware quantum computers, on your laptop?

• For hard optimization problems, like MAXCUT, Traveling Salesman Problem, and transverse field ising model (TFIM), see PyQrackIsing.
• For random circuit sampling (RCS) cross-entropy benchmark (XEB) fidelity experiments, like Google's Sycamore, Willow, and related benchmarks, you want automatic circuit elision (ACE) approximation. Set environment variable QRACK_DISABLE_QUNIT_FIDELITY_GUARD=1 to turn off the "limiter" for first-principles fidelity estimate, because the estimate becomes grossly pessimistic for anti-concentration in RCS. ACE with "Schmidt decomposition" (QUnit) will break the simulation down into separable subsystems limited to m qubits for (environment variable setting) QRACK_MAX_PAGING_QB=m (or QRACK_MAX_CPU_QB=m), so you might set subsystem size to exactly half, or a quarter, or some small, simple fraction of your total count of qubits. For a 2D square lattice with 4 subsystems (so QRACK_MAX_PAGING_QB=m with overall qubit width of 4*m for the benchmark), like in the PyQrack RCS examples, you might expect roughly 50% XEB fidelity for large circuits (almost entirely independent of circuit width or depth, seemingly). The only situations where this seems not to work is with highly symmetric geometries, like perfect-square 2D layouts (4-by-4 qubits, 5-by-5, 6-by-6, etc.) of fully-connected geometries.
• For these remaining hard symmetric cases, you likely want to experiment with a mixture of ACE and sparse truncation. The sparse truncation approximation features are currently CPU-only, but they act somewhat similarly to matrix product state simulation by retaining only a (sparse) set of probability amplitudes with the highest relative probabilities, retaining much of the fidelity of the ideal circuit. Environment variable `QRACK_S