psipose 0.1.3

Scikit-learn compatible quantum machine learning library powered by PennyLane

psipose

A scikit-learn-compatible quantum machine learning library powered by PennyLane.

Drop in quantum estimators — classifiers, regressors, and kernels — that follow scikit-learn's API conventions. Use them seamlessly in existing sklearn workflows like Pipeline, GridSearchCV, and cross_val_score.

Note: This project is in early development (v0.1.x alpha). API may change.

Quick Start

Installation

# With uv (recommended)
uv pip install psipose

# With pip
pip install psipose

Your First Quantum Classifier

from psipose import VQCClassifier
from sklearn.datasets import make_moons
from sklearn.model_selection import train_test_split

# Generate data
X, y = make_moons(n_samples=100, noise=0.1)
X_train, X_test, y_train, y_test = train_test_split(X, y)

# Train quantum classifier
clf = VQCClassifier(n_qubits=2, n_iter=100, random_state=42)
clf.fit(X_train, y_train)

# Evaluate
print(f"Accuracy: {clf.score(X_test, y_test):.2%}")

Quantum Kernel SVM

from psipose import QSVC
from sklearn.datasets import make_circles

X, y = make_circles(n_samples=100, noise=0.1, factor=0.3)
X_train, X_test, y_train, y_test = train_test_split(X, y)

svc = QSVC(n_qubits=2, random_state=42)
svc.fit(X_train, y_train)

print(f"QSVC Accuracy: {svc.score(X_test, y_test):.2%}")

Quantum Regression

from psipose import VQCRegressor
from sklearn.datasets import make_regression

X, y = make_regression(n_samples=100, n_features=2, noise=0.1)
X_train, X_test, y_train, y_test = train_test_split(X, y)

reg = VQCRegressor(n_qubits=2, n_iter=100, random_state=42)
reg.fit(X_train, y_train)

print(f"R^2 score: {reg.score(X_test, y_test):.2%}")

Available Estimators

Estimator	Type	Description
VQCClassifier	Classifier	Variational Quantum Classifier with trainable ansatz
QSVC	Classifier	Quantum kernel SVM using fidelity-based kernels
VQCRegressor	Regressor	Variational Quantum Regressor for continuous outputs

Architecture

psipose uses composition over inheritance — estimators combine independent, swappable components:

Encoders map classical data to quantum states:

• AngleEncoder(rotation="Y") — one feature per qubit as a rotation angle
• AmplitudeEncoder() — encodes a 2**n_qubits-dim vector as a quantum state

Ansatze provide parameterized quantum circuits:

• HardwareEfficientAnsatz(n_qubits, layers) — alternating rotation + entanglement layers
• StronglyEntanglingAnsatz(n_qubits, layers) — PennyLane's StronglyEntanglingLayers

All components are composable — swap encoders and ansatze independently:

from psipose import VQCClassifier, AmplitudeEncoder, StronglyEntanglingAnsatz

clf = VQCClassifier(
    encoder=AmplitudeEncoder(),
    ansatz=StronglyEntanglingAnsatz(layers=3),
    n_qubits=2,
    n_iter=200,
)

Development

Setup

# Install with dev dependencies
uv sync --dev

# Install pre-commit hooks
pre-commit install

Testing & Linting

# Run tests (handles ROS plugin conflicts)
./scripts/test.sh

# Run fast tests only (skip slow)
pytest tests/ -k "not slow"

# Lint and format
uv run ruff check psipose tests
uv run ruff format psipose tests

Project Structure

psipose/
├── psipose/              # Main package
│   ├── __init__.py       # Public API exports
│   ├── base.py           # QuantumEstimator base class
│   ├── encoders/         # Data encoding circuits
│   ├── ansatze/          # Parameterized quantum circuits
│   ├── estimators/       # sklearn-compatible estimators
│   ├── kernels/          # Quantum kernels
│   └── utils/            # Utility helpers
├── tests/                # Test suite
├── docs/                 # Sphinx documentation
├── scripts/              # Development scripts
└── pyproject.toml        # Project configuration

Dependencies

• Required: pennylane>=0.40.0, numpy>=1.21.0, scikit-learn>=1.2.0
• Dev: pytest, ruff, pre-commit, mypy

Roadmap

• Phase 0: Project setup
• Phase 1: Minimal VQCClassifier
• Phase 2: Full VQCClassifier (multi-class, predict_proba)
• Phase 3: Quantum kernels (FidelityQuantumKernel, QSVC)
• Phase 4: Regression (VQCRegressor)
• Phase 5: Additional quantum kernels
• Phase 6: Hardware backend support

License

MIT - see LICENSE for details.