---
slug: api-reference/cpp-api-cluster-kmeans
---

# K-Means

_Source header: `cuvs/cluster/kmeans.hpp`_

## Types

<a id="cluster-kmeans-base-params"></a>
### cluster::kmeans::base_params

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

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

**Fields**

| Name | Type | Description |
| --- | --- | --- |
| `metric` | [`cuvs::distance::DistanceType`](/api-reference/cpp-api-distance-distance#distance-distancetype) | Metric to use for distance computation. The supported metrics can vary per algorithm. |

## k-means hyperparameters

<a id="cluster-kmeans-params"></a>
### cluster::kmeans::params

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

```cpp
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**

| Name | Type | Description |
| --- | --- | --- |
| `n_clusters` | `int` | The number of clusters to form as well as the number of centroids to generate (default:8). |
| `init` | `InitMethod` | Method for initialization, defaults to k-means++:<br />- InitMethod::KMeansPlusPlus (k-means++): Use scalable k-means++ algorithm to select the initial cluster centers.<br />- InitMethod::Random (random): Choose 'n_clusters' observations (rows) at random from the input data for the initial centroids.<br />- InitMethod::Array (ndarray): Use 'centroids' as initial cluster centers. |
| `max_iter` | `int` | Maximum number of iterations of the k-means algorithm for a single run. |
| `tol` | `double` | Relative tolerance with regards to inertia to declare convergence. |
| `verbosity` | `rapids_logger::level_enum` | verbosity level. |
| `rng_state` | `raft::random::RngState` | Seed to the random number generator. |
| `n_init` | `int` | Number of instance k-means algorithm will be run with different seeds. |
| `oversampling_factor` | `double` | Oversampling factor for use in the k-means\|\| algorithm.<br /><br />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.<br /><br />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_samples` | `int` | batch_samples and batch_centroids are used to tile 1NN computation which is useful to optimize/control the memory footprint<br />Default tile is [batch_samples x n_clusters] i.e. when batch_centroids is 0 then don't tile the centroids<br /><br />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_centroids` | `int` | if 0 then batch_centroids = n_clusters |
| `init_size` | `int64_t` | Number of samples used for KMeansPlusPlus initialization. This applies to host floating-point input and to byte input in either memory location; device floating-point input always uses the full dataset.<br /><br />Zero uses `min(3 * n_clusters, n_samples)`; byte input also limits the<br />default to the automatically selected conversion batch size, but keeps at least `min(n_clusters, n_samples)` rows for seeding.<br /><br />In batched multi-GPU host-data fits, every device must hold the sample, and rank 0 must also hold the seeding workspace.<br /><br />Default: 0. |
| `device_buffer_samples` | `int64_t` | Number of host-resident samples to buffer on the GPU. Zero buffers all rows at once. Device-resident input ignores this parameter.<br /><br />Byte input is staged in its original type, then converted to float in smaller batches. For both host and device byte input, conversion batches use the smaller of 80% of free workspace and 512 MiB for the float buffer and per-row scratch. The row count is rounded down to a multiple of 64 when possible and clamped to the buffered input size. Host staging buffers are additional to this conversion workspace budget.<br /><br />Host inputs spanning multiple buffers are double-buffered when the handle has an auxiliary stream. In floating-point multi-GPU mode this is a per-rank buffer size, clamped to the local sample count. Byte-input Lloyd k-means is single-GPU only.<br /><br />Default: 0 (buffer all host rows). |

<a id="cluster-kmeans-balanced-donor-selection"></a>
### cluster::kmeans::balanced_donor_selection

Donor selection strategy used by balanced k-means rebalancing.

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

**Values**

| Name | Value |
| --- | --- |
| `SizeSorted` | `0` |
| `Random` | `1` |

<a id="cluster-kmeans-kmeans-type"></a>
### cluster::kmeans::kmeans_type

Type of k-means algorithm.

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

**Values**

| Name | Value |
| --- | --- |
| `KMeans` | `0` |
| `KMeansBalanced` | `1` |

## k-means clustering APIs

<a id="cluster-kmeans-fit"></a>
### cluster::kmeans::fit

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

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | The raft handle. When a multi-GPU resource is attached, multi-GPU dispatch is used automatically. |
| `params` | in | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | Parameters for KMeans model. Batch size is read from params.device_buffer_samples. |
| `X` | in | `raft::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_weight` | in | `std::optional<raft::host_vector_view<const float, int64_t>>` | Optional weights for each observation in X (on host). [len = n_samples] |
| `centroids` | inout | `raft::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] |
| `inertia` | out | `raft::host_scalar_view<float>` | Sum of squared distances of samples to their closest cluster center. |
| `n_iter` | out | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` |  | `raft::resources const&` |  |
| `params` |  | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) |  |
| `X` |  | `raft::host_matrix_view<const double, int64_t>` |  |
| `sample_weight` |  | `std::optional<raft::host_vector_view<const double, int64_t>>` |  |
| `centroids` |  | `raft::device_matrix_view<double, int64_t>` |  |
| `inertia` |  | `raft::host_scalar_view<double>` |  |
| `n_iter` |  | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | The raft handle. |
| `params` | in | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | Parameters for KMeans model. |
| `X` | in | `raft::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_weight` | in | `std::optional<raft::device_vector_view<const float, int>>` | Optional weights for each observation in X. [len = n_samples] |
| `centroids` | inout | `raft::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] |
| `inertia` | out | `raft::host_scalar_view<float>` | Sum of squared distances of samples to their closest cluster center. |
| `n_iter` | out | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | The raft handle. |
| `params` | in | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | Parameters for KMeans model. |
| `X` | in | `raft::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_weight` | in | `std::optional<raft::device_vector_view<const float, int64_t>>` | Optional weights for each observation in X. [len = n_samples] |
| `centroids` | inout | `raft::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] |
| `inertia` | out | `raft::host_scalar_view<float>` | Sum of squared distances of samples to their closest cluster center. |
| `n_iter` | out | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | The raft handle. |
| `params` | in | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | Parameters for KMeans model. |
| `X` | in | `raft::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_weight` | in | `std::optional<raft::device_vector_view<const double, int>>` | Optional weights for each observation in X. [len = n_samples] |
| `centroids` | inout | `raft::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] |
| `inertia` | out | `raft::host_scalar_view<double>` | Sum of squared distances of samples to their closest cluster center. |
| `n_iter` | out | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | The raft handle. |
| `params` | in | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | Parameters for KMeans model. |
| `X` | in | `raft::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_weight` | in | `std::optional<raft::device_vector_view<const double, int64_t>>` | Optional weights for each observation in X. [len = n_samples] |
| `centroids` | inout | `raft::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] |
| `inertia` | out | `raft::host_scalar_view<double>` | Sum of squared distances of samples to their closest cluster center. |
| `n_iter` | out | `raft::host_scalar_view<int64_t>` | Number of iterations run. |

**Returns**

`void`

**Additional overload:** `cluster::kmeans::fit`

Find clusters with Lloyd k-means from byte input.

```cpp
void fit(raft::resources const& handle,
const cuvs::cluster::kmeans::params& params,
raft::host_matrix_view<const int8_t, 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);
```

Supports host- and device-resident `int8_t` and `uint8_t` input on one GPU. Values are converted by batches to float32 and divided by 128 or 256, respectively. Weights, centroids, and inertia are float32; caller-provided centroids must use the normalized float space.

**Parameters**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | RAFT resources. |
| `params` | in | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | K-means parameters. |
| `X` | in | `raft::host_matrix_view<const int8_t, int64_t>` | Row-major input. [n_samples x n_features] |
| `sample_weight` | in | `std::optional<raft::host_vector_view<const float, int64_t>>` | Optional weights. [n_samples] |
| `centroids` | inout | `raft::device_matrix_view<float, int64_t>` | Initial and fitted centroids. |
| `inertia` | out | `raft::host_scalar_view<float>` | Sum of squared distances. |
| `n_iter` | out | `raft::host_scalar_view<int64_t>` | Number of iterations run. |

**Returns**

`void`

**Additional overload:** `cluster::kmeans::fit`

```cpp
void fit(raft::resources const& handle,
const cuvs::cluster::kmeans::params& params,
raft::device_matrix_view<const int8_t, 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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` |  | `raft::resources const&` |  |
| `params` |  | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) |  |
| `X` |  | `raft::device_matrix_view<const int8_t, int64_t>` |  |
| `sample_weight` |  | `std::optional<raft::device_vector_view<const float, int64_t>>` |  |
| `centroids` |  | `raft::device_matrix_view<float, int64_t>` |  |
| `inertia` |  | `raft::host_scalar_view<float>` |  |
| `n_iter` |  | `raft::host_scalar_view<int64_t>` |  |

**Returns**

`void`

**Additional overload:** `cluster::kmeans::fit`

```cpp
void fit(raft::resources const& handle,
const cuvs::cluster::kmeans::params& params,
raft::host_matrix_view<const uint8_t, 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);
```

**Parameters**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` |  | `raft::resources const&` |  |
| `params` |  | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) |  |
| `X` |  | `raft::host_matrix_view<const uint8_t, int64_t>` |  |
| `sample_weight` |  | `std::optional<raft::host_vector_view<const float, int64_t>>` |  |
| `centroids` |  | `raft::device_matrix_view<float, int64_t>` |  |
| `inertia` |  | `raft::host_scalar_view<float>` |  |
| `n_iter` |  | `raft::host_scalar_view<int64_t>` |  |

**Returns**

`void`

**Additional overload:** `cluster::kmeans::fit`

```cpp
void fit(raft::resources const& handle,
const cuvs::cluster::kmeans::params& params,
raft::device_matrix_view<const uint8_t, 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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` |  | `raft::resources const&` |  |
| `params` |  | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) |  |
| `X` |  | `raft::device_matrix_view<const uint8_t, int64_t>` |  |
| `sample_weight` |  | `std::optional<raft::device_vector_view<const float, int64_t>>` |  |
| `centroids` |  | `raft::device_matrix_view<float, int64_t>` |  |
| `inertia` |  | `raft::host_scalar_view<float>` |  |
| `n_iter` |  | `raft::host_scalar_view<int64_t>` |  |

**Returns**

`void`

**Additional overload:** `cluster::kmeans::fit`

Find balanced clusters with k-means algorithm.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `const raft::resources&` | The raft handle. |
| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. |
| `X` | in | `raft::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] |
| `centroids` | out | `raft::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] |
| `inertia` | out | `std::optional<raft::host_scalar_view<float>>` | Sum of squared distances of samples to their closest cluster center.<br />Default: `std::nullopt`. |

**Returns**

`void`

**Additional overload:** `cluster::kmeans::fit`

Find balanced clusters with k-means algorithm.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `const raft::resources&` | The raft handle. |
| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. |
| `X` | in | `raft::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] |
| `centroids` | inout | `raft::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] |
| `inertia` | out | `std::optional<raft::host_scalar_view<float>>` | Sum of squared distances of samples to their closest cluster center.<br />Default: `std::nullopt`. |

**Returns**

`void`

**Additional overload:** `cluster::kmeans::fit`

Find balanced clusters with k-means algorithm.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `const raft::resources&` | The raft handle. |
| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. |
| `X` | in | `raft::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] |
| `centroids` | inout | `raft::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] |
| `inertia` | out | `std::optional<raft::host_scalar_view<float>>` | Sum of squared distances of samples to their closest cluster center.<br />Default: `std::nullopt`. |

**Returns**

`void`

**Additional overload:** `cluster::kmeans::fit`

Find balanced clusters with k-means algorithm.

```cpp
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);
```

**Parameters**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `const raft::resources&` | The raft handle. |
| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. |
| `X` | in | `raft::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] |
| `centroids` | inout | `raft::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] |
| `inertia` | out | `std::optional<raft::host_scalar_view<float>>` | Sum of squared distances of samples to their closest cluster center.<br />Default: `std::nullopt`. |

**Returns**

`void`

<a id="cluster-kmeans-predict"></a>
### cluster::kmeans::predict

Predict the closest cluster each sample in X belongs to.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | The raft handle. |
| `params` | in | [`const kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | Parameters for KMeans model. |
| `X` | in | `raft::device_matrix_view<const float, int>` | New data to predict. [dim = n_samples x n_features] |
| `sample_weight` | in | `std::optional<raft::device_vector_view<const float, int>>` | Optional weights for each observation in X. [len = n_samples] |
| `centroids` | in | `raft::device_matrix_view<const float, int>` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] |
| `labels` | out | `raft::device_vector_view<int, int>` | Index of the cluster each sample in X belongs to. [len = n_samples] |
| `normalize_weight` | in | `bool` | True if the weights should be normalized |
| `inertia` | out | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | The raft handle. |
| `params` | in | [`const kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | Parameters for KMeans model. |
| `X` | in | `raft::device_matrix_view<const float, int64_t>` | New data to predict. [dim = n_samples x n_features] |
| `sample_weight` | in | `std::optional<raft::device_vector_view<const float, int64_t>>` | Optional weights for each observation in X. [len = n_samples] |
| `centroids` | in | `raft::device_matrix_view<const float, int64_t>` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] |
| `labels` | out | `raft::device_vector_view<int64_t, int64_t>` | Index of the cluster each sample in X belongs to. [len = n_samples] |
| `normalize_weight` | in | `bool` | True if the weights should be normalized |
| `inertia` | out | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | The raft handle. |
| `params` | in | [`const kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | Parameters for KMeans model. |
| `X` | in | `raft::device_matrix_view<const double, int>` | New data to predict. [dim = n_samples x n_features] |
| `sample_weight` | in | `std::optional<raft::device_vector_view<const double, int>>` | Optional weights for each observation in X. [len = n_samples] |
| `centroids` | in | `raft::device_matrix_view<const double, int>` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] |
| `labels` | out | `raft::device_vector_view<int, int>` | Index of the cluster each sample in X belongs to. [len = n_samples] |
| `normalize_weight` | in | `bool` | True if the weights should be normalized |
| `inertia` | out | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | The raft handle. |
| `params` | in | [`const kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | Parameters for KMeans model. |
| `X` | in | `raft::device_matrix_view<const double, int64_t>` | New data to predict. [dim = n_samples x n_features] |
| `sample_weight` | in | `std::optional<raft::device_vector_view<const double, int64_t>>` | Optional weights for each observation in X. [len = n_samples] |
| `centroids` | in | `raft::device_matrix_view<const double, int64_t>` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] |
| `labels` | out | `raft::device_vector_view<int64_t, int64_t>` | Index of the cluster each sample in X belongs to. [len = n_samples] |
| `normalize_weight` | in | `bool` | True if the weights should be normalized |
| `inertia` | out | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `const raft::resources&` | The raft handle. |
| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. |
| `X` | in | `raft::device_matrix_view<const int8_t, int64_t>` | New data to predict. [dim = n_samples x n_features] |
| `centroids` | in | `raft::device_matrix_view<const float, int64_t>` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] |
| `labels` | out | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `const raft::resources&` | The raft handle. |
| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. |
| `X` | in | `raft::device_matrix_view<const int8_t, int64_t>` | New data to predict. [dim = n_samples x n_features] |
| `centroids` | in | `raft::device_matrix_view<const float, int64_t>` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] |
| `labels` | out | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `const raft::resources&` | The raft handle. |
| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. |
| `X` | in | `raft::device_matrix_view<const float, int64_t>` | New data to predict. [dim = n_samples x n_features] |
| `centroids` | in | `raft::device_matrix_view<const float, int64_t>` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] |
| `labels` | out | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `const raft::resources&` | The raft handle. |
| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. |
| `X` | in | `raft::device_matrix_view<const float, int64_t>` | New data to predict. [dim = n_samples x n_features] |
| `centroids` | in | `raft::device_matrix_view<const float, int64_t>` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] |
| `labels` | out | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `const raft::resources&` | The raft handle. |
| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. |
| `X` | in | `raft::device_matrix_view<const half, int64_t>` | New data to predict. [dim = n_samples x n_features] |
| `centroids` | in | `raft::device_matrix_view<const float, int64_t>` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] |
| `labels` | out | `raft::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.

```cpp
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);
```

**Parameters**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `const raft::resources&` | The raft handle. |
| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. |
| `X` | in | `raft::device_matrix_view<const uint8_t, int64_t>` | New data to predict. [dim = n_samples x n_features] |
| `centroids` | in | `raft::device_matrix_view<const float, int64_t>` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] |
| `labels` | out | `raft::device_vector_view<uint32_t, int64_t>` | Index of the cluster each sample in X belongs to. [len = n_samples] |

**Returns**

`void`

<a id="cluster-kmeans-fit-predict"></a>
### cluster::kmeans::fit_predict

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

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | The raft handle. |
| `params` | in | [`const kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | Parameters for KMeans model. |
| `X` | in | `raft::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_weight` | in | `std::optional<raft::device_vector_view<const float, int>>` | Optional weights for each observation in X. [len = n_samples] |
| `centroids` | inout | `std::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] |
| `labels` | out | `raft::device_vector_view<int, int>` | Index of the cluster each sample in X belongs to. [len = n_samples] |
| `inertia` | out | `raft::host_scalar_view<float>` | Sum of squared distances of samples to their closest cluster center. |
| `n_iter` | out | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | The raft handle. |
| `params` | in | [`const kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | Parameters for KMeans model. |
| `X` | in | `raft::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_weight` | in | `std::optional<raft::device_vector_view<const float, int64_t>>` | Optional weights for each observation in X. [len = n_samples] |
| `centroids` | inout | `std::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] |
| `labels` | out | `raft::device_vector_view<int64_t, int64_t>` | Index of the cluster each sample in X belongs to. [len = n_samples] |
| `inertia` | out | `raft::host_scalar_view<float>` | Sum of squared distances of samples to their closest cluster center. |
| `n_iter` | out | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | The raft handle. |
| `params` | in | [`const kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | Parameters for KMeans model. |
| `X` | in | `raft::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_weight` | in | `std::optional<raft::device_vector_view<const double, int>>` | Optional weights for each observation in X. [len = n_samples] |
| `centroids` | inout | `std::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] |
| `labels` | out | `raft::device_vector_view<int, int>` | Index of the cluster each sample in X belongs to. [len = n_samples] |
| `inertia` | out | `raft::host_scalar_view<double>` | Sum of squared distances of samples to their closest cluster center. |
| `n_iter` | out | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | The raft handle. |
| `params` | in | [`const kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | Parameters for KMeans model. |
| `X` | in | `raft::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_weight` | in | `std::optional<raft::device_vector_view<const double, int64_t>>` | Optional weights for each observation in X. [len = n_samples] |
| `centroids` | inout | `std::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] |
| `labels` | out | `raft::device_vector_view<int64_t, int64_t>` | Index of the cluster each sample in X belongs to. [len = n_samples] |
| `inertia` | out | `raft::host_scalar_view<double>` | Sum of squared distances of samples to their closest cluster center. |
| `n_iter` | out | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `const raft::resources&` | The raft handle. |
| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. |
| `X` | in | `raft::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] |
| `centroids` | inout | `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] |
| `labels` | out | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `const raft::resources&` | The raft handle. |
| `params` | in | `cuvs::cluster::kmeans::balanced_params const&` | Parameters for KMeans model. |
| `X` | in | `raft::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] |
| `centroids` | inout | `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] |
| `labels` | out | `raft::device_vector_view<uint32_t, int64_t>` | Index of the cluster each sample in X belongs to. [len = n_samples] |

**Returns**

`void`

<a id="cluster-kmeans-transform"></a>
### cluster::kmeans::transform

Transform X to a cluster-distance space.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | The raft handle. |
| `params` | in | [`const kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | Parameters for KMeans model. |
| `X` | in | `raft::device_matrix_view<const float, int>` | Training instances to cluster. The data must be in row-major format [dim = n_samples x n_features] |
| `centroids` | in | `raft::device_matrix_view<const float, int>` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] |
| `X_new` | out | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | The raft handle. |
| `params` | in | [`const kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) | Parameters for KMeans model. |
| `X` | in | `raft::device_matrix_view<const double, int>` | Training instances to cluster. The data must be in row-major format [dim = n_samples x n_features] |
| `centroids` | in | `raft::device_matrix_view<const double, int>` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] |
| `X_new` | out | `raft::device_matrix_view<double, int>` | X transformed in the new space. [dim = n_samples x n_features] |

**Returns**

`void`

<a id="cluster-kmeans-cluster-cost"></a>
### cluster::kmeans::cluster_cost

Compute (optionally weighted) cluster cost

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `const raft::resources&` | The raft handle |
| `X` | in | `raft::device_matrix_view<const float, int>` | Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features] |
| `centroids` | in | `raft::device_matrix_view<const float, int>` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] |
| `cost` | out | `raft::host_scalar_view<float>` | Resulting cluster cost |
| `sample_weight` | in | `std::optional<raft::device_vector_view<const float, int>>` | Optional per-sample weights. [len = n_samples]<br />Default: `std::nullopt`. |

**Returns**

`void`

**Additional overload:** `cluster::kmeans::cluster_cost`

Compute cluster cost

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `const raft::resources&` | The raft handle |
| `X` | in | `raft::device_matrix_view<const double, int>` | Training instances to cluster. The data must be in row-major format. [dim = n_samples x n_features] |
| `centroids` | in | `raft::device_matrix_view<const double, int>` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] |
| `cost` | out | `raft::host_scalar_view<double>` | Resulting cluster cost |
| `sample_weight` | in | `std::optional<raft::device_vector_view<const double, int>>` | Optional per-sample weights. [len = n_samples]<br />Default: `std::nullopt`. |

**Returns**

`void`

**Additional overload:** `cluster::kmeans::cluster_cost`

Compute (optionally weighted) cluster cost

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `const raft::resources&` | The raft handle |
| `X` | in | `raft::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] |
| `centroids` | in | `raft::device_matrix_view<const float, int64_t>` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] |
| `cost` | out | `raft::host_scalar_view<float>` | Resulting cluster cost |
| `sample_weight` | in | `std::optional<raft::device_vector_view<const float, int64_t>>` | Optional per-sample weights. [len = n_samples]<br />Default: `std::nullopt`. |

**Returns**

`void`

**Additional overload:** `cluster::kmeans::cluster_cost`

Compute (optionally weighted) cluster cost

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `const raft::resources&` | The raft handle |
| `X` | in | `raft::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] |
| `centroids` | in | `raft::device_matrix_view<const double, int64_t>` | Cluster centroids. The data must be in row-major format. [dim = n_clusters x n_features] |
| `cost` | out | `raft::host_scalar_view<double>` | Resulting cluster cost |
| `sample_weight` | in | `std::optional<raft::device_vector_view<const double, int64_t>>` | Optional per-sample weights. [len = n_samples]<br />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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | The raft handle. Must have NCCL comms or a SNMG clique initialized. |
| `params` | in | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#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_parts` | in | `const 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_parts` | in | `const std::optional<std::vector<raft::device_vector_view<const float, int>>>&` | Optional per-partition row weights with one vector per data partition. |
| `centroids` | inout | `raft::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. |
| `inertia` | out | `raft::host_scalar_view<float>` | Host scalar receiving the final clustering cost. |
| `n_iter` | out | `raft::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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` |  | `raft::resources const&` |  |
| `params` |  | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) |  |
| `X_parts` |  | `const std::vector<raft::device_matrix_view<const float, int64_t>>&` |  |
| `sample_weight_parts` |  | `const std::optional<std::vector<raft::device_vector_view<const float, int64_t>>>&` |  |
| `centroids` |  | `raft::device_matrix_view<float, int64_t>` |  |
| `inertia` |  | `raft::host_scalar_view<float>` |  |
| `n_iter` |  | `raft::host_scalar_view<int64_t>` |  |

**Returns**

`void`

**Additional overload:** `cluster::kmeans::fit`

Multi-GPU k-means fit.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` |  | `raft::resources const&` |  |
| `params` |  | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) |  |
| `X_parts` |  | `const std::vector<raft::device_matrix_view<const double, int>>&` |  |
| `sample_weight_parts` |  | `const std::optional<std::vector<raft::device_vector_view<const double, int>>>&` |  |
| `centroids` |  | `raft::device_matrix_view<double, int>` |  |
| `inertia` |  | `raft::host_scalar_view<double>` |  |
| `n_iter` |  | `raft::host_scalar_view<int>` |  |

**Returns**

`void`

**Additional overload:** `cluster::kmeans::fit`

Multi-GPU k-means fit.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` |  | `raft::resources const&` |  |
| `params` |  | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) |  |
| `X_parts` |  | `const std::vector<raft::device_matrix_view<const double, int64_t>>&` |  |
| `sample_weight_parts` |  | `const std::optional<std::vector<raft::device_vector_view<const double, int64_t>>>&` |  |
| `centroids` |  | `raft::device_matrix_view<double, int64_t>` |  |
| `inertia` |  | `raft::host_scalar_view<double>` |  |
| `n_iter` |  | `raft::host_scalar_view<int64_t>` |  |

**Returns**

`void`

**Additional overload:** `cluster::kmeans::fit`

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

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` |  | `raft::resources const&` |  |
| `params` |  | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) |  |
| `X_parts` |  | `const std::vector<raft::host_matrix_view<const float, int64_t>>&` |  |
| `sample_weight_parts` |  | `const std::optional<std::vector<raft::host_vector_view<const float, int64_t>>>&` |  |
| `centroids` |  | `raft::device_matrix_view<float, int64_t>` |  |
| `inertia` |  | `raft::host_scalar_view<float>` |  |
| `n_iter` |  | `raft::host_scalar_view<int64_t>` |  |

**Returns**

`void`

**Additional overload:** `cluster::kmeans::fit`

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

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` |  | `raft::resources const&` |  |
| `params` |  | [`const cuvs::cluster::kmeans::params&`](/api-reference/cpp-api-cluster-kmeans#cluster-kmeans-params) |  |
| `X_parts` |  | `const std::vector<raft::host_matrix_view<const double, int64_t>>&` |  |
| `sample_weight_parts` |  | `const std::optional<std::vector<raft::host_vector_view<const double, int64_t>>>&` |  |
| `centroids` |  | `raft::device_matrix_view<double, int64_t>` |  |
| `inertia` |  | `raft::host_scalar_view<double>` |  |
| `n_iter` |  | `raft::host_scalar_view<int64_t>` |  |

**Returns**

`void`

## k-means API helpers

<a id="cluster-kmeans-helpers-find-k"></a>
### 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.

```cpp
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**

| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` |  | `raft::resources const&` | raft handle |
| `X` |  | `raft::device_matrix_view<const float, int>` | input observations (shape n_samples, n_dims) |
| `best_k` |  | `raft::host_scalar_view<int>` | best k found from binary search |
| `inertia` |  | `raft::host_scalar_view<float>` | inertia of best k found |
| `n_iter` |  | `raft::host_scalar_view<int>` | number of iterations used to find best k |
| `kmax` |  | `int` | maximum k to try in search |
| `kmin` |  | `int` | minimum k to try in search (should be &gt;= 1)<br />Default: `1`. |
| `maxiter` |  | `int` | maximum number of iterations to run<br />Default: `100`. |
| `tol` |  | `float` | tolerance for early stopping convergence<br />Default: `1e-3`. |

**Returns**

`void`