Merge pull request rapidsai#2882 from rapidsai/release/25.12

Forward-merge release/25.12 into main

Author: GPUtester

cpp/include/raft/cluster/detail/kmeans_deprecated.cuh

@@ -0,0 +1,54 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2020-2025, NVIDIA CORPORATION.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#include <raft/cluster/detail/kmeans_deprecated.cuh>
+
+namespace raft {
+namespace cluster {
+
+/**
+ *  @brief Find clusters with k-means algorithm.
+ *    Initial centroids are chosen with k-means++ algorithm. Empty
+ *    clusters are reinitialized by choosing new centroids with
+ *    k-means++ algorithm.
+ *  @tparam index_type_t the type of data used for indexing.
+ *  @tparam value_type_t the type of data used for weights, distances.
+ *  @param handle the raft handle.
+ *  @param n Number of observation vectors.
+ *  @param d Dimension of observation vectors.
+ *  @param k Number of clusters.
+ *  @param tol Tolerance for convergence. k-means stops when the
+ *    change in residual divided by n is less than tol.
+ *  @param maxiter Maximum number of k-means iterations.
+ *  @param obs (Input, device memory, d*n entries) Observation
+ *    matrix. Matrix is stored column-major and each column is an
+ *    observation vector. Matrix dimensions are d x n.
+ *  @param codes (Output, device memory, n entries) Cluster
+ *    assignments.
+ *  @param residual On exit, residual sum of squares (sum of squares
+ *    of distances between observation vectors and centroids).
+ *  @param iters on exit, number of k-means iterations.
+ *  @param seed random seed to be used.
+ *  @return error flag
+ */
+template <typename index_type_t, typename value_type_t>
+int kmeans(raft::resources const& handle,
+           index_type_t n,
+           index_type_t d,
+           index_type_t k,
+           value_type_t tol,
+           index_type_t maxiter,
+           const value_type_t* __restrict__ obs,
+           index_type_t* __restrict__ codes,
+           value_type_t& residual,
+           index_type_t& iters,
+           unsigned long long seed = 123456)
+{
+  return detail::kmeans<index_type_t, value_type_t>(
+    handle, n, d, k, tol, maxiter, obs, codes, residual, iters, seed);
+}
+}  // namespace cluster
+}  // namespace raft

cpp/include/raft/cluster/kmeans.cuh

@@ -0,0 +1,102 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2021-2025, NVIDIA CORPORATION.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#include <raft/cluster/detail/single_linkage.cuh>
+#include <raft/cluster/single_linkage_types.hpp>
+#include <raft/core/device_mdspan.hpp>
+
+namespace raft::cluster {
+
+/**
+ * Note: All of the functions below in the raft::cluster namespace are deprecated
+ * and will be removed in a future release. Please use raft::cluster::hierarchy
+ * instead.
+ */
+
+/**
+ * Single-linkage clustering, capable of constructing a KNN graph to
+ * scale the algorithm beyond the n^2 memory consumption of implementations
+ * that use the fully-connected graph of pairwise distances by connecting
+ * a knn graph when k is not large enough to connect it.
+
+ * @tparam value_idx
+ * @tparam value_t
+ * @tparam dist_type method to use for constructing connectivities graph
+ * @param[in] handle raft handle
+ * @param[in] X dense input matrix in row-major layout
+ * @param[in] m number of rows in X
+ * @param[in] n number of columns in X
+ * @param[in] metric distance metrix to use when constructing connectivities graph
+ * @param[out] out struct containing output dendrogram and cluster assignments
+ * @param[in] c a constant used when constructing connectivities from knn graph. Allows the indirect
+ control
+ *            of k. The algorithm will set `k = log(n) + c`
+ * @param[in] n_clusters number of clusters to assign data samples
+ */
+template <typename value_idx,
+          typename value_t,
+          LinkageDistance dist_type = LinkageDistance::KNN_GRAPH>
+[[deprecated("Use cuVS instead")]] void single_linkage(raft::resources const& handle,
+                                                       const value_t* X,
+                                                       value_idx m,
+                                                       value_idx n,
+                                                       raft::distance::DistanceType metric,
+                                                       linkage_output<value_idx>* out,
+                                                       int c,
+                                                       size_t n_clusters)
+{
+  detail::single_linkage<value_idx, value_t, dist_type>(
+    handle, X, m, n, metric, out, c, n_clusters);
+}
+};  // namespace raft::cluster
+
+namespace raft::cluster::hierarchy {
+
+constexpr int DEFAULT_CONST_C = 15;
+
+/**
+ * Single-linkage clustering, capable of constructing a KNN graph to
+ * scale the algorithm beyond the n^2 memory consumption of implementations
+ * that use the fully-connected graph of pairwise distances by connecting
+ * a knn graph when k is not large enough to connect it.
+
+ * @tparam value_idx
+ * @tparam value_t
+ * @tparam dist_type method to use for constructing connectivities graph
+ * @param[in] handle raft handle
+ * @param[in] X dense input matrix in row-major layout
+ * @param[out] dendrogram output dendrogram (size [n_rows - 1] * 2)
+ * @param[out] labels output labels vector (size n_rows)
+ * @param[in] metric distance metrix to use when constructing connectivities graph
+ * @param[in] n_clusters number of clusters to assign data samples
+ * @param[in] c a constant used when constructing connectivities from knn graph. Allows the indirect
+ control of k. The algorithm will set `k = log(n) + c`
+ */
+template <typename value_t, typename idx_t, LinkageDistance dist_type = LinkageDistance::KNN_GRAPH>
+[[deprecated("Use cuVS instead")]] void single_linkage(
+  raft::resources const& handle,
+  raft::device_matrix_view<const value_t, idx_t, row_major> X,
+  raft::device_matrix_view<idx_t, idx_t, row_major> dendrogram,
+  raft::device_vector_view<idx_t, idx_t> labels,
+  raft::distance::DistanceType metric,
+  size_t n_clusters,
+  std::optional<int> c = std::make_optional<int>(DEFAULT_CONST_C))
+{
+  linkage_output<idx_t> out_arrs;
+  out_arrs.children = dendrogram.data_handle();
+  out_arrs.labels   = labels.data_handle();
+
+  raft::cluster::single_linkage<idx_t, value_t, dist_type>(
+    handle,
+    X.data_handle(),
+    X.extent(0),
+    X.extent(1),
+    metric,
+    &out_arrs,
+    c.has_value() ? c.value() : DEFAULT_CONST_C,
+    n_clusters);
+}
+};  // namespace raft::cluster::hierarchy

cpp/include/raft/cluster/kmeans_balanced.cuh

@@ -74,6 +74,71 @@ struct index : ann::index {
   auto operator=(index&&) -> index&      = default;
   ~index()                               = default;
 
+  /** Construct a brute force index from dataset
+   *
+   * Constructs a brute force index from a dataset. This lets us precompute norms for
+   * the dataset, providing a speed benefit over doing this at query time.
+
+   * If the dataset is already in GPU memory, then this class stores a non-owning reference to
+   * the dataset. If the dataset is in host memory, it will be copied to the device and the
+   * index will own the device memory.
+   */
+
+  template <typename data_accessor>
+  [[deprecated("Use cuVS instead")]] index(
+    raft::resources const& res,
+    mdspan<const T, matrix_extent<int64_t>, row_major, data_accessor> dataset,
+    std::optional<raft::device_vector<T, int64_t>>&& norms,
+    raft::distance::DistanceType metric,
+    T metric_arg = 0.0)
+    : ann::index(),
+      metric_(metric),
+      dataset_(make_device_matrix<T, int64_t>(res, 0, 0)),
+      norms_(std::move(norms)),
+      metric_arg_(metric_arg)
+  {
+    if (norms_) { norms_view_ = make_const_mdspan(norms_.value().view()); }
+    update_dataset(res, dataset);
+    resource::sync_stream(res);
+  }
+
+  /** Construct a brute force index from dataset
+   *
+   * This class stores a non-owning reference to the dataset and norms here.
+   * Having precomputed norms gives us a performance advantage at query time.
+   */
+  [[deprecated("Use cuVS instead")]] index(
+    raft::resources const& res,
+    raft::device_matrix_view<const T, int64_t, row_major> dataset_view,
+    std::optional<raft::device_vector_view<const T, int64_t>> norms_view,
+    raft::distance::DistanceType metric,
+    T metric_arg = 0.0)
+    : ann::index(),
+      metric_(metric),
+      dataset_(make_device_matrix<T, int64_t>(res, 0, 0)),
+      dataset_view_(dataset_view),
+      norms_view_(norms_view),
+      metric_arg_(metric_arg)
+  {
+  }
+
+  template <typename data_accessor>
+  [[deprecated("Use cuVS instead")]] index(
+    raft::resources const& res,
+    index_params const& params,
+    mdspan<const T, matrix_extent<int64_t>, row_major, data_accessor> dataset,
+    std::optional<raft::device_vector<T, int64_t>>&& norms = std::nullopt)
+    : ann::index(),
+      metric_(params.metric),
+      dataset_(make_device_matrix<T, int64_t>(res, 0, 0)),
+      norms_(std::move(norms)),
+      metric_arg_(params.metric_arg)
+  {
+    if (norms_) { norms_view_ = make_const_mdspan(norms_.value().view()); }
+    update_dataset(res, dataset);
+    resource::sync_stream(res);
+  }
+
   /**
    * Replace the dataset with a new dataset.
    */

cpp/include/raft/cluster/kmeans_deprecated.cuh

@@ -374,3 +374,12 @@ void search(raft::resources const& res,
 /** @} */  // end group cagra
 
 }  // namespace raft::neighbors::cagra
+
+// TODO: Remove deprecated experimental namespace in 23.12 release
+namespace raft::neighbors::experimental::cagra {
+using raft::neighbors::cagra::build;
+using raft::neighbors::cagra::build_knn_graph;
+using raft::neighbors::cagra::optimize;
+using raft::neighbors::cagra::search;
+using raft::neighbors::cagra::sort_knn_graph;
+}  // namespace raft::neighbors::experimental::cagra

cpp/include/raft/cluster/single_linkage.cuh

@@ -217,3 +217,10 @@ index<T, IdxT> deserialize(raft::resources const& handle, const std::string& fil
 /**@}*/
 
 }  // namespace raft::neighbors::cagra
+
+// TODO: Remove deprecated experimental namespace in 23.12 release
+namespace raft::neighbors::experimental::cagra {
+using raft::neighbors::cagra::deserialize;
+using raft::neighbors::cagra::serialize;
+
+}  // namespace raft::neighbors::experimental::cagra

cpp/include/raft/neighbors/brute_force_types.hpp

@@ -154,6 +154,21 @@ struct index : ann::index {
     return graph_view_.extent(1);
   }
 
+  /**
+   * DEPRECATED: please use data() instead.
+   *   If you need to query dataset dimensions, use the dim() and size() of the cagra index.
+   *   The data_handle() is not always available: you need to do a dynamic_cast to the expected
+   *   dataset type at runtime.
+   */
+  [[nodiscard]] [[deprecated("Use data()")]] inline auto dataset() const noexcept
+    -> device_matrix_view<const T, int64_t, layout_stride>
+  {
+    auto p = dynamic_cast<strided_dataset<T, int64_t>*>(dataset_.get());
+    if (p != nullptr) { return p->view(); }
+    auto d = dataset_->dim();
+    return make_device_strided_matrix_view<const T, int64_t>(nullptr, 0, d, d);
+  }
+
   /** Dataset [size, dim] */
   [[nodiscard]] inline auto data() const noexcept -> const neighbors::dataset<int64_t>&
   {
@@ -174,6 +189,88 @@ struct index : ann::index {
   auto operator=(index&&) -> index&      = default;
   ~index()                               = default;
 
+  /** Construct an empty index. */
+  [[deprecated("Use cuVS instead")]] index(
+    raft::resources const& res,
+    raft::distance::DistanceType metric = raft::distance::DistanceType::L2Expanded)
+    : ann::index(),
+      metric_(metric),
+      graph_(make_device_matrix<IdxT, int64_t>(res, 0, 0)),
+      dataset_(new neighbors::empty_dataset<int64_t>(0))
+  {
+  }
+
+  /** Construct an index from dataset and knn_graph arrays
+   *
+   * If the dataset and graph is already in GPU memory, then the index is just a thin wrapper around
+   * these that stores a non-owning a reference to the arrays.
+   *
+   * The constructor also accepts host arrays. In that case they are copied to the device, and the
+   * device arrays will be owned by the index.
+   *
+   * In case the dasates rows are not 16 bytes aligned, then we create a padded copy in device
+   * memory to ensure alignment for vectorized load.
+   *
+   * Usage examples:
+   *
+   * - Cagra index is normally created by the cagra::build
+   * @code{.cpp}
+   *   using namespace raft::neighbors::experimental;
+   *   auto dataset = raft::make_host_matrix<float, int64_t>(n_rows, n_cols);
+   *   load_dataset(dataset.view());
+   *   // use default index parameters
+   *   cagra::index_params index_params;
+   *   // create and fill the index from a [N, D] dataset
+   *   auto index = cagra::build(res, index_params, dataset);
+   *   // use default search parameters
+   *   cagra::search_params search_params;
+   *   // search K nearest neighbours
+   *   auto neighbors = raft::make_device_matrix<uint32_t, int64_t>(res, n_queries, k);
+   *   auto distances = raft::make_device_matrix<float, int64_t>(res, n_queries, k);
+   *   cagra::search(res, search_params, index, queries, neighbors, distances);
+   * @endcode
+   *   In the above example, we have passed a host dataset to build. The returned index will own a
+   * device copy of the dataset and the knn_graph. In contrast, if we pass the dataset as a
+   * device_mdspan to build, then it will only store a reference to it.
+   *
+   * - Constructing index using existing knn-graph
+   * @code{.cpp}
+   *   using namespace raft::neighbors::experimental;
+   *
+   *   auto dataset = raft::make_device_matrix<float, int64_t>(res, n_rows, n_cols);
+   *   auto knn_graph = raft::make_device_matrix<uint32_n, int64_t>(res, n_rows, graph_degree);
+   *
+   *   // custom loading and graph creation
+   *   // load_dataset(dataset.view());
+   *   // create_knn_graph(knn_graph.view());
+   *
+   *   // Wrap the existing device arrays into an index structure
+   *   cagra::index<T, IdxT> index(res, metric, raft::make_const_mdspan(dataset.view()),
+   *                               raft::make_const_mdspan(knn_graph.view()));
+   *
+   *   // Both knn_graph and dataset objects have to be in scope while the index is used because
+   *   // the index only stores a reference to these.
+   *   cagra::search(res, search_params, index, queries, neighbors, distances);
+   * @endcode
+   *
+   */
+  template <typename data_accessor, typename graph_accessor>
+  [[deprecated("Use cuVS instead")]] index(
+    raft::resources const& res,
+    raft::distance::DistanceType metric,
+    mdspan<const T, matrix_extent<int64_t>, row_major, data_accessor> dataset,
+    mdspan<const IdxT, matrix_extent<int64_t>, row_major, graph_accessor> knn_graph)
+    : ann::index(),
+      metric_(metric),
+      graph_(make_device_matrix<IdxT, int64_t>(res, 0, 0)),
+      dataset_(make_aligned_dataset(res, dataset, 16))
+  {
+    RAFT_EXPECTS(dataset.extent(0) == knn_graph.extent(0),
+                 "Dataset and knn_graph must have equal number of rows");
+    update_graph(res, knn_graph);
+    resource::sync_stream(res);
+  }
+
   /**
    * Replace the dataset with a new dataset.
    *
@@ -263,3 +360,13 @@ struct index : ann::index {
 /** @} */
 
 }  // namespace raft::neighbors::cagra
+
+// TODO: Remove deprecated experimental namespace in 23.12 release
+namespace raft::neighbors::experimental::cagra {
+using raft::neighbors::cagra::graph_build_algo;
+using raft::neighbors::cagra::hash_mode;
+using raft::neighbors::cagra::index;
+using raft::neighbors::cagra::index_params;
+using raft::neighbors::cagra::search_algo;
+using raft::neighbors::cagra::search_params;
+}  // namespace raft::neighbors::experimental::cagra

cpp/include/raft/neighbors/cagra.cuh

@@ -30,6 +30,20 @@ struct search_params : ann::search_params {
 template <typename T>
 struct index : ann::index {
  public:
+  /**
+   * @brief load a base-layer-only hnswlib index originally saved from a built CAGRA index.
+   *  This is a virtual class and it cannot be used directly. To create an index, use the factory
+   *  function `raft::neighbors::hnsw::from_cagra` from the header
+   *  `raft/neighbors/hnsw.hpp`
+   *
+   * @param[in] dim dimensions of the training dataset
+   * @param[in] metric distance metric to search. Supported metrics ("L2Expanded", "InnerProduct")
+   */
+  [[deprecated("Use cuVS instead")]] index(int dim, raft::distance::DistanceType metric)
+    : dim_{dim}, metric_{metric}
+  {
+  }
+
   /**
   @brief Get underlying index
   */