Distance#

This page provides C++ class references for the publicly-exposed elements of the cuvs/distance package. cuVS’s distances have been highly optimized and support a wide assortment of different distance measures.

Distance Types#

#include <cuvs/distance/distance.h>

namespace cuvs::distance

enum cuvsDistanceType#

enum to tell how to compute distance

Values:

enumerator L2Expanded#

evaluate as dist_ij = sum(x_ik^2) + sum(y_ij)^2 - 2*sum(x_ik * y_jk)

enumerator L2SqrtExpanded#

same as above, but inside the epilogue, perform square root operation

enumerator CosineExpanded#

cosine distance

enumerator L1#

L1 distance

enumerator L2Unexpanded#

evaluate as dist_ij += (x_ik - y-jk)^2

enumerator L2SqrtUnexpanded#

same as above, but inside the epilogue, perform square root operation

enumerator InnerProduct#

basic inner product

enumerator Linf#

Chebyshev (Linf) distance

enumerator Canberra#

Canberra distance

enumerator LpUnexpanded#

Generalized Minkowski distance

enumerator CorrelationExpanded#

Correlation distance

enumerator JaccardExpanded#

Jaccard distance

enumerator HellingerExpanded#

Hellinger distance

enumerator Haversine#

Haversine distance

enumerator BrayCurtis#

Bray-Curtis distance

enumerator JensenShannon#

Jensen-Shannon distance

enumerator HammingUnexpanded#

Hamming distance

enumerator KLDivergence#

KLDivergence

enumerator RusselRaoExpanded#

RusselRao

enumerator DiceExpanded#

Dice-Sorensen distance

enumerator BitwiseHamming#

Bitstring Hamming distance

enumerator Precomputed#

Precomputed (special value)

Pairwise Distances#

include <cuvs/distance/distance.hpp>

namespace cuvs::distance

void pairwise_distance(
raft::resources const &handle,
raft::device_matrix_view<const float, std::int64_t, raft::layout_c_contiguous> const x,
raft::device_matrix_view<const float, std::int64_t, raft::layout_c_contiguous> const y,
raft::device_matrix_view<float, std::int64_t, raft::layout_c_contiguous> dist,
cuvs::distance::DistanceType metric,
float metric_arg = 2.0f
)#

Compute pairwise distances for two matrices.

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

Usage example:

#include <raft/core/resources.hpp>
#include <raft/core/device_mdarray.hpp>
#include <cuvs/distance/distance.hpp>

raft::resources handle;
int n_samples = 5000;
int n_features = 50;

auto input = raft::make_device_matrix<float>(handle, n_samples, n_features);

// ... fill input with data ...

auto output = raft::make_device_matrix<float>(handle, n_samples, n_samples);

auto metric = cuvs::distance::DistanceType::L2SqrtExpanded;
cuvs::distance::pairwise_distance(handle,
                                  raft::make_const(input.view()),
                                  raft::make_const(input.view()),
                                  output.view(),
                                  metric);

Parameters:
  • handle[in] raft handle for managing expensive resources

  • x[in] first set of points (size n*k)

  • y[in] second set of points (size m*k)

  • dist[out] output distance matrix (size n*m)

  • metric[in] distance to evaluate

  • metric_arg[in] metric argument (used for Minkowski distance)

void pairwise_distance(
raft::resources const &handle,
raft::device_matrix_view<const double, std::int64_t, raft::layout_c_contiguous> const x,
raft::device_matrix_view<const double, std::int64_t, raft::layout_c_contiguous> const y,
raft::device_matrix_view<double, std::int64_t, raft::layout_c_contiguous> dist,
cuvs::distance::DistanceType metric,
double metric_arg = 2.0f
)#

Compute pairwise distances for two matrices.

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

Usage example:

#include <raft/core/resources.hpp>
#include <raft/core/device_mdarray.hpp>
#include <cuvs/distance/distance.hpp>

raft::resources handle;
int n_samples = 5000;
int n_features = 50;

auto input = raft::make_device_matrix<double>(handle, n_samples, n_features);

// ... fill input with data ...

auto output = raft::make_device_matrix<double>(handle, n_samples, n_samples);

auto metric = cuvs::distance::DistanceType::L2SqrtExpanded;
cuvs::distance::pairwise_distance(handle,
                                  raft::make_const(input.view()),
                                  raft::make_const(input.view()),
                                  output.view(),
                                  metric);

Parameters:
  • handle[in] raft handle for managing expensive resources

  • x[in] first set of points (size n*k)

  • y[in] second set of points (size m*k)

  • dist[out] output distance matrix (size n*m)

  • metric[in] distance to evaluate

  • metric_arg[in] metric argument (used for Minkowski distance)

void pairwise_distance(
raft::resources const &handle,
raft::device_matrix_view<const half, std::int64_t, raft::layout_c_contiguous> const x,
raft::device_matrix_view<const half, std::int64_t, raft::layout_c_contiguous> const y,
raft::device_matrix_view<float, std::int64_t, raft::layout_c_contiguous> dist,
cuvs::distance::DistanceType metric,
float metric_arg = 2.0f
)#

Compute pairwise distances for two matrices.

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

Usage example:

#include <raft/core/resources.hpp>
#include <raft/core/device_mdarray.hpp>
#include <cuvs/distance/distance.hpp>

raft::resources handle;
int n_samples = 5000;
int n_features = 50;

auto input = raft::make_device_matrix<float>(handle, n_samples, n_features);

// ... fill input with data ...

auto output = raft::make_device_matrix<float>(handle, n_samples, n_samples);

auto metric = cuvs::distance::DistanceType::L2SqrtExpanded;
cuvs::distance::pairwise_distance(handle,
                                  raft::make_const(input.view()),
                                  raft::make_const(input.view()),
                                  output.view(),
                                  metric);

Parameters:
  • handle[in] raft handle for managing expensive resources

  • x[in] first set of points (size n*k)

  • y[in] second set of points (size m*k)

  • dist[out] output distance matrix (size n*m)

  • metric[in] distance to evaluate

  • metric_arg[in] metric argument (used for Minkowski distance)

void pairwise_distance(
raft::resources const &handle,
raft::device_matrix_view<const float, std::int64_t, raft::layout_f_contiguous> const x,
raft::device_matrix_view<const float, std::int64_t, raft::layout_f_contiguous> const y,
raft::device_matrix_view<float, std::int64_t, raft::layout_f_contiguous> dist,
cuvs::distance::DistanceType metric,
float metric_arg = 2.0f
)#

Compute pairwise distances for two matrices.

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

Usage example:

#include <raft/core/resources.hpp>
#include <raft/core/device_mdarray.hpp>
#include <cuvs/distance/distance.hpp>

raft::resources handle;
int n_samples = 5000;
int n_features = 50;

auto input = raft::make_device_matrix<float>(handle, n_samples, n_features);

// ... fill input with data ...

auto output = raft::make_device_matrix<float>(handle, n_samples, n_samples);

auto metric = cuvs::distance::DistanceType::L2SqrtExpanded;
cuvs::distance::pairwise_distance(handle,
                                  raft::make_const(input.view()),
                                  raft::make_const(input.view()),
                                  output.view(),
                                  metric);

Parameters:
  • handle[in] raft handle for managing expensive resources

  • x[in] first set of points (size n*k)

  • y[in] second set of points (size m*k)

  • dist[out] output distance matrix (size n*m)

  • metric[in] distance to evaluate

  • metric_arg[in] metric argument (used for Minkowski distance)

void pairwise_distance(
raft::resources const &handle,
raft::device_matrix_view<const double, std::int64_t, raft::layout_f_contiguous> const x,
raft::device_matrix_view<const double, std::int64_t, raft::layout_f_contiguous> const y,
raft::device_matrix_view<double, std::int64_t, raft::layout_f_contiguous> dist,
cuvs::distance::DistanceType metric,
double metric_arg = 2.0f
)#

Compute pairwise distances for two matrices.

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

Usage example:

#include <raft/core/resources.hpp>
#include <raft/core/device_mdarray.hpp>
#include <cuvs/distance/distance.hpp>

raft::resources handle;
int n_samples = 5000;
int n_features = 50;

auto input = raft::make_device_matrix<double>(handle, n_samples, n_features);

// ... fill input with data ...

auto output = raft::make_device_matrix<double>(handle, n_samples, n_samples);

auto metric = cuvs::distance::DistanceType::L2SqrtExpanded;
cuvs::distance::pairwise_distance(handle,
                                  raft::make_const(input.view()),
                                  raft::make_const(input.view()),
                                  output.view(),
                                  metric);

Parameters:
  • handle[in] raft handle for managing expensive resources

  • x[in] first set of points (size n*k)

  • y[in] second set of points (size m*k)

  • dist[out] output distance matrix (size n*m)

  • metric[in] distance to evaluate

  • metric_arg[in] metric argument (used for Minkowski distance)

void pairwise_distance(
raft::resources const &handle,
raft::device_matrix_view<const half, std::int64_t, raft::layout_f_contiguous> const x,
raft::device_matrix_view<const half, std::int64_t, raft::layout_f_contiguous> const y,
raft::device_matrix_view<float, std::int64_t, raft::layout_f_contiguous> dist,
cuvs::distance::DistanceType metric,
float metric_arg = 2.0f
)#

Compute pairwise distances for two matrices.

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

Usage example:

#include <raft/core/resources.hpp>
#include <raft/core/device_mdarray.hpp>
#include <cuvs/distance/distance.hpp>

raft::resources handle;
int n_samples = 5000;
int n_features = 50;

auto input = raft::make_device_matrix<float>(handle, n_samples, n_features);

// ... fill input with data ...

auto output = raft::make_device_matrix<float>(handle, n_samples, n_samples);

auto metric = cuvs::distance::DistanceType::L2SqrtExpanded;
cuvs::distance::pairwise_distance(handle,
                                  raft::make_const(input.view()),
                                  raft::make_const(input.view()),
                                  output.view(),
                                  metric);

Parameters:
  • handle[in] raft handle for managing expensive resources

  • x[in] first set of points (size n*k)

  • y[in] second set of points (size m*k)

  • dist[out] output distance matrix (size n*m)

  • metric[in] distance to evaluate

  • metric_arg[in] metric argument (used for Minkowski distance)

void pairwise_distance(
raft::resources const &handle,
raft::device_csr_matrix_view<const float, int, int, int> x,
raft::device_csr_matrix_view<const float, int, int, int> y,
raft::device_matrix_view<float, int, raft::row_major> dist,
cuvs::distance::DistanceType metric,
float metric_arg = 2.0f
)#

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

#include <raft/core/device_resources.hpp>
#include <raft/core/device_csr_matrix.hpp>
#include <raft/core/device_mdspan.hpp>

int x_n_rows = 100000;
int y_n_rows = 50000;
int n_cols = 10000;

raft::device_resources handle;
auto x = raft::make_device_csr_matrix<float>(handle, x_n_rows, n_cols);
auto y = raft::make_device_csr_matrix<float>(handle, y_n_rows, n_cols);

...
// populate data
...

auto out = raft::make_device_matrix<float>(handle, x_nrows, y_nrows);
auto metric = cuvs::distance::DistanceType::L2Expanded;
raft::sparse::distance::pairwise_distance(handle, x.view(), y.view(), out, metric);
Parameters:
  • handle[in] raft::resources

  • x[in] raft::device_csr_matrix_view

  • y[in] raft::device_csr_matrix_view

  • dist[out] raft::device_matrix_view dense matrix

  • metric[in] distance metric to use

  • metric_arg[in] metric argument (used for Minkowski distance)

void pairwise_distance(
raft::resources const &handle,
raft::device_csr_matrix_view<const double, int, int, int> x,
raft::device_csr_matrix_view<const double, int, int, int> y,
raft::device_matrix_view<double, int, raft::row_major> dist,
cuvs::distance::DistanceType metric,
float metric_arg = 2.0f
)#

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

#include <raft/core/device_resources.hpp>
#include <raft/core/device_csr_matrix.hpp>
#include <raft/core/device_mdspan.hpp>

int x_n_rows = 100000;
int y_n_rows = 50000;
int n_cols = 10000;

raft::device_resources handle;
auto x = raft::make_device_csr_matrix<double>(handle, x_n_rows, n_cols);
auto y = raft::make_device_csr_matrix<double>(handle, y_n_rows, n_cols);

...
// populate data
...

auto out = raft::make_device_matrix<double>(handle, x_nrows, y_nrows);
auto metric = cuvs::distance::DistanceType::L2Expanded;
raft::sparse::distance::pairwise_distance(handle, x.view(), y.view(), out, metric);
Parameters:
  • handle[in] raft::resources

  • x[in] raft::device_csr_matrix_view

  • y[in] raft::device_csr_matrix_view

  • dist[out] raft::device_matrix_view dense matrix

  • metric[in] distance metric to use

  • metric_arg[in] metric argument (used for Minkowski distance)