K-Means
Source header: cuvs/cluster/kmeans.hpp
Types
cluster::kmeans::base_params
Base structure for parameters that are common to all k-means algorithms
Fields
k-means hyperparameters
cluster::kmeans::params
Simple object to specify hyper-parameters to the kmeans algorithm.
Fields
cluster::kmeans::balanced_donor_selection
Donor selection strategy used by balanced k-means rebalancing.
Values
cluster::kmeans::kmeans_type
Type of k-means algorithm.
Values
k-means clustering APIs
cluster::kmeans::fit
Find clusters with k-means algorithm using batched processing of host data.
Runs on multiple GPUs when handle carries an SNMG clique (raft::resource::is_multi_gpu(handle)) or initialized RAFT comms (raft::resource::comms_initialized(handle)), and on a single GPU otherwise.
TODO: Evaluate replacing the extent type with int64_t. Reference issue: https://github.com/NVIDIA/cuvs/issues/1961
This overload supports out-of-core computation where the dataset resides on the host. Data is processed in batches, streaming from host to device. The batch size is controlled by params.device_buffer_samples. Multiple batches are double-buffered when an auxiliary stream is available. Without a stream pool, the fit uses one input buffer and remains correct but serialized. One auxiliary stream is sufficient to overlap transfer and compute. Pinned host memory is crucial for OOC performance: ordinary pageable or unregistered mmap-backed input degrades throughput rapidly.
A pool memory resource is optional but recommended, especially for repeated fits. Configure both pools before fit and before first using the handle’s workspace resources.
Multi-GPU dispatch is selected automatically based on the handle state:
- If
raft::resource::is_multi_gpu(handle)(cuVS SNMG): the full dataset X is split across GPUs internally with an OpenMP parallel region and NCCL. - If
raft::resource::comms_initialized(handle)(Dask/Ray/MPI): X is treated as this worker’s partition, and RAFT communicators are used for collectives. - Otherwise: single-GPU batched k-means.
With params.init == InitMethod::KMeansPlusPlus in multi-GPU mode, the effective initialization sample must fit in GPU memory on every rank because it is materialized on every device. Rank 0 must also have enough GPU memory for the seeding workspace before centroids are broadcast.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit
Find clusters with k-means algorithm using batched processing of host data.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit
Find clusters with k-means algorithm. Initial centroids are chosen with k-means++ algorithm. Empty clusters are reinitialized by choosing new centroids with k-means++ algorithm.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit
Find clusters with k-means algorithm. Initial centroids are chosen with k-means++ algorithm. Empty clusters are reinitialized by choosing new centroids with k-means++ algorithm.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit
Find clusters with k-means algorithm. Initial centroids are chosen with k-means++ algorithm. Empty clusters are reinitialized by choosing new centroids with k-means++ algorithm.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit
Find clusters with k-means algorithm. Initial centroids are chosen with k-means++ algorithm. Empty clusters are reinitialized by choosing new centroids with k-means++ algorithm.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit
Find clusters with k-means algorithm. Initial centroids are chosen with k-means++ algorithm. Empty clusters are reinitialized by choosing new centroids with k-means++ algorithm.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit
Find balanced clusters with k-means algorithm.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit
Find balanced clusters with k-means algorithm.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit
Find balanced clusters with k-means algorithm.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit
Find balanced clusters with k-means algorithm.
Note: When params.is_packed_binary is true, X.extent(1) counts packed bytes,
and centroids must have 8 * X.extent(1) floating-point coordinates. Bits are
expanded least-significant bit first to {-1, +1}; the selected metric operates
on those expanded vectors. CosineExpanded is not supported in packed binary mode.
With the flag disabled, uint8_t values are numeric.
Parameters
Returns
void
cluster::kmeans::predict
Predict the closest cluster each sample in X belongs to.
Parameters
Returns
void
Additional overload: cluster::kmeans::predict
Predict the closest cluster each sample in X belongs to.
Parameters
Returns
void
Additional overload: cluster::kmeans::predict
Predict the closest cluster each sample in X belongs to.
Parameters
Returns
void
Additional overload: cluster::kmeans::predict
Predict the closest cluster each sample in X belongs to.
Parameters
Returns
void
Additional overload: cluster::kmeans::predict
Predict the closest cluster each sample in X belongs to.
Parameters
Returns
void
Additional overload: cluster::kmeans::predict
Predict the closest cluster each sample in X belongs to.
Parameters
Returns
void
Additional overload: cluster::kmeans::predict
Predict the closest cluster each sample in X belongs to.
Parameters
Returns
void
Additional overload: cluster::kmeans::predict
Predict the closest cluster each sample in X belongs to.
Parameters
Returns
void
Additional overload: cluster::kmeans::predict
Predict the closest cluster each sample in X belongs to.
Parameters
Returns
void
Additional overload: cluster::kmeans::predict
Predict the closest cluster each sample in X belongs to.
Note: When params.is_packed_binary is true, X.extent(1) counts packed bytes,
and centroids must have 8 * X.extent(1) floating-point coordinates. Bits are
expanded least-significant bit first to {-1, +1}; the selected metric operates
on those expanded vectors. CosineExpanded is not supported in packed binary mode.
With the flag disabled, uint8_t values are numeric.
Parameters
Returns
void
cluster::kmeans::fit_predict
Compute k-means clustering and predicts cluster index for each sample in the input.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit_predict
Compute k-means clustering and predicts cluster index for each sample in the input.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit_predict
Compute k-means clustering and predicts cluster index for each sample in the input.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit_predict
Compute k-means clustering and predicts cluster index for each sample in the input.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit_predict
Compute balanced k-means clustering and predicts cluster index for each sample in the input.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit_predict
Compute balanced k-means clustering and predicts cluster index for each sample in the input.
Parameters
Returns
void
cluster::kmeans::transform
Transform X to a cluster-distance space.
Parameters
Returns
void
Additional overload: cluster::kmeans::transform
Transform X to a cluster-distance space.
Parameters
Returns
void
cluster::kmeans::cluster_cost
Compute (optionally weighted) cluster cost
Parameters
Returns
void
Additional overload: cluster::kmeans::cluster_cost
Compute cluster cost
Parameters
Returns
void
Additional overload: cluster::kmeans::cluster_cost
Compute (optionally weighted) cluster cost
Parameters
Returns
void
Additional overload: cluster::kmeans::cluster_cost
Compute (optionally weighted) cluster cost
Parameters
Returns
void
Multi-GPU / out-of-core k-means fit (multiple partitions per rank)
Additional overload: cluster::kmeans::fit
Multi-GPU k-means fit with one or more local data partitions per rank.
Each rank supplies its local training data as a vector of partitions. For host-resident partitions the implementation streams each partition using params.device_buffer_samples (per rank). For device-resident partitions device_buffer_samples is ignored and each local partition is processed in full. Host partitions spanning multiple batches are double-buffered when an auxiliary stream is available. Each rank needs one auxiliary stream for transfer/compute overlap; otherwise execution uses one input buffer and is correct but serialized. Pinned host memory is crucial: pageable or unregistered mmap-backed input degrades throughput rapidly. A per-device memory pool is also recommended. With raft::device_resources_snmg, configure these before fit with handle.set_stream_pool(1) and handle.set_memory_pool(percent); both calls apply the setting to every device managed by the handle. With independently managed per-rank resources, configure the stream pool and current RMM memory resource in each process.
The active backend is selected by the resources attached to handle:
- When
raft::resource::is_multi_gpu(handle)is true (SNMG clique), the call must be issued from inside an OpenMP region with one thread per rank in the clique. - Otherwise, multi-process NCCL comms must be initialized on the handle (
raft::resource::comms_initialized(handle)); each process supplies its own local partitions.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit
Multi-GPU k-means fit.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit
Multi-GPU k-means fit.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit
Multi-GPU k-means fit.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit
Multi-GPU / out-of-core k-means fit.
Parameters
Returns
void
Additional overload: cluster::kmeans::fit
Multi-GPU / out-of-core k-means fit.
Parameters
Returns
void
k-means API helpers
cluster::kmeans::helpers::find_k
Automatically find the optimal value of k using a binary search. This method maximizes the Calinski-Harabasz Index while minimizing the per-cluster inertia.
Parameters
Returns
void