# TNO Quantum: ML - Clustering - Balanced K-Means
TNO Quantum provides generic software components aimed at facilitating the development
of quantum applications.
This package implements a QUBO based Balanced K-Means clustering algorithm.
The implementation has been done in accordance with the [scikit-learn estimator API](https://scikit-learn.org/stable/developers/develop.html), which means that the clustering algorithm can be used as any other scikit-learn
clustering algorithm and combined with transforms through
[Pipelines](https://scikit-learn.org/stable/modules/generated/sklearn.pipeline.Pipeline.html).
*Limitations in (end-)use: the content of this software package may solely be used for applications
that comply with international export control laws.*
## Documentation
Documentation of the `tno.quantum.ml.clustering.bkmeans` package can be found [here](https://tno-quantum.github.io/documentation/).
## Install
Easily install the `tno.quantum.ml.clustering.bkmeans` package using pip:
```console
$ python -m pip install tno.quantum.ml.clustering.bkmeans
```
## Example
The Balanced K-Means clustering can be used as shown in the following example.
- Note: This example requires `tno.quantum.optimization.solvers[dwave]` and `tno.quantum.ml.datasets` which can be installed along the package using:
```console
$ python -m pip install tno.quantum.ml.clustering.bkmeans[example]
```
```python
import matplotlib.pyplot as plt
import numpy as np
from tno.quantum.ml.clustering.bkmeans import QBKMeans
from tno.quantum.ml.datasets import get_blobs_clustering_dataset
# Generate sample data
n_centers = 4
X, true_labels = get_blobs_clustering_dataset(
n_samples=20, n_features=2, n_centers=n_centers
)
# Create QBKMeans object and fit
cluster_algo = QBKMeans(
n_clusters=n_centers,
solver_config={
"name": "simulated_annealing_solver",
"options": {"number_of_reads": 100},
},
)
pred_labels = cluster_algo.fit_predict(X)
# Plot results
fig, ax = plt.subplots(nrows=1, ncols=1)
unique_labels = np.unique(pred_labels)
colors = plt.cm.Spectral(np.linspace(0, 1, len(unique_labels)))
for k, col in zip(unique_labels, colors):
class_member_mask = cluster_algo.labels_ == k
xy = X[class_member_mask]
x, y = np.split(xy, 2, axis=1)
ax.plot(x, y, "o", mfc=tuple(col), mec="k", ms=6)
ax.set_title("Quantum BKMeans clustering")
plt.show()
```
Raw data
{
"_id": null,
"home_page": null,
"name": "tno.quantum.ml.clustering.bkmeans",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "TNO Quantum Code Lab <tnoquantum@tno.nl>",
"keywords": "TNO, Quantum, Balanced K-Means, Machine Learning",
"author": null,
"author_email": "TNO Quantum Code Lab <tnoquantum@tno.nl>",
"download_url": "https://files.pythonhosted.org/packages/7f/d6/e3259391259c9e6c724bb96f8754d0884796fd203fd5bcafb8b6c6dd5c20/tno_quantum_ml_clustering_bkmeans-2.0.3.tar.gz",
"platform": "any",
"description": "# TNO Quantum: ML - Clustering - Balanced K-Means\r\n\r\nTNO Quantum provides generic software components aimed at facilitating the development\r\nof quantum applications.\r\n\r\nThis package implements a QUBO based Balanced K-Means clustering algorithm.\r\nThe implementation has been done in accordance with the [scikit-learn estimator API](https://scikit-learn.org/stable/developers/develop.html), which means that the clustering algorithm can be used as any other scikit-learn\r\nclustering algorithm and combined with transforms through\r\n[Pipelines](https://scikit-learn.org/stable/modules/generated/sklearn.pipeline.Pipeline.html).\r\n\r\n\r\n*Limitations in (end-)use: the content of this software package may solely be used for applications \r\nthat comply with international export control laws.*\r\n\r\n## Documentation\r\n\r\nDocumentation of the `tno.quantum.ml.clustering.bkmeans` package can be found [here](https://tno-quantum.github.io/documentation/).\r\n\r\n\r\n## Install\r\n\r\nEasily install the `tno.quantum.ml.clustering.bkmeans` package using pip:\r\n\r\n```console\r\n$ python -m pip install tno.quantum.ml.clustering.bkmeans\r\n```\r\n\r\n## Example\r\n\r\nThe Balanced K-Means clustering can be used as shown in the following example.\r\n\r\n- Note: This example requires `tno.quantum.optimization.solvers[dwave]` and `tno.quantum.ml.datasets` which can be installed along the package using:\r\n\r\n ```console\r\n $ python -m pip install tno.quantum.ml.clustering.bkmeans[example]\r\n ```\r\n\r\n```python\r\nimport matplotlib.pyplot as plt\r\nimport numpy as np\r\n\r\nfrom tno.quantum.ml.clustering.bkmeans import QBKMeans\r\nfrom tno.quantum.ml.datasets import get_blobs_clustering_dataset\r\n\r\n# Generate sample data\r\nn_centers = 4\r\nX, true_labels = get_blobs_clustering_dataset(\r\n n_samples=20, n_features=2, n_centers=n_centers\r\n)\r\n\r\n# Create QBKMeans object and fit\r\ncluster_algo = QBKMeans(\r\n n_clusters=n_centers,\r\n solver_config={\r\n \"name\": \"simulated_annealing_solver\",\r\n \"options\": {\"number_of_reads\": 100},\r\n },\r\n)\r\npred_labels = cluster_algo.fit_predict(X)\r\n\r\n# Plot results\r\nfig, ax = plt.subplots(nrows=1, ncols=1)\r\nunique_labels = np.unique(pred_labels)\r\ncolors = plt.cm.Spectral(np.linspace(0, 1, len(unique_labels)))\r\nfor k, col in zip(unique_labels, colors):\r\n class_member_mask = cluster_algo.labels_ == k\r\n xy = X[class_member_mask]\r\n x, y = np.split(xy, 2, axis=1)\r\n ax.plot(x, y, \"o\", mfc=tuple(col), mec=\"k\", ms=6)\r\n\r\nax.set_title(\"Quantum BKMeans clustering\")\r\nplt.show()\r\n```\r\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "Quantum Balanced K-Means Clustering module",
"version": "2.0.3",
"project_urls": {
"Documentation": "https://github.com/TNO-Quantum/",
"Homepage": "https://github.com/TNO-Quantum/",
"Source": "https://github.com/TNO-Quantum/ml.clustering.bkmeans"
},
"split_keywords": [
"tno",
" quantum",
" balanced k-means",
" machine learning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cc8d21a568ab9a8c0603cb33efca0aace83f48137e53b7d700da5ac9fab1a007",
"md5": "85141c2aa36d0d9b741ba675b8588137",
"sha256": "80333b75d872642093234aa24725f9e25960b5835c2a510d9a5153bb4f10e7c5"
},
"downloads": -1,
"filename": "tno_quantum_ml_clustering_bkmeans-2.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "85141c2aa36d0d9b741ba675b8588137",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 29564,
"upload_time": "2025-10-20T08:38:01",
"upload_time_iso_8601": "2025-10-20T08:38:01.602591Z",
"url": "https://files.pythonhosted.org/packages/cc/8d/21a568ab9a8c0603cb33efca0aace83f48137e53b7d700da5ac9fab1a007/tno_quantum_ml_clustering_bkmeans-2.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7fd6e3259391259c9e6c724bb96f8754d0884796fd203fd5bcafb8b6c6dd5c20",
"md5": "4f25e65b27b78692321548551620149e",
"sha256": "cf3f672c46d1f7e7a7c252f74f1ef97409212d41212f7e25471b1918a938dadc"
},
"downloads": -1,
"filename": "tno_quantum_ml_clustering_bkmeans-2.0.3.tar.gz",
"has_sig": false,
"md5_digest": "4f25e65b27b78692321548551620149e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 31396,
"upload_time": "2025-10-20T08:38:02",
"upload_time_iso_8601": "2025-10-20T08:38:02.652767Z",
"url": "https://files.pythonhosted.org/packages/7f/d6/e3259391259c9e6c724bb96f8754d0884796fd203fd5bcafb8b6c6dd5c20/tno_quantum_ml_clustering_bkmeans-2.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 08:38:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TNO-Quantum",
"github_project": "ml.clustering.bkmeans",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "tno.quantum.ml.clustering.bkmeans"
}
JSON
