clustor 0.1.0

Rust-accelerated high-performance clustering algorithms.

Clustor

Clustor is a Rust-accelerated clustering toolkit with a Python-first API built on PyO3 and maturin. It delivers fast, minimal-dependency implementations of common clustering algorithms and cluster validation metrics for use inside production data pipelines.

Clustor focuses on unsupervised learning primitives. Use it alongside dataset balancing tools when you need reweighting or resampling.

[!CAUTION] Active development. APIs may evolve before a 1.0 release.

Features

• KMeans and MiniBatchKMeans with KMeans++ initialization, n_init, Euclidean/Cosine metrics, optional normalization, sample_weight, and streaming partial_fit.
• BisectingKMeans for hierarchical top-down splitting.
• DBSCAN with noise labeling and core sample indices.
• OPTICS reachability ordering and core distances.
• Affinity Propagation for exemplar-based clustering.
• BIRCH streaming clustering using CF-tree summaries.
• GaussianMixture (EM, diagonal covariance): predict_proba, score_samples, score, aic, bic, sample, and model selection metrics.
• Cluster validation: Silhouette, Calinski–Harabasz, Davies–Bouldin.
• HAC linkage (dendrogram output) with SciPy-style linkage matrices.

Installation

Python (recommended)

Use a virtual environment, then install build tools and the package:

python -m venv .venv
. .venv/bin/activate
pip install -U pip
pip install -U maturin numpy
maturin develop --release

Local development

python -m venv .venv
. .venv/bin/activate
pip install -U pip
pip install -U maturin numpy pytest pre-commit
pre-commit run --all-files
maturin develop --release
pytest -q

Quick usage

import numpy as np
import clustor

X = np.vstack([np.random.randn(200, 2), np.random.randn(200, 2) + 6])

km = clustor.KMeans(n_clusters=2, n_init=10, random_state=0)
result = km.fit(X)
print(result["inertia"])

op = clustor.OPTICS(min_samples=10, max_eps=1.0)
res = op.fit(X)
print(res["reachability"].shape, res["ordering"].shape)

ap = clustor.AffinityPropagation(damping=0.7)
res = ap.fit(X)
print("clusters:", len(res["exemplars"]), "converged:", res["converged"])

br = clustor.Birch(threshold=0.7, branching_factor=30, n_clusters=2)
res = br.fit(X)
print(res["centers"].shape)

Z = clustor.hac_dendrogram(X, method="average", metric="euclidean")
print(Z.shape)  # (n-1, 4)

Advanced usage

Streaming MiniBatchKMeans

mb = clustor.MiniBatchKMeans(n_clusters=2, batch_size=2, max_steps=20, random_state=0)
mb.fit(X[:3])
mb.partial_fit(X[3:])
print(mb.predict(X))

Output:

[0 0 0 1 1 1]

GaussianMixture model selection metrics

gm = clustor.GaussianMixture(2, max_iter=50, tol=1e-4, random_state=0)
gm.fit(X)
print(gm.score_samples(X))
print(gm.score(X))
print(gm.aic(X))
print(gm.bic(X))

Output:

[-1.526949 -2.276946 -2.276946 -1.526949 -2.276946 -2.276946]
-2.026946850203142
42.3233622024377
40.4491974254902

Examples with outputs

The following examples use a fixed dataset and deterministic seeds to keep outputs stable.

import numpy as np
import clustor

np.set_printoptions(precision=6, suppress=True)
X = np.array(
    [
        [0.0, 0.0],
        [0.0, 1.0],
        [1.0, 0.0],
        [10.0, 10.0],
        [10.0, 11.0],
        [11.0, 10.0],
    ],
    dtype=np.float64,
)

KMeans

km = clustor.KMeans(n_clusters=2, n_init=1, max_iter=50, random_state=0)
km_out = km.fit(X)
print(km_out["centers"])
print(km_out["labels"])

Output:

[[10.333333 10.333333]
 [ 0.333333  0.333333]]
[1 1 1 0 0 0]

MiniBatchKMeans

mb = clustor.MiniBatchKMeans(n_clusters=2, batch_size=3, max_steps=200, random_state=0)
mb_out = mb.fit(X)
print(mb_out["centers"])
print(mb.predict(X))

Output:

[[10.374126 10.300699]
 [ 0.33121   0.321656]]
[1 1 1 0 0 0]

BisectingKMeans

bk = clustor.BisectingKMeans(n_clusters=2, n_init=1, max_iter=50, random_state=0)
bk_out = bk.fit(X)
print(bk_out["centers"])
print(bk.predict(X))

Output:

[[10.333333 10.333333]
 [ 0.333333  0.333333]]
[1 1 1 0 0 0]

DBSCAN

db = clustor.DBSCAN(eps=1.6, min_samples=2)
db_out = db.fit(X)
print(db_out["labels"])
print(db_out["core_sample_indices"])

Output:

[0 0 0 1 1 1]
[0 1 2 3 4 5]

OPTICS

opt = clustor.OPTICS(min_samples=2, max_eps=2.0)
opt_out = opt.fit(X)
print(opt_out["ordering"])
print(opt_out["reachability"])
print(opt_out["core_distances"])
print(opt_out["predecessor"])

Output:

[0 2 1 3 5 4]
[inf  1.  1. inf  1.  1.]
[1. 1. 1. 1. 1. 1.]
[-1  0  0 -1  3  3]

Affinity Propagation

ap = clustor.AffinityPropagation(damping=0.6, max_iter=200, convergence_iter=15)
ap_out = ap.fit(X)
print(ap_out["exemplars"])
print(ap_out["labels"])
print(ap_out["converged"])

Output:

[0 3]
[0 0 0 1 1 1]
True

Birch

br = clustor.Birch(threshold=1.5, branching_factor=10, n_clusters=2)
br_out = br.fit(X)
print(br_out["centers"])
print(br_out["labels"])
print(br_out["n_subclusters"])

Output:

[[10.333333 10.333333]
 [ 0.333333  0.333333]]
[1 1 1 0 0 0]
2

GaussianMixture

gm = clustor.GaussianMixture(2, max_iter=50, tol=1e-4, random_state=0)
gm_out = gm.fit(X)
print(gm_out["weights"])
print(gm_out["means"])
print(gm_out["covars"])
print(gm_out["converged"])

Output:

[0.5 0.5]
[[10.333333 10.333333]
 [ 0.333333  0.333333]]
[[0.222223 0.222223]
 [0.222223 0.222223]]
True

Validation metrics

labels = km_out["labels"]
print(clustor.silhouette_score(X, labels))
print(clustor.calinski_harabasz_score(X, labels))
print(clustor.davies_bouldin_score(X, labels))

Output:

0.9196222281154851
450.00000000000017
0.09249505911485287

HAC linkage

Z = clustor.hac_dendrogram(X, method="average", metric="euclidean")
print(Z)

Output:

[[ 0.        1.        1.        2.      ]
 [ 3.        4.        1.        2.      ]
 [ 6.        2.        1.207107  3.      ]
 [ 7.        5.        1.207107  3.      ]
 [ 8.        9.       14.165681  6.      ]]

API overview

Estimators

• KMeans, MiniBatchKMeans, BisectingKMeans
• DBSCAN
• OPTICS
• AffinityPropagation
• Birch
• GaussianMixture

All estimators accept NumPy arrays and return NumPy arrays for outputs. Methods that accept sample_weight validate length consistency with the input data.

Functional APIs

• kmeans, bisecting_kmeans, dbscan, gaussian_mixture
• optics, affinity_propagation, birch, hac_dendrogram

Metrics

• silhouette_score, calinski_harabasz_score, davies_bouldin_score

Data handling and performance

• Inputs are converted to contiguous float64 NumPy arrays for predictable performance.
• Heavy computation runs outside the Python GIL for improved multi-threaded throughput when Python threads are present.
• Algorithms are implemented in Rust with minimal dependencies to keep builds lightweight.

Example notebooks

Each notebook is executed with deterministic inputs and includes narrative context plus outputs.

• examples/01_kmeans_family.ipynb: KMeans, MiniBatchKMeans, and BisectingKMeans.
• examples/02_density_clustering.ipynb: DBSCAN and OPTICS.
• examples/03_affinity_birch.ipynb: Affinity Propagation and Birch.
• examples/04_gaussian_mixture_metrics.ipynb: GaussianMixture and validation metrics.
• examples/05_hac_linkage.ipynb: HAC linkage matrices.

Production readiness

• Deterministic results when random_state is provided, including in the notebooks.
• Strict input validation for shape mismatches, empty datasets, and invalid cluster counts.
• GIL-free Rust kernels for improved parallel throughput in Python pipelines.
• Typed Python API surface (py.typed) with docstrings that include args/returns/examples.

Edge cases and validation

• Estimators raise ValueError for empty inputs, invalid shapes, or non-positive n_clusters.
• Weight-aware estimators validate that sample_weight has the same length as X.
• MiniBatchKMeans.partial_fit requires a prior fit call and consistent feature dimensions.
• Validation metrics ignore noise labels (-1) and require at least two non-noise clusters; they raise ValueError when the input data or label configuration is invalid.

Testing and quality

• Rust tests: cargo test
• Python tests: pytest
• Linting and formatting: pre-commit run --all-files

Citation

If you use clustor in your work and wish to refer to it, please use the following BibTeX entry.

@software{clustor,
  author = {Soumyadip Sarkar},
  title = {Clustor: Rust-accelerated High-Performance Clustering Algorithms},
  year = {2026},
  url = {https://github.com/alphavelocity/clustor}
}

License

This project is licensed under the Apache License - see the LICENSE file for details.