falcondale 0.5.0

Falcondale SDK is an open source project that lowers the barrier for computer scientists and data scientists entering the field of Quantum Machine Learning. Bring a pandas DataFrame and try quantum feature selection, quantum classifiers and quantum clustering with a few lines of code, no quantum computing background or cloud account needed. Everything runs locally on simulators.

Installation

pip install "falcondale[all]"
# or
uv add "falcondale[all]"

The core only depends on numpy, pandas, scikit-learn, scipy and rich. Each family of techniques has its own extra (feature-selection, qml, clustering and tabular for tables with categories, text or dates), so you can install just the one you need, for example pip install "falcondale[clustering]".

Quickstart

from sklearn import datasets
from falcondale import Project

X, y = datasets.load_breast_cancer(return_X_y=True, as_frame=True)
data = X.assign(target=y)

project = Project(data, target="target")
project.profile_dataset()  # spot missing values, constant columns, class imbalance...
project.preprocess()  # fill gaps and scale features

# Pick the 3 most informative and least redundant features solving a QUBO
features = project.feature_selection(max_cols=3, method="sa")

# How well suited is the data for QML? Which model should go first?
project.assess().report()

# Train a Quantum Support Vector Classifier and compare it with a classical one
model = project.evaluate("qsvc")  # or evaluate("auto") for the one recommended by the assessment
baseline = project.evaluate("svc")
print(model.metric("auc"), baseline.metric("auc"))

model.print_report()
model.save("qsvc.pkl")

What is inside

Every model follows the scikit-learn estimator API, so you can also use them in your own pipelines. Run Project.list_options() to see what is available.

Quantum clustering can be fitted on a train split and assign unseen samples with their membership probabilities:

from falcondale.clustering import make_clustering_pipeline

pipeline = make_clustering_pipeline(components=6, random_state=101)  # imputation, scaling, PCA, APQC
pipeline.fit(train)
labels, probabilities = pipeline.predict(test), pipeline.predict_proba(test)

Documentation

The official documentation can be found at https://falcondale.readthedocs.io/en/latest/, including explanations of each technique and example notebooks.

Contributing

Contributions are welcome! Check the contributing guide to set up the development environment (uv, ruff, ty, pytest, pre-commit and commitizen) and the open issues for ideas. Please follow our Code of Conduct.

git clone https://github.com/Falcondale/falcondale-sdk.git
cd falcondale-sdk
uv sync --all-extras
uv run pre-commit install --install-hooks
uv run pytest -m "not slow"

Authors

Falcondale SDK is developed and maintained by Falcondale. Get in touch at info@falcondale.pro.

License

This project is licensed under the terms of the MIT license.