QuAIRKit is a Python SDK for algorithm development in quantum computing, quantum information, and quantum machine learning. It focuses on flexible design, real-time simulation and rapid verification of quantum and classical algorithms.
QuAIRKit provides the following functionalities,
- Quantum algorithm simulation & optimization
- Quantum circuit simulation & visualization
- Quantum channel simulation
- Quantum algorithm/information tools
We provide skills for coding agents to use QuAIRKit.
The minimum supported Python version for QuAIRKit is 3.10.
A typical fresh environment is:
conda create -n quair python=3.10
conda activate quair
conda install jupyter notebook # for notebook tutorialsIf you use Python >= 3.10, PyTorch >= 2.11, and one of the following platforms: Windows x86_64, Linux x86_64, or macOS Apple Silicon (arm64), the command below installs the recommended PyPI wheel.
pip install quairkitOr install a wheel downloaded from GitHub Releases (Assets):
pip install ./quairkit-0.5.1-*.whlThese wheels are built against PyTorch 2.11.x and are expected to work with both CPU and CUDA PyTorch builds, as long as your installed PyTorch is also 2.11.x.
If you need a source or developer install instead, see Installation from source at the end of this README.
After installation, you can import QuAIRKit in your Python code as follows:
import quairkit as qkit
import torch # library for tensor manipulation
from quairkit import Circuit # standard quantum circuit interface
from quairkit.database import * # common matrices, sets, Hamiltonian, states, etc.
from quairkit.qinfo import * # common functions in quantum information processing
from quairkit.loss import * # common loss operators in neural network trainingIn most workflows, Circuit builds the executable workflow, quairkit.database provides standard states, matrices, and channels, quairkit.qinfo analyzes outputs, and quairkit.loss packages reusable training objectives.
QuAIRKit provides global setup functions to set the default data type, device and random seed.
qkit.set_dtype('complex128') # default data type is 'complex64'
qkit.set_device('cuda') # make sure CUDA is setup with torch
qkit.set_seed(73) # set seeds for all random number generatorsQuAIRKit provides a wide range of features for quantum computing, quantum information processing and quantum machine learning. Below are some of the key features:
QuAIRKit supports batch computations for quantum circuit simulations, state measurement and quantum information processing. It is easy to use and can be customized for different quantum (machine learning) algorithms.
Below is an example of batched circuit simulation. Here one circuit applies a batched oracle and batched rotation parameters, then compares the four outputs with the same target state.
target_state = zero_state(1)
unitary_data = pauli_group(1) # I, Pauli-X/Y/Z
cir = Circuit(1)
cir.oracle(unitary_data, 0)
cir.ry(param=[0, 1, 2, 3])
output_state = cir() # zero-state input by default
print(state_fidelity(output_state, target_state))tensor([1.0000, 0.4794, 0.8415, 0.0707])
Above output is equivalent to
QuAIRKit also supports qudit workflows, including mixed-dimension circuits and batched operators, as shown below
# create two systems: one qubit and one qutrit
cir = Circuit(2, system_dim=[2, 3])
# apply dimension-6 Heisenberg-Weyl operators on the composite system
cir.oracle(heisenberg_weyl(6), [0, 1])
# apply the H gate on the qubit, controlled by the qutrit
cir.oracle(h(), [1, 0], control_idx=0)
# trace out the qutrit system and get the qubit state
traced_state = cir().trace(1)
print('The 6th and 7th state for the batched qubit state is', traced_state[5:7])The 6th and 7th state for the batched qubit state is
---------------------------------------------------
Backend: density_matrix
System dimension: [2]
System sequence: [0]
Batch size: [2]
# 0:
[[1.+0.j 0.+0.j]
[0.+0.j 0.+0.j]]
# 1:
[[0.5+0.j 0.5+0.j]
[0.5+0.j 0.5+0.j]]
---------------------------------------------------
QuAIRKit supports probabilistic quantum circuit simulation, which allows you to simulate quantum circuits with probabilistic operations such as measurement, partial post-selection, and LOCC. This is useful in quantum communication protocols and quantum algorithm design. This functionality is also compatible with batch and qudit computation.
Below is the implementation of a qubit teleportation protocol in QuAIRKit.
M1_locc = torch.stack([eye(), x()]) # apply X gate for measure outcome 1
M2_locc = torch.stack([eye(), z()]) # apply Z gate for measure outcome 1
# setup protocol
cir = Circuit(3)
cir.cnot([0, 1])
cir.h(0)
cir.locc(M1_locc, [1, 2]) # measure on qubit 1, apply local operations on qubit 2
cir.locc(M2_locc, [0, 2]) # measure on qubit 0, apply local operations on qubit 2
# test with 100 random single-qubit (mixed) states
psi = random_state(1, size=100)
input_state = nkron(psi, bell_state(2))
output_state = cir(input_state).trace([0, 1]) # discard first two qubits
fid = state_fidelity(output_state.expec_state(), psi).mean().item()
print('The average fidelity of the teleportation protocol is', fid)The average fidelity of the teleportation protocol is 0.9999999999998951
Here cir(input_state) keeps the LOCC branch structure, and expec_state() averages that branch axis before the fidelity is compared with one reference state per input sample.
Circuit in QuAIRKit can be visualized with Quantikz, a LaTeX package for quantum circuit presentation. Use to_latex() if you only need the source code, or plot() if you want QuAIRKit to render the figure. Make sure you have an up-to-date LaTeX installation so that the quantikz package is available.
cir: Circuit = ...
cir.plot(print_code=True) # plot the circuit with LaTeX codeSee the tutorial for more details.
QuAIRKit supports third-party cloud integration through StateOperator backends. This is a backend-integrator interface rather than the default user path; ordinary users typically interact with such backends through set_backend together with measurement and expectation-value APIs.
class YourState(qkit.StateOperator):
def _execute(self, qasm: str, shots: int) -> Dict[str, int]:
r"""IMPLEMENT HERE to execute the circuit on the quantum cloud."""
qkit.set_backend(YourState)See the tutorial for more details.
QuAIRKit provides a fast and flexible way to construct quantum circuits, by self-managing the parameters. All parameters would be created randomly if not specified. QuAIRKit also supports built-in layer ansatz, such as complex_entangled_layer.
cir = Circuit(2)
cir.rx() # apply Rx gates on all qubits with random parameters
cir.complex_entangled_layer(depth=2) # apply complex entangled layers of depth 2
cir.universal_two_qubits() # apply universal two-qubit gate with random parametersCircuit is a child class of torch.nn.Module, so you can access its parameters and other attributes directly, or use it as a layer in a hybrid neural network.
If you want to perform noise simulation or mixed-state-related analysis, there is no need to switch backends manually or import other libraries. Just call the function, and QuAIRKit will move the simulator from the pure-state path to the mixed-state path when the workflow becomes non-unitary.
cir = Circuit(3)
cir.complex_entangled_layer(depth=3)
print(cir().backend)
# partial transpose on the first two qubits
print(cir().transpose([0, 1]).backend)
cir.depolarizing(prob=0.1)
print(cir().backend)default-pure
default-mixed
default-mixed
-
- Analyze Barren Plateau in quantum neural networks
- Hamiltonian simulation via Trotter decomposition
- Quantum State Teleportation and Distribution
- Rediscovering Simon's algorithm with PQC
- Search quantum information protocols with LOCCNet
- Training quantum process transformation with PQC
- Quantum Boltzmann Machine
-
Tutorials for AIAA 5072, a quantum computing course instructed in HKUST(GZ)
Installation from source will compile the C++ extension and compiler/toolchain with C++17 support. Source builds support PyTorch >= 2.4 (recommended: PyTorch 2.11 or newer).
Compiler toolchain references (official):
- Windows: Visual Studio Build Tools (C++)
- Linux: GCC (or Clang)
- macOS: Xcode Command Line Tools
Install from source (assumes your environment is already activated):
git clone https://github.com/QuAIR/QuAIRKit
cd QuAIRKit
pip install -e . --no-build-isolationIf VSCode/Pylance cannot resolve quairkit after the editable install above, you can choose one of the following:
- Reinstall in strict editable mode for better IDE compatibility:
pip install -e . --config-settings editable_mode=strict --no-build-isolation- Keep the default editable install and add your local QuAIRKit repository root to the global
python.analysis.extraPathssetting in VSCode/Pylance. Since thequairkit/package directory lives directly under the repository root, add the absolute path to your clonedQuAIRKitdirectory, for example:
{
"python.analysis.extraPaths": [
"/path/to/QuAIRKit"
]
}If you frequently modify the source code, we recommend the extraPaths approach above. The strict editable mode may require rerunning the install command after C++ changes.