pytket-custatevec 0.1.0
Extension for pytket providing access to cuStateVec functionality.
Requires Python: >=3.10

<div align="center">
  <img src="docs/assets/logo.svg" height="100" alt="pytket-custatevec logo" />
  <h1>pytket-custatevec</h1>
  <p><strong>GPU-accelerated statevector and shot-based simulation for pytket.</strong></p>

<p>
  <a href="https://github.com/CQCL/pytket-custatevec/actions"><img src="https://img.shields.io/badge/build-passing-brightgreen?style=flat&logo=github" alt="Build" /></a>
  <a href="https://pypi.org/project/pytket-custatevec/"><img src="https://img.shields.io/badge/pypi-v0.0.1-blue?style=flat&logo=pypi" alt="PyPI" /></a>
  <a href="https://github.com/CQCL/pytket-custatevec/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green?style=flat" alt="License" /></a>
  <a href="https://tketusers.slack.com/"><img src="https://img.shields.io/badge/Slack-TKET%20Users-4A154B?logo=slack" alt="Slack" /></a>
<a href="https://quantumcomputing.stackexchange.com/tags/pytket"><img src="https://img.shields.io/badge/StackExchange-pytket-2287F4?logo=stackexchange" alt="Stack Exchange" /></a>
</p>

  <h3>
    <a href="https://cqcl.github.io/pytket-custatevec/">📚 Read the Full Documentation</a>
  </h3>
</div>

---

<p align="center">
  <small>
    <a href="#features" style="font-weight: 600;">🚀 Features</a>
    &nbsp; &bull; &nbsp;
    <a href="#benchmarks" style="font-weight: 600;">📊 Benchmarks</a>
    &nbsp; &bull; &nbsp;
    <a href="#installation" style="font-weight: 600;">📦 Installation</a>
    &nbsp; &bull; &nbsp;
    <a href="#quick-start" style="font-weight: 600;">⚡ Quick Start</a>
    &nbsp; &bull; &nbsp;
    <a href="#development" style="font-weight: 600;">💻 Development</a>
    &nbsp; &bull; &nbsp;
    <a href="#citing" style="font-weight: 600;">📄 Citing</a>
  </small>
</p>

---

**pytket-custatevec** is a high-performance extension for [pytket](https://tket.quantinuum.com/) that allows quantum circuits to be simulated on NVIDIA GPUs.

It acts as an open-source bridge to the [NVIDIA cuQuantum](https://developer.nvidia.com/cuquantum-sdk) SDK, utilizing `cuStateVec` to optimize memory usage and gate execution speed for large statevector 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.

<p align="center">
  <img src="docs/assets/benchmark_sv.png" width="48%" alt="Statevector Simulation Performance" />
  <img src="docs/assets/benchmark_shots.png" width="48%" alt="Shot-based Simulation Performance" />
</p>

> [!NOTE]
> The charts above are static snapshots. View the **[Interactive Benchmarks](https://cqcl.github.io/pytket-custatevec/examples/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.

```shell
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.

```shell
pip install pytket-custatevec
```

## ⚡ Quick Start

```python
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:

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

### Code Style
We use `pre-commit` to maintain code quality. Before committing, run:

```shell
pre-commit run
```
This handles formatting (ruff), type checking (mypy), and linting.

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

```shell
pytest tests/
```

## 📄 Citing

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

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