.. toctree:: :maxdepth: 1 :caption: API api_torchquantum api_functional api_operators api_layers .. toctree:: :maxdepth: 1 :caption: Usage usage_installation examples/index.rst .. raw:: html

A PyTorch Library for Quantum Simulation and Quantum Machine Learning

Faster, Scalable, Easy Debugging, Easy Deployment on Real Machine

MIT License Documentation Chat @ Slack Forum Website Pypi


👋 Welcome ========== What it does ^^^^^^^^^^^^ Quantum simulation framework based on PyTorch. It supports statevector simulation and pulse simulation (coming soon) on GPUs. It can scale up to the simulation of 30+ qubits with multiple GPUs. Who will benefit ^^^^^^^^^^^^^^^^ Researchers on quantum algorithm design, parameterized quantum circuit training, quantum optimal control, quantum machine learning, quantum neural networks. Differences from Qiskit/Pennylane ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Dynamic computation graph, automatic gradient computation, fast GPU support, batch model tersorized processing. News ---- - v0.1.7 Available! - Join our `Slack `__ for real time support! - Welcome to contribute! Please contact us or post in the `forum `__ if you want to have new examples implemented by TorchQuantum or any other questions. - Qmlsys website goes online: `qmlsys.mit.edu `__ and `torchquantum.org `__ Features -------- - Easy construction and simulation of quantum circuits in **PyTorch** - **Dynamic computation graph** for easy debugging - **Gradient support** via autograd - **Batch mode** inference and training on **CPU/GPU** - Easy **deployment on real quantum devices** such as IBMQ - **Easy hybrid classical-quantum** model construction - (coming soon) **pulse-level simulation** Installation ------------ .. code:: bash git clone https://github.com/mit-han-lab/torchquantum.git cd torchquantum pip install --editable . Basic Usage ----------- .. code:: python import torchquantum as tq import torchquantum.functional as tqf qdev = tq.QuantumDevice(n_wires=2, bsz=5, device="cpu", record_op=True) # use device='cuda' for GPU # use qdev.op qdev.h(wires=0) qdev.cnot(wires=[0, 1]) # use tqf tqf.h(qdev, wires=1) tqf.x(qdev, wires=1) # use tq.Operator op = tq.RX(has_params=True, trainable=True, init_params=0.5) op(qdev, wires=0) # print the current state (dynamic computation graph supported) print(qdev) # obtain the qasm string from torchquantum.plugin import op_history2qasm print(op_history2qasm(qdev.n_wires, qdev.op_history)) # measure the state on z basis print(tq.measure(qdev, n_shots=1024)) # obtain the expval on a observable by stochastic sampling (doable on simulator and real quantum hardware) from torchquantum.measurement import expval_joint_sampling expval_sampling = expval_joint_sampling(qdev, 'ZX', n_shots=1024) print(expval_sampling) # obtain the expval on a observable by analytical computation (only doable on classical simulator) from torchquantum.measurement import expval_joint_analytical expval = expval_joint_analytical(qdev, 'ZX') print(expval) # obtain gradients of expval w.r.t. trainable parameters expval[0].backward() print(op.params.grad) .. raw:: html Guide to the examples --------------------- We also prepare many example and tutorials using TorchQuantum. For **beginning level**, you may check `QNN for MNIST `__, `Quantum Convolution (Quanvolution) `__ and `Quantum Kernel Method `__, and `Quantum Regression `__. For **intermediate level**, you may check `Amplitude Encoding for MNIST `__, `Clifford gate QNN `__, `Save and Load QNN models `__, `PauliSum Operation `__, `How to convert tq to Qiskit `__. For **expert**, you may check `Parameter Shift on-chip Training `__, `VQA Gradient Pruning `__, `VQE `__, `VQA for State Prepration `__, `QAOA (Quantum Approximate Optimization Algorithm) `__. Usage ----- Construct parameterized quantum circuit models as simple as constructing a normal pytorch model. .. code:: python import torch.nn as nn import torch.nn.functional as F import torchquantum as tq import torchquantum.functional as tqf class QFCModel(nn.Module): def __init__(self): super().__init__() self.n_wires = 4 self.measure = tq.MeasureAll(tq.PauliZ) self.encoder_gates = [tqf.rx] * 4 + [tqf.ry] * 4 + \ [tqf.rz] * 4 + [tqf.rx] * 4 self.rx0 = tq.RX(has_params=True, trainable=True) self.ry0 = tq.RY(has_params=True, trainable=True) self.rz0 = tq.RZ(has_params=True, trainable=True) self.crx0 = tq.CRX(has_params=True, trainable=True) def forward(self, x): bsz = x.shape[0] # down-sample the image x = F.avg_pool2d(x, 6).view(bsz, 16) # create a quantum device to run the gates qdev = tq.QuantumDevice(n_wires=self.n_wires, bsz=bsz, device=x.device) # encode the classical image to quantum domain for k, gate in enumerate(self.encoder_gates): gate(qdev, wires=k % self.n_wires, params=x[:, k]) # add some trainable gates (need to instantiate ahead of time) self.rx0(qdev, wires=0) self.ry0(qdev, wires=1) self.rz0(qdev, wires=3) self.crx0(qdev, wires=[0, 2]) # add some more non-parameterized gates (add on-the-fly) qdev.h(wires=3) qdev.sx(wires=2) qdev.cnot(wires=[3, 0]) qdev.qubitunitary(wires=[1, 2], params=[[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 0, 1j], [0, 0, -1j, 0]]) # perform measurement to get expectations (back to classical domain) x = self.measure(qdev).reshape(bsz, 2, 2) # classification x = x.sum(-1).squeeze() x = F.log_softmax(x, dim=1) return x VQE Example ----------- Train a quantum circuit to perform VQE task. Quito quantum computer as in `simple_vqe.py <./examples/simple_vqe/simple_vqe.py>`__ script: .. code:: python cd examples/simple_vqe python simple_vqe.py MNIST Example ------------- Train a quantum circuit to perform MNIST task and deploy on the real IBM Quito quantum computer as in `mnist_example.py <./examples/simple_mnist/mnist_example_no_binding.py>`__ script: .. code:: python cd examples/simple_mnist python mnist_example.py Files ----- +-----------------------------------+-----------------------------------+ | File | Description | +===================================+===================================+ | devices.py | QuantumDevice class which stores | | | the statevector | +-----------------------------------+-----------------------------------+ | encoding.py | Encoding layers to encode | | | classical values to quantum | | | domain | +-----------------------------------+-----------------------------------+ | functional.py | Quantum gate functions | +-----------------------------------+-----------------------------------+ | operators.py | Quantum gate classes | +-----------------------------------+-----------------------------------+ | layers.py | Layer templates such as | | | RandomLayer | +-----------------------------------+-----------------------------------+ | measure.py | Measurement of quantum states to | | | get classical values | +-----------------------------------+-----------------------------------+ | graph.py | Quantum gate graph used in static | | | mode | +-----------------------------------+-----------------------------------+ | super_layer.py | Layer templates for SuperCircuits | +-----------------------------------+-----------------------------------+ | plugins/qiskit\* | Convertors and processors for | | | easy deployment on IBMQ | +-----------------------------------+-----------------------------------+ | examples/ | More examples for training QML | | | and VQE models | +-----------------------------------+-----------------------------------+ Coding Style ------------ torchquantum uses pre-commit hooks to ensure Python style consistency and prevent common mistakes in its codebase. To enable it pre-commit hooks please reproduce: .. code:: bash pip install pre-commit pre-commit install Papers using TorchQuantum ------------------------- - [HPCA’22] `Wang et al., “QuantumNAS: Noise-Adaptive Search for Robust Quantum Circuits” `__ - [DAC’22] `Wang et al., “QuantumNAT: Quantum Noise-Aware Training with Noise Injection, Quantization and Normalization” `__ - [DAC’22] `Wang et al., “QOC: Quantum On-Chip Training with Parameter Shift and Gradient Pruning” `__ - [QCE’22] `Liang et al., “Variational Quantum Pulse Learning” `__ - [ICCAD’22] `Hu et al., “Quantum Neural Network Compression” `__ - [ICCAD’22] `Wang et al., “QuEst: Graph Transformer for Quantum Circuit Reliability Estimation” `__ - [ICML Workshop] `Yun et al., “Slimmable Quantum Federated Learning” `__ - [IEEE ICDCS] `Yun et al., “Quantum Multi-Agent Reinforcement Learning via Variational Quantum Circuit Design” `__ .. raw:: html
.. raw:: html Manuscripts .. raw:: html .. rubric:: Manuscripts :name: manuscripts - `Yun et al., “Projection Valued Measure-based Quantum Machine Learning for Multi-Class Classification” `__ - `Baek et al., “3D Scalable Quantum Convolutional Neural Networks for Point Cloud Data Processing in Classification Applications” `__ - `Baek et al., “Scalable Quantum Convolutional Neural Networks” `__ - `Yun et al., “Quantum Multi-Agent Meta Reinforcement Learning” `__ .. raw:: html
Dependencies ------------ - 3.9 >= Python >= 3.7 (Python 3.10 may have the ``concurrent`` package issue for Qiskit) - PyTorch >= 1.8.0 - configargparse >= 0.14 - GPU model training requires NVIDIA GPUs Contact ------- TorchQuantum `Forum `__ Hanrui Wang hanrui@mit.edu Contributors ------------ Jiannan Cao, Jessica Ding, Jiai Gu, Song Han, Zhirui Hu, Zirui Li, Zhiding Liang, Pengyu Liu, Yilian Liu, Mohammadreza Tavasoli, Hanrui Wang, Zhepeng Wang, Zhuoyang Ye Citation -------- :: @inproceedings{hanruiwang2022quantumnas, title = {Quantumnas: Noise-adaptive search for robust quantum circuits}, author = {Wang, Hanrui and Ding, Yongshan and Gu, Jiaqi and Li, Zirui and Lin, Yujun and Pan, David Z and Chong, Frederic T and Han, Song}, booktitle = {The 28th IEEE International Symposium on High-Performance Computer Architecture (HPCA-28)}, year = {2022} }