geokmeans.GeoKMeans

class geokmeans.GeoKMeans(n_clusters=8, *, algorithm='geo', max_iter=300, tol=0.0001, random_state=None, verbose=False)[source]

k-means clustering with a choice of acceleration algorithm.

All seven algorithms compute the same Lloyd’s k-means solution; they differ only in how aggressively they prune distance computations. "geo" (Geometric-k-means) is the bound-free method from Sharma et al. (2026).

Parameters:

  • n_clusters (int, default=8) – Number of clusters k.

  • algorithm (str, default="geo") – One of geokmeans.ALGORITHMS: "geo", "lloyd", "elkan", "hamerly", "annulus", "exponion", "ball".

  • max_iter (int, default=300) – Maximum number of iterations.

  • tol (float, default=1e-4) – Convergence threshold on centroid movement between iterations.

  • random_state (int or None, default=None) – Seed for centroid initialisation. None draws a fresh random seed.

  • verbose (bool, default=False) – If True, stream the C++ routine’s progress messages to stdout.

cluster_centers_
Type:

ndarray of shape (n_clusters, n_features)

labels_

0-based cluster index for each training point.

Type:

ndarray of shape (n_samples,)

n_iter_

Iterations run before convergence.

Type:

int

n_distance_calculations_

Point-to-centroid distance computations performed (the efficiency metric the algorithms optimise).

Type:

int

Examples

>>> import numpy as np
>>> from geokmeans import GeoKMeans
>>> X = np.random.default_rng(0).random((100, 5))
>>> km = GeoKMeans(n_clusters=3, algorithm="geo", random_state=0).fit(X)
>>> km.labels_.shape
(100,)
__init__(n_clusters=8, *, algorithm='geo', max_iter=300, tol=0.0001, random_state=None, verbose=False)[source]
Parameters:
Return type:

None

Methods

__init__([n_clusters, algorithm, max_iter, ...])

fit(X[, y])

Compute clustering and store results on self.

fit_predict(X[, y])

Fit, then return the training labels.

predict(X)

Assign each row of X to the nearest fitted centroid.