Revert "Remove Deprecated API (rapidsai#2813)"

This reverts commit d594a8c.

Author: csadorf

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

@@ -0,0 +1,54 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2020-2023, 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-2024, 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

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2023-2025, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2023-2024, NVIDIA CORPORATION.
  * SPDX-License-Identifier: Apache-2.0
  */
 
@@ -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

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2023-2025, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2023-2024, NVIDIA CORPORATION.
  * SPDX-License-Identifier: Apache-2.0
  */
 
@@ -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

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2023-2025, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2023-2024, NVIDIA CORPORATION.
  * SPDX-License-Identifier: Apache-2.0
  */
 
@@ -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