important doc updates for core, cluster, and neighbors

cpp/include/raft/cluster/kmeans_types.hpp

@@ -18,8 +18,7 @@
 #include <raft/distance/distance_types.hpp>
 #include <raft/random/rng_state.hpp>
 
-namespace raft {
-namespace cluster {
+namespace raft::cluster::kmeans {
 
 struct KMeansParams {
   enum InitMethod { KMeansPlusPlus, Random, Array };
@@ -69,5 +68,11 @@ struct KMeansParams {
 
   bool inertia_check = false;
 };
-}  // namespace cluster
-}  // namespace raft
+
+}  // namespace raft::cluster::kmeans
+
+namespace raft::cluster {
+
+using kmeans::KMeansParams;
+
+}  // namespace raft::cluster

cpp/include/raft/cluster/single_linkage.cuh

@@ -21,7 +21,11 @@
 
 namespace raft::cluster {
 
-constexpr int DEFAULT_CONST_C = 15;
+/**
+ * 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
@@ -58,6 +62,11 @@ void single_linkage(const raft::handle_t& handle,
   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
@@ -90,14 +99,14 @@ void single_linkage(const raft::handle_t& handle,
   out_arrs.children = dendrogram.data_handle();
   out_arrs.labels   = labels.data_handle();
 
-  single_linkage<idx_t, value_t, dist_type>(handle,
-                                            X.data_handle(),
-                                            static_cast<std::size_t>(X.extent(0)),
-                                            static_cast<std::size_t>(X.extent(1)),
-                                            metric,
-                                            &out_arrs,
-                                            c.has_value() ? c.value() : DEFAULT_CONST_C,
-                                            n_clusters);
+  raft::cluster::single_linkage<idx_t, value_t, dist_type>(
+    handle,
+    X.data_handle(),
+    static_cast<std::size_t>(X.extent(0)),
+    static_cast<std::size_t>(X.extent(1)),
+    metric,
+    &out_arrs,
+    c.has_value() ? c.value() : DEFAULT_CONST_C,
+    n_clusters);
 }
-
-};  // namespace raft::cluster
+};  // namespace raft::cluster::hierarchy

cpp/include/raft/cluster/single_linkage_types.hpp

@@ -18,9 +18,15 @@
 
 #include <raft/core/device_mdspan.hpp>
 
+namespace raft::cluster::hierarchy {
+enum LinkageDistance { PAIRWISE = 0, KNN_GRAPH = 1 };
+
+};  // end namespace raft::cluster::hierarchy
+
+// The code below is legacy
 namespace raft::cluster {
 
-enum LinkageDistance { PAIRWISE = 0, KNN_GRAPH = 1 };
+using hierarchy::LinkageDistance;
 
 /**
  * Simple POCO for consolidating linkage results. This closely

cpp/test/CMakeLists.txt

@@ -82,7 +82,7 @@ if(BUILD_TESTS)
             PATH
             test/cluster/kmeans.cu
             test/cluster_solvers.cu
-            test/sparse/linkage.cu
+            test/cluster/linkage.cu
             OPTIONAL DIST NN
     )
 

cpp/test/sparse/linkage.cu → cpp/test/cluster/linkage.cu

@@ -180,20 +180,21 @@ class LinkageTest : public ::testing::TestWithParam<LinkageInputs<T, IdxT>> {
 
     raft::handle_t handle;
 
-    auto data_view =
-      raft::make_device_matrix_view<T, IdxT, row_major>(data.data(), params.n_row, params.n_col);
+    auto data_view = raft::make_device_matrix_view<const T, IdxT, row_major>(
+      data.data(), params.n_row, params.n_col);
     auto dendrogram_view =
       raft::make_device_matrix_view<IdxT, IdxT, row_major>(out_children.data(), params.n_row, 2);
     auto labels_view = raft::make_device_vector_view<IdxT, IdxT>(labels.data(), params.n_row);
 
-    raft::cluster::single_linkage<T, IdxT, raft::hierarchy::LinkageDistance::KNN_GRAPH>(
-      handle,
-      data_view,
-      dendrogram_view,
-      labels_view,
-      raft::distance::DistanceType::L2SqrtExpanded,
-      params.n_clusters,
-      std::make_optional<int>(params.c));
+    raft::cluster::hierarchy::
+      single_linkage<T, IdxT, raft::cluster::hierarchy::LinkageDistance::KNN_GRAPH>(
+        handle,
+        data_view,
+        dendrogram_view,
+        labels_view,
+        raft::distance::DistanceType::L2SqrtExpanded,
+        params.n_clusters,
+        std::make_optional<int>(params.c));
 
     handle.sync_stream(stream);
 

cpp/test/cluster_solvers_deprecated.cu

@@ -20,7 +20,6 @@
 #include <raft/core/handle.hpp>
 
 #include <raft/spectral/cluster_solvers_deprecated.cuh>
-#include <raft/spectral/modularity_maximization.cuh>
 
 namespace raft {
 namespace spectral {
@@ -54,52 +53,5 @@ TEST(Raft, ClusterSolvers)
   EXPECT_ANY_THROW(cluster_solver.solve(h, n, d, eigvecs, codes));
 }
 
-TEST(Raft, ModularitySolvers)
-{
-  using namespace matrix;
-  using index_type = int;
-  using value_type = double;
-
-  handle_t h;
-  ASSERT_EQ(0,
-            h.
-
-            get_device()
-
-  );
-
-  index_type neigvs{10};
-  index_type maxiter{100};
-  index_type restart_iter{10};
-  value_type tol{1.0e-10};
-  bool reorthog{true};
-
-  // nullptr expected to trigger exceptions:
-  //
-  index_type* clusters{nullptr};
-  value_type* eigvals{nullptr};
-  value_type* eigvecs{nullptr};
-
-  unsigned long long seed{100110021003};
-
-  eigen_solver_config_t<index_type, value_type> eig_cfg{
-    neigvs, maxiter, restart_iter, tol, reorthog, seed};
-  lanczos_solver_t<index_type, value_type> eig_solver{eig_cfg};
-
-  index_type k{5};
-
-  cluster_solver_config_deprecated_t<index_type, value_type> clust_cfg{k, maxiter, tol, seed};
-  kmeans_solver_deprecated_t<index_type, value_type> cluster_solver{clust_cfg};
-
-  auto stream = h.get_stream();
-  sparse_matrix_t<index_type, value_type> sm{h, nullptr, nullptr, nullptr, 0, 0};
-
-  EXPECT_ANY_THROW(spectral::modularity_maximization(
-    h, sm, eig_solver, cluster_solver, clusters, eigvals, eigvecs));
-
-  value_type modularity{0};
-  EXPECT_ANY_THROW(spectral::analyzeModularity(h, sm, k, clusters, modularity));
-}
-
 }  // namespace spectral
 }  // namespace raft

docs/source/cpp_api.rst

@@ -9,11 +9,12 @@ RAFT C++ API Reference
    :maxdepth: 4
 
    cpp_api/core.rst
-   cpp_api/clustering.rst
+   cpp_api/cluster.rst
+   cpp_api/distance.rst
    cpp_api/linalg.rst
    cpp_api/matrix.rst
-   cpp_api/optimization.rst
+   cpp_api/neighbors.rst
+   cpp_api/solver.rst
    cpp_api/random.rst
-   cpp_api/spatial.rst
    cpp_api/sparse.rst
    cpp_api/stats.rst

docs/source/cpp_api/cluster.rst

@@ -0,0 +1,27 @@
+Cluster
+=======
+
+This page provides C++ class references for the publicly-exposed elements of the cluster package.
+
+K-Means
+-------
+
+.. doxygennamespace:: raft::cluster::kmeans
+    :project: RAFT
+    :members:
+
+
+Hierarchical Clustering
+-----------------------
+
+.. doxygennamespace:: raft::cluster::hierarchy
+    :project: RAFT
+    :members:
+
+
+Spectral Clustering
+-------------------
+
+.. doxygennamespace:: raft::spectral
+    :project: RAFT
+    :members:

docs/source/cpp_api/core.rst

@@ -4,7 +4,6 @@ Core
 This page provides C++ class references for the publicly-exposed elements of the core package.
 
 
-
 handle_t
 ########
 
@@ -20,6 +19,13 @@ interruptible
     :project: RAFT
     :members:
 
+NVTX
+####
+
+.. doxygennamespace:: raft::common::nvtx
+    :project: RAFT
+    :members:
+
 
 mdarray
 #######
@@ -28,11 +34,64 @@ mdarray
     :project: RAFT
     :members:
 
+.. doxygenclass:: raft::make_device_matrix
+    :project: RAFT
+
+.. doxygenclass:: raft::make_device_vector
+    :project: RAFT
+
+.. doxygenclass:: raft::make_device_scalar
+    :project: RAFT
+
+.. doxygenclass:: raft::make_host_matrix
+    :project: RAFT
+
+.. doxygenclass:: raft::make_host_vector
+    :project: RAFT
+
+.. doxygenclass:: raft::make_device_scalar
+    :project: RAFT
+
+
+mdspan
+#######
+
+.. doxygenfunction:: raft::make_device_mdspan
+    :project: RAFT
+
+.. doxygenfunction:: raft::make_device_matrix_view
+    :project: RAFT
+
+.. doxygenfunction:: raft::make_device_vector_view
+    :project: RAFT
+
+.. doxygenfunction:: raft::make_device_scalar_view
+    :project: RAFT
+
+.. doxygenfunction:: raft::make_host_matrix_view
+    :project: RAFT
+
+.. doxygenfunction:: raft::make_host_vector_view
+    :project: RAFT
+
+.. doxygenfunction:: raft::make_device_scalar_view
+    :project: RAFT
 
 span
 ####
 
-.. doxygenclass:: raft::span
+.. doxygenclass:: raft::device_span
+    :project: RAFT
+    :members:
+
+.. doxygenclass:: raft::host_span
+    :project: RAFT
+    :members:
+
+Key-Value Pair
+##############
+
+.. doxygenclass:: raft::KeyValuePair
     :project: RAFT
     :members:
 

docs/source/cpp_api/distance.rst

@@ -0,0 +1,10 @@
+Distance
+========
+
+This page provides C++ class references for the publicly-exposed elements of the distance package.
+
+Distance
+########
+
+.. doxygennamespace:: raft::distance
+    :project: RAFT

docs/source/cpp_api/neighbors.rst

@@ -0,0 +1,43 @@
+Neighbors
+=========
+
+This page provides C++ class references for the publicly-exposed elements of the neighbors package.
+
+
+Brute-force
+-----------
+
+.. doxygennamespace:: raft::neighbors::brute_force
+    :project: RAFT
+
+
+IVF-Flat
+--------
+
+.. doxygennamespace:: raft::neighbors::ivf_flat
+    :project: RAFT
+    :members:
+
+
+IVF-PQ
+--------
+
+.. doxygennamespace:: raft::neighbors::ivf_pq
+    :project: RAFT
+    :members:
+
+
+Epsilon Neighborhood
+--------------------
+
+.. doxygennamespace:: raft::neighbors::epsilon_neighborhood
+    :project: RAFT
+    :members:
+
+
+Random Ball Cover
+-----------------
+
+.. doxygennamespace:: raft::neighbors::ball_cover
+    :project: RAFT
+    :members: