Metadata-Version: 2.4
Name: psipose
Version: 0.1.0
Summary: Scikit-learn compatible quantum machine learning library powered by PennyLane
License-Expression: MIT
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.32.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: sphinx-rtd-theme>=1.3.0; extra == "docs"
Dynamic: license-file

# 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

```bash
# 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

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

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

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

### Regression with VQCRegressor

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

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:

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

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

### Running Tests

```bash
# 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

```bash
# 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

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

## License

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