Skip to navigation

K-Means

View as Markdown

Source header: cuvs/cluster/kmeans.hpp

Types

cluster::kmeans::base_params

Base structure for parameters that are common to all k-means algorithms

struct base_params {
cuvs::distance::DistanceType metric;
};

Fields

NameTypeDescription
metriccuvs::distance::DistanceTypeMetric to use for distance computation. The supported metrics can vary per algorithm.

k-means hyperparameters

cluster::kmeans::params

Simple object to specify hyper-parameters to the kmeans algorithm.

struct params : base_params {
int n_clusters;
InitMethod init;
int max_iter;
double tol;
rapids_logger::level_enum verbosity;
raft::random::RngState rng_state;
int n_init;
double oversampling_factor;
int batch_samples;
int batch_centroids;
int64_t init_size;
int64_t device_buffer_samples;
};

Fields

NameTypeDescription
n_clustersintThe number of clusters to form as well as the number of centroids to generate (default:8).
initInitMethodMethod for initialization, defaults to k-means++:
- InitMethod::KMeansPlusPlus (k-means++): Use scalable k-means++ algorithm to select the initial cluster centers.
- InitMethod::Random (random): Choose ‘n_clusters’ observations (rows) at random from the input data for the initial centroids.
- InitMethod::Array (ndarray): Use ‘centroids’ as initial cluster centers.
max_iterintMaximum number of iterations of the k-means algorithm for a single run.
toldoubleRelative tolerance with regards to inertia to declare convergence.
verbosityrapids_logger::level_enumverbosity level.
rng_stateraft::random::RngStateSeed to the random number generator.
n_initintNumber of instance k-means algorithm will be run with different seeds.
oversampling_factordoubleOversampling factor for use in the k-means|| algorithm.

In the single-GPU path the value 0 is overloaded as an algorithm switch that selects the classic sequential k-means++ instead of the scalable variant. Any value > 0 is used as-is.

In the multi-GPU path (a fit call issued with a multi-GPU handle and device-resident inputs) any value < 1.0 (including 0) is internally clamped to 1.0. Values >= 1.0 are passed through unchanged.
batch_samplesintbatch_samples and batch_centroids are used to tile 1NN computation which is useful to optimize/control the memory footprint
Default tile is [batch_samples x n_clusters] i.e. when batch_centroids is 0 then don’t tile the centroids

NB: These parameters are unrelated to device_buffer_samples, which specifies the number of training vectors that get buffered on device when the training vectors are passed in on host.
batch_centroidsintif 0 then batch_centroids = n_clusters
init_sizeint64_tNumber of samples to randomly draw for the KMeansPlusPlus initialization step. A random subset of this size is used for centroid seeding.

Only applies when dataset is on host; for device data the full dataset is always used for seeding and this parameter is ignored.

When set to 0 (default) with host data uses min(3 * n_clusters, n_samples) as a default.

In Batched multi-GPU host-data fits, the effective KMeansPlusPlus initialization sample is materialized on device on every rank. Every rank must have enough GPU memory for this sample, and rank 0 must also have enough GPU memory for the seeding workspace.

Default: 0.
device_buffer_samplesint64_tNumber of samples to process per GPU batch when fitting with host data. When set to 0, defaults to n_samples (process all at once). Only used by the batched (host-data) code path and ignored by device-data overloads.

Inputs spanning multiple batches are double-buffered when the handle has an auxiliary stream, and use one buffer otherwise. Budget about device_buffer_samples * n_features * sizeof(value_type) bytes per input buffer, plus algorithm workspaces. Sample weights require the same number of additional buffers with device_buffer_samples * sizeof(value_type) bytes each.

In multi-GPU mode this is a per-rank batch size: each rank processes up to this many local samples per batch, clamped to that rank’s local sample count. This is ignored by device-data overloads.
Default: 0 (process all data at once).

cluster::kmeans::balanced_donor_selection

Donor selection strategy used by balanced k-means rebalancing.

enum class balanced_donor_selection {
SizeSorted = 0,
Random = 1
};

Values

NameValue
SizeSorted0
Random1

cluster::kmeans::kmeans_type

Type of k-means algorithm.

enum class kmeans_type {
KMeans = 0,
KMeansBalanced = 1
};

Values

NameValue
KMeans0
KMeansBalanced1

k-means clustering APIs

cluster::kmeans::fit

Find clusters with k-means algorithm using batched processing of host data.

void fit(raft::resources const& handle,
const cuvs::cluster::kmeans::params& params,
raft::host_matrix_view<const float, int64_t> X,
std::optional<raft::host_vector_view<const float, int64_t>> sample_weight,
raft::device_matrix_view<float, int64_t> centroids,
raft::host_scalar_view<float> inertia,
raft::host_scalar_view<int64_t> n_iter);

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

NameDirectionTypeDescription
handleinraft::resources const&The raft handle. When a multi-GPU resource is attached, multi-GPU dispatch is used automatically.
paramsinconst cuvs::cluster::kmeans::params&Parameters for KMeans model. Batch size is read from params.device_buffer_samples.
Xinraft::host_matrix_view<const float, int64_t>Training instances on HOST memory. The data must be in row-major format. [dim = n_samples x n_features]
sample_weightinstd::optional<raft::host_vector_view<const float, int64_t>>Optional weights for each observation in X (on host). [len = n_samples]
centroidsinoutraft::device_matrix_view<float, int64_t>[in] When init is InitMethod::Array, use centroids as the initial cluster centers. [out] The generated centroids from the kmeans algorithm are stored at the address pointed by ‘centroids’. [dim = n_clusters x n_features]
inertiaoutraft::host_scalar_view<float>Sum of squared distances of samples to their closest cluster center.
n_iteroutraft::host_scalar_view<int64_t>Number of iterations run.

Returns

void

Additional overload: cluster::kmeans::fit

Find clusters with k-means algorithm using batched processing of host data.

void fit(raft::resources const& handle,
const cuvs::cluster::kmeans::params& params,
raft::host_matrix_view<const double, int64_t> X,
std::optional<raft::host_vector_view<const double, int64_t>> sample_weight,
raft::device_matrix_view<double, int64_t> centroids,
raft::host_scalar_view<double> inertia,
raft::host_scalar_view<int64_t> n_iter);

Parameters

NameDirectionTypeDescription
handleraft::resources const&
paramsconst cuvs::cluster::kmeans::params&
Xraft::host_matrix_view<const double, int64_t>
sample_weightstd::optional<raft::host_vector_view<const double, int64_t>>
centroidsraft::device_matrix_view<double, int64_t>
inertiaraft::host_scalar_view<double>
n_iterraft::host_scalar_view<int64_t>

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.

void fit(raft::resources const& handle,
const cuvs::cluster::kmeans::params& params,
raft::device_matrix_view<const float, int> X,
std::optional<raft::device_vector_view<const float, int>> sample_weight,
raft::device_matrix_view<float, int> centroids,
raft::host_scalar_view<float> inertia,
raft::host_scalar_view<int> n_iter);

Parameters

NameDirectionTypeDescription
handleinraft::resources const&The raft handle.
paramsinconst cuvs::cluster::kmeans::params&Parameters for KMeans model.
Xinraft::device_matrix_view<const float, int>Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features]
sample_weightinstd::optional<raft::device_vector_view<const float, int>>Optional weights for each observation in X. [len = n_samples]
centroidsinoutraft::device_matrix_view<float, int>[in] When init is InitMethod::Array, use centroids as the initial cluster centers. [out] The generated centroids from the kmeans algorithm are stored at the address pointed by ‘centroids’. [dim = n_clusters x n_features]
inertiaoutraft::host_scalar_view<float>Sum of squared distances of samples to their closest cluster center.
n_iteroutraft::host_scalar_view<int>Number of iterations run.

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.

void fit(raft::resources const& handle,
const cuvs::cluster::kmeans::params& params,
raft::device_matrix_view<const float, int64_t> X,
std::optional<raft::device_vector_view<const float, int64_t>> sample_weight,
raft::device_matrix_view<float, int64_t> centroids,
raft::host_scalar_view<float> inertia,
raft::host_scalar_view<int64_t> n_iter);

Parameters

NameDirectionTypeDescription
handleinraft::resources const&The raft handle.
paramsinconst cuvs::cluster::kmeans::params&Parameters for KMeans model.
Xinraft::device_matrix_view<const float, int64_t>Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features]
sample_weightinstd::optional<raft::device_vector_view<const float, int64_t>>Optional weights for each observation in X. [len = n_samples]
centroidsinoutraft::device_matrix_view<float, int64_t>[in] When init is InitMethod::Array, use centroids as the initial cluster centers. [out] The generated centroids from the kmeans algorithm are stored at the address pointed by ‘centroids’. [dim = n_clusters x n_features]
inertiaoutraft::host_scalar_view<float>Sum of squared distances of samples to their closest cluster center.
n_iteroutraft::host_scalar_view<int64_t>Number of iterations run.

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.

void fit(raft::resources const& handle,
const cuvs::cluster::kmeans::params& params,
raft::device_matrix_view<const double, int> X,
std::optional<raft::device_vector_view<const double, int>> sample_weight,
raft::device_matrix_view<double, int> centroids,
raft::host_scalar_view<double> inertia,
raft::host_scalar_view<int> n_iter);

Parameters

NameDirectionTypeDescription
handleinraft::resources const&The raft handle.
paramsinconst cuvs::cluster::kmeans::params&Parameters for KMeans model.
Xinraft::device_matrix_view<const double, int>Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features]
sample_weightinstd::optional<raft::device_vector_view<const double, int>>Optional weights for each observation in X. [len = n_samples]
centroidsinoutraft::device_matrix_view<double, int>[in] When init is InitMethod::Array, use centroids as the initial cluster centers. [out] The generated centroids from the kmeans algorithm are stored at the address pointed by ‘centroids’. [dim = n_clusters x n_features]
inertiaoutraft::host_scalar_view<double>Sum of squared distances of samples to their closest cluster center.
n_iteroutraft::host_scalar_view<int>Number of iterations run.

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.

void fit(raft::resources const& handle,
const cuvs::cluster::kmeans::params& params,
raft::device_matrix_view<const double, int64_t> X,
std::optional<raft::device_vector_view<const double, int64_t>> sample_weight,
raft::device_matrix_view<double, int64_t> centroids,
raft::host_scalar_view<double> inertia,
raft::host_scalar_view<int64_t> n_iter);

Parameters

NameDirectionTypeDescription
handleinraft::resources const&The raft handle.
paramsinconst cuvs::cluster::kmeans::params&Parameters for KMeans model.
Xinraft::device_matrix_view<const double, int64_t>Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features]
sample_weightinstd::optional<raft::device_vector_view<const double, int64_t>>Optional weights for each observation in X. [len = n_samples]
centroidsinoutraft::device_matrix_view<double, int64_t>[in] When init is InitMethod::Array, use centroids as the initial cluster centers. [out] The generated centroids from the kmeans algorithm are stored at the address pointed by ‘centroids’. [dim = n_clusters x n_features]
inertiaoutraft::host_scalar_view<double>Sum of squared distances of samples to their closest cluster center.
n_iteroutraft::host_scalar_view<int64_t>Number of iterations run.

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.

void fit(raft::resources const& handle,
const cuvs::cluster::kmeans::params& params,
raft::device_matrix_view<const int8_t, int> X,
std::optional<raft::device_vector_view<const int8_t, int>> sample_weight,
raft::device_matrix_view<int8_t, int> centroids,
raft::host_scalar_view<int8_t> inertia,
raft::host_scalar_view<int> n_iter);

Parameters

NameDirectionTypeDescription
handleinraft::resources const&The raft handle.
paramsinconst cuvs::cluster::kmeans::params&Parameters for KMeans model.
Xinraft::device_matrix_view<const int8_t, int>Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features]
sample_weightinstd::optional<raft::device_vector_view<const int8_t, int>>Optional weights for each observation in X. [len = n_samples]
centroidsinoutraft::device_matrix_view<int8_t, int>[in] When init is InitMethod::Array, use centroids as the initial cluster centers. [out] The generated centroids from the kmeans algorithm are stored at the address pointed by ‘centroids’. [dim = n_clusters x n_features]
inertiaoutraft::host_scalar_view<int8_t>Sum of squared distances of samples to their closest cluster center.
n_iteroutraft::host_scalar_view<int>Number of iterations run.

Returns

void

Additional overload: cluster::kmeans::fit

Find balanced clusters with k-means algorithm.

void fit(const raft::resources& handle,
cuvs::cluster::kmeans::balanced_params const& params,
raft::device_matrix_view<const float, int64_t> X,
raft::device_matrix_view<float, int64_t> centroids,
std::optional<raft::host_scalar_view<float>> inertia = std::nullopt);

Parameters

NameDirectionTypeDescription
handleinconst raft::resources&The raft handle.
paramsincuvs::cluster::kmeans::balanced_params const&Parameters for KMeans model.
Xinraft::device_matrix_view<const float, int64_t>Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features]
centroidsoutraft::device_matrix_view<float, int64_t>[out] The generated centroids from the kmeans algorithm are stored at the address pointed by ‘centroids’. [dim = n_clusters x n_features]
inertiaoutstd::optional<raft::host_scalar_view<float>>Sum of squared distances of samples to their closest cluster center.
Default: std::nullopt.

Returns

void

Additional overload: cluster::kmeans::fit

Find balanced clusters with k-means algorithm.

void fit(const raft::resources& handle,
cuvs::cluster::kmeans::balanced_params const& params,
raft::device_matrix_view<const int8_t, int64_t> X,
raft::device_matrix_view<float, int64_t> centroids,
std::optional<raft::host_scalar_view<float>> inertia = std::nullopt);

Parameters

NameDirectionTypeDescription
handleinconst raft::resources&The raft handle.
paramsincuvs::cluster::kmeans::balanced_params const&Parameters for KMeans model.
Xinraft::device_matrix_view<const int8_t, int64_t>Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features]
centroidsinoutraft::device_matrix_view<float, int64_t>[out] The generated centroids from the kmeans algorithm are stored at the address pointed by ‘centroids’. [dim = n_clusters x n_features]
inertiaoutstd::optional<raft::host_scalar_view<float>>Sum of squared distances of samples to their closest cluster center.
Default: std::nullopt.

Returns

void

Additional overload: cluster::kmeans::fit

Find balanced clusters with k-means algorithm.

void fit(const raft::resources& handle,
cuvs::cluster::kmeans::balanced_params const& params,
raft::device_matrix_view<const half, int64_t> X,
raft::device_matrix_view<float, int64_t> centroids,
std::optional<raft::host_scalar_view<float>> inertia = std::nullopt);

Parameters

NameDirectionTypeDescription
handleinconst raft::resources&The raft handle.
paramsincuvs::cluster::kmeans::balanced_params const&Parameters for KMeans model.
Xinraft::device_matrix_view<const half, int64_t>Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features]
centroidsinoutraft::device_matrix_view<float, int64_t>[out] The generated centroids from the kmeans algorithm are stored at the address pointed by ‘centroids’. [dim = n_clusters x n_features]
inertiaoutstd::optional<raft::host_scalar_view<float>>Sum of squared distances of samples to their closest cluster center.
Default: std::nullopt.

Returns

void

Additional overload: cluster::kmeans::fit

Find balanced clusters with k-means algorithm.

void fit(const raft::resources& handle,
cuvs::cluster::kmeans::balanced_params const& params,
raft::device_matrix_view<const uint8_t, int64_t> X,
raft::device_matrix_view<float, int64_t> centroids,
std::optional<raft::host_scalar_view<float>> inertia = std::nullopt);

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

NameDirectionTypeDescription
handleinconst raft::resources&The raft handle.
paramsincuvs::cluster::kmeans::balanced_params const&Parameters for KMeans model.
Xinraft::device_matrix_view<const uint8_t, int64_t>Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features]
centroidsinoutraft::device_matrix_view<float, int64_t>[out] The generated centroids from the kmeans algorithm are stored at the address pointed by ‘centroids’. [dim = n_clusters x n_features]
inertiaoutstd::optional<raft::host_scalar_view<float>>Sum of squared distances of samples to their closest cluster center.
Default: std::nullopt.

Returns

void

cluster::kmeans::predict

Predict the closest cluster each sample in X belongs to.

void predict(raft::resources const& handle,
const kmeans::params& params,
raft::device_matrix_view<const float, int> X,
std::optional<raft::device_vector_view<const float, int>> sample_weight,
raft::device_matrix_view<const float, int> centroids,
raft::device_vector_view<int, int> labels,
bool normalize_weight,
raft::host_scalar_view<float> inertia);

Parameters

NameDirectionTypeDescription
handleinraft::resources const&The raft handle.
paramsinconst kmeans::params&Parameters for KMeans model.
Xinraft::device_matrix_view<const float, int>New data to predict. [dim = n_samples x n_features]
sample_weightinstd::optional<raft::device_vector_view<const float, int>>Optional weights for each observation in X. [len = n_samples]
centroidsinraft::device_matrix_view<const float, int>Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features]
labelsoutraft::device_vector_view<int, int>Index of the cluster each sample in X belongs to. [len = n_samples]
normalize_weightinboolTrue if the weights should be normalized
inertiaoutraft::host_scalar_view<float>Sum of squared distances of samples to their closest cluster center.

Returns

void

Additional overload: cluster::kmeans::predict

Predict the closest cluster each sample in X belongs to.

void predict(raft::resources const& handle,
const kmeans::params& params,
raft::device_matrix_view<const float, int64_t> X,
std::optional<raft::device_vector_view<const float, int64_t>> sample_weight,
raft::device_matrix_view<const float, int64_t> centroids,
raft::device_vector_view<int64_t, int64_t> labels,
bool normalize_weight,
raft::host_scalar_view<float> inertia);

Parameters

NameDirectionTypeDescription
handleinraft::resources const&The raft handle.
paramsinconst kmeans::params&Parameters for KMeans model.
Xinraft::device_matrix_view<const float, int64_t>New data to predict. [dim = n_samples x n_features]
sample_weightinstd::optional<raft::device_vector_view<const float, int64_t>>Optional weights for each observation in X. [len = n_samples]
centroidsinraft::device_matrix_view<const float, int64_t>Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features]
labelsoutraft::device_vector_view<int64_t, int64_t>Index of the cluster each sample in X belongs to. [len = n_samples]
normalize_weightinboolTrue if the weights should be normalized
inertiaoutraft::host_scalar_view<float>Sum of squared distances of samples to their closest cluster center.

Returns

void

Additional overload: cluster::kmeans::predict

Predict the closest cluster each sample in X belongs to.

void predict(raft::resources const& handle,
const kmeans::params& params,
raft::device_matrix_view<const double, int> X,
std::optional<raft::device_vector_view<const double, int>> sample_weight,
raft::device_matrix_view<const double, int> centroids,
raft::device_vector_view<int, int> labels,
bool normalize_weight,
raft::host_scalar_view<double> inertia);

Parameters

NameDirectionTypeDescription
handleinraft::resources const&The raft handle.
paramsinconst kmeans::params&Parameters for KMeans model.
Xinraft::device_matrix_view<const double, int>New data to predict. [dim = n_samples x n_features]
sample_weightinstd::optional<raft::device_vector_view<const double, int>>Optional weights for each observation in X. [len = n_samples]
centroidsinraft::device_matrix_view<const double, int>Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features]
labelsoutraft::device_vector_view<int, int>Index of the cluster each sample in X belongs to. [len = n_samples]
normalize_weightinboolTrue if the weights should be normalized
inertiaoutraft::host_scalar_view<double>Sum of squared distances of samples to their closest cluster center.

Returns

void

Additional overload: cluster::kmeans::predict

Predict the closest cluster each sample in X belongs to.

void predict(raft::resources const& handle,
const kmeans::params& params,
raft::device_matrix_view<const double, int64_t> X,
std::optional<raft::device_vector_view<const double, int64_t>> sample_weight,
raft::device_matrix_view<const double, int64_t> centroids,
raft::device_vector_view<int64_t, int64_t> labels,
bool normalize_weight,
raft::host_scalar_view<double> inertia);

Parameters

NameDirectionTypeDescription
handleinraft::resources const&The raft handle.
paramsinconst kmeans::params&Parameters for KMeans model.
Xinraft::device_matrix_view<const double, int64_t>New data to predict. [dim = n_samples x n_features]
sample_weightinstd::optional<raft::device_vector_view<const double, int64_t>>Optional weights for each observation in X. [len = n_samples]
centroidsinraft::device_matrix_view<const double, int64_t>Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features]
labelsoutraft::device_vector_view<int64_t, int64_t>Index of the cluster each sample in X belongs to. [len = n_samples]
normalize_weightinboolTrue if the weights should be normalized
inertiaoutraft::host_scalar_view<double>Sum of squared distances of samples to their closest cluster center.

Returns

void

Additional overload: cluster::kmeans::predict

Predict the closest cluster each sample in X belongs to.

void predict(const raft::resources& handle,
cuvs::cluster::kmeans::balanced_params const& params,
raft::device_matrix_view<const int8_t, int64_t> X,
raft::device_matrix_view<const float, int64_t> centroids,
raft::device_vector_view<uint32_t, int64_t> labels);

Parameters

NameDirectionTypeDescription
handleinconst raft::resources&The raft handle.
paramsincuvs::cluster::kmeans::balanced_params const&Parameters for KMeans model.
Xinraft::device_matrix_view<const int8_t, int64_t>New data to predict. [dim = n_samples x n_features]
centroidsinraft::device_matrix_view<const float, int64_t>Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features]
labelsoutraft::device_vector_view<uint32_t, int64_t>Index of the cluster each sample in X belongs to. [len = n_samples]

Returns

void

Additional overload: cluster::kmeans::predict

Predict the closest cluster each sample in X belongs to.

void predict(const raft::resources& handle,
cuvs::cluster::kmeans::balanced_params const& params,
raft::device_matrix_view<const int8_t, int64_t> X,
raft::device_matrix_view<const float, int64_t> centroids,
raft::device_vector_view<int, int64_t> labels);

Parameters

NameDirectionTypeDescription
handleinconst raft::resources&The raft handle.
paramsincuvs::cluster::kmeans::balanced_params const&Parameters for KMeans model.
Xinraft::device_matrix_view<const int8_t, int64_t>New data to predict. [dim = n_samples x n_features]
centroidsinraft::device_matrix_view<const float, int64_t>Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features]
labelsoutraft::device_vector_view<int, int64_t>Index of the cluster each sample in X belongs to. [len = n_samples]

Returns

void

Additional overload: cluster::kmeans::predict

Predict the closest cluster each sample in X belongs to.

void predict(const raft::resources& handle,
cuvs::cluster::kmeans::balanced_params const& params,
raft::device_matrix_view<const float, int64_t> X,
raft::device_matrix_view<const float, int64_t> centroids,
raft::device_vector_view<int, int64_t> labels);

Parameters

NameDirectionTypeDescription
handleinconst raft::resources&The raft handle.
paramsincuvs::cluster::kmeans::balanced_params const&Parameters for KMeans model.
Xinraft::device_matrix_view<const float, int64_t>New data to predict. [dim = n_samples x n_features]
centroidsinraft::device_matrix_view<const float, int64_t>Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features]
labelsoutraft::device_vector_view<int, int64_t>Index of the cluster each sample in X belongs to. [len = n_samples]

Returns

void

Additional overload: cluster::kmeans::predict

Predict the closest cluster each sample in X belongs to.

void predict(const raft::resources& handle,
cuvs::cluster::kmeans::balanced_params const& params,
raft::device_matrix_view<const float, int64_t> X,
raft::device_matrix_view<const float, int64_t> centroids,
raft::device_vector_view<uint32_t, int64_t> labels);

Parameters

NameDirectionTypeDescription
handleinconst raft::resources&The raft handle.
paramsincuvs::cluster::kmeans::balanced_params const&Parameters for KMeans model.
Xinraft::device_matrix_view<const float, int64_t>New data to predict. [dim = n_samples x n_features]
centroidsinraft::device_matrix_view<const float, int64_t>Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features]
labelsoutraft::device_vector_view<uint32_t, int64_t>Index of the cluster each sample in X belongs to. [len = n_samples]

Returns

void

Additional overload: cluster::kmeans::predict

Predict the closest cluster each sample in X belongs to.

void predict(const raft::resources& handle,
cuvs::cluster::kmeans::balanced_params const& params,
raft::device_matrix_view<const half, int64_t> X,
raft::device_matrix_view<const float, int64_t> centroids,
raft::device_vector_view<uint32_t, int64_t> labels);

Parameters

NameDirectionTypeDescription
handleinconst raft::resources&The raft handle.
paramsincuvs::cluster::kmeans::balanced_params const&Parameters for KMeans model.
Xinraft::device_matrix_view<const half, int64_t>New data to predict. [dim = n_samples x n_features]
centroidsinraft::device_matrix_view<const float, int64_t>Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features]
labelsoutraft::device_vector_view<uint32_t, int64_t>Index of the cluster each sample in X belongs to. [len = n_samples]

Returns

void

Additional overload: cluster::kmeans::predict

Predict the closest cluster each sample in X belongs to.

void predict(const raft::resources& handle,
cuvs::cluster::kmeans::balanced_params const& params,
raft::device_matrix_view<const uint8_t, int64_t> X,
raft::device_matrix_view<const float, int64_t> centroids,
raft::device_vector_view<uint32_t, int64_t> labels);

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

NameDirectionTypeDescription
handleinconst raft::resources&The raft handle.
paramsincuvs::cluster::kmeans::balanced_params const&Parameters for KMeans model.
Xinraft::device_matrix_view<const uint8_t, int64_t>New data to predict. [dim = n_samples x n_features]
centroidsinraft::device_matrix_view<const float, int64_t>Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features]
labelsoutraft::device_vector_view<uint32_t, int64_t>Index of the cluster each sample in X belongs to. [len = n_samples]

Returns

void

cluster::kmeans::fit_predict

Compute k-means clustering and predicts cluster index for each sample in the input.

void fit_predict(raft::resources const& handle,
const kmeans::params& params,
raft::device_matrix_view<const float, int> X,
std::optional<raft::device_vector_view<const float, int>> sample_weight,
std::optional<raft::device_matrix_view<float, int>> centroids,
raft::device_vector_view<int, int> labels,
raft::host_scalar_view<float> inertia,
raft::host_scalar_view<int> n_iter);

Parameters

NameDirectionTypeDescription
handleinraft::resources const&The raft handle.
paramsinconst kmeans::params&Parameters for KMeans model.
Xinraft::device_matrix_view<const float, int>Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features]
sample_weightinstd::optional<raft::device_vector_view<const float, int>>Optional weights for each observation in X. [len = n_samples]
centroidsinoutstd::optional<raft::device_matrix_view<float, int>>Optional [in] When init is InitMethod::Array, use centroids as the initial cluster centers [out] The generated centroids from the kmeans algorithm are stored at the address pointed by ‘centroids’. [dim = n_clusters x n_features]
labelsoutraft::device_vector_view<int, int>Index of the cluster each sample in X belongs to. [len = n_samples]
inertiaoutraft::host_scalar_view<float>Sum of squared distances of samples to their closest cluster center.
n_iteroutraft::host_scalar_view<int>Number of iterations run.

Returns

void

Additional overload: cluster::kmeans::fit_predict

Compute k-means clustering and predicts cluster index for each sample in the input.

void fit_predict(raft::resources const& handle,
const kmeans::params& params,
raft::device_matrix_view<const float, int64_t> X,
std::optional<raft::device_vector_view<const float, int64_t>> sample_weight,
std::optional<raft::device_matrix_view<float, int64_t>> centroids,
raft::device_vector_view<int64_t, int64_t> labels,
raft::host_scalar_view<float> inertia,
raft::host_scalar_view<int64_t> n_iter);

Parameters

NameDirectionTypeDescription
handleinraft::resources const&The raft handle.
paramsinconst kmeans::params&Parameters for KMeans model.
Xinraft::device_matrix_view<const float, int64_t>Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features]
sample_weightinstd::optional<raft::device_vector_view<const float, int64_t>>Optional weights for each observation in X. [len = n_samples]
centroidsinoutstd::optional<raft::device_matrix_view<float, int64_t>>Optional [in] When init is InitMethod::Array, use centroids as the initial cluster centers [out] The generated centroids from the kmeans algorithm are stored at the address pointed by ‘centroids’. [dim = n_clusters x n_features]
labelsoutraft::device_vector_view<int64_t, int64_t>Index of the cluster each sample in X belongs to. [len = n_samples]
inertiaoutraft::host_scalar_view<float>Sum of squared distances of samples to their closest cluster center.
n_iteroutraft::host_scalar_view<int64_t>Number of iterations run.

Returns

void

Additional overload: cluster::kmeans::fit_predict

Compute k-means clustering and predicts cluster index for each sample in the input.

void fit_predict(raft::resources const& handle,
const kmeans::params& params,
raft::device_matrix_view<const double, int> X,
std::optional<raft::device_vector_view<const double, int>> sample_weight,
std::optional<raft::device_matrix_view<double, int>> centroids,
raft::device_vector_view<int, int> labels,
raft::host_scalar_view<double> inertia,
raft::host_scalar_view<int> n_iter);

Parameters

NameDirectionTypeDescription
handleinraft::resources const&The raft handle.
paramsinconst kmeans::params&Parameters for KMeans model.
Xinraft::device_matrix_view<const double, int>Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features]
sample_weightinstd::optional<raft::device_vector_view<const double, int>>Optional weights for each observation in X. [len = n_samples]
centroidsinoutstd::optional<raft::device_matrix_view<double, int>>Optional [in] When init is InitMethod::Array, use centroids as the initial cluster centers [out] The generated centroids from the kmeans algorithm are stored at the address pointed by ‘centroids’. [dim = n_clusters x n_features]
labelsoutraft::device_vector_view<int, int>Index of the cluster each sample in X belongs to. [len = n_samples]
inertiaoutraft::host_scalar_view<double>Sum of squared distances of samples to their closest cluster center.
n_iteroutraft::host_scalar_view<int>Number of iterations run.

Returns

void

Additional overload: cluster::kmeans::fit_predict

Compute k-means clustering and predicts cluster index for each sample in the input.

void fit_predict(raft::resources const& handle,
const kmeans::params& params,
raft::device_matrix_view<const double, int64_t> X,
std::optional<raft::device_vector_view<const double, int64_t>> sample_weight,
std::optional<raft::device_matrix_view<double, int64_t>> centroids,
raft::device_vector_view<int64_t, int64_t> labels,
raft::host_scalar_view<double> inertia,
raft::host_scalar_view<int64_t> n_iter);

Parameters

NameDirectionTypeDescription
handleinraft::resources const&The raft handle.
paramsinconst kmeans::params&Parameters for KMeans model.
Xinraft::device_matrix_view<const double, int64_t>Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features]
sample_weightinstd::optional<raft::device_vector_view<const double, int64_t>>Optional weights for each observation in X. [len = n_samples]
centroidsinoutstd::optional<raft::device_matrix_view<double, int64_t>>Optional [in] When init is InitMethod::Array, use centroids as the initial cluster centers [out] The generated centroids from the kmeans algorithm are stored at the address pointed by ‘centroids’. [dim = n_clusters x n_features]
labelsoutraft::device_vector_view<int64_t, int64_t>Index of the cluster each sample in X belongs to. [len = n_samples]
inertiaoutraft::host_scalar_view<double>Sum of squared distances of samples to their closest cluster center.
n_iteroutraft::host_scalar_view<int64_t>Number of iterations run.

Returns

void

Additional overload: cluster::kmeans::fit_predict

Compute balanced k-means clustering and predicts cluster index for each sample in the input.

void fit_predict(const raft::resources& handle,
cuvs::cluster::kmeans::balanced_params const& params,
raft::device_matrix_view<const float, int64_t> X,
raft::device_matrix_view<float, int64_t> centroids,
raft::device_vector_view<uint32_t, int64_t> labels);

Parameters

NameDirectionTypeDescription
handleinconst raft::resources&The raft handle.
paramsincuvs::cluster::kmeans::balanced_params const&Parameters for KMeans model.
Xinraft::device_matrix_view<const float, int64_t>Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features]
centroidsinoutraft::device_matrix_view<float, int64_t>Optional [in] When init is InitMethod::Array, use centroids as the initial cluster centers [out] The generated centroids from the kmeans algorithm are stored at the address pointed by ‘centroids’. [dim = n_clusters x n_features]
labelsoutraft::device_vector_view<uint32_t, int64_t>Index of the cluster each sample in X belongs to. [len = n_samples]

Returns

void

Additional overload: cluster::kmeans::fit_predict

Compute balanced k-means clustering and predicts cluster index for each sample in the input.

void fit_predict(const raft::resources& handle,
cuvs::cluster::kmeans::balanced_params const& params,
raft::device_matrix_view<const int8_t, int64_t> X,
raft::device_matrix_view<float, int64_t> centroids,
raft::device_vector_view<uint32_t, int64_t> labels);

Parameters

NameDirectionTypeDescription
handleinconst raft::resources&The raft handle.
paramsincuvs::cluster::kmeans::balanced_params const&Parameters for KMeans model.
Xinraft::device_matrix_view<const int8_t, int64_t>Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features]
centroidsinoutraft::device_matrix_view<float, int64_t>Optional [in] When init is InitMethod::Array, use centroids as the initial cluster centers [out] The generated centroids from the kmeans algorithm are stored at the address pointed by ‘centroids’. [dim = n_clusters x n_features]
labelsoutraft::device_vector_view<uint32_t, int64_t>Index of the cluster each sample in X belongs to. [len = n_samples]

Returns

void

cluster::kmeans::transform

Transform X to a cluster-distance space.

void transform(raft::resources const& handle,
const kmeans::params& params,
raft::device_matrix_view<const float, int> X,
raft::device_matrix_view<const float, int> centroids,
raft::device_matrix_view<float, int> X_new);

Parameters

NameDirectionTypeDescription
handleinraft::resources const&The raft handle.
paramsinconst kmeans::params&Parameters for KMeans model.
Xinraft::device_matrix_view<const float, int>Training instances to cluster. The data must be in row-major format [dim = n_samples x n_features]
centroidsinraft::device_matrix_view<const float, int>Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features]
X_newoutraft::device_matrix_view<float, int>X transformed in the new space. [dim = n_samples x n_features]

Returns

void

Additional overload: cluster::kmeans::transform

Transform X to a cluster-distance space.

void transform(raft::resources const& handle,
const kmeans::params& params,
raft::device_matrix_view<const double, int> X,
raft::device_matrix_view<const double, int> centroids,
raft::device_matrix_view<double, int> X_new);

Parameters

NameDirectionTypeDescription
handleinraft::resources const&The raft handle.
paramsinconst kmeans::params&Parameters for KMeans model.
Xinraft::device_matrix_view<const double, int>Training instances to cluster. The data must be in row-major format [dim = n_samples x n_features]
centroidsinraft::device_matrix_view<const double, int>Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features]
X_newoutraft::device_matrix_view<double, int>X transformed in the new space. [dim = n_samples x n_features]

Returns

void

cluster::kmeans::cluster_cost

Compute (optionally weighted) cluster cost

void cluster_cost(
const raft::resources& handle,
raft::device_matrix_view<const float, int> X,
raft::device_matrix_view<const float, int> centroids,
raft::host_scalar_view<float> cost,
std::optional<raft::device_vector_view<const float, int>> sample_weight = std::nullopt);

Parameters

NameDirectionTypeDescription
handleinconst raft::resources&The raft handle
Xinraft::device_matrix_view<const float, int>Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features]
centroidsinraft::device_matrix_view<const float, int>Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features]
costoutraft::host_scalar_view<float>Resulting cluster cost
sample_weightinstd::optional<raft::device_vector_view<const float, int>>Optional per-sample weights. [len = n_samples]
Default: std::nullopt.

Returns

void

Additional overload: cluster::kmeans::cluster_cost

Compute cluster cost

void cluster_cost(
const raft::resources& handle,
raft::device_matrix_view<const double, int> X,
raft::device_matrix_view<const double, int> centroids,
raft::host_scalar_view<double> cost,
std::optional<raft::device_vector_view<const double, int>> sample_weight = std::nullopt);

Parameters

NameDirectionTypeDescription
handleinconst raft::resources&The raft handle
Xinraft::device_matrix_view<const double, int>Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features]
centroidsinraft::device_matrix_view<const double, int>Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features]
costoutraft::host_scalar_view<double>Resulting cluster cost
sample_weightinstd::optional<raft::device_vector_view<const double, int>>Optional per-sample weights. [len = n_samples]
Default: std::nullopt.

Returns

void

Additional overload: cluster::kmeans::cluster_cost

Compute (optionally weighted) cluster cost

void cluster_cost(
const raft::resources& handle,
raft::device_matrix_view<const float, int64_t> X,
raft::device_matrix_view<const float, int64_t> centroids,
raft::host_scalar_view<float> cost,
std::optional<raft::device_vector_view<const float, int64_t>> sample_weight = std::nullopt);

Parameters

NameDirectionTypeDescription
handleinconst raft::resources&The raft handle
Xinraft::device_matrix_view<const float, int64_t>Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features]
centroidsinraft::device_matrix_view<const float, int64_t>Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features]
costoutraft::host_scalar_view<float>Resulting cluster cost
sample_weightinstd::optional<raft::device_vector_view<const float, int64_t>>Optional per-sample weights. [len = n_samples]
Default: std::nullopt.

Returns

void

Additional overload: cluster::kmeans::cluster_cost

Compute (optionally weighted) cluster cost

void cluster_cost(
const raft::resources& handle,
raft::device_matrix_view<const double, int64_t> X,
raft::device_matrix_view<const double, int64_t> centroids,
raft::host_scalar_view<double> cost,
std::optional<raft::device_vector_view<const double, int64_t>> sample_weight = std::nullopt);

Parameters

NameDirectionTypeDescription
handleinconst raft::resources&The raft handle
Xinraft::device_matrix_view<const double, int64_t>Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features]
centroidsinraft::device_matrix_view<const double, int64_t>Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features]
costoutraft::host_scalar_view<double>Resulting cluster cost
sample_weightinstd::optional<raft::device_vector_view<const double, int64_t>>Optional per-sample weights. [len = n_samples]
Default: std::nullopt.

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.

void fit(
raft::resources const& handle,
const cuvs::cluster::kmeans::params& params,
const std::vector<raft::device_matrix_view<const float, int>>& X_parts,
const std::optional<std::vector<raft::device_vector_view<const float, int>>>& sample_weight_parts,
raft::device_matrix_view<float, int> centroids,
raft::host_scalar_view<float> inertia,
raft::host_scalar_view<int> n_iter);

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

NameDirectionTypeDescription
handleinraft::resources const&The raft handle. Must have NCCL comms or a SNMG clique initialized.
paramsinconst cuvs::cluster::kmeans::params&K-means parameters. For host-resident partitions the per-rank streaming batch size is read from params.device_buffer_samples; it is ignored for device-resident partitions.
X_partsinconst std::vector<raft::device_matrix_view<const float, int>>&Per-partition local data on this rank. Each entry is [n_rows_i x n_features].
sample_weight_partsinconst std::optional<std::vector<raft::device_vector_view<const float, int>>>&Optional per-partition row weights with one vector per data partition.
centroidsinoutraft::device_matrix_view<float, int>Device matrix [n_clusters x n_features]. On entry, used as the initial centers when params.init == InitMethod::Array. On return, holds the converged centroids.
inertiaoutraft::host_scalar_view<float>Host scalar receiving the final clustering cost.
n_iteroutraft::host_scalar_view<int>Host scalar receiving the iteration count at which the run terminated.

Returns

void

Additional overload: cluster::kmeans::fit

Multi-GPU k-means fit.

void fit(raft::resources const& handle,
const cuvs::cluster::kmeans::params& params,
const std::vector<raft::device_matrix_view<const float, int64_t>>& X_parts,
const std::optional<std::vector<raft::device_vector_view<const float, int64_t>>>&
sample_weight_parts,
raft::device_matrix_view<float, int64_t> centroids,
raft::host_scalar_view<float> inertia,
raft::host_scalar_view<int64_t> n_iter);

Parameters

NameDirectionTypeDescription
handleraft::resources const&
paramsconst cuvs::cluster::kmeans::params&
X_partsconst std::vector<raft::device_matrix_view<const float, int64_t>>&
sample_weight_partsconst std::optional<std::vector<raft::device_vector_view<const float, int64_t>>>&
centroidsraft::device_matrix_view<float, int64_t>
inertiaraft::host_scalar_view<float>
n_iterraft::host_scalar_view<int64_t>

Returns

void

Additional overload: cluster::kmeans::fit

Multi-GPU k-means fit.

void fit(raft::resources const& handle,
const cuvs::cluster::kmeans::params& params,
const std::vector<raft::device_matrix_view<const double, int>>& X_parts,
const std::optional<std::vector<raft::device_vector_view<const double, int>>>&
sample_weight_parts,
raft::device_matrix_view<double, int> centroids,
raft::host_scalar_view<double> inertia,
raft::host_scalar_view<int> n_iter);

Parameters

NameDirectionTypeDescription
handleraft::resources const&
paramsconst cuvs::cluster::kmeans::params&
X_partsconst std::vector<raft::device_matrix_view<const double, int>>&
sample_weight_partsconst std::optional<std::vector<raft::device_vector_view<const double, int>>>&
centroidsraft::device_matrix_view<double, int>
inertiaraft::host_scalar_view<double>
n_iterraft::host_scalar_view<int>

Returns

void

Additional overload: cluster::kmeans::fit

Multi-GPU k-means fit.

void fit(raft::resources const& handle,
const cuvs::cluster::kmeans::params& params,
const std::vector<raft::device_matrix_view<const double, int64_t>>& X_parts,
const std::optional<std::vector<raft::device_vector_view<const double, int64_t>>>&
sample_weight_parts,
raft::device_matrix_view<double, int64_t> centroids,
raft::host_scalar_view<double> inertia,
raft::host_scalar_view<int64_t> n_iter);

Parameters

NameDirectionTypeDescription
handleraft::resources const&
paramsconst cuvs::cluster::kmeans::params&
X_partsconst std::vector<raft::device_matrix_view<const double, int64_t>>&
sample_weight_partsconst std::optional<std::vector<raft::device_vector_view<const double, int64_t>>>&
centroidsraft::device_matrix_view<double, int64_t>
inertiaraft::host_scalar_view<double>
n_iterraft::host_scalar_view<int64_t>

Returns

void

Additional overload: cluster::kmeans::fit

Multi-GPU / out-of-core k-means fit.

void fit(raft::resources const& handle,
const cuvs::cluster::kmeans::params& params,
const std::vector<raft::host_matrix_view<const float, int64_t>>& X_parts,
const std::optional<std::vector<raft::host_vector_view<const float, int64_t>>>&
sample_weight_parts,
raft::device_matrix_view<float, int64_t> centroids,
raft::host_scalar_view<float> inertia,
raft::host_scalar_view<int64_t> n_iter);

Parameters

NameDirectionTypeDescription
handleraft::resources const&
paramsconst cuvs::cluster::kmeans::params&
X_partsconst std::vector<raft::host_matrix_view<const float, int64_t>>&
sample_weight_partsconst std::optional<std::vector<raft::host_vector_view<const float, int64_t>>>&
centroidsraft::device_matrix_view<float, int64_t>
inertiaraft::host_scalar_view<float>
n_iterraft::host_scalar_view<int64_t>

Returns

void

Additional overload: cluster::kmeans::fit

Multi-GPU / out-of-core k-means fit.

void fit(raft::resources const& handle,
const cuvs::cluster::kmeans::params& params,
const std::vector<raft::host_matrix_view<const double, int64_t>>& X_parts,
const std::optional<std::vector<raft::host_vector_view<const double, int64_t>>>&
sample_weight_parts,
raft::device_matrix_view<double, int64_t> centroids,
raft::host_scalar_view<double> inertia,
raft::host_scalar_view<int64_t> n_iter);

Parameters

NameDirectionTypeDescription
handleraft::resources const&
paramsconst cuvs::cluster::kmeans::params&
X_partsconst std::vector<raft::host_matrix_view<const double, int64_t>>&
sample_weight_partsconst std::optional<std::vector<raft::host_vector_view<const double, int64_t>>>&
centroidsraft::device_matrix_view<double, int64_t>
inertiaraft::host_scalar_view<double>
n_iterraft::host_scalar_view<int64_t>

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.

void find_k(raft::resources const& handle,
raft::device_matrix_view<const float, int> X,
raft::host_scalar_view<int> best_k,
raft::host_scalar_view<float> inertia,
raft::host_scalar_view<int> n_iter,
int kmax,
int kmin = 1,
int maxiter = 100,
float tol = 1e-3);

Parameters

NameDirectionTypeDescription
handleraft::resources const&raft handle
Xraft::device_matrix_view<const float, int>input observations (shape n_samples, n_dims)
best_kraft::host_scalar_view<int>best k found from binary search
inertiaraft::host_scalar_view<float>inertia of best k found
n_iterraft::host_scalar_view<int>number of iterations used to find best k
kmaxintmaximum k to try in search
kminintminimum k to try in search (should be >= 1)
Default: 1.
maxiterintmaximum number of iterations to run
Default: 100.
tolfloattolerance for early stopping convergence
Default: 1e-3.

Returns

void