PyQit is a quantum machine learning framework built on PennyLane. It puts a Trainer, a DataModule and model classes on top of PennyLane QNodes, so training a variational circuit is a fit call rather than an optimizer loop you write yourself. PyTorch and PyTorch Lightning are optional. Install them and the same code trains through PyTorch Lightning instead of autograd. That is the PyTorch project, not PennyLane's lightning.qubit simulator, which is a device and works on either backend.

Version 0.1.0.

The documentation has the tutorials, the API reference and the design notes. This page is the short version.

Installation

pip install pyqit                 # pennylane and numpy
pip install "pyqit[pytorch]"      # adds torch and pytorch lightning
pip install "pyqit[all_extras]"   # adds matplotlib and rich as well
pip install "pyqit[qiskit]"       # adds the PennyLane-Qiskit plugin

With uv, uv add pyqit or uv pip install "pyqit[pytorch]" takes the same extras. There is no conda package. Inside a conda environment, use pip.

all_extras covers torch, lightning, matplotlib and rich. The Qiskit plugin is not part of it, because it needs Python 3.11 or newer. Install it through the qiskit extra on its own.

Quickstart

from sklearn.datasets import make_moons

import pyqit
from pyqit.ansatzes import SELAnsatz
from pyqit.core import AngleEmbedding
from pyqit.models import VQCClassifier

pyqit.set_seed(42)

X, y = make_moons(n_samples=200, noise=0.1, random_state=0)

# Nothing is split, normalized or prescaled until the Trainer calls setup().
dm = pyqit.DataModule(X, y, normalize="minmax", batch_size=16)

model = VQCClassifier(
    n_qubits=4,
    n_layers=3,
    ansatz=SELAnsatz,
    encoder=AngleEmbedding,
)

trainer = pyqit.Trainer(max_epochs=30, learning_rate=0.05)
history = trainer.fit(model, dm)

print(history.best_epoch, history.best_score)   # 22 0.0947
preds = trainer.predict(model, dm)              # runs on the test split

fit returns a TrainingHistory with one entry per epoch for train and validation loss and accuracy. The model draws its weights and reads the backend in __init__, so seed and pick the backend before you build it.

What is in the box

Each item links to its page in the docs.

• Backends. pyqit.set_backend("torch") moves training to PyTorch Lightning. Same model, same callbacks, same history. PyTorch Lightning settings go through Trainer(backend_kwargs=...).
• DataModule. Nothing runs until the Trainer asks. It splits, fits normalization on the train split only, and prescales inputs for the model's embedding.
• Callbacks. EarlyStopping and ModelCheckpoint work on both backends. Your own is a BaseCallback with up to three methods.
• Losses. mse, hinge, cross_entropy, or any callable.
• Barren-plateau check. Trainer(check_bp=True) samples gradients at random weights before training and tells you whether their variance sits above the theoretical floor.
• Pipelines. QuantumPipeline chains models or runs them as an ensemble.
• Devices. device= takes any PennyLane device name, plugins included. The PennyLane-Qiskit plugin is tested, and Trainer(verbose=2) prints which differentiation method a device gets.

Tutorials walk through a VQC end to end, callbacks and checkpoints and barren plateaus.

Contributing

Issues and pull requests are welcome. The contributing guide has the conventions.

pip install -e ".[dev,all_extras]"
python -m pytest -n auto
pre-commit run --all-files