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.hpp>

namespace cuvs::distance

Warning

doxygenenum: Cannot find enum “cuvs::distance::DistanceType” in doxygen xml output for project “cuvs” from directory: ../../cpp/doxygen/_xml/

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)