Metadata-Version: 2.4
Name: pyqit
Version: 0.1.0
Summary: A high-level orchestration and pipeline framework for quantum machine learning
Author: Aryan Saini
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/phoeenniixx/pyQit
Project-URL: Documentation, https://pyqit.readthedocs.io/en/stable/
Project-URL: Source, https://github.com/phoeenniixx/pyQit
Project-URL: Changelog, https://github.com/phoeenniixx/pyQit/blob/main/CHANGELOG.md
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pennylane<0.46.0,>=0.42.0
Requires-Dist: numpy<3.0.0
Requires-Dist: pandas<3.1.0,>=2.3.3
Requires-Dist: scikit-learn<2.0,>=1.7.2
Requires-Dist: scikit-base<1.2.0
Provides-Extra: all-extras
Requires-Dist: torch!=2.0.1,<3.0.0,>=2.11.0; extra == "all-extras"
Requires-Dist: lightning; extra == "all-extras"
Requires-Dist: matplotlib; extra == "all-extras"
Requires-Dist: rich; extra == "all-extras"
Provides-Extra: pytorch
Requires-Dist: torch!=2.0.1,<3.0.0,>=2.11.0; extra == "pytorch"
Requires-Dist: lightning; extra == "pytorch"
Provides-Extra: qiskit
Requires-Dist: pennylane-qiskit; extra == "qiskit"
Provides-Extra: dev
Requires-Dist: pydocstyle; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: nbconvert; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: pydata-sphinx-theme; extra == "dev"
Requires-Dist: nbsphinx; extra == "dev"
Requires-Dist: myst-parser; extra == "dev"
Requires-Dist: ipywidgets<9.0.0,>=8.1.8; extra == "dev"
Requires-Dist: pytest-dotenv<1.0.0,>=0.5.2; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx<9.1.1,>3.2; extra == "docs"
Requires-Dist: pydata-sphinx-theme; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: nbconvert; extra == "docs"
Requires-Dist: ipywidgets<9.0.0,>=8.1.8; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: docutils; extra == "docs"
Provides-Extra: github-actions
Requires-Dist: pytest-github-actions-annotate-failures; extra == "github-actions"
Dynamic: license-file

<p align="center">
  <img src="docs/_static/pyqit-banner.png" alt="PyQit" width="320">
</p>

[![PyPI](https://img.shields.io/pypi/v/pyqit.svg)](https://pypi.org/project/pyqit/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
![Status: Active Development](https://img.shields.io/badge/status-active_development-orange.svg)
[![Docs](https://app.readthedocs.org/projects/pyqit/badge/?version=stable)](https://pyqit.readthedocs.io/en/stable/)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-261230.svg)](https://github.com/astral-sh/ruff)
[![Build Status](https://img.shields.io/github/actions/workflow/status/phoeenniixx/pyQit/test.yml)](https://github.com/phoeenniixx/pyqit/actions)

PyQit is a quantum machine learning framework built on
[PennyLane](https://docs.pennylane.ai/en/stable/). 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](https://pytorch.org/docs/stable/) and
[PyTorch Lightning](https://lightning.ai/docs/pytorch/stable/) 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](https://pyqit.readthedocs.io/en/stable/) has the tutorials, the API
reference and the design notes. This page is the short version.

## Installation

```bash
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

```python
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](https://pyqit.readthedocs.io/en/stable/api/trainer.html). `pyqit.set_backend("torch")` moves training to PyTorch Lightning. Same model, same callbacks, same history. PyTorch Lightning settings go through `Trainer(backend_kwargs=...)`.
- [DataModule](https://pyqit.readthedocs.io/en/stable/api/datamodule.html). Nothing runs until the Trainer asks. It splits, fits normalization on the train split only, and prescales inputs for the model's embedding.
- [Callbacks](https://pyqit.readthedocs.io/en/stable/api/callbacks.html). `EarlyStopping` and `ModelCheckpoint` work on both backends. Your own is a `BaseCallback` with up to three methods.
- [Losses](https://pyqit.readthedocs.io/en/stable/api/losses.html). `mse`, `hinge`, `cross_entropy`, or any callable.
- [Barren-plateau check](https://pyqit.readthedocs.io/en/stable/api/diagnostics.html). `Trainer(check_bp=True)` samples gradients at random weights before training and tells you whether their variance sits above the theoretical floor.
- [Pipelines](https://pyqit.readthedocs.io/en/stable/api/pipeline.html). `QuantumPipeline` chains models or runs them as an ensemble.
- [Devices](https://pyqit.readthedocs.io/en/stable/api/models.html#devices). `device=` takes any PennyLane device name, plugins included. The [PennyLane-Qiskit](https://docs.pennylane.ai/projects/qiskit/en/stable/) plugin is tested, and `Trainer(verbose=2)` prints which differentiation method a device gets.

Tutorials walk through a [VQC end to end](https://pyqit.readthedocs.io/en/stable/tutorials/vqc.html),
[callbacks and checkpoints](https://pyqit.readthedocs.io/en/stable/tutorials/callbacks.html)
and [barren plateaus](https://pyqit.readthedocs.io/en/stable/tutorials/barren_plateau.html).

## Contributing

Issues and pull requests are welcome. The
[contributing guide](https://pyqit.readthedocs.io/en/stable/contributing.html) has the
conventions.

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