Paying down some tech debt on docs, runtime API, and cython

cpp/include/raft/distance/distance.cuh

@@ -25,14 +25,14 @@
 
 #include <raft/core/device_mdspan.hpp>
 
+namespace raft {
+namespace distance {
+
 /**
- * @defgroup pairwise_distance pairwise distance prims
+ * @defgroup pairwise_distance pointer-based pairwise distance prims
  * @{
  */
 
-namespace raft {
-namespace distance {
-
 /**
  * @brief Evaluate pairwise distances with the user epilogue lamba allowed
  * @tparam DistanceType which distance to evaluate
@@ -219,58 +219,6 @@ void distance(const InType* x,
     x, y, dist, m, n, k, workspace.data(), worksize, stream, isRowMajor, metric_arg);
 }
 
-/**
- * @brief Evaluate pairwise distances for the simple use case.
- *
- * Note: Only contiguous row- or column-major layouts supported currently.
- *
- * @tparam DistanceType which distance to evaluate
- * @tparam InType input argument type
- * @tparam AccType accumulation type
- * @tparam OutType output type
- * @tparam Index_ Index type
- * @param handle raft handle for managing expensive resources
- * @param x first set of points (size n*k)
- * @param y second set of points (size m*k)
- * @param dist output distance matrix (size n*m)
- * @param metric_arg metric argument (used for Minkowski distance)
- */
-template <raft::distance::DistanceType distanceType,
-          typename InType,
-          typename AccType,
-          typename OutType,
-          typename layout = raft::layout_c_contiguous,
-          typename Index_ = int>
-void distance(raft::handle_t const& handle,
-              raft::device_matrix_view<InType, Index_, layout> const x,
-              raft::device_matrix_view<InType, Index_, layout> const y,
-              raft::device_matrix_view<OutType, Index_, layout> dist,
-              InType metric_arg = 2.0f)
-{
-  RAFT_EXPECTS(x.extent(1) == y.extent(1), "Number of columns must be equal.");
-  RAFT_EXPECTS(dist.extent(0) == x.extent(0),
-               "Number of rows in output must be equal to "
-               "number of rows in X");
-  RAFT_EXPECTS(dist.extent(1) == y.extent(0),
-               "Number of columns in output must be equal to "
-               "number of rows in Y");
-
-  RAFT_EXPECTS(x.is_exhaustive(), "Input x must be contiguous.");
-  RAFT_EXPECTS(y.is_exhaustive(), "Input y must be contiguous.");
-
-  constexpr auto is_rowmajor = std::is_same_v<layout, layout_c_contiguous>;
-
-  distance<distanceType, InType, AccType, OutType, Index_>(x.data_handle(),
-                                                           y.data_handle(),
-                                                           dist.data_handle(),
-                                                           x.extent(0),
-                                                           y.extent(0),
-                                                           x.extent(1),
-                                                           handle.get_stream(),
-                                                           is_rowmajor,
-                                                           metric_arg);
-}
-
 /**
  * @brief Convenience wrapper around 'distance' prim to convert runtime metric
  * into compile time for the purpose of dispatch
@@ -401,6 +349,85 @@ void pairwise_distance(const raft::handle_t& handle,
     handle, x, y, dist, m, n, k, workspace, metric, isRowMajor, metric_arg);
 }
 
+/** @} */
+
+/**
+ * \defgroup distance_mdspan Pairwise distance functions
+ * @{
+ */
+
+/**
+ * @brief Evaluate pairwise distances for the simple use case.
+ *
+ * Note: Only contiguous row- or column-major layouts supported currently.
+ *
+ * Usage example:
+ * @code{.cpp}
+ * #include <raft/core/handle.hpp>
+ * #include <raft/core/device_mdarray.hpp>
+ * #include <raft/random/make_blobs.cuh>
+ * #include <raft/distance/distance.cuh>
+ *
+ * raft::handle_t handle;
+ * int n_samples = 5000;
+ * int n_features = 50;
+ *
+ * auto input = raft::make_device_matrix<float>(handle, n_samples, n_features);
+ * auto labels = raft::make_device_vector<int>(handle, n_samples);
+ * auto output = raft::make_device_matrix<float>(handle, n_samples, n_samples);
+ *
+ * raft::random::make_blobs(handle, input.view(), labels.view());
+ * auto metric = raft::distance::DistanceType::L2SqrtExpanded;
+ * raft::distance::pairwise_distance(handle, input.view(), input.view(), output.view(), metric);
+ * @endcode
+ *
+ * @tparam DistanceType which distance to evaluate
+ * @tparam InType input argument type
+ * @tparam AccType accumulation type
+ * @tparam OutType output type
+ * @tparam Index_ Index type
+ * @param handle raft handle for managing expensive resources
+ * @param x first set of points (size n*k)
+ * @param y second set of points (size m*k)
+ * @param dist output distance matrix (size n*m)
+ * @param metric_arg metric argument (used for Minkowski distance)
+ */
+template <raft::distance::DistanceType distanceType,
+          typename InType,
+          typename AccType,
+          typename OutType,
+          typename layout = raft::layout_c_contiguous,
+          typename Index_ = int>
+void distance(raft::handle_t const& handle,
+              raft::device_matrix_view<InType, Index_, layout> const x,
+              raft::device_matrix_view<InType, Index_, layout> const y,
+              raft::device_matrix_view<OutType, Index_, layout> dist,
+              InType metric_arg = 2.0f)
+{
+  RAFT_EXPECTS(x.extent(1) == y.extent(1), "Number of columns must be equal.");
+  RAFT_EXPECTS(dist.extent(0) == x.extent(0),
+               "Number of rows in output must be equal to "
+               "number of rows in X");
+  RAFT_EXPECTS(dist.extent(1) == y.extent(0),
+               "Number of columns in output must be equal to "
+               "number of rows in Y");
+
+  RAFT_EXPECTS(x.is_exhaustive(), "Input x must be contiguous.");
+  RAFT_EXPECTS(y.is_exhaustive(), "Input y must be contiguous.");
+
+  constexpr auto is_rowmajor = std::is_same_v<layout, layout_c_contiguous>;
+
+  distance<distanceType, InType, AccType, OutType, Index_>(x.data_handle(),
+                                                           y.data_handle(),
+                                                           dist.data_handle(),
+                                                           x.extent(0),
+                                                           y.extent(0),
+                                                           x.extent(1),
+                                                           handle.get_stream(),
+                                                           is_rowmajor,
+                                                           metric_arg);
+}
+
 /**
  * @brief Convenience wrapper around 'distance' prim to convert runtime metric
  * into compile time for the purpose of dispatch
@@ -449,9 +476,9 @@ void pairwise_distance(raft::handle_t const& handle,
                     metric_arg);
 }
 
+/** @} */
+
 };  // namespace distance
 };  // namespace raft
 
-/** @} */
-
 #endif

cpp/include/raft/distance/fused_l2_nn.cuh

@@ -30,6 +30,10 @@
 
 namespace raft {
 namespace distance {
+/**
+ * \defgroup fused_l2_nn Fused 1-nearest neighbors
+ * @{
+ */
 
 template <typename LabelT, typename DataT>
 using KVPMinReduce = detail::KVPMinReduceImpl<LabelT, DataT>;
@@ -40,6 +44,8 @@ using MinAndDistanceReduceOp = detail::MinAndDistanceReduceOpImpl<LabelT, DataT>
 template <typename LabelT, typename DataT>
 using MinReduceOp = detail::MinReduceOpImpl<LabelT, DataT>;
 
+/** @} */
+
 /**
  * Initialize array using init value from reduction op
  */
@@ -49,6 +55,10 @@ void initialize(const raft::handle_t& handle, OutT* min, IdxT m, DataT maxVal, R
   detail::initialize<DataT, OutT, IdxT, ReduceOpT>(min, m, maxVal, redOp, handle.get_stream());
 }
 
+/**
+ * \ingroup fused_l2_nn
+ * @{
+ */
 /**
  * @brief Fused L2 distance and 1-nearest-neighbor computation in a single call.
  *
@@ -211,6 +221,8 @@ void fusedL2NNMinReduce(OutT* min,
     min, x, y, xn, yn, m, n, k, workspace, redOp, pairRedOp, sqrt, initOutBuffer, stream);
 }
 
+/** @} */
+
 }  // namespace distance
 }  // namespace raft
 

cpp/include/raft/linalg/add.cuh

@@ -16,11 +16,6 @@
 #ifndef __ADD_H
 #define __ADD_H
 
-/**
- * @defgroup arithmetic Dense matrix arithmetic
- * @{
- */
-
 #pragma once
 
 #include "detail/add.cuh"
@@ -94,7 +89,7 @@ void addDevScalar(
 }
 
 /**
- * @defgroup add Addition Arithmetic
+ * @defgroup add_dense Addition Arithmetic
  * @{
  */
 
@@ -226,6 +221,4 @@ void add_scalar(const raft::handle_t& handle,
 };  // end namespace linalg
 };  // end namespace raft
 
-/** @} */
-
 #endif

cpp/include/raft/linalg/axpy.cuh

@@ -54,7 +54,7 @@ void axpy(const raft::handle_t& handle,
 }
 
 /**
- * @defgroup axpy axpy
+ * @defgroup axpy axpy routine
  * @{
  */
 

cpp/include/raft/linalg/dot.cuh

@@ -25,6 +25,12 @@
 #include <raft/core/host_mdspan.hpp>
 
 namespace raft::linalg {
+
+/**
+ * @defgroup dot BLAS dot routine
+ * @{
+ */
+
 /**
  * @brief Computes the dot product of two vectors.
  * @param[in] handle   raft::handle_t
@@ -84,5 +90,8 @@ void dot(const raft::handle_t& handle,
                                     out.data_handle(),
                                     handle.get_stream()));
 }
+
+/** @} */  // end of group dot
+
 }  // namespace raft::linalg
 #endif

cpp/include/raft/linalg/eig.cuh

@@ -25,11 +25,6 @@
 namespace raft {
 namespace linalg {
 
-/**
- * @defgroup eig Eigen Decomposition Methods
- * @{
- */
-
 /**
  * @brief eig decomp with divide and conquer method for the column-major
  * symmetric matrices
@@ -115,6 +110,11 @@ void eigJacobi(const raft::handle_t& handle,
   detail::eigJacobi(handle, in, n_rows, n_cols, eig_vectors, eig_vals, stream, tol, sweeps);
 }
 
+/**
+ * @defgroup eig Eigen Decomposition Methods
+ * @{
+ */
+
 /**
  * @brief eig decomp with divide and conquer method for the column-major
  * symmetric matrices

cpp/include/raft/linalg/map_reduce.cuh

@@ -24,11 +24,6 @@
 
 namespace raft::linalg {
 
-/**
- * @defgroup map_reduce Map-Reduce ops
- * @{
- */
-
 /**
  * @brief CUDA version of map and then generic reduction operation
  * @tparam Type data-type upon which the math operation will be performed
@@ -67,6 +62,10 @@ void mapReduce(OutType* out,
     out, len, neutral, map, op, stream, in, args...);
 }
 
+/**
+ * @defgroup map_reduce Map-Reduce ops
+ * @{
+ */
 /**
  * @brief CUDA version of map and then generic reduction operation
  * @tparam InValueType the data-type of the input

cpp/include/raft/linalg/matrix_vector.cuh

@@ -23,6 +23,11 @@
 
 namespace raft::linalg {
 
+/**
+ * @defgroup matrix_vector Matrix-Vector Operations
+ * @{
+ */
+
 /**
  * @brief multiply each row or column of matrix with vector, skipping zeros in vector
  * @param [in] handle: raft handle for managing library resources
@@ -191,4 +196,7 @@ void binary_sub(const raft::handle_t& handle,
                                         bcast_along_rows,
                                         handle.get_stream());
 }
+
+/** @} */  // end of matrix_vector
+
 }  // namespace raft::linalg

cpp/include/raft/linalg/norm.cuh

@@ -87,6 +87,11 @@ void colNorm(Type* dots,
   detail::colNormCaller(dots, data, D, N, type, rowMajor, stream, fin_op);
 }
 
+/**
+ * @defgroup norm Row- or Col-norm computation
+ * @{
+ */
+
 /**
  * @brief Compute norm of the input matrix and perform fin_op
  * @tparam ElementType Input/Output data type
@@ -142,6 +147,8 @@ void norm(const raft::handle_t& handle,
   }
 }
 
+/** @} */
+
 };  // end namespace linalg
 };  // end namespace raft
 

cpp/include/raft/linalg/normalize.cuh

@@ -23,6 +23,11 @@
 namespace raft {
 namespace linalg {
 
+/**
+ * @defgroup norm Row- or Col-norm computation
+ * @{
+ */
+
 /**
  * @brief Divide rows by their norm defined by main_op, reduce_op and fin_op
  *
@@ -127,5 +132,7 @@ void row_normalize(const raft::handle_t& handle,
   }
 }
 
+/** @} */
+
 }  // namespace linalg
 }  // namespace raft