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;
cuvs::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;
cuvs::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)