Metadata-Version: 2.4
Name: qiskit-trev
Version: 0.1.1
Summary: GPU-accelerated tensor ring VQA simulation plugin for Qiskit, powered by PyTorch
Author: Keunjun Park
License-Expression: MIT
Project-URL: Homepage, https://github.com/keunjunpark/qiskit-trev
Project-URL: Repository, https://github.com/keunjunpark/qiskit-trev
Project-URL: Issues, https://github.com/keunjunpark/qiskit-trev/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: qiskit>=1.0
Requires-Dist: numpy>=1.23.0
Requires-Dist: torch>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Provides-Extra: ci
Requires-Dist: pytest>=7.0.0; extra == "ci"
Requires-Dist: pytest-cov>=4.0.0; extra == "ci"
Dynamic: license-file

# qiskit-trev

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![codecov](https://codecov.io/gh/keunjunpark/qiskit-trev/branch/main/graph/badge.svg)](https://codecov.io/gh/keunjunpark/qiskit-trev)
[![Tests](https://github.com/keunjunpark/qiskit-trev/actions/workflows/test.yml/badge.svg)](https://github.com/keunjunpark/qiskit-trev/actions/workflows/test.yml)
[![Qiskit Ecosystem](https://qisk.it/e-e2beb4ad)](https://qisk.it/e)

**Qiskit TREV** is a GPU-accelerated quantum circuit simulation plugin for Qiskit, built on PyTorch. It provides efficient variational quantum algorithm (VQA) simulation using tensor ring (periodic Matrix Product State) representations, powered by PyTorch's GPU acceleration.

## Features

- **Tensor Ring Architecture**: Efficient quantum state representation using periodic Matrix Product States
- **PyTorch Backend**: GPU acceleration via PyTorch tensors and CUDA
- **Qiskit Integration**: Works seamlessly as a Qiskit plugin with `BackendV2` interface
- **Multiple Measurement Methods**:
  - Full Contraction
  - Perfect Sampling
  - Efficient Contraction
  - Right Suffix Contraction
- **Variational Algorithm Support**: Built-in parameter-shift rule gradient computation
- **Hamiltonian Operations**: Full support for Pauli string Hamiltonians via `SparsePauliOp`

## Requirements

- Python 3.10+
- NVIDIA GPU with CUDA support
- [PyTorch](https://pytorch.org/) with CUDA
- Qiskit >= 1.0
- NumPy

## Installation

```bash
pip install qiskit-trev
```

For development:

```bash
git clone https://github.com/keunjunpark/qiskit-trev.git
cd qiskit-trev
pip install -e ".[dev]"
```

## Tutorials

See the [`tutorials/`](tutorials/) directory for Jupyter notebooks:

1. **[Getting Started](tutorials/01_getting_started.ipynb)** — Circuits, sampling, and the TREV backend
2. **[Expectation Values](tutorials/02_expectation_values.ipynb)** — Hamiltonians, estimator, and measurement methods
3. **[VQE Optimization](tutorials/03_vqe_optimization.ipynb)** — Gradient descent and CMA-ES for variational algorithms
4. **[Auto Batch Size](tutorials/04_auto_batch_size.ipynb)** — GPU memory-aware batch size tuning for parameter-shift gradients

## Architecture

```
qiskit_trev/
├── __init__.py               # Public API
├── backend.py                # TREVBackend (Qiskit BackendV2)
├── estimator.py              # TREVEstimator (Qiskit Estimator primitive)
├── sampler.py                # TREVSampler (Qiskit Sampler primitive)
├── tensor_ring/              # Core tensor ring engine
│   ├── state.py              # Tensor ring state representation
│   ├── contraction.py        # Tensor contraction routines
│   └── gates.py              # Gate-to-tensor decomposition
├── measure/                  # Measurement strategies
│   ├── full_contraction.py
│   ├── perfect_sampling.py
│   ├── efficient_contraction.py
│   └── right_suffix.py
└── transpiler/               # TREV-specific transpiler passes
    └── passes.py
```

## How It Differs from TREV

| | TREV | qiskit-trev |
|---|---|---|
| **Backend** | PyTorch | PyTorch |
| **Interface** | Custom `Circuit` API | Qiskit `BackendV2` / Primitives |
| **Gradients** | Parameter-shift rule | Parameter-shift rule |
| **Ecosystem** | Standalone | Qiskit plugin |
| **Install** | `pip install TREV` | `pip install qiskit-trev` |

## Contributing

Contributions are welcome! Please feel free to submit pull requests, report bugs, or suggest features.

```bash
pip install -e ".[dev]"
pytest
```

## License

MIT License

## Citation

If you use qiskit-trev in your research, please cite:

```bibtex
@software{qiskit_trev,
  title={qiskit-trev: PyTorch-based Tensor Ring VQA Simulation for Qiskit},
  author={Park, Keunjun},
  url={https://github.com/keunjunpark/qiskit-trev},
}
```

## Acknowledgments

This project builds on [TREV](https://github.com/keunjunpark/TREV).
