Metadata-Version: 2.4
Name: psipose
Version: 0.1.4
Summary: Scikit-learn compatible quantum machine learning library powered by PennyLane
License-Expression: MIT
Project-URL: Homepage, https://github.com/dduyanhhoang/psipose
Project-URL: Repository, https://github.com/dduyanhhoang/psipose
Project-URL: Issues, https://github.com/dduyanhhoang/psipose/issues
Project-URL: Documentation, https://psipose.readthedocs.io/
Classifier: Development Status :: 3 - Alpha
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: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: scikit-learn>=1.2.0
Requires-Dist: pennylane>=0.40.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: hypothesis>=6.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0.0; extra == "docs"
Requires-Dist: pydata-sphinx-theme>=0.15.0; extra == "docs"
Requires-Dist: sphinx_design>=0.5.0; extra == "docs"
Dynamic: license-file

# psipose

[![Documentation](https://img.shields.io/badge/Documentation-ReadTheDocs-blue?logo=readthedocs)](https://psipose.readthedocs.io/)
[![GitHub](https://img.shields.io/badge/GitHub-dduyanhhoang/psipose-blue?logo=github)](https://github.com/dduyanhhoang/psipose)
[![PyPI](https://img.shields.io/pypi/v/psipose?logo=pypi)](https://pypi.org/project/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](.claude/SHIFTING.md) for details.

## Quick Start

### Installation

```bash
# With uv (recommended)
uv pip install psipose

# With pip
pip install psipose
```

### Your First Quantum Classifier

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

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

```python
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:

```python
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:

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

```bash
# Install with dev dependencies
uv sync --dev

# Install pre-commit hooks
pre-commit install
```

### Testing & Linting

```bash
# 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](LICENSE) for details.
