⚛️ QFlow

scikit-learn for Quantum Machine Learning

QFlow is an open-source Python framework that makes quantum machine learning as easy as scikit-learn. All quantum complexity — qubits, circuits, gates, encodings, ansatz, optimizers, and backends — is handled automatically. You focus on your ML problem.

✨ Quickstart

from qflow import Classifier

model = Classifier()
model.fit(X_train, y_train)
predictions = model.predict(X_test)
accuracy = model.score(X_test, y_test)

That's it. No quantum knowledge required.

📦 Installation

pip install qflow-ml

From source:

git clone https://github.com/qflow-ml/qflow.git
cd qflow
pip install -e ".[dev]"

🔬 Features

📖 Examples

Classification

from qflow import Classifier
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from sklearn.preprocessing import StandardScaler

X, y = load_iris(return_X_y=True)
# Use 2 classes for binary classification
mask = y < 2
X, y = X[mask], y[mask]

X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)
scaler = StandardScaler()
X_train = scaler.fit_transform(X_train)
X_test = scaler.transform(X_test)

model = Classifier(n_layers=3, optimizer="adam", max_iter=100)
model.fit(X_train, y_train)
print(f"Accuracy: {model.score(X_test, y_test):.2%}")

Regression

from qflow import Regressor
import numpy as np

X = np.linspace(0, 2*np.pi, 80).reshape(-1, 1)
y = np.sin(X).ravel()

reg = Regressor()
reg.fit(X[:60], y[:60])
preds = reg.predict(X[60:])

Dimensionality Reduction

from qflow import Transformer

transformer = Transformer(n_components=2)
X_reduced = transformer.fit_transform(X_train)

Scikit-learn Integration

from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.model_selection import GridSearchCV
from qflow import Classifier

pipe = Pipeline([
    ("scaler", StandardScaler()),
    ("qclf", Classifier()),
])

param_grid = {"qclf__n_layers": [1, 2, 3], "qclf__optimizer": ["adam", "cobyla"]}
grid = GridSearchCV(pipe, param_grid, cv=3)
grid.fit(X_train, y_train)

Visualization

from qflow import Classifier
from qflow.visualization import plot_training_history, plot_circuit

model = Classifier()
model.fit(X_train, y_train)

plot_training_history(model)   # Loss/accuracy curves
plot_circuit(model)            # Circuit diagram

🏗️ Architecture

qflow/
├── Classifier         ← Public API
├── Regressor          ← Public API
├── Transformer        ← Public API
├── core/
│   ├── auto_config    ← Automatic hyperparameter selection
│   ├── circuit_builder← PennyLane circuit construction
│   ├── optimizer      ← Optimizer factory
│   └── measurement    ← Measurement strategies
├── encodings/         ← Angle, Amplitude, IQP
├── ansatz/            ← StronglyEntangling, HardwareEfficient, BasicEntangler
├── backends/          ← PennyLane (default), Qiskit (planned)
└── visualization/     ← Training plots, circuit diagrams

🔧 Advanced Usage

Custom configuration

from qflow import Classifier
from qflow.encodings import AmplitudeEncoding
from qflow.ansatz import HardwareEfficientAnsatz
from qflow.backends import PennyLaneBackend

model = Classifier(
    encoding="amplitude",
    ansatz="hardware_efficient",
    n_layers=4,
    optimizer="adam",
    learning_rate=0.01,
    max_iter=200,
    backend="pennylane",
    random_state=42,
)
model.fit(X_train, y_train)

Multiclass classification

model = Classifier(strategy="one_vs_rest")   # OvR decomposition
model.fit(X_train, y_train)                  # y_train can have > 2 classes

🤝 Contributing

See CONTRIBUTING.md. All contributions welcome!

git clone https://github.com/qflow-ml/qflow.git
cd qflow
pip install -e ".[dev]"
pre-commit install
pytest

📄 License

Apache 2.0 — see LICENSE.

🔗 Related Work

• PennyLane — Differentiable quantum computing
• Qiskit Machine Learning
• TensorFlow Quantum