Metadata-Version: 2.4
Name: psipose
Version: 0.1.3
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"
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.

## 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:

**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:

```python
from psipose import VQCClassifier, AmplitudeEncoder, StronglyEntanglingAnsatz

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

## 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
│   ├── 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

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

## License

MIT - see [LICENSE](LICENSE) for details.
