pytket-custatevec

GPU-accelerated statevector and shot-based simulation for pytket.

📚 Read the Full Documentation

---

🚀 Features   •   📊 Benchmarks   •   📦 Installation   •   ⚡ Quick Start   •   💻 Development   •   📄 Citing

---

pytket-custatevec is a high-performance extension for pytket that allows quantum circuits to be simulated on NVIDIA GPUs.

It acts as an open-source bridge to the NVIDIA cuQuantum SDK, utilizing cuStateVec to optimize memory usage and gate execution speed for large circuit simulations.

Features

• High Performance: Designed for rapid simulation of quantum circuits using parallel GPU architecture.
• Seamless Integration: Works as a standard pytket Backend.
• Optimized Memory: Manages GPU VRAM efficiently for complex simulations.

Benchmarks

These results are auto-generated by our CI pipeline. They compare pytket-custatevec (GPU) against standard CPU simulators (Aer, Qulacs) for a dense random circuit.

Note

The charts above are static snapshots. View the Interactive Benchmarks in our documentation to see hardware details and zoom into specific data points.

Installation

Prerequisites

• Python 3.10+
• Linux machine with NVIDIA GPU (Compute Capability 7.0+)
• NVIDIA Drivers installed

Option A: Conda (Recommended) We recommend Conda to reliably handle system-level CUDA libraries.

conda install -c conda-forge cuquantum-python
pip install pytket-custatevec

Option B: Pip You can install everything via pip, which pulls the necessary binary wheels automatically.

pip install pytket-custatevec

Quick Start

from pytket import Circuit
from pytket.extensions.custatevec import CuStateVecStateBackend

# 1. Define a circuit
circ = Circuit(2).H(0).CX(0, 1)

# 2. Initialize the GPU backend
backend = CuStateVecStateBackend()
compiled_circ = backend.get_compiled_circuit(circ)

# 3. Run on GPU
statevector = backend.run_circuit(compiled_circ).get_state()
print(statevector)

Development

Setup

To install the extension in editable mode for development:

pip install -e ".[dev,docs,test]"

Code Style

We use pre-commit to maintain code quality. Before committing, run:

pre-commit run

This handles formatting (ruff), type checking (mypy), and linting.

Testing

To run the test suite (requires a GPU environment):

pytest tests/

Citing

If you use pytket-custatevec in your research, please cite it as follows:

@software{pytket_custatevec,
  author = {{The pytket-custatevec Developers}},
  title = {pytket-custatevec: GPU-accelerated pytket simulation},
  url = {https://github.com/quantinuum/pytket-custatevec},
  year = {2025}
}