> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/cuvs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/cuvs/_mcp/server.
# Silhouette Score
_Source header: `cuvs/stats/silhouette_score.hpp`_
## Silhouette Score
### stats::silhouette_score
main function that returns the average silhouette score for a given set of data and its clusterings
```cpp
float silhouette_score(
raft::resources const& handle,
raft::device_matrix_view X_in,
raft::device_vector_view labels,
std::optional silhouette_score_per_sample,
int64_t n_unique_labels,
cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Unexpanded);
```
**Parameters**
| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | raft handle for managing expensive resources |
| `X_in` | in | `raft::device_matrix_view` | input matrix Data in row-major format (nRows x nCols) |
| `labels` | in | `raft::device_vector_view` | the pointer to the array containing labels for every data sample (length: nRows) |
| `silhouette_score_per_sample` | out | `std::optional` | optional array populated with the silhouette score for every sample (length: nRows) |
| `n_unique_labels` | in | `int64_t` | number of unique labels in the labels array |
| `metric` | in | [`cuvs::distance::DistanceType`](/api-reference/cpp-api-distance-distance#distance-distancetype) | Distance metric to use. Euclidean (L2) is used by default
Default: `cuvs::distance::DistanceType::L2Unexpanded`. |
**Returns**
`float`
The silhouette score.
### stats::silhouette_score_batched
function that returns the average silhouette score for a given set of data and its clusterings
```cpp
float silhouette_score_batched(
raft::resources const& handle,
raft::device_matrix_view X,
raft::device_vector_view labels,
std::optional silhouette_score_per_sample,
int64_t n_unique_labels,
int64_t batch_size,
cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Unexpanded);
```
**Parameters**
| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | raft handle for managing expensive resources |
| `X` | in | `raft::device_matrix_view` | input matrix Data in row-major format (nRows x nCols) |
| `labels` | in | `raft::device_vector_view` | the pointer to the array containing labels for every data sample (length: nRows) |
| `silhouette_score_per_sample` | out | `std::optional` | optional array populated with the silhouette score for every sample (length: nRows) |
| `n_unique_labels` | in | `int64_t` | number of unique labels in the labels array |
| `batch_size` | in | `int64_t` | number of samples per batch |
| `metric` | in | [`cuvs::distance::DistanceType`](/api-reference/cpp-api-distance-distance#distance-distancetype) | the numerical value that maps to the type of distance metric to be used in the calculations
Default: `cuvs::distance::DistanceType::L2Unexpanded`. |
**Returns**
`float`
The silhouette score.
**Additional overload:** `stats::silhouette_score`
main function that returns the average silhouette score for a given set of data and its clusterings
```cpp
double silhouette_score(
raft::resources const& handle,
raft::device_matrix_view X_in,
raft::device_vector_view labels,
std::optional silhouette_score_per_sample,
int64_t n_unique_labels,
cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Unexpanded);
```
**Parameters**
| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | raft handle for managing expensive resources |
| `X_in` | in | `raft::device_matrix_view` | input matrix Data in row-major format (nRows x nCols) |
| `labels` | in | `raft::device_vector_view` | the pointer to the array containing labels for every data sample (length: nRows) |
| `silhouette_score_per_sample` | out | `std::optional` | optional array populated with the silhouette score for every sample (length: nRows) |
| `n_unique_labels` | in | `int64_t` | number of unique labels in the labels array |
| `metric` | in | [`cuvs::distance::DistanceType`](/api-reference/cpp-api-distance-distance#distance-distancetype) | the numerical value that maps to the type of distance metric to be used in the calculations
Default: `cuvs::distance::DistanceType::L2Unexpanded`. |
**Returns**
`double`
The silhouette score.
**Additional overload:** `stats::silhouette_score_batched`
function that returns the average silhouette score for a given set of data and its clusterings
```cpp
double silhouette_score_batched(
raft::resources const& handle,
raft::device_matrix_view X,
raft::device_vector_view labels,
std::optional silhouette_score_per_sample,
int64_t n_unique_labels,
int64_t batch_size,
cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Unexpanded);
```
**Parameters**
| Name | Direction | Type | Description |
| --- | --- | --- | --- |
| `handle` | in | `raft::resources const&` | raft handle for managing expensive resources |
| `X` | in | `raft::device_matrix_view` | input matrix Data in row-major format (nRows x nCols) |
| `labels` | in | `raft::device_vector_view` | the pointer to the array containing labels for every data sample (length: nRows) |
| `silhouette_score_per_sample` | out | `std::optional` | optional array populated with the silhouette score for every sample (length: nRows) |
| `n_unique_labels` | in | `int64_t` | number of unique labels in the labels array |
| `batch_size` | in | `int64_t` | number of samples per batch |
| `metric` | in | [`cuvs::distance::DistanceType`](/api-reference/cpp-api-distance-distance#distance-distancetype) | the numerical value that maps to the type of distance metric to be used in the calculations
Default: `cuvs::distance::DistanceType::L2Unexpanded`. |
**Returns**
`double`
The silhouette score.