https://github.com/turingq/deepquantum
DeepQuantum for quantum computing
https://github.com/turingq/deepquantum
photonic-quantum-computing pytorch quantum-computing quantum-machine-learning
Last synced: about 2 months ago
JSON representation
DeepQuantum for quantum computing
- Host: GitHub
- URL: https://github.com/turingq/deepquantum
- Owner: TuringQ
- License: apache-2.0
- Created: 2024-06-19T16:48:45.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2026-04-24T12:58:37.000Z (about 2 months ago)
- Last Synced: 2026-04-24T13:31:03.402Z (about 2 months ago)
- Topics: photonic-quantum-computing, pytorch, quantum-computing, quantum-machine-learning
- Language: Jupyter Notebook
- Homepage: https://deepquantum.turingq.com/
- Size: 11.1 MB
- Stars: 75
- Watchers: 1
- Forks: 17
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# DeepQuantum
[](https://dqapi.turingq.com/)
[](https://pypi.org/project/deepquantum/)
[](./LICENSE)
[](https://pypi.org/project/deepquantum/)
[](https://pepy.tech/project/deepquantum)
DeepQuantum is a platform that integrates artificial intelligence (AI) and quantum computing (QC).
It is an efficient programming framework designed for quantum machine learning and photonic quantum computing.
By leveraging the PyTorch deep learning platform for QC, DeepQuantum provides a powerful and easy-to-use tool for creating and simulating quantum circuits and photonic quantum circuits.
This makes it ideal for developers to quickly get started and explore the field in depth.
It also serves as a valuable learning platform for quantum computing enthusiasts.
# Key Features
- **AI-Enhanced Quantum Computing Framework**:
Seamlessly integrated with PyTorch, it utilizes technologies such as automatic differentiation, vectorized parallelism, and GPU acceleration for efficiency.
It facilitates the easy construction of hybrid quantum-classical models, enabling end-to-end training and inference.
- **User-Friendly API Design**:
The API is designed to be simple and intuitive, making it easy to initialize quantum neural networks and providing flexibility in data encoding.
- **Photonic Quantum Computing Simulation**:
The Photonic module includes Fock, Gaussian and Bosonic backends, catering to different simulation needs in photonic quantum computing.
It comes with built-in optimizers to support on-chip training of photonic quantum circuits.
- **Large-Scale Quantum Circuit Simulation**:
Leveraging tensor network techniques, DeepQuantum enables approximate simulation of circuits with over 100 qubits on a single laptop.
Through a distributed parallel architecture and PyTorch's native communication protocol, it efficiently utilizes multi-node, multi-GPU computational power to boost large-scale quantum simulations.
These capabilities allow DeepQuantum to deliver industry-leading performance in both simulation scale and efficiency.
- **Advanced Architecture for Cutting-Edge Algorithm Exploration**:
The first framework to support algorithm design and mapping for time-domain-multiplexed photonic quantum circuits, and the first to realize closed-loop integration of quantum circuits, photonic quantum circuits, and MBQC, enabling robust support for both specialized and universal photonic quantum algorithm design.
# Installation
## 1. Prerequisites (PyTorch)
DeepQuantum requires **PyTorch 2**.
We recommend installing it manually first to ensure compatibility with your system and CUDA version.
0. **(Optional)** Install [uv](https://docs.astral.sh/uv/getting-started/installation/).
We strongly recommend using `uv` instead of standard `pip` for lightning-fast package installations.
1. Install [Miniconda](https://www.anaconda.com/docs/getting-started/miniconda/main) or [Anaconda](https://www.anaconda.com/docs/getting-started/main).
2. Create and activate a conda environment.
For example, run `conda create -n python=3.12` and `conda activate `.
3. Install PyTorch following the [official instructions](https://pytorch.org/get-started/locally/).
For example, run `pip install torch` or `uv pip install torch`.
*(Tip: Avoid using `conda install` with `uv`)*
## 2. Install DeepQuantum
### For Users (Stable Version)
To install DeepQuantum with `uv` or standard `pip`, run
```bash
uv pip install deepquantum
# Or use a mirror site for faster download
uv pip install deepquantum -i https://pypi.tuna.tsinghua.edu.cn/simple
# Fallback for standard pip
pip install deepquantum
```
### For Developers (Source Installation)
If you intend to contribute to DeepQuantum or run unit tests, **we strongly recommend installing from source**.
> **Note on Dependencies**: `strawberryfields` and `thewalrus` on PyPI are outdated and may have compatibility issues with modern environments.
For development, our project is configured to automatically pull their latest GitHub `master` branches.
#### Option A: Using `uv` (Recommended)
Since you have `uv` installed, it will automatically handle the Git branch overrides defined in our `pyproject.toml`.
```bash
git clone https://github.com/TuringQ/deepquantum.git
cd deepquantum
uv pip install -e ".[dev]"
# Or use a mirror site for faster download
uv pip install -e ".[dev]" -i https://pypi.tuna.tsinghua.edu.cn/simple
```
#### Option B: Using standard `pip`
If you prefer not to use `uv`, you must use our `requirements-dev.txt` to explicitly enforce the necessary Git overrides.
```bash
git clone https://github.com/TuringQ/deepquantum.git
cd deepquantum
pip install -e .
pip install -r requirements-dev.txt
# Or use a mirror site for faster download
pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install -r requirements-dev.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```
# Getting Started
To begin, please start with the tutorials (CN) on [basics](./tutorials/basics.ipynb) and [photonic basics](./tutorials/photonic_basics.ipynb).
Below are some minimal examples to help you get started.
- Quantum circuit
```python
import deepquantum as dq
cir = dq.QubitCircuit(2)
cir.h(0)
cir.cnot(0, 1)
cir.rx(1, 0.2)
cir.observable(0)
print(cir())
print(cir.expectation())
```
- Quantum circuit based on matrix product state
You can simply set `mps=True` in `QubitCircuit` and adjust the bond dimension `chi` to control the complexity.
```python
cir = dq.QubitCircuit(2, mps=True, chi=4)
cir.h(0)
cir.cnot(0, 1)
cir.rx(1, 0.2)
cir.observable(0)
print(cir())
print(cir.expectation())
```
- Photonic quantum circuit with the Fock backend, based on Fock basis state
```python
cir = dq.QumodeCircuit(2, [1, 1])
cir.dc([0, 1])
cir.ps(0, 0.1)
cir.bs([0, 1], [0.2, 0.3])
print(cir())
print(cir.measure())
```
- Photonic quantum circuit with the Fock backend, based on Fock state tensor
```python
cir = dq.QumodeCircuit(2, [(1, [1, 1])], basis=False)
cir.dc([0, 1])
cir.ps(0, 0.1)
cir.bs([0, 1], [0.2, 0.3])
print(cir())
print(cir.measure())
```
- Photonic quantum circuit with the Gaussian backend
```python
cir = dq.QumodeCircuit(2, 'vac', cutoff=10, backend='gaussian')
cir.s(0, 0.1)
cir.d(1, 0.1)
cir.bs([0, 1], [0.2, 0.3])
print(cir())
print(cir.measure())
print(cir.photon_number_mean_var(wires=0))
print(cir.measure_homodyne(wires=1))
```
- Photonic quantum circuit with the Bosonic backend
```python
cir = dq.QumodeCircuit(2, 'vac', backend='bosonic')
cir.cat(0, 0.5, 0.0)
cir.gkp(1, 0.5, 0.5)
cir.bs([0, 1], [0.2, 0.3])
print(cir())
print(cir.photon_number_mean_var(wires=0))
print(cir.measure_homodyne(wires=1))
```
- Pattern of measurement-based quantum computation
```python
pattern = dq.Pattern(2)
# Hadamard gate on qubit 1
pattern.n(2)
pattern.e(1, 2)
pattern.m(1)
pattern.x(2, domain=1)
# CNOT
pattern.n([3, 4])
pattern.e(2, 3)
pattern.e(0, 3)
pattern.e(3, 4)
pattern.m(2)
pattern.m(3)
pattern.x(4, domain=3)
pattern.z(4, domain=2)
pattern.z(0, domain=2)
print(abs(pattern().full_state))
```
- Transpile quantum circuit to MBQC pattern
```python
cir = dq.QubitCircuit(2)
cir.h(0)
cir.cnot(0, 1)
cir.rx(1, 0.2)
pattern = cir.pattern()
print(cir())
print(pattern().full_state)
print(cir() / pattern().full_state)
```
- Distributed simulation of quantum circuit
```python
import torch
# OMP_NUM_THREADS=2 torchrun --nproc_per_node=4 main.py
backend = 'gloo' # for CPU
# torchrun --nproc_per_node=4 main.py
backend = 'nccl' # for GPU
rank, world_size, local_rank = dq.setup_distributed(backend)
if backend == 'nccl':
device = f'cuda:{local_rank}'
elif backend == 'gloo':
device = 'cpu'
data = torch.arange(4, dtype=torch.float, device=device, requires_grad=True)
cir = dq.DistributedQubitCircuit(4)
cir.rylayer(encode=True)
cir.cnot_ring()
cir.observable(0)
cir.observable(1, 'x')
if backend == 'nccl':
cir.to(f'cuda:{local_rank}')
state = cir(data).amps
result = cir.measure(with_prob=True)
exp = cir.expectation().sum()
exp.backward()
if rank == 0:
print(state)
print(result)
print(exp)
print(data.grad)
dq.cleanup_distributed()
```
- Distributed simulation of photonic quantum circuit
```python
# OMP_NUM_THREADS=2 torchrun --nproc_per_node=4 main.py
backend = 'gloo' # for CPU
# torchrun --nproc_per_node=4 main.py
backend = 'nccl' # for GPU
rank, world_size, local_rank = dq.setup_distributed(backend)
nmode = 4
cutoff = 4
data = torch.arange(14, dtype=torch.float) / 10
cir = dq.DistributedQumodeCircuit(nmode, [0] * nmode, cutoff)
for i in range(nmode):
cir.s(i, encode=True)
for i in range(nmode - 1):
cir.bs([i, i + 1], encode=True)
if backend == 'nccl':
data = data.to(f'cuda:{local_rank}')
cir.to(f'cuda:{local_rank}')
state = cir(data).amps
result = cir.measure(with_prob=True)
if rank == 0:
print(state)
print(result)
dq.cleanup_distributed()
```
# Contributing
We welcome contributions from the community!
To maintain high code quality and consistent style, we use a modern development workflow.
[](https://github.com/astral-sh/ruff)
[](https://github.com/mwouts/jupytext)
[](https://github.com/pre-commit/pre-commit)
Please refer to our **[CONTRIBUTING.md](./CONTRIBUTING.md)** for detailed instructions on:
- **Linting & Formatting**: Our coding standards using Ruff.
- **Notebook Management**: How we sync `.ipynb` and `.py` files using Jupytext.
- **Pull Request Process**: How to link issues and submit your changes.
Before your first commit, remember to run `pre-commit install` in your local environment.
# Citation
If you use DeepQuantum in your research, please cite [our paper](https://arxiv.org/abs/2512.18995):
```bibtex
@article{he2025deepquantum,
title={DeepQuantum: A PyTorch-based Software Platform for Quantum Machine Learning and Photonic Quantum Computing},
author={He, Jun-Jie and Hu, Ke-Ming and Zhu, Yu-Ze and Yan, Guan-Ju and Liang, Shu-Yi and Zhao, Xiang and Wang, Ding and Guo, Fei-Xiang and Lan, Ze-Feng and Shang, Xiao-Wen and others},
journal={arXiv preprint arXiv:2512.18995},
year={2025}
}
```
# Star History
[](https://starchart.cc/TuringQ/deepquantum)
# License
DeepQuantum is open source, released under the Apache License, Version 2.0.