Updating docs for 22.04 (#566)

Finalizing some more bits of the docs. This has also included cleaning up several header files to make the docs a little more clean.

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

Approvers:
  - Dante Gama Dessavre (https://github.com/dantegd)

URL: #566

README.md

@@ -16,7 +16,7 @@ While not exhaustive, the following general categories help summarize the accele
 | **Spatial** | pairwise distances, nearest neighbors, neighborhood graph construction |
 | **Sparse Operations** | linear algebra, eigenvalue problems, slicing, symmetrization, labeling |
 | **Basic Clustering** | spectral clustering, hierarchical clustering, k-means |
-| **Optimization** | combinatorial optimization, iterative solvers |
+| **Solvers** | combinatorial optimization, iterative solvers |
 | **Statistics** | sampling, moments and summary statistics, metrics |
 | **Distributed Tools** | multi-node multi-gpu infrastructure |
 

cpp/doxygen/Doxyfile.in

@@ -798,7 +798,7 @@ INPUT_ENCODING         = UTF-8
 # *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f, *.for, *.tcl,
 # *.vhd, *.vhdl, *.ucf, *.qsf, *.as and *.js.
 
-FILE_PATTERNS          = *.hpp
+FILE_PATTERNS          = *.hpp *.cuh
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
@@ -814,8 +814,7 @@ RECURSIVE              = YES
 # run.
 
 EXCLUDE                = @CMAKE_CURRENT_SOURCE_DIR@/include/raft/sparse/linalg/symmetrize.hpp \ # Contains device code
-                         @CMAKE_CURRENT_SOURCE_DIR@/include/raft/sparse/csr.hpp \    # Contains device code
-                         @CMAKE_CURRENT_SOURCE_DIR@/include/raft/sparse/detail/cusparse_wrappers.h
+                         @CMAKE_CURRENT_SOURCE_DIR@/include/raft/sparse/csr.hpp     # Contains device code
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -832,8 +831,7 @@ EXCLUDE_SYMLINKS       = NO
 # exclude all test directories for example use the pattern */test/*
 
 EXCLUDE_PATTERNS       = */detail/* \
-                         */specializations/* \
-                         */spectral/*
+                         */specializations/*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the

cpp/doxygen/main_page.md

@@ -1,14 +1,22 @@
 # libraft
 
-RAFT (RAPIDS Analytics Framework Toolkit) is a library containing building-blocks for rapid composition of RAPIDS Analytics. These building-blocks include shared representations, mathematical computational primitives, and utilities that accelerate building analytics and data science algorithms in the RAPIDS ecosystem. Both the C++ and Python components can be included in consuming libraries, providing building-blocks for both dense and sparse matrix formats in the following general categories:
+RAFT contains fundamental widely-used algorithms and primitives for data science, graph and machine learning. The algorithms are CUDA-accelerated and form building-blocks for rapidly composing analytics.
+
+By taking a primitives-based approach to algorithm development, RAFT
+- accelerates algorithm construction time,
+- reduces the maintenance burden by maximizing reuse across projects, and
+- centralizes core reusable computations, allowing future optimizations to benefit all algorithms that use them.
+
+While not exhaustive, the following general categories help summarize the accelerated functions in RAFT:
 
 #####
-| Category | Description / Examples |
+| Category | Examples |
 | --- | --- |
-| **Data Formats** | tensor representations and conversions for both sparse and dense formats |
-| **Data Generation** | graph, spatial, and machine learning dataset generation |
-| **Dense Operations** | linear algebra, statistics |
-| **Spatial** | pairwise distances, nearest neighbors, neighborhood / proximity graph construction |
-| **Sparse/Graph Operations** | linear algebra, statistics, slicing, msf, spectral embedding/clustering, slhc, vertex degree |
-| **Solvers** | eigenvalue decomposition, least squares, lanczos |
-| **Tools** | multi-node multi-gpu communicator, utilities |
+| **Data Formats** | sparse & dense, conversions, data generation |
+| **Dense Linear Algebra** | matrix arithmetic, norms, factorization, least squares, svd & eigenvalue problems |
+| **Spatial** | pairwise distances, nearest neighbors, neighborhood graph construction |
+| **Sparse Operations** | linear algebra, eigenvalue problems, slicing, symmetrization, labeling |
+| **Basic Clustering** | spectral clustering, hierarchical clustering, k-means |
+| **Solvers** | combinatorial optimization, iterative solvers |
+| **Statistics** | sampling, moments and summary statistics, metrics |
+| **Distributed Tools** | multi-node multi-gpu infrastructure |

cpp/include/raft.hpp

@@ -15,7 +15,7 @@
  */
 
 /**
- * @warning This file is deprecated and will be removed in release 22.06.
+ * This file is deprecated and will be removed in release 22.06.
  */
 #include "raft/handle.hpp"
 #include "raft/mdarray.hpp"

cpp/include/raft/cache/cache_util.cuh

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019-2021, NVIDIA CORPORATION.
+ * Copyright (c) 2019-2022, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -111,7 +111,7 @@ __global__ void store_vecs(const math_t* tile,
  * @brief Map a key to a cache set.
  *
  * @param key key to be hashed
- * @param n_cache_set number of cache sets
+ * @param n_cache_sets number of cache sets
  * @return index of the cache set [0..n_cache_set)
  */
 int DI hash(int key, int n_cache_sets) { return key % n_cache_sets; }

cpp/include/raft/comms/comms.hpp

@@ -15,7 +15,7 @@
  */
 
 /**
- * @warning This file is deprecated and will be removed in release 22.06.
+ * This file is deprecated and will be removed in release 22.06.
  * Please use raft_runtime/comms.hpp instead.
  */
 

cpp/include/raft/cudart_utils.h

@@ -15,7 +15,7 @@
  */
 
 /**
- * @warning This file is deprecated and will be removed in release 22.06.
+ * This file is deprecated and will be removed in release 22.06.
  * Please use raft_runtime/cudart_utils.hpp instead.
  */
 

cpp/include/raft/device_atomics.cuh

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019-2020, NVIDIA CORPORATION.
+ * Copyright (c) 2019-2022, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -462,7 +462,7 @@ struct typesAtomicCASImpl<T, 8> {
  * int8_t, int16_t, int32_t, int64_t, float, double
  *
  * @param[in] address The address of old value in global or shared memory
- * @param[in] val The value to be computed
+ * @param[in] update_value The value to be computed
  * @param[in] op  The binary operator used for compute
  *
  * @returns The old value at `address`

cpp/include/raft/distance/distance.cuh

@@ -25,6 +25,11 @@
 
 #include <raft/mdarray.hpp>
 
+/**
+ * @defgroup pairwise_distance pairwise distance prims
+ * @{
+ */
+
 namespace raft {
 namespace distance {
 
@@ -267,12 +272,11 @@ void distance(raft::handle_t const& handle,
 }
 
 /**
- * @defgroup pairwise_distance pairwise distance prims
- * @{
  * @brief Convenience wrapper around 'distance' prim to convert runtime metric
  * into compile time for the purpose of dispatch
  * @tparam Type input/accumulation/output data-type
  * @tparam Index_ indexing type
+ * @param handle raft handle for managing expensive resources
  * @param x first set of points
  * @param y second set of points
  * @param dist output distance matrix
@@ -282,8 +286,8 @@ void distance(raft::handle_t const& handle,
  * @param workspace temporary workspace buffer which can get resized as per the
  * needed workspace size
  * @param metric distance metric
- * @param stream cuda stream
  * @param isRowMajor whether the matrices are row-major or col-major
+ * @param metric_arg metric argument (used for Minkowski distance)
  */
 template <typename Type, typename Index_ = int>
 void pairwise_distance(const raft::handle_t& handle,
@@ -363,24 +367,22 @@ void pairwise_distance(const raft::handle_t& handle,
     default: THROW("Unknown or unsupported distance metric '%d'!", (int)metric);
   };
 }
-/** @} */
 
 /**
- * @defgroup pairwise_distance pairwise distance prims
- * @{
  * @brief Convenience wrapper around 'distance' prim to convert runtime metric
  * into compile time for the purpose of dispatch
  * @tparam Type input/accumulation/output data-type
  * @tparam Index_ indexing type
+ * @param handle raft handle for managing expensive resources
  * @param x first set of points
  * @param y second set of points
  * @param dist output distance matrix
  * @param m number of points in x
  * @param n number of points in y
  * @param k dimensionality
  * @param metric distance metric
- * @param stream cuda stream
  * @param isRowMajor whether the matrices are row-major or col-major
+ * @param metric_arg metric argument (used for Minkowski distance)
  */
 template <typename Type, typename Index_ = int>
 void pairwise_distance(const raft::handle_t& handle,
@@ -400,20 +402,16 @@ void pairwise_distance(const raft::handle_t& handle,
 }
 
 /**
- * @defgroup pairwise_distance pairwise distance prims
- * @{
  * @brief Convenience wrapper around 'distance' prim to convert runtime metric
  * into compile time for the purpose of dispatch
  * @tparam Type input/accumulation/output data-type
  * @tparam Index_ indexing type
+ * @param handle raft handle for managing expensive resources
  * @param x first matrix of points (size mxk)
  * @param y second matrix of points (size nxk)
  * @param dist output distance matrix (size mxn)
- * @param workspace temporary workspace buffer which can get resized as per the
- * needed workspace size
  * @param metric distance metric
- * @param stream cuda stream
- * @param isRowMajor whether the matrices are row-major or col-major
+ * @param metric_arg metric argument (used for Minkowski distance)
  */
 template <typename Type, typename Index_ = int, typename layout = layout_c_contiguous>
 void pairwise_distance(raft::handle_t const& handle,
@@ -454,4 +452,6 @@ void pairwise_distance(raft::handle_t const& handle,
 };  // namespace distance
 };  // namespace raft
 
+/** @} */
+
 #endif