psipose 0.1.0

Scikit-learn compatible quantum machine learning library powered by PennyLane

psipose

Scikit-learn compatible quantum machine learning library powered by PennyLane.

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

Quick Start

Installation

# Clone and enter the directory
git clone https://github.com/dduyanhhoang/psipose.git
cd psipose

# Install dependencies with uv
uv sync --dev

# Or with pip
pip install -e ".[dev]"

Classification with VQCClassifier

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

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

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

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

Quantum Kernel SVM (QSVC)

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)

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

Regression with VQCRegressor

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)

score = reg.score(X_test, y_test)
print(f"R^2 score: {score:.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

Encoders & Ansatze

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 dependencies (including dev)
uv sync --dev

# Install pre-commit hooks
pre-commit install

Running Tests

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

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

# Run a single test file
pytest tests/test_vqc_regressor.py

Linting and Formatting

# Check linting
uv run ruff check psipose tests

# Format code
uv run ruff format psipose tests

# Or use the scripts
./scripts/lint.sh
./scripts/format.sh

Project Structure

psipose/
├── psipose/              # Main package
│   ├── __init__.py       # Public API exports
│   ├── base.py           # QuantumEstimator base class (sklearn BaseEstimator)
│   ├── encoders/         # Data encoding circuits
│   │   ├── _base.py      # BaseEncoder abstract class
│   │   ├── angle.py      # AngleEncoder (RY/RX/RZ rotations)
│   │   └── amplitude.py  # AmplitudeEncoder (state amplitude encoding)
│   ├── ansatze/          # Parameterized quantum circuits
│   │   ├── _base.py      # BaseAnsatz abstract class
│   │   ├── hardware_efficient.py  # HardwareEfficientAnsatz
│   │   └── strongly_entangling.py # StronglyEntanglingAnsatz
│   ├── estimators/       # sklearn-compatible estimators
│   │   ├── vqc.py        # VQCClassifier (binary & multi-class)
│   │   ├── qsvc.py       # QSVC (quantum kernel SVM)
│   │   └── vqc_regressor.py  # VQCRegressor (quantum regression)
│   ├── kernels/          # Quantum kernels
│   │   └── fidelity.py   # FidelityQuantumKernel (kernel matrix via fidelity)
│   └── utils/            # Utility helpers
├── tests/                # Test suite organized by module
├── scripts/              # Development shell scripts
│   ├── clean_commit.sh   # Automated conventional commit script
│   ├── format.sh         # Format code with ruff
│   ├── lint.sh           # Lint check with ruff
│   ├── setup-hooks.sh    # Install git hooks
│   └── test.sh           # Run tests (handles ROS conflicts)
├── .github/workflows/    # CI configuration
└── pyproject.toml        # Project metadata, dependencies, tool configs

Dependencies

• Required: pennylane, numpy, scikit-learn
• Dev: pytest, pytest-cov, ruff, pre-commit, mypy

Roadmap

• Phase 0: Project setup
• Phase 1: Minimal VQCClassifier (AngleEncoder + HardwareEfficientAnsatz)
• Phase 2: Full VQCClassifier (multi-class, predict_proba)
• Phase 3: Quantum kernels (FidelityQuantumKernel, QSVC)
• Phase 4: Regression (VQCRegressor)

License

MIT - see LICENSE for details.