Quickstart

import numpy as np
from geokmeans import GeoKMeans

X = np.random.default_rng(0).random((1000, 20))

km = GeoKMeans(n_clusters=8, algorithm="geo", random_state=0).fit(X)

km.labels_                    # cluster index per point
km.cluster_centers_           # centroids
km.n_iter_                    # iterations to convergence
km.n_distance_calculations_   # distance computations performed

km.predict(np.random.random((5, 20)))   # assign new points

Choosing an algorithm

Pass algorithm= to select a variant. All produce the same clustering for a given seed:

"geo" (default), "lloyd", "elkan", "hamerly", "annulus", "exponion", "ball".

Long-running jobs

The compute runs in C++ with the GIL released, so a long fit does not freeze the interpreter and can run off the main thread:

from concurrent.futures import ProcessPoolExecutor

def cluster(X):
    return GeoKMeans(n_clusters=50, random_state=0).fit(X)

with ProcessPoolExecutor() as pool:
    result = pool.submit(cluster, X).result()

Pass verbose=True to stream convergence progress.