For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
GitHubCUDA-X
    • Home
    • Installation
  • Getting Started
    • Introduction
    • Integrations
    • Use-cases
  • User Guide
    • API Guide
    • Benchmarking Guide
    • Field Guide
    • References
  • Developer Guide
    • Coding Guidelines
    • Contributing
  • API Reference
    • C API Documentation
    • Cpp API Documentation
      • Cluster Agglomerative
      • Cluster Kmeans
      • Cluster Spectral
      • Common Types
      • Distance Distance
      • Distance Grammian
      • Neighbors All Neighbors
      • Neighbors Ball Cover
      • Neighbors Brute Force
      • Neighbors Cagra
      • Neighbors Common
      • Neighbors Dynamic Batching
      • Neighbors Epsilon Neighborhood
      • Neighbors HNSW
      • Neighbors Composite Index
      • Neighbors IVF Flat
      • Neighbors IVF PQ
      • Neighbors IVF SQ
      • Neighbors NN Descent
      • Neighbors Refine
      • Neighbors Scann
      • Neighbors Tiered Index
      • Neighbors Vamana
      • Preprocessing Quantize Binary
      • Preprocessing PCA
      • Preprocessing Quantize PQ
      • Preprocessing Quantize Scalar
      • Preprocessing Spectral Embedding
      • Selection Select K
      • Stats Silhouette Score
      • Stats Trustworthiness Score
      • Util Cutlass Utils
      • Util File Io
    • Python API Documentation
    • Java API Documentation
    • Rust API Documentation
    • Go API Documentation
NVIDIANVIDIA
Developer-friendly docs for your API
Privacy Policy | Your Privacy Choices | Terms of Service | Accessibility | Corporate Policies | Product Security | Contact

Copyright © 2026, NVIDIA Corporation.

LogoLogocuVS
GitHubCUDA-X
On this page
  • Types
  • distance::DistanceType
  • distance::DensityKernelType
  • distance::kernels::KernelParams
  • Pairwise Distances API
  • distance::pairwise_distance
API ReferenceCpp API Documentation

Distance

||View as Markdown|
Previous

Errors and Logging

Next

Distance Grammian

Source header: cuvs/distance/distance.hpp

Types

distance::DistanceType

enum to tell how to compute distance

1enum class DistanceType : int {
2 L2Expanded = 0,
3 CosineExpanded = 2,
4 L1 = 3,
5 L2Unexpanded = 4,
6 InnerProduct = 6,
7 Linf = 7,
8 Canberra = 8,
9 LpUnexpanded = 9,
10 CorrelationExpanded = 10,
11 JaccardExpanded = 11,
12 HellingerExpanded = 12,
13 Haversine = 13,
14 BrayCurtis = 14,
15 JensenShannon = 15,
16 HammingUnexpanded = 16,
17 KLDivergence = 17,
18 RusselRaoExpanded = 18,
19 DiceExpanded = 19,
20 BitwiseHamming = 20,
21 Precomputed = 100,
22 CustomUDF = 101
23};

Values

NameValue
L2Expanded0
CosineExpanded2
L13
L2Unexpanded4
InnerProduct6
Linf7
Canberra8
LpUnexpanded9
CorrelationExpanded10
JaccardExpanded11
HellingerExpanded12
Haversine13
BrayCurtis14
JensenShannon15
HammingUnexpanded16
KLDivergence17
RusselRaoExpanded18
DiceExpanded19
BitwiseHamming20
Precomputed100
CustomUDF101

distance::DensityKernelType

Density kernel type for Kernel Density Estimation.

These are the smoothing kernels used in KDE — distinct from the dot-product kernels (RBF, Polynomial, etc.) in cuvs::distance::kernels used by SVMs.

1enum class DensityKernelType : int {
2 Gaussian = 0,
3 Tophat = 1,
4 Epanechnikov = 2,
5 Exponential = 3,
6 Linear = 4,
7 Cosine = 5
8};

Values

NameValue
Gaussian0
Tophat1
Epanechnikov2
Exponential3
Linear4
Cosine5

distance::kernels::KernelParams

Parameters for kernel matrices.

The following kernels are implemented:

  • LINEAR K(x1,x2)=⟨x1,x2⟩,K(x_1,x_2) = \langle x_1,x_2 \rangle,K(x1​,x2​)=⟨x1​,x2​⟩, where ⟨,⟩\langle , \rangle⟨,⟩ is the dot product
  • POLYNOMIAL K(x1,x2)=(γ⟨x1,x2⟩+coef0)degreeK(x_1, x_2) = (\gamma \langle x_1,x_2 \rangle + \mathrm{coef0})^\mathrm{degree}K(x1​,x2​)=(γ⟨x1​,x2​⟩+coef0)degree
  • RBF K(x1,x2)=exp⁡(−γ∥x1−x2∥2)K(x_1, x_2) = \exp(- \gamma \lVert x_1-x_2 \rVert^2)K(x1​,x2​)=exp(−γ∥x1​−x2​∥2)
  • TANH K(x1,x2)=tanh⁡(γ⟨x1,x2⟩+coef0)K(x_1, x_2) = \tanh(\gamma \langle x_1,x_2 \rangle + \mathrm{coef0})K(x1​,x2​)=tanh(γ⟨x1​,x2​⟩+coef0)
1struct KernelParams {
2 KernelType kernel;
3 int degree;
4 double gamma;
5 double coef0;
6};

Fields

NameTypeDescription
kernelKernelType
degreeint
gammadouble
coef0double

Pairwise Distances API

distance::pairwise_distance

Compute pairwise distances for two matrices

1void pairwise_distance(
2raft::resources const& handle,
3raft::device_matrix_view<const float, std::int64_t, raft::layout_c_contiguous> const x,
4raft::device_matrix_view<const float, std::int64_t, raft::layout_c_contiguous> const y,
5raft::device_matrix_view<float, std::int64_t, raft::layout_c_contiguous> dist,
6cuvs::distance::DistanceType metric,
7float metric_arg = 2.0f);

Note: Only contiguous row- or column-major layouts supported currently.

Usage example:

Parameters

NameDirectionTypeDescription
handleinraft::resources const&raft handle for managing expensive resources
xinraft::device_matrix_view<const float, std::int64_t, raft::layout_c_contiguous> constfirst set of points (size n*k)
yinraft::device_matrix_view<const float, std::int64_t, raft::layout_c_contiguous> constsecond set of points (size m*k)
distoutraft::device_matrix_view<float, std::int64_t, raft::layout_c_contiguous>output distance matrix (size n*m)
metricincuvs::distance::DistanceTypedistance to evaluate
metric_arginfloatmetric argument (used for Minkowski distance)
Default: 2.0f.

Returns

void

Additional overload: distance::pairwise_distance

Compute pairwise distances for two matrices

1void pairwise_distance(
2raft::resources const& handle,
3raft::device_matrix_view<const double, std::int64_t, raft::layout_c_contiguous> const x,
4raft::device_matrix_view<const double, std::int64_t, raft::layout_c_contiguous> const y,
5raft::device_matrix_view<double, std::int64_t, raft::layout_c_contiguous> dist,
6cuvs::distance::DistanceType metric,
7double metric_arg = 2.0f);

Note: Only contiguous row- or column-major layouts supported currently.

Usage example:

Parameters

NameDirectionTypeDescription
handleinraft::resources const&raft handle for managing expensive resources
xinraft::device_matrix_view<const double, std::int64_t, raft::layout_c_contiguous> constfirst set of points (size n*k)
yinraft::device_matrix_view<const double, std::int64_t, raft::layout_c_contiguous> constsecond set of points (size m*k)
distoutraft::device_matrix_view<double, std::int64_t, raft::layout_c_contiguous>output distance matrix (size n*m)
metricincuvs::distance::DistanceTypedistance to evaluate
metric_argindoublemetric argument (used for Minkowski distance)
Default: 2.0f.

Returns

void

Additional overload: distance::pairwise_distance

Compute pairwise distances for two matrices

1void pairwise_distance(
2raft::resources const& handle,
3raft::device_matrix_view<const half, std::int64_t, raft::layout_c_contiguous> const x,
4raft::device_matrix_view<const half, std::int64_t, raft::layout_c_contiguous> const y,
5raft::device_matrix_view<float, std::int64_t, raft::layout_c_contiguous> dist,
6cuvs::distance::DistanceType metric,
7float metric_arg = 2.0f);

Note: Only contiguous row- or column-major layouts supported currently.

Usage example:

Parameters

NameDirectionTypeDescription
handleinraft::resources const&raft handle for managing expensive resources
xinraft::device_matrix_view<const half, std::int64_t, raft::layout_c_contiguous> constfirst set of points (size n*k)
yinraft::device_matrix_view<const half, std::int64_t, raft::layout_c_contiguous> constsecond set of points (size m*k)
distoutraft::device_matrix_view<float, std::int64_t, raft::layout_c_contiguous>output distance matrix (size n*m)
metricincuvs::distance::DistanceTypedistance to evaluate
metric_arginfloatmetric argument (used for Minkowski distance)
Default: 2.0f.

Returns

void

Additional overload: distance::pairwise_distance

Compute pairwise distances for two matrices

1void pairwise_distance(
2raft::resources const& handle,
3raft::device_matrix_view<const float, std::int64_t, raft::layout_f_contiguous> const x,
4raft::device_matrix_view<const float, std::int64_t, raft::layout_f_contiguous> const y,
5raft::device_matrix_view<float, std::int64_t, raft::layout_f_contiguous> dist,
6cuvs::distance::DistanceType metric,
7float metric_arg = 2.0f);

Note: Only contiguous row- or column-major layouts supported currently.

Usage example:

Parameters

NameDirectionTypeDescription
handleinraft::resources const&raft handle for managing expensive resources
xinraft::device_matrix_view<const float, std::int64_t, raft::layout_f_contiguous> constfirst set of points (size n*k)
yinraft::device_matrix_view<const float, std::int64_t, raft::layout_f_contiguous> constsecond set of points (size m*k)
distoutraft::device_matrix_view<float, std::int64_t, raft::layout_f_contiguous>output distance matrix (size n*m)
metricincuvs::distance::DistanceTypedistance to evaluate
metric_arginfloatmetric argument (used for Minkowski distance)
Default: 2.0f.

Returns

void

Additional overload: distance::pairwise_distance

Compute pairwise distances for two matrices

1void pairwise_distance(
2raft::resources const& handle,
3raft::device_matrix_view<const double, std::int64_t, raft::layout_f_contiguous> const x,
4raft::device_matrix_view<const double, std::int64_t, raft::layout_f_contiguous> const y,
5raft::device_matrix_view<double, std::int64_t, raft::layout_f_contiguous> dist,
6cuvs::distance::DistanceType metric,
7double metric_arg = 2.0f);

Note: Only contiguous row- or column-major layouts supported currently.

Usage example:

Parameters

NameDirectionTypeDescription
handleinraft::resources const&raft handle for managing expensive resources
xinraft::device_matrix_view<const double, std::int64_t, raft::layout_f_contiguous> constfirst set of points (size n*k)
yinraft::device_matrix_view<const double, std::int64_t, raft::layout_f_contiguous> constsecond set of points (size m*k)
distoutraft::device_matrix_view<double, std::int64_t, raft::layout_f_contiguous>output distance matrix (size n*m)
metricincuvs::distance::DistanceTypedistance to evaluate
metric_argindoublemetric argument (used for Minkowski distance)
Default: 2.0f.

Returns

void

Additional overload: distance::pairwise_distance

Compute pairwise distances for two matrices

1void pairwise_distance(
2raft::resources const& handle,
3raft::device_matrix_view<const half, std::int64_t, raft::layout_f_contiguous> const x,
4raft::device_matrix_view<const half, std::int64_t, raft::layout_f_contiguous> const y,
5raft::device_matrix_view<float, std::int64_t, raft::layout_f_contiguous> dist,
6cuvs::distance::DistanceType metric,
7float metric_arg = 2.0f);

Note: Only contiguous row- or column-major layouts supported currently.

Usage example:

Parameters

NameDirectionTypeDescription
handleinraft::resources const&raft handle for managing expensive resources
xinraft::device_matrix_view<const half, std::int64_t, raft::layout_f_contiguous> constfirst set of points (size n*k)
yinraft::device_matrix_view<const half, std::int64_t, raft::layout_f_contiguous> constsecond set of points (size m*k)
distoutraft::device_matrix_view<float, std::int64_t, raft::layout_f_contiguous>output distance matrix (size n*m)
metricincuvs::distance::DistanceTypedistance to evaluate
metric_arginfloatmetric argument (used for Minkowski distance)
Default: 2.0f.

Returns

void

Additional overload: distance::pairwise_distance

Compute sparse pairwise distances between x and y, using the provided input configuration and distance function.

1void pairwise_distance(raft::resources const& handle,
2raft::device_csr_matrix_view<const float, int, int, int> x,
3raft::device_csr_matrix_view<const float, int, int, int> y,
4raft::device_matrix_view<float, int, raft::row_major> dist,
5cuvs::distance::DistanceType metric,
6float metric_arg = 2.0f);

Parameters

NameDirectionTypeDescription
handleinraft::resources const&raft::resources
xinraft::device_csr_matrix_view<const float, int, int, int>raft::device_csr_matrix_view
yinraft::device_csr_matrix_view<const float, int, int, int>raft::device_csr_matrix_view
distoutraft::device_matrix_view<float, int, raft::row_major>raft::device_matrix_view dense matrix
metricincuvs::distance::DistanceTypedistance metric to use
metric_arginfloatmetric argument (used for Minkowski distance)
Default: 2.0f.

Returns

void

Additional overload: distance::pairwise_distance

Compute sparse pairwise distances between x and y, using the provided input configuration and distance function.

1void pairwise_distance(raft::resources const& handle,
2raft::device_csr_matrix_view<const double, int, int, int> x,
3raft::device_csr_matrix_view<const double, int, int, int> y,
4raft::device_matrix_view<double, int, raft::row_major> dist,
5cuvs::distance::DistanceType metric,
6float metric_arg = 2.0f);

Parameters

NameDirectionTypeDescription
handleinraft::resources const&raft::resources
xinraft::device_csr_matrix_view<const double, int, int, int>raft::device_csr_matrix_view
yinraft::device_csr_matrix_view<const double, int, int, int>raft::device_csr_matrix_view
distoutraft::device_matrix_view<double, int, raft::row_major>raft::device_matrix_view dense matrix
metricincuvs::distance::DistanceTypedistance metric to use
metric_arginfloatmetric argument (used for Minkowski distance)
Default: 2.0f.

Returns

void