Implementation:Rapidsai Cuml Cpp Metrics API

Knowledge Sources	Rapidsai_Cuml
Domains	Machine_Learning, Model_Evaluation
Last Updated	2026-02-08 12:00 GMT

Overview

Provides the C++ API for GPU-accelerated machine learning evaluation metrics including R-squared, rand index, silhouette score, adjusted rand index, KL divergence, entropy, mutual information, homogeneity, completeness, V-measure, accuracy, pairwise distances, and trustworthiness.

Description

This header defines a comprehensive set of evaluation metrics in the ML::Metrics namespace, all designed for GPU-accelerated computation:

Regression Metrics:

r2_score_py: Computes the R-squared (coefficient of determination) score. Available in float and double precision.

Clustering Metrics:

rand_index: Computes the rand index measuring similarity between two clusterings.
adjusted_rand_index: Chance-corrected version of the rand index. Overloaded for int and int64_t label types.
silhouette_score: Computes the silhouette coefficient using mean intra-cluster and nearest-cluster distances. A batched variant in ML::Metrics::Batched tiles the pairwise distance matrix to reduce memory usage.
entropy: Measures the purity of a single clustering.
mutual_info_score: Measures similarity between two label assignments.
homogeneity_score: Measures whether clusters contain only members of a single class.
completeness_score: Measures whether all members of a class are in the same cluster.
v_measure: Harmonic mean of homogeneity and completeness, with configurable beta weight.

Classification Metrics:

accuracy_score_py: Computes classification accuracy.

Information-Theoretic Metrics:

kl_divergence: Computes Kullback-Leibler divergence between two probability distributions. Available in float and double.

Distance Metrics:

pairwise_distance: Computes dense pairwise distances between two matrices. Overloaded for float and double.
pairwiseDistance_sparse: Computes pairwise distances for sparse CSR-format matrices. Overloaded for float and double.

Embedding Quality:

trustworthiness_score: Evaluates dimensionality reduction quality by comparing neighborhoods in original and embedded spaces. Template function parameterized on data type and distance metric.

Usage

Use these functions for GPU-accelerated evaluation of machine learning models. They are the cuML equivalents of scikit-learn's sklearn.metrics module and are used internally by cuML's Python API as well as directly from C++ code.

Code Reference

Source Location

Repository: Rapidsai_Cuml
File: cpp/include/cuml/metrics/metrics.hpp

Signature

namespace ML {
namespace Metrics {

// R-squared
float r2_score_py(const raft::handle_t& handle, float* y, float* y_hat, int n);
double r2_score_py(const raft::handle_t& handle, double* y, double* y_hat, int n);

// Rand Index
double rand_index(const raft::handle_t& handle, double* y, double* y_hat, int n);

// Silhouette Score
double silhouette_score(const raft::handle_t& handle,
                        double* y, int nRows, int nCols,
                        int* labels, int nLabels,
                        double* silScores,
                        ML::distance::DistanceType metric);

namespace Batched {
float silhouette_score(const raft::handle_t& handle,
                       float* X, int n_rows, int n_cols,
                       int* y, int n_labels, float* scores,
                       int chunk, ML::distance::DistanceType metric);
double silhouette_score(const raft::handle_t& handle,
                        double* X, int n_rows, int n_cols,
                        int* y, int n_labels, double* scores,
                        int chunk, ML::distance::DistanceType metric);
}  // namespace Batched

// Adjusted Rand Index
double adjusted_rand_index(const raft::handle_t& handle,
                           const int64_t* y, const int64_t* y_hat, const int64_t n);
double adjusted_rand_index(const raft::handle_t& handle,
                           const int* y, const int* y_hat, const int n);

// KL Divergence
double kl_divergence(const raft::handle_t& handle,
                     const double* y, const double* y_hat, int n);
float kl_divergence(const raft::handle_t& handle,
                    const float* y, const float* y_hat, int n);

// Entropy
double entropy(const raft::handle_t& handle,
               const int* y, const int n,
               const int lower_class_range, const int upper_class_range);

// Mutual Information
double mutual_info_score(const raft::handle_t& handle,
                         const int* y, const int* y_hat, const int n,
                         const int lower_class_range, const int upper_class_range);

// Homogeneity
double homogeneity_score(const raft::handle_t& handle,
                         const int* y, const int* y_hat, const int n,
                         const int lower_class_range, const int upper_class_range);

// Completeness
double completeness_score(const raft::handle_t& handle,
                          const int* y, const int* y_hat, const int n,
                          const int lower_class_range, const int upper_class_range);

// V-Measure
double v_measure(const raft::handle_t& handle,
                 const int* y, const int* y_hat, const int n,
                 const int lower_class_range, const int upper_class_range,
                 double beta);

// Accuracy
float accuracy_score_py(const raft::handle_t& handle,
                        const int* predictions, const int* ref_predictions, int n);

// Dense Pairwise Distance
void pairwise_distance(const raft::handle_t& handle,
                       const double* x, const double* y, double* dist,
                       int m, int n, int k,
                       ML::distance::DistanceType metric,
                       bool isRowMajor = true, double metric_arg = 2.0);
void pairwise_distance(const raft::handle_t& handle,
                       const float* x, const float* y, float* dist,
                       int m, int n, int k,
                       ML::distance::DistanceType metric,
                       bool isRowMajor = true, float metric_arg = 2.0f);

// Sparse Pairwise Distance
void pairwiseDistance_sparse(const raft::handle_t& handle,
                             double* x, double* y, double* dist,
                             int x_nrows, int y_nrows, int n_cols,
                             int x_nnz, int y_nnz,
                             int* x_indptr, int* y_indptr,
                             int* x_indices, int* y_indices,
                             ML::distance::DistanceType metric,
                             float metric_arg);
void pairwiseDistance_sparse(const raft::handle_t& handle,
                             float* x, float* y, float* dist,
                             int x_nrows, int y_nrows, int n_cols,
                             int x_nnz, int y_nnz,
                             int* x_indptr, int* y_indptr,
                             int* x_indices, int* y_indices,
                             ML::distance::DistanceType metric,
                             float metric_arg);

// Trustworthiness
template <typename math_t, ML::distance::DistanceType distance_type>
double trustworthiness_score(const raft::handle_t& h,
                             const math_t* X, math_t* X_embedded,
                             int n, int m, int d,
                             int n_neighbors, int batchSize = 512);

}  // namespace Metrics
}  // namespace ML

Import

#include <cuml/metrics/metrics.hpp>

I/O Contract

Inputs (r2_score_py)

Name	Type	Required	Description
handle	const raft::handle_t&	Yes	RAFT handle for GPU resource management
y	float/double	Yes	Device pointer to ground-truth response values [n]
y_hat	float/double	Yes	Device pointer to predicted response values [n]
n	int	Yes	Number of elements

Inputs (silhouette_score)

Name	Type	Required	Description
handle	const raft::handle_t&	Yes	RAFT handle
y	double*	Yes	Device pointer to data samples [nRows x nCols]
nRows	int	Yes	Number of samples
nCols	int	Yes	Number of features
labels	int*	Yes	Device pointer to cluster labels [nRows]
nLabels	int	Yes	Number of distinct labels
silScores	double*	No	Optional per-sample silhouette scores output [nRows]; nullptr to skip
metric	ML::distance::DistanceType	Yes	Distance metric to use

Inputs (pairwise_distance)

Name	Type	Required	Description
handle	const raft::handle_t&	Yes	RAFT handle
x	const float/double	Yes	Device pointer to first data matrix [m x k]
y	const float/double	Yes	Device pointer to second data matrix [n x k]
m	int	Yes	Number of rows in x
n	int	Yes	Number of rows in y
k	int	Yes	Number of columns (features) in both x and y
metric	ML::distance::DistanceType	Yes	Distance metric to use
isRowMajor	bool	No (default true)	Whether input arrays are row-major
metric_arg	float/double	No (default 2.0)	Parameter p for Minkowski distance

Outputs

Name	Type	Description
return (r2_score_py)	float/double	R-squared score
return (rand_index)	double	Rand index value
return (adjusted_rand_index)	double	Adjusted rand index value
return (silhouette_score)	double/float	Mean silhouette score
return (kl_divergence)	float/double	KL divergence value
return (entropy)	double	Entropy value
return (mutual_info_score)	double	Mutual information score
return (homogeneity_score)	double	Homogeneity score
return (completeness_score)	double	Completeness score
return (v_measure)	double	V-measure value
return (accuracy_score_py)	float	Classification accuracy
dist (pairwise_distance)	float/double	Device pointer to output distance matrix [m x n]
return (trustworthiness_score)	double	Trustworthiness score

Usage Examples

#include <cuml/metrics/metrics.hpp>
#include <cuml/common/distance_type.hpp>
#include <raft/core/handle.hpp>

void evaluate_model() {
    raft::handle_t handle;

    int n = 100;

    // Allocate device memory for ground truth and predictions
    float* y;
    float* y_hat;
    cudaMalloc(&y, n * sizeof(float));
    cudaMalloc(&y_hat, n * sizeof(float));

    // Load y and y_hat onto device...

    // Compute R-squared score
    float r2 = ML::Metrics::r2_score_py(handle, y, y_hat, n);

    // Compute pairwise L2 distances
    int m = 50, k = 10;
    float* x_data;
    float* y_data;
    float* dist;
    cudaMalloc(&x_data, m * k * sizeof(float));
    cudaMalloc(&y_data, n * k * sizeof(float));
    cudaMalloc(&dist, m * n * sizeof(float));

    ML::Metrics::pairwise_distance(handle, x_data, y_data, dist,
                                    m, n, k,
                                    ML::distance::DistanceType::L2SqrtExpanded);

    // Compute classification accuracy
    int* predictions;
    int* ref_predictions;
    cudaMalloc(&predictions, n * sizeof(int));
    cudaMalloc(&ref_predictions, n * sizeof(int));

    // Load predictions and ref_predictions...

    float acc = ML::Metrics::accuracy_score_py(handle, predictions,
                                                ref_predictions, n);

    handle.sync_stream();

    // Clean up
    cudaFree(y);
    cudaFree(y_hat);
    cudaFree(x_data);
    cudaFree(y_data);
    cudaFree(dist);
    cudaFree(predictions);
    cudaFree(ref_predictions);
}

Related Pages

Environment:Rapidsai_Cuml_CUDA_GPU

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment