psipose 1.0.1

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: psipose 1.0 provides a stable public API for the core feature maps, ansatze, estimators, kernels, preprocessing helpers, datasets, and training diagnostics documented below.

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
• PauliFeatureMap(reps=2) — Pauli-Z/ZZ feature map for fidelity kernels

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,
)

Training Diagnostics

psipose uses loguru for opt-in diagnostics. Library imports stay quiet by default.

from psipose import VQCClassifier, configure_logging, disable_logging

configure_logging(level="INFO")
clf = VQCClassifier(n_qubits=2, n_iter=20, verbose=True, log_every=5)
clf.fit(X_train, y_train)
disable_logging()

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

API Stability

psipose follows semantic versioning from 1.0.0 onward. Documented imports from psipose and public subpackages are treated as stable during the 1.x series. See the ReadTheDocs API stability guide for deprecation policy and scope.

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
│   ├── 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, loguru>=0.7.3
• Dev: pytest, ruff, pre-commit, mypy

License

MIT - see LICENSE for details.