Renaming namespaces to promote CAGRA from experimental (#1666)

This PR formally renames the namespaces to promote CAGRA from experimental. It's a lot of very small changes but the approach was the following:

1. Rename all occurrences of `raft::neighbors::experimental::cagra` to `raft::neighbors::cagra`
2. Create new namespaces in each of the public API headers for CAGRA that export `raft::neighbors::cagra` to `raft::neighbors::experimental::cagra`
3. Create an issue to eventually remove the deprecated `raft::neighbors::experimental::cagra` namespace
4. Reference issue in TODO comments in the corresponding files to remove the experimental namespaces after a couple releases.

Authors:
  - Corey J. Nolet (https://github.com/cjnolet)

Approvers:
  - Bradley Dice (https://github.com/bdice)
  - Tamas Bela Feher (https://github.com/tfeher)

URL: #1666

cpp/bench/ann/src/raft/raft_cagra_wrapper.h

@@ -50,7 +50,7 @@ class RaftCagra : public ANN<T> {
     raft::neighbors::experimental::cagra::search_params p;
   };
 
-  using BuildParam = raft::neighbors::experimental::cagra::index_params;
+  using BuildParam = raft::neighbors::cagra::index_params;
 
   RaftCagra(Metric metric, int dim, const BuildParam& param);
 
@@ -82,8 +82,8 @@ class RaftCagra : public ANN<T> {
  private:
   raft::device_resources handle_;
   BuildParam index_params_;
-  raft::neighbors::experimental::cagra::search_params search_params_;
-  std::optional<raft::neighbors::experimental::cagra::index<T, IdxT>> index_;
+  raft::neighbors::cagra::search_params search_params_;
+  std::optional<raft::neighbors::cagra::index<T, IdxT>> index_;
   int device_;
   int dimension_;
   rmm::mr::pool_memory_resource<rmm::mr::device_memory_resource> mr_;
@@ -106,13 +106,11 @@ void RaftCagra<T, IdxT>::build(const T* dataset, size_t nrow, cudaStream_t)
 {
   if (get_property().dataset_memory_type == MemoryType::Host) {
     auto dataset_view = raft::make_host_matrix_view<const T, IdxT>(dataset, IdxT(nrow), dimension_);
-    index_.emplace(
-      raft::neighbors::experimental::cagra::build(handle_, index_params_, dataset_view));
+    index_.emplace(raft::neighbors::cagra::build(handle_, index_params_, dataset_view));
   } else {
     auto dataset_view =
       raft::make_device_matrix_view<const T, IdxT>(dataset, IdxT(nrow), dimension_);
-    index_.emplace(
-      raft::neighbors::experimental::cagra::build(handle_, index_params_, dataset_view));
+    index_.emplace(raft::neighbors::cagra::build(handle_, index_params_, dataset_view));
   }
   return;
 }
@@ -128,14 +126,14 @@ void RaftCagra<T, IdxT>::set_search_param(const AnnSearchParam& param)
 template <typename T, typename IdxT>
 void RaftCagra<T, IdxT>::save(const std::string& file) const
 {
-  raft::neighbors::experimental::cagra::serialize(handle_, file, *index_);
+  raft::neighbors::cagra::serialize(handle_, file, *index_);
   return;
 }
 
 template <typename T, typename IdxT>
 void RaftCagra<T, IdxT>::load(const std::string& file)
 {
-  index_ = raft::neighbors::experimental::cagra::deserialize<T, IdxT>(handle_, file);
+  index_ = raft::neighbors::cagra::deserialize<T, IdxT>(handle_, file);
   return;
 }
 
@@ -156,7 +154,7 @@ void RaftCagra<T, IdxT>::search(
   auto neighbors_view = raft::make_device_matrix_view<IdxT, IdxT>(neighbors_IdxT, batch_size, k);
   auto distances_view = raft::make_device_matrix_view<float, IdxT>(distances, batch_size, k);
 
-  raft::neighbors::experimental::cagra::search(
+  raft::neighbors::cagra::search(
     handle_, search_params_, *index_, queries_view, neighbors_view, distances_view);
 
   if (!std::is_same<IdxT, size_t>::value) {

cpp/bench/prims/neighbors/cagra_bench.cuh

@@ -74,13 +74,13 @@ struct CagraBench : public fixture {
 
     auto metric = raft::distance::DistanceType::L2Expanded;
 
-    index_.emplace(raft::neighbors::experimental::cagra::index<T, IdxT>(
+    index_.emplace(raft::neighbors::cagra::index<T, IdxT>(
       handle, metric, make_const_mdspan(dataset_.view()), make_const_mdspan(knn_graph_.view())));
   }
 
   void run_benchmark(::benchmark::State& state) override
   {
-    raft::neighbors::experimental::cagra::search_params search_params;
+    raft::neighbors::cagra::search_params search_params;
     search_params.max_queries       = 1024;
     search_params.itopk_size        = params_.itopk_size;
     search_params.team_size         = 0;
@@ -96,7 +96,7 @@ struct CagraBench : public fixture {
 
     auto queries_v = make_const_mdspan(queries_.view());
     loop_on_state(state, [&]() {
-      raft::neighbors::experimental::cagra::search(
+      raft::neighbors::cagra::search(
         this->handle, search_params, *this->index_, queries_v, ind_v, dist_v);
     });
 
@@ -124,7 +124,7 @@ struct CagraBench : public fixture {
 
  private:
   const params params_;
-  std::optional<const raft::neighbors::experimental::cagra::index<T, IdxT>> index_;
+  std::optional<const raft::neighbors::cagra::index<T, IdxT>> index_;
   raft::device_matrix<T, IdxT, row_major> queries_;
   raft::device_matrix<T, IdxT, row_major> dataset_;
   raft::device_matrix<IdxT, IdxT, row_major> knn_graph_;

cpp/include/raft/neighbors/cagra.cuh

@@ -27,7 +27,7 @@
 #include <raft/neighbors/cagra_types.hpp>
 #include <rmm/cuda_stream_view.hpp>
 
-namespace raft::neighbors::experimental::cagra {
+namespace raft::neighbors::cagra {
 
 /**
  * @defgroup cagra CUDA ANN Graph-based nearest neighbor search
@@ -91,7 +91,7 @@ void build_knn_graph(raft::resources const& res,
   auto dataset_internal = mdspan<const DataT, matrix_extent<internal_IdxT>, row_major, accessor>(
     dataset.data_handle(), dataset.extent(0), dataset.extent(1));
 
-  detail::build_knn_graph(
+  cagra::detail::build_knn_graph(
     res, dataset_internal, knn_graph_internal, refine_rate, build_params, search_params);
 }
 
@@ -149,7 +149,7 @@ void sort_knn_graph(raft::resources const& res,
   auto dataset_internal = mdspan<const DataT, matrix_extent<internal_IdxT>, row_major, d_accessor>(
     dataset.data_handle(), dataset.extent(0), dataset.extent(1));
 
-  detail::graph::sort_knn_graph(res, dataset_internal, knn_graph_internal);
+  cagra::detail::graph::sort_knn_graph(res, dataset_internal, knn_graph_internal);
 }
 
 /**
@@ -188,7 +188,7 @@ void optimize(raft::resources const& res,
       knn_graph.extent(0),
       knn_graph.extent(1));
 
-  detail::graph::optimize(res, knn_graph_internal, new_graph_internal);
+  cagra::detail::graph::optimize(res, knn_graph_internal, new_graph_internal);
 }
 
 /**
@@ -312,9 +312,18 @@ void search(raft::resources const& res,
   auto distances_internal = raft::make_device_matrix_view<float, internal_IdxT, row_major>(
     distances.data_handle(), distances.extent(0), distances.extent(1));
 
-  detail::search_main<T, internal_IdxT, IdxT>(
+  cagra::detail::search_main<T, internal_IdxT, IdxT>(
     res, params, idx, queries_internal, neighbors_internal, distances_internal);
 }
 /** @} */  // 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/neighbors/cagra_serialize.cuh

@@ -18,7 +18,7 @@
 
 #include "detail/cagra/cagra_serialize.cuh"
 
-namespace raft::neighbors::experimental::cagra {
+namespace raft::neighbors::cagra {
 
 /**
  * \defgroup cagra_serialize CAGRA Serialize
@@ -110,7 +110,7 @@ void serialize(raft::resources const& handle,
  * @param[in] handle the raft handle
  * @param[in] is input stream
  *
- * @return raft::neighbors::cagra::index<T, IdxT>
+ * @return raft::neighbors::experimental::cagra::index<T, IdxT>
  */
 template <typename T, typename IdxT>
 index<T, IdxT> deserialize(raft::resources const& handle, std::istream& is)
@@ -141,7 +141,7 @@ index<T, IdxT> deserialize(raft::resources const& handle, std::istream& is)
  * @param[in] handle the raft handle
  * @param[in] filename the name of the file that stores the index
  *
- * @return raft::neighbors::cagra::index<T, IdxT>
+ * @return raft::neighbors::experimental::cagra::index<T, IdxT>
  */
 template <typename T, typename IdxT>
 index<T, IdxT> deserialize(raft::resources const& handle, const std::string& filename)
@@ -151,4 +151,11 @@ index<T, IdxT> deserialize(raft::resources const& handle, const std::string& fil
 
 /**@}*/
 
-}  // namespace raft::neighbors::experimental::cagra
+}  // 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/cagra_types.hpp

@@ -35,7 +35,7 @@
 #include <type_traits>
 
 #include <raft/core/logger.hpp>
-namespace raft::neighbors::experimental::cagra {
+namespace raft::neighbors::cagra {
 /**
  * @ingroup cagra
  * @{
@@ -347,4 +347,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::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/detail/cagra/bitonic.hpp

@@ -18,7 +18,7 @@
 #include <cstdint>
 #include <raft/core/detail/macros.hpp>
 
-namespace raft::neighbors::experimental::cagra::detail {
+namespace raft::neighbors::cagra::detail {
 namespace bitonic {
 
 namespace detail {
@@ -223,4 +223,4 @@ __device__ void warp_sort(K k[N], V v[N], const bool asc = true)
 }
 
 }  // namespace bitonic
-}  // namespace raft::neighbors::experimental::cagra::detail
+}  // namespace raft::neighbors::cagra::detail

cpp/include/raft/neighbors/detail/cagra/cagra_build.cuh

@@ -36,7 +36,7 @@
 #include <raft/neighbors/ivf_pq_types.hpp>
 #include <raft/neighbors/refine.cuh>
 
-namespace raft::neighbors::experimental::cagra::detail {
+namespace raft::neighbors::cagra::detail {
 
 template <typename DataT, typename IdxT, typename accessor>
 void build_knn_graph(raft::resources const& res,
@@ -237,4 +237,4 @@ void build_knn_graph(raft::resources const& res,
   if (!first) RAFT_LOG_DEBUG("# Finished building kNN graph");
 }
 
-}  // namespace raft::neighbors::experimental::cagra::detail
+}  // namespace raft::neighbors::cagra::detail

cpp/include/raft/neighbors/detail/cagra/cagra_search.cuh

@@ -30,7 +30,7 @@
 #include "search_plan.cuh"
 #include "search_single_cta.cuh"
 
-namespace raft::neighbors::experimental::cagra::detail {
+namespace raft::neighbors::cagra::detail {
 
 /**
  * @brief Search ANN using the constructed index.
@@ -133,4 +133,4 @@ void search_main(raft::resources const& res,
 }
 /** @} */  // end group cagra
 
-}  // namespace raft::neighbors::experimental::cagra::detail
+}  // namespace raft::neighbors::cagra::detail

cpp/include/raft/neighbors/detail/cagra/cagra_serialize.cuh

@@ -22,7 +22,7 @@
 
 #include <fstream>
 
-namespace raft::neighbors::experimental::cagra::detail {
+namespace raft::neighbors::cagra::detail {
 
 // Serialization version 1.
 constexpr int serialization_version = 2;
@@ -133,4 +133,4 @@ auto deserialize(raft::resources const& res, const std::string& filename) -> ind
 
   return index;
 }
-}  // namespace raft::neighbors::experimental::cagra::detail
+}  // namespace raft::neighbors::cagra::detail

cpp/include/raft/neighbors/detail/cagra/compute_distance.hpp

@@ -22,7 +22,7 @@
 #include "utils.hpp"
 #include <type_traits>
 
-namespace raft::neighbors::experimental::cagra::detail {
+namespace raft::neighbors::cagra::detail {
 namespace device {
 
 // using LOAD_256BIT_T = ulonglong4;
@@ -254,4 +254,4 @@ _RAFT_DEVICE void compute_distance_to_child_nodes(INDEX_T* const result_child_in
 }
 
 }  // namespace device
-}  // namespace raft::neighbors::experimental::cagra::detail
+}  // namespace raft::neighbors::cagra::detail

cpp/include/raft/neighbors/detail/cagra/device_common.hpp

@@ -21,7 +21,7 @@
 #include <cuda_fp16.h>
 #include <raft/core/detail/macros.hpp>
 
-namespace raft::neighbors::experimental::cagra::detail {
+namespace raft::neighbors::cagra::detail {
 namespace device {
 
 // warpSize for compile time calculation
@@ -49,4 +49,4 @@ _RAFT_DEVICE inline T swizzling(T x)
 }
 
 }  // namespace device
-}  // namespace raft::neighbors::experimental::cagra::detail
+}  // namespace raft::neighbors::cagra::detail

cpp/include/raft/neighbors/detail/cagra/factory.cuh

@@ -21,7 +21,7 @@
 #include "search_plan.cuh"
 #include "search_single_cta.cuh"
 
-namespace raft::neighbors::experimental::cagra::detail {
+namespace raft::neighbors::cagra::detail {
 
 template <typename T, typename IdxT = uint32_t, typename DistanceT = float>
 class factory {
@@ -86,4 +86,4 @@ class factory {
     }
   }
 };
-};  // namespace raft::neighbors::experimental::cagra::detail
+};  // namespace raft::neighbors::cagra::detail

cpp/include/raft/neighbors/detail/cagra/fragment.hpp

@@ -20,7 +20,7 @@
 #include <raft/core/logger.hpp>
 #include <type_traits>
 
-namespace raft::neighbors::experimental::cagra::detail {
+namespace raft::neighbors::cagra::detail {
 namespace device {
 
 namespace detail {
@@ -208,4 +208,4 @@ _RAFT_DEVICE void print_fragment(const device::fragment<DIM, T, TEAM_SIZE>& a)
 }
 
 }  // namespace device
-}  // namespace raft::neighbors::experimental::cagra::detail
+}  // namespace raft::neighbors::cagra::detail

cpp/include/raft/neighbors/detail/cagra/graph_core.cuh

@@ -36,7 +36,7 @@
 
 #include "utils.hpp"
 
-namespace raft::neighbors::experimental::cagra::detail {
+namespace raft::neighbors::cagra::detail {
 namespace graph {
 
 // unnamed namespace to avoid multiple definition error
@@ -588,4 +588,4 @@ void optimize(raft::resources const& res,
 }
 
 }  // namespace graph
-}  // namespace raft::neighbors::experimental::cagra::detail
+}  // namespace raft::neighbors::cagra::detail

cpp/include/raft/neighbors/detail/cagra/hashmap.hpp

@@ -23,7 +23,7 @@
 // #pragma GCC diagnostic push
 // #pragma GCC diagnostic ignored
 // #pragma GCC diagnostic pop
-namespace raft::neighbors::experimental::cagra::detail {
+namespace raft::neighbors::cagra::detail {
 namespace hashmap {
 
 _RAFT_HOST_DEVICE inline uint32_t get_size(const uint32_t bitlen) { return 1U << bitlen; }
@@ -85,4 +85,4 @@ _RAFT_DEVICE inline uint32_t insert(IdxT* const table, const uint32_t bitlen, co
 }
 
 }  // namespace hashmap
-}  // namespace raft::neighbors::experimental::cagra::detail
+}  // namespace raft::neighbors::cagra::detail

cpp/include/raft/neighbors/detail/cagra/search_multi_cta.cuh

@@ -41,7 +41,7 @@
 #include <raft/util/cuda_rt_essentials.hpp>
 #include <raft/util/cudart_utils.hpp>  // RAFT_CUDA_TRY_NOT_THROW is used TODO(tfeher): consider moving this to cuda_rt_essentials.hpp
 
-namespace raft::neighbors::experimental::cagra::detail {
+namespace raft::neighbors::cagra::detail {
 namespace multi_cta_search {
 
 template <unsigned TEAM_SIZE,
@@ -237,4 +237,4 @@ struct search : public search_plan_impl<DATA_T, INDEX_T, DISTANCE_T> {
 };
 
 }  // namespace multi_cta_search
-}  // namespace raft::neighbors::experimental::cagra::detail
+}  // namespace raft::neighbors::cagra::detail

cpp/include/raft/neighbors/detail/cagra/search_multi_cta_kernel-ext.cuh

@@ -17,7 +17,7 @@
 
 #include <raft/util/raft_explicit.hpp>  // RAFT_EXPLICIT
 
-namespace raft::neighbors::experimental::cagra::detail {
+namespace raft::neighbors::cagra::detail {
 namespace multi_cta_search {
 
 #ifdef RAFT_EXPLICIT_INSTANTIATE_ONLY
@@ -93,4 +93,4 @@ instantiate_kernel_selection(32, 512, uint8_t, uint32_t, float);
 
 #undef instantiate_kernel_selection
 }  // namespace multi_cta_search
-}  // namespace raft::neighbors::experimental::cagra::detail
+}  // namespace raft::neighbors::cagra::detail