psipose 0.1.4

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.

Version 0.1.4 introduces a major architectural refactor with new layered structure, FeatureMap naming (renamed from Encoder), and additional modules. See SHIFTING.md for details.

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:

Feature Maps map classical data to quantum states:

• AngleFeatureMap(rotation="Y") — one feature per qubit as a rotation angle
• AmplitudeFeatureMap() — 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

Measurements define how to extract classical values:

• PauliZExpectation() — expectation of Pauli-Z on first qubit (default)
• ProbabilityMeasurement() — full probability distribution

All components are composable — swap feature maps, ansatze, and measurements independently:

from psipose import VQCClassifier
from psipose.feature_maps import AmplitudeFeatureMap
from psipose.ansatze import StronglyEntanglingAnsatz

clf = VQCClassifier(
    feature_map=AmplitudeFeatureMap(),
    ansatz=StronglyEntanglingAnsatz(layers=3),
    n_qubits=2,
    n_iter=200,
)

Advanced: Pure Quantum Models

For research use cases, VariationalModel and QuantumKernel provide pure quantum models without sklearn dependencies:

from psipose import VariationalModel, AngleFeatureMap, StronglyEntanglingAnsatz, PauliZExpectation

model = VariationalModel(
    feature_map=AngleFeatureMap(),
    ansatz=StronglyEntanglingAnsatz(n_qubits=4, layers=2),
    measurement=PauliZExpectation(),
    n_iter=100,
)
model.fit(X_train, y_train)
predictions = model.predict(X_test)

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
│   ├── core/             # Protocols and utilities
│   │   ├── protocols.py  # FeatureMap, Ansatz, Measurement protocols
│   │   ├── circuit.py    # Circuit composition helpers
│   │   └── device.py     # Device management
│   ├── feature_maps/     # Data encoding
│   │   ├── base.py       # FeatureMap ABC
│   │   ├── angle.py      # AngleFeatureMap
│   │   ├── amplitude.py  # AmplitudeFeatureMap
│   │   └── pauli.py      # PauliFeatureMap (placeholder)
│   ├── ansatze/          # Parameterized circuits
│   │   ├── base.py       # Ansatz ABC
│   │   ├── hardware_efficient.py
│   │   └── strongly_entangling.py
│   ├── measurements/     # Quantum measurements
│   │   ├── base.py       # Measurement ABC
│   │   ├── expectation.py # PauliZExpectation, etc.
│   │   └── probability.py # ProbabilityMeasurement
│   ├── models/           # Pure quantum models
│   │   ├── variational.py # VariationalModel
│   │   └── kernel.py     # QuantumKernel
│   ├── training/         # Training utilities
│   │   ├── loss.py       # Loss functions
│   │   └── optimizer.py  # Optimizer adapter
│   ├── estimators/       # Sklearn-facing estimators
│   │   ├── base.py       # QuantumEstimator
│   │   ├── classification.py # VQCClassifier, QSVC
│   │   └── regression.py # VQCRegressor
│   ├── preprocessing/    # Sklearn transformers
│   │   ├── angle_scaler.py
│   │   └── amplitude_normalizer.py
│   └── datasets/         # QML datasets
│       ├── bars_and_stripes.py
│       ├── ad_hoc.py
│       └── quantum_moons.py
├── 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

License

MIT - see LICENSE for details.