clustering::KMeans< T, Algo, Seeder > Class Template Reference

Lloyd-family k-means. More...

#include <clustering/kmeans.h>

Public Member Functions
	KMeans (std::size_t k, std::size_t nJobs=0)
	Construct a reusable k-means fitter.
	KMeans (std::size_t k, std::size_t nJobs, math::OwnedPool &externalPool)
	Construct a reusable k-means fitter that borrows a caller-owned thread pool.
	KMeans (const KMeans &)=delete
KMeans &	operator= (const KMeans &)=delete
	KMeans (KMeans &&)=delete
KMeans &	operator= (KMeans &&)=delete
	~KMeans ()=default
void	run (const NDArray< T, 2 > &X, std::size_t maxIter=300, T tol=T{1e-4}, std::uint64_t seedFirst=0, std::size_t nInit=1)
	Fit to X with optional best-of-restarts.
const NDArray< std::int32_t, 1 > &	labels () const noexcept
	Length-n assignment; each entry is in [0, k).
const NDArray< T, 2, Layout::Contig > &	centroids () const noexcept
	k x d fitted centroids.
double	inertia () const noexcept
	Final inertia: Kahan-summed f64 total of per-point squared distance to assignment.
std::size_t	nIter () const noexcept
	Iterations executed before tol or maxIter fired.
bool	converged () const noexcept
	True iff the last run stopped because centroid shift fell at or below tol.
void	reset ()
	Release every scratch buffer. The next run call reallocates against its shape.

Detailed Description

template<class T, class Algo = kmeans::LloydFusedGemm<T>, class Seeder = kmeans::AutoSeeder<T>>
requires kmeans::LloydStrategy<Algo, T> && kmeans::SeederStrategy<Seeder, T>
class clustering::KMeans< T, Algo, Seeder >

Lloyd-family k-means.

The algorithm and seeder are template parameters with concept constraints. The default instantiation carries LloydFusedGemm<T> and AutoSeeder<T>, the latter picking between greedy k-means++ and AFK-MC2 against workload shape at run time. Callers who want to pin a specific combination spell it out, e.g. KMeans<float, LloydFusedGemm<float>, AfkMc2Seeder<float>>.

Note

KMeans does NOT own X. The caller must keep the NDArray alive for the lifetime of every run call on this instance. An n_init > 1 harness constructs KMeans once and calls run repeatedly against the same X so policy scratch amortizes across runs at a fixed (n, d, k, nJobs) tuple.

Template Parameters

T	Element type. Only float is supported; add a double specialization to extend.
Algo	Lloyd driver satisfying clustering::kmeans::LloydStrategy.
Seeder	Seeder satisfying clustering::kmeans::SeederStrategy.

Definition at line 38 of file kmeans.h.

Constructor & Destructor Documentation

KMeans() [1/4]

template<class T, class Algo = kmeans::LloydFusedGemm<T>, class Seeder = kmeans::AutoSeeder<T>>

clustering::KMeans< T, Algo, Seeder >::KMeans ( std::size_t k, std::size_t nJobs = 0 )

inlineexplicit

Construct a reusable k-means fitter.

Parameters

k	Number of clusters (>= 1).
nJobs	Worker count for the internal thread pool. A value of 0 is clamped upward to std::thread::hardware_concurrency() so the pool is always usable by the math::Pool helpers.

Definition at line 51 of file kmeans.h.

KMeans() [2/4]

template<class T, class Algo = kmeans::LloydFusedGemm<T>, class Seeder = kmeans::AutoSeeder<T>>

clustering::KMeans< T, Algo, Seeder >::KMeans ( std::size_t k, std::size_t nJobs, math::OwnedPool & externalPool )

inline

Construct a reusable k-means fitter that borrows a caller-owned thread pool.

Use when the caller wants to keep a private math::OwnedPool out of the process-wide shared registry (tests, multi-tenant scoping, embedded use). The pool must outlive every run call on this instance.

Definition at line 65 of file kmeans.h.

KMeans() [3/4]

template<class T, class Algo = kmeans::LloydFusedGemm<T>, class Seeder = kmeans::AutoSeeder<T>>

clustering::KMeans< T, Algo, Seeder >::KMeans ( const KMeans< T, Algo, Seeder > & )

delete

KMeans() [4/4]

template<class T, class Algo = kmeans::LloydFusedGemm<T>, class Seeder = kmeans::AutoSeeder<T>>

clustering::KMeans< T, Algo, Seeder >::KMeans ( KMeans< T, Algo, Seeder > && )

delete

~KMeans()

template<class T, class Algo = kmeans::LloydFusedGemm<T>, class Seeder = kmeans::AutoSeeder<T>>

clustering::KMeans< T, Algo, Seeder >::~KMeans ( )

default

Member Function Documentation

centroids()

template<class T, class Algo = kmeans::LloydFusedGemm<T>, class Seeder = kmeans::AutoSeeder<T>>

const NDArray< T, 2, Layout::Contig > & clustering::KMeans< T, Algo, Seeder >::centroids ( ) const

inlinenodiscardnoexcept

k x d fitted centroids.

Definition at line 159 of file kmeans.h.

converged()

template<class T, class Algo = kmeans::LloydFusedGemm<T>, class Seeder = kmeans::AutoSeeder<T>>

bool clustering::KMeans< T, Algo, Seeder >::converged ( ) const

inlinenodiscardnoexcept

True iff the last run stopped because centroid shift fell at or below tol.

Definition at line 167 of file kmeans.h.

inertia()

template<class T, class Algo = kmeans::LloydFusedGemm<T>, class Seeder = kmeans::AutoSeeder<T>>

double clustering::KMeans< T, Algo, Seeder >::inertia ( ) const

inlinenodiscardnoexcept

Final inertia: Kahan-summed f64 total of per-point squared distance to assignment.

Definition at line 163 of file kmeans.h.

labels()

template<class T, class Algo = kmeans::LloydFusedGemm<T>, class Seeder = kmeans::AutoSeeder<T>>

const NDArray< std::int32_t, 1 > & clustering::KMeans< T, Algo, Seeder >::labels ( ) const

inlinenodiscardnoexcept

Length-n assignment; each entry is in [0, k).

Definition at line 157 of file kmeans.h.

nIter()

template<class T, class Algo = kmeans::LloydFusedGemm<T>, class Seeder = kmeans::AutoSeeder<T>>

std::size_t clustering::KMeans< T, Algo, Seeder >::nIter ( ) const

inlinenodiscardnoexcept

Iterations executed before tol or maxIter fired.

Definition at line 165 of file kmeans.h.

operator=() [1/2]

template<class T, class Algo = kmeans::LloydFusedGemm<T>, class Seeder = kmeans::AutoSeeder<T>>

KMeans & clustering::KMeans< T, Algo, Seeder >::operator= ( const KMeans< T, Algo, Seeder > & )

delete

operator=() [2/2]

template<class T, class Algo = kmeans::LloydFusedGemm<T>, class Seeder = kmeans::AutoSeeder<T>>

KMeans & clustering::KMeans< T, Algo, Seeder >::operator= ( KMeans< T, Algo, Seeder > && )

delete

reset()

template<class T, class Algo = kmeans::LloydFusedGemm<T>, class Seeder = kmeans::AutoSeeder<T>>

void clustering::KMeans< T, Algo, Seeder >::reset ( )

inline

Release every scratch buffer. The next run call reallocates against its shape.

Definition at line 170 of file kmeans.h.

run()

template<class T, class Algo = kmeans::LloydFusedGemm<T>, class Seeder = kmeans::AutoSeeder<T>>

void clustering::KMeans< T, Algo, Seeder >::run ( const NDArray< T, 2 > & X, std::size_t maxIter = 300, T tol = T{1e-4}, std::uint64_t seedFirst = 0, std::size_t nInit = 1 )

inline

Fit to X with optional best-of-restarts.

Runs nInit independent restarts against the same data, each seeded as seedFirst, seedFirst+1, ..., seedFirst+nInit-1, and keeps the lowest-inertia outcome. nInit == 1 is the single-restart path; nInit > 1 matches the sklearn n_init convention and amortizes seeder, Lloyd-side scratch, and X-stats compute across all restarts inside one C++ call (the policy scratch persists across restarts on the same KMeans instance).

Parameters

X	Contiguous n x d dataset. The caller retains ownership; X must outlive this call.
maxIter	Iteration cap on each inner Lloyd loop.
tol	Convergence tolerance relative to the mean column variance of X (sklearn convention).
seedFirst	PRNG seed for the first restart. Identical (seedFirst, nInit, nJobs, X, maxIter, tol) produces bit-identical labels, centroids, and inertia at nJobs=1.
nInit	Number of independent restarts (>= 1). The accessor methods report the best (lowest-inertia) restart's labels, centroids, inertia, n_iter, and converged flag.

Warning

X must remain alive and unchanged for the full duration of this call.

Definition at line 101 of file kmeans.h.

---

The documentation for this class was generated from the following file:

• include/clustering/kmeans.h