torch-vqc

Pure-torch variational quantum circuit (VQC) with autograd training — ~3000× faster than PennyLane parameter-shift on 6-qubit StronglyEntanglingLayers.

Why

PennyLane's default.qubit + parameter-shift gradient is the standard for VQC research, but it's painfully slow:

• Per gradient step: 2 extra forward passes per parameter (~216 for a 6×6×3 StronglyEntanglingLayers)
• No batching: samples processed one at a time in a Python loop
• Result: training a small VQC classifier on 400 samples × 10 epochs takes minutes

torch-vqc re-implements the same circuit as explicit state-vector math in torch:

• Autograd backprop replaces parameter-shift: one backward pass for the whole gradient
• Batched: all samples in parallel via einsum/index_select on the state tensor
• Validated: forward output matches PennyLane default.qubit to 1e-5

Benchmark (6 qubits, 6 layers, 120 train samples × 3 epochs):

Backend	Time	Speedup
PennyLane parameter-shift	~99 s	1×
torch-vqc autograd	~30 ms	~3000×

Install

pip install torch-vqc
# or for dev:
git clone https://github.com/electron-rare/torch-vqc
cd torch-vqc && pip install -e ".[dev]"

Quick start

import torch
from torch_vqc import torch_vqc_forward, TorchVQCRouter

# Low-level: run a circuit forward pass directly
features = torch.randn(32, 10, dtype=torch.float64)   # batch of 32, 10 input features
weights = torch.randn(6, 6, 3, dtype=torch.float64)   # (n_layers, n_qubits, 3)
z_expvals = torch_vqc_forward(features, weights, n_qubits=6, n_layers=6)
# → shape (32, 6), values in [-1, 1]

# High-level: VQC + classical head, ready to train
model = TorchVQCRouter(
    n_qubits=4,
    n_layers=6,
    n_classes=10,
    input_dim=384,        # enables learned projection (384 → n_qubits) before circuit
    weight_decay=1e-4,    # L2 regularization
    lr=0.05,
    seed=0,
)
X = torch.randn(400, 384, dtype=torch.float64)
y = torch.randint(0, 10, (400,))
losses = model.train_batched(X, y, epochs=300)
preds = model.predict(X)

What's included

Module	Purpose
torch_vqc.circuit.torch_vqc_forward	Pure forward pass — AngleEmbedding + StronglyEntanglingLayers + PauliZ expectations, validated vs PennyLane at 1e-5
torch_vqc.router.TorchVQCRouter	nn.Module wrapping circuit + classical head, optional learned projection, full-batch SGD with train_batched()

Conventions (matched to PennyLane default.qubit)

• Wire 0 = most significant bit in the ket notation |q₀ q₁ ... q_{N-1}⟩
• Rot(φ, θ, ω) = RZ(ω) · RY(θ) · RZ(φ) (PennyLane convention)
• AngleEmbedding uses RX (PennyLane default), not RY — easy to miss
• StronglyEntanglingLayers CNOT ring range r_l = l % (N-1) + 1

Tests

pip install -e ".[test]"
pytest tests/ -v

Ten tests covering:

• Forward matches PennyLane (single + batched)
• Training reduces loss, reaches non-trivial accuracy
• Gradients flow through VQC weights
• Speedup ≥ 20× vs PennyLane parameter-shift reference
• Learned projection rescues architecture on tasks where truncation fails

Background

This work was extracted from the micro-kiki project, where it was used to execute a VQC reproducibility investigation in 2 hours of compute instead of the 3 days that PennyLane's parameter-shift would have required. See docs/findings.md for the full scientific context.

License

Apache 2.0 — see LICENSE.

Citation

If you use this in academic work, cite as:

@software{torch_vqc_2026,
  author = {L'électron rare},
  title  = {torch-vqc: Pure-torch VQC with autograd training at 3000× PennyLane speedup},
  year   = {2026},
  url    = {https://github.com/electron-rare/torch-vqc}
}