From 87597a85d74fef611422f85dc632c8c89cde2c3f Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Mon, 22 May 2023 13:24:34 -0400 Subject: [PATCH] Various updates to the docs for 23.06 release (#1538) Authors: - Corey J. Nolet (https://github.com/cjnolet) Approvers: - Divye Gala (https://github.com/divyegala) URL: https://github.com/rapidsai/raft/pull/1538 --- cpp/include/raft/core/device_span.hpp | 10 +++- cpp/include/raft/core/host_mdarray.hpp | 12 +++++ cpp/include/raft/core/host_span.hpp | 12 ++++- cpp/include/raft/core/interruptible.hpp | 9 ++++ cpp/include/raft/core/mdarray.hpp | 20 ++++++++ cpp/include/raft/core/mdspan.hpp | 9 ++++ cpp/include/raft/core/span.hpp | 9 ++++ cpp/include/raft/linalg/normalize.cuh | 2 +- cpp/include/raft/random/rng.cuh | 23 +++++++++ docs/source/cpp_api/core_interruptible.rst | 7 +-- docs/source/cpp_api/core_resources.rst | 6 ++- docs/source/cpp_api/distance_1nn.rst | 2 +- docs/source/cpp_api/mdspan_mdarray.rst | 24 ++-------- docs/source/cpp_api/mdspan_representation.rst | 14 +++--- docs/source/cpp_api/mdspan_span.rst | 15 ++++-- docs/source/cpp_api/neighbors.rst | 3 +- docs/source/cpp_api/neighbors_cagra.rst | 21 ++++++++ docs/source/cpp_api/random_datagen.rst | 2 +- .../cpp_api/random_sampling_univariate.rst | 48 ++----------------- 19 files changed, 160 insertions(+), 88 deletions(-) create mode 100644 docs/source/cpp_api/neighbors_cagra.rst diff --git a/cpp/include/raft/core/device_span.hpp b/cpp/include/raft/core/device_span.hpp index 0730b20bfb..d3350b5e3a 100644 --- a/cpp/include/raft/core/device_span.hpp +++ b/cpp/include/raft/core/device_span.hpp @@ -1,5 +1,5 @@ /* - * Copyright (c) 2022, NVIDIA CORPORATION. + * Copyright (c) 2022-2023, NVIDIA CORPORATION. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -20,10 +20,18 @@ namespace raft { +/** + * @defgroup device_span one-dimensional device span type + * @{ + */ + /** * @brief A span class for device pointer. */ template using device_span = span; +/** + * @} + */ } // end namespace raft \ No newline at end of file diff --git a/cpp/include/raft/core/host_mdarray.hpp b/cpp/include/raft/core/host_mdarray.hpp index 9ba29e38d4..02c8914ca1 100644 --- a/cpp/include/raft/core/host_mdarray.hpp +++ b/cpp/include/raft/core/host_mdarray.hpp @@ -67,6 +67,11 @@ template using host_matrix = host_mdarray, LayoutPolicy>; +/** + * @defgroup host_mdarray_factories factories to create host mdarrays + * @{ + */ + /** * @brief Create a host mdarray. * @tparam ElementType the data type of the matrix elements @@ -90,6 +95,10 @@ auto make_host_mdarray(raft::resources& res, extents exts return mdarray_t{res, layout, policy}; } +/** + * @} + */ + /** * @brief Create a host mdarray. * @tparam ElementType the data type of the matrix elements @@ -117,6 +126,7 @@ auto make_host_mdarray(extents exts) } /** + * @ingroup host_mdarray_factories * @brief Create a 2-dim c-contiguous host mdarray. * @tparam ElementType the data type of the matrix elements * @tparam IndexType the index type of the extents @@ -157,6 +167,7 @@ auto make_host_matrix(IndexType n_rows, IndexType n_cols) } /** + * @ingroup host_mdarray_factories * @brief Create a host scalar from v. * * @tparam ElementType the data type of the scalar element @@ -206,6 +217,7 @@ auto make_host_scalar(ElementType const& v) } /** + * @ingroup host_mdarray_factories * @brief Create a 1-dim host mdarray. * @tparam ElementType the data type of the vector elements * @tparam IndexType the index type of the extents diff --git a/cpp/include/raft/core/host_span.hpp b/cpp/include/raft/core/host_span.hpp index 3cad62b7cd..8b37414e76 100644 --- a/cpp/include/raft/core/host_span.hpp +++ b/cpp/include/raft/core/host_span.hpp @@ -1,5 +1,5 @@ /* - * Copyright (c) 2022, NVIDIA CORPORATION. + * Copyright (c) 2022-2023, NVIDIA CORPORATION. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -19,10 +19,20 @@ #include namespace raft { + +/** + * @defgroup device_span one-dimensional device span type + * @{ + */ + /** * @brief A span class for host pointer. */ template using host_span = span; +/** + * @} + */ + } // end namespace raft \ No newline at end of file diff --git a/cpp/include/raft/core/interruptible.hpp b/cpp/include/raft/core/interruptible.hpp index 62e481a801..f7351c3411 100644 --- a/cpp/include/raft/core/interruptible.hpp +++ b/cpp/include/raft/core/interruptible.hpp @@ -30,6 +30,11 @@ namespace raft { +/** + * @defgroup interruptible definitions and classes related to the interruptible API + * @{ + */ + /** * @brief Exception thrown during `interruptible::synchronize` call when it detects a request * to cancel the work performed in this CPU thread. @@ -297,6 +302,10 @@ class interruptible { } }; +/** + * @} + */ + } // namespace raft #endif diff --git a/cpp/include/raft/core/mdarray.hpp b/cpp/include/raft/core/mdarray.hpp index 5ae0886ce9..7bd5a28a0c 100644 --- a/cpp/include/raft/core/mdarray.hpp +++ b/cpp/include/raft/core/mdarray.hpp @@ -32,6 +32,12 @@ #include namespace raft { + +/** + * @defgroup mdarray multi-dimensional memory-owning type + * @{ + */ + /** * @brief Interface to implement an owning multi-dimensional array * @@ -207,6 +213,7 @@ class mdarray : cp_(cp), map_(m), c_(cp_.create(handle, map_.required_span_size())) { } + RAFT_MDARRAY_CTOR_CONSTEXPR mdarray(raft::resources const& handle, mapping_type const& m, container_policy_type& cp) @@ -336,6 +343,15 @@ class mdarray container_type c_; }; +/** + * @} + */ + +/** + * @defgroup mdarray_reshape Row- or Col-norm computation + * @{ + */ + /** * @brief Flatten object implementing raft::array_interface into a 1-dim array view * @@ -371,4 +387,8 @@ auto reshape(const array_interface_type& mda, extents new return reshape(mda.view(), new_shape); } +/** + * }@ + */ + } // namespace raft diff --git a/cpp/include/raft/core/mdspan.hpp b/cpp/include/raft/core/mdspan.hpp index cd9ca26ed9..e87c76d82d 100644 --- a/cpp/include/raft/core/mdspan.hpp +++ b/cpp/include/raft/core/mdspan.hpp @@ -213,6 +213,11 @@ constexpr auto make_extents(Extents... exts) return extents{exts...}; } +/** + * @defgroup mdspan_reshape Row- or Col-norm computation + * @{ + */ + /** * @brief Flatten raft::mdspan into a 1-dim array view * @@ -298,6 +303,10 @@ RAFT_INLINE_FUNCTION auto unravel_index(Idx idx, } } +/** + * @} + */ + /** * @brief Const accessor specialization for default_accessor * diff --git a/cpp/include/raft/core/span.hpp b/cpp/include/raft/core/span.hpp index a896ba1977..22906580de 100644 --- a/cpp/include/raft/core/span.hpp +++ b/cpp/include/raft/core/span.hpp @@ -32,6 +32,11 @@ #include namespace raft { + +/** + * @defgroup span one-dimensional span type + * @{ + */ /** * @brief The span class defined in ISO C++20. Iterator is defined as plain pointer and * most of the methods have bound check on debug build. @@ -274,4 +279,8 @@ auto as_writable_bytes(span s) noexcept { return {reinterpret_cast(s.data()), s.size_bytes()}; } + +/** + * @} + */ } // namespace raft diff --git a/cpp/include/raft/linalg/normalize.cuh b/cpp/include/raft/linalg/normalize.cuh index 86bc597bdc..6169cf1dfa 100644 --- a/cpp/include/raft/linalg/normalize.cuh +++ b/cpp/include/raft/linalg/normalize.cuh @@ -26,7 +26,7 @@ namespace raft { namespace linalg { /** - * @defgroup norm Row- or Col-norm computation + * @defgroup normalize Row- or Col-norm computation * @{ */ diff --git a/cpp/include/raft/random/rng.cuh b/cpp/include/raft/random/rng.cuh index c3b44a7577..a946471312 100644 --- a/cpp/include/raft/random/rng.cuh +++ b/cpp/include/raft/random/rng.cuh @@ -29,6 +29,11 @@ namespace raft::random { +/** + * \defgroup univariate_random_sampling Univariate random sampling + * @{ + */ + /** * @brief Generate uniformly distributed numbers in the given range * @@ -52,6 +57,10 @@ void uniform(raft::resources const& handle, rng_state, out.data_handle(), out.extent(0), start, end, resource::get_cuda_stream(handle)); } +/** + * @} + */ + /** * @brief Legacy overload of `uniform` taking raw pointers * @@ -76,6 +85,7 @@ void uniform(raft::resources const& handle, } /** + * @ingroup univariate_random_sampling * @brief Generate uniformly distributed integers in the given range * * @tparam OutputValueType Integral type; value type of the output vector @@ -128,6 +138,7 @@ void uniformInt(raft::resources const& handle, } /** + * @ingroup univariate_random_sampling * @brief Generate normal distributed numbers * with a given mean and standard deviation * @@ -175,6 +186,7 @@ void normal(raft::resources const& handle, } /** + * @ingroup univariate_random_sampling * @brief Generate normal distributed integers * * @tparam OutputValueType Integral type; value type of the output vector @@ -228,6 +240,7 @@ void normalInt(raft::resources const& handle, } /** + * @ingroup univariate_random_sampling * @brief Generate normal distributed table according to the given set of * means and scalar standard deviations. * @@ -326,6 +339,7 @@ void normalTable(raft::resources const& handle, } /** + * @ingroup univariate_random_sampling * @brief Fill a vector with the given value * * @tparam OutputValueType Value type of the output vector @@ -364,6 +378,7 @@ void fill( } /** + * @ingroup univariate_random_sampling * @brief Generate bernoulli distributed boolean array * * @tparam OutputValueType Type of each element of the output vector; @@ -407,6 +422,7 @@ void bernoulli( } /** + * @ingroup univariate_random_sampling * @brief Generate bernoulli distributed array and applies scale * * @tparam OutputValueType Data type in which to compute the probabilities @@ -453,6 +469,7 @@ void scaled_bernoulli(raft::resources const& handle, } /** + * @ingroup univariate_random_sampling * @brief Generate Gumbel distributed random numbers * * @tparam OutputValueType data type of output random number @@ -501,6 +518,7 @@ void gumbel(raft::resources const& handle, } /** + * @ingroup univariate_random_sampling * @brief Generate lognormal distributed numbers * * @tparam OutputValueType data type of output random number @@ -547,6 +565,7 @@ void lognormal(raft::resources const& handle, } /** + * @ingroup univariate_random_sampling * @brief Generate logistic distributed random numbers * * @tparam OutputValueType data type of output random number @@ -593,6 +612,7 @@ void logistic(raft::resources const& handle, } /** + * @ingroup univariate_random_sampling * @brief Generate exponentially distributed random numbers * * @tparam OutputValueType data type of output random number @@ -632,6 +652,7 @@ void exponential( } /** + * @ingroup univariate_random_sampling * @brief Generate rayleigh distributed random numbers * * @tparam OutputValueType data type of output random number @@ -670,6 +691,7 @@ void rayleigh( detail::rayleigh(rng_state, ptr, len, sigma, resource::get_cuda_stream(handle)); } /** + * @ingroup univariate_random_sampling * @brief Generate laplace distributed random numbers * * @tparam OutputValueType data type of output random number @@ -716,6 +738,7 @@ void laplace(raft::resources const& handle, } /** + * @ingroup univariate_random_sampling * @brief Generate random integers, where the probability of i is weights[i]/sum(weights) * * Usage example: diff --git a/docs/source/cpp_api/core_interruptible.rst b/docs/source/cpp_api/core_interruptible.rst index da767cdd6d..3f12f602f8 100644 --- a/docs/source/cpp_api/core_interruptible.rst +++ b/docs/source/cpp_api/core_interruptible.rst @@ -10,6 +10,7 @@ Interruptible namespace *raft::core* -.. doxygenclass:: raft::interruptible - :project: RAFT - :members: + .. doxygengroup:: interruptible + :project: RAFT + :members: + :content-only: diff --git a/docs/source/cpp_api/core_resources.rst b/docs/source/cpp_api/core_resources.rst index b148e38e44..4f1dd4e5a4 100644 --- a/docs/source/cpp_api/core_resources.rst +++ b/docs/source/cpp_api/core_resources.rst @@ -6,7 +6,7 @@ Resources :class: highlight All resources which are specific to a computing environment like host or device are contained within, and managed by, -raft::resources. This design simplifies the APIs and eases user burden by making them opaque by default but allowing customization based on user preference. +`raft::resources`. This design simplifies the APIs and eases user burden by making the APIs opaque by default but allowing customization based on user preference. Vocabulary @@ -25,6 +25,8 @@ namespace *raft::resource* Device Resources ---------------- +`raft::device_resources` is a convenience over using `raft::resources` directly. It provides accessor methods to retrieve resources such as the CUDA stream, stream pool, and handles to the various CUDA math libraries like cuBLAS and cuSOLVER. + ``#include `` namespace *raft::core* @@ -81,7 +83,7 @@ CUDA Stream Pool namespace *raft::resource* -.. doxygengroup:: resource_cuda_stream_pool +.. doxygengroup:: resource_stream_pool :project: RAFT :members: :content-only: diff --git a/docs/source/cpp_api/distance_1nn.rst b/docs/source/cpp_api/distance_1nn.rst index bf99603522..8c1c00d6c9 100644 --- a/docs/source/cpp_api/distance_1nn.rst +++ b/docs/source/cpp_api/distance_1nn.rst @@ -17,7 +17,7 @@ namespace *raft::distance* ``#include `` namespace *raft::distance* -.. doxygengroup:: masked_l2_nn +.. doxygengroup:: masked_nn :project: RAFT :members: :content-only: diff --git a/docs/source/cpp_api/mdspan_mdarray.rst b/docs/source/cpp_api/mdspan_mdarray.rst index bf9e9e0139..e14fe5a9e3 100644 --- a/docs/source/cpp_api/mdspan_mdarray.rst +++ b/docs/source/cpp_api/mdspan_mdarray.rst @@ -7,20 +7,10 @@ mdarray: Multi-dimensional Owning Container ``#include `` -.. doxygenclass:: raft::mdarray +.. doxygengroup:: mdarray :project: RAFT :members: - -.. doxygenclass:: raft::array_interface - :project: RAFT - :members: - -.. doxygenstruct:: raft::is_array_interface - :project: RAFT - :members: - -.. doxygentypedef:: raft::is_array_interface_t - :project RAFT + :content-only: Device Vocabulary ----------------- @@ -75,11 +65,7 @@ Host Factories ``#include `` -.. doxygenfunction:: raft::make_host_matrix - :project: RAFT - -.. doxygenfunction:: raft::make_host_vector - :project: RAFT - -.. doxygenfunction:: raft::make_device_scalar +.. doxygengroup:: host_mdarray_factories :project: RAFT + :members: + :content-only: \ No newline at end of file diff --git a/docs/source/cpp_api/mdspan_representation.rst b/docs/source/cpp_api/mdspan_representation.rst index fbae03a3e0..f514cf38e0 100644 --- a/docs/source/cpp_api/mdspan_representation.rst +++ b/docs/source/cpp_api/mdspan_representation.rst @@ -40,17 +40,15 @@ Shapes .. doxygentypedef:: raft::extent_5d :project: RAFT -.. doxygenfunction:: raft::flatten(mdspan_type mds) - :project: RAFT - -.. doxygenfunction:: raft:: flatten(const array_interface_type& mda) - :project: RAFT - -.. doxygenfunction:: raft::reshape(mdspan_type mds, extents new_shape) +.. doxygengroup:: mdspan_reshape :project: RAFT + :members: + :content-only: -.. doxygenfunction:: raft::reshape(const array_interface_type& mda, extents new_shape) +.. doxygengroup:: mdarray_reshape :project: RAFT + :members: + :content-only: Accessors diff --git a/docs/source/cpp_api/mdspan_span.rst b/docs/source/cpp_api/mdspan_span.rst index 2bdaf4941e..870c4329d0 100644 --- a/docs/source/cpp_api/mdspan_span.rst +++ b/docs/source/cpp_api/mdspan_span.rst @@ -7,17 +7,22 @@ span: One-dimensional Non-owning View ``#include `` -.. doxygenclass:: raft::span +.. doxygengroup:: span :project: RAFT :members: + :content-only: ``#include `` -.. doxygentypedef:: raft::device_span - :project: RAFT +.. doxygengroup:: device_span + :project: RAFT + :members: + :content-only: ``#include `` -.. doxygentypedef:: raft::host_span - :project: RAFT +.. doxygengroup:: host_span + :project: RAFT + :members: + :content-only: diff --git a/docs/source/cpp_api/neighbors.rst b/docs/source/cpp_api/neighbors.rst index 9d2e762689..876f68b1bf 100644 --- a/docs/source/cpp_api/neighbors.rst +++ b/docs/source/cpp_api/neighbors.rst @@ -15,4 +15,5 @@ This page provides C++ class references for the publicly-exposed elements of the neighbors_ivf_flat.rst neighbors_ivf_pq.rst neighbors_epsilon_neighborhood.rst - neighbors_ball_cover.rst \ No newline at end of file + neighbors_ball_cover.rst + neighbors_cagra.rst \ No newline at end of file diff --git a/docs/source/cpp_api/neighbors_cagra.rst b/docs/source/cpp_api/neighbors_cagra.rst new file mode 100644 index 0000000000..68372bbb71 --- /dev/null +++ b/docs/source/cpp_api/neighbors_cagra.rst @@ -0,0 +1,21 @@ +CAGRA +===== + +CAGRA is a graph-based nearest neighbors implementation with state-of-the art query performance for both small- and large-batch sized search. + +Please note that the CAGRA implementation is currently experimental and the API is subject to change from release to release. We are currently working on promoting CAGRA to a top-level stable API within RAFT. + +.. role:: py(code) + :language: c++ + :class: highlight + +``#include `` + +namespace *raft::neighbors::experimental::cagra* + +.. doxygengroup:: cagra + :project: RAFT + :members: + :content-only: + + diff --git a/docs/source/cpp_api/random_datagen.rst b/docs/source/cpp_api/random_datagen.rst index ec23845b6b..a07f5e0154 100644 --- a/docs/source/cpp_api/random_datagen.rst +++ b/docs/source/cpp_api/random_datagen.rst @@ -11,7 +11,7 @@ make_blobs ``#include `` namespace *raft::random* -2 + .. doxygengroup:: make_blobs :project: RAFT :members: diff --git a/docs/source/cpp_api/random_sampling_univariate.rst b/docs/source/cpp_api/random_sampling_univariate.rst index ffa58a0d3a..cabad6945a 100644 --- a/docs/source/cpp_api/random_sampling_univariate.rst +++ b/docs/source/cpp_api/random_sampling_univariate.rst @@ -9,49 +9,7 @@ Univariate Random Sampling namespace *raft::random* -.. doxygenfunction:: raft::random::uniform(const raft::handle_t& handle, RngState& rng_state, raft::device_vector_view out, OutputValueType start, OutputValueType end) +.. doxygengroup:: univariate_random_sampling :project: RAFT - -.. doxygenfunction:: raft::random::uniformInt(const raft::handle_t& handle, RngState& rng_state, raft::device_vector_view out, OutputValueType start, OutputValueType end) - :project: RAFT - -.. doxygenfunction:: raft::random::normal(const raft::handle_t& handle, RngState& rng_state, raft::device_vector_view out, OutputValueType mu, OutputValueType sigma) - :project: RAFT - -.. doxygenfunction:: raft::random::normalInt(const raft::handle_t& handle, RngState& rng_state, raft::device_vector_view out, OutputValueType mu, OutputValueType sigma) - :project: RAFT - -.. doxygenfunction:: raft::random::normalTable(const raft::handle_t& handle, RngState& rng_state, raft::device_vector_view mu_vec, std::variant, OutputValueType> sigma, raft::device_matrix_view out) - :project: RAFT - -.. doxygenfunction:: raft::random::fill(const raft::handle_t& handle, RngState& rng_state, OutputValueType val, raft::device_vector_view out) - :project: RAFT - -.. doxygenfunction:: raft::random::bernoulli(const raft::handle_t& handle, RngState& rng_state, raft::device_vector_view out, Type prob) - :project: RAFT - -.. doxygenfunction:: raft::random::scaled_bernoulli(const raft::handle_t& handle, RngState& rng_state, raft::device_vector_view out, OutputValueType prob, OutputValueType scale) - :project: RAFT - -.. doxygenfunction:: raft::random::gumbel(const raft::handle_t& handle, RngState& rng_state, raft::device_vector_view out, OutputValueType mu, OutputValueType beta) - :project: RAFT - -.. doxygenfunction:: raft::random::lognormal(const raft::handle_t& handle, RngState& rng_state, raft::device_vector_view out, OutputValueType mu, OutputValueType sigma) - :project: RAFT - -.. doxygenfunction:: raft::random::logistic(const raft::handle_t& handle, RngState& rng_state, raft::device_vector_view out, OutputValueType mu, OutputValueType scale) - :project: RAFT - -.. doxygenfunction:: raft::random::exponential(const raft::handle_t& handle, RngState& rng_state, raft::device_vector_view out, OutputValueType lambda) - :project: RAFT - -.. doxygenfunction:: raft::random::rayleigh(const raft::handle_t& handle, RngState& rng_state, raft::device_vector_view out, OutputValueType sigma) - :project: RAFT - -.. doxygenfunction:: raft::random::laplace(const raft::handle_t& handle, RngState& rng_state, raft::device_vector_view out, OutputValueType mu, OutputValueType scale) - :project: RAFT - -.. doxygenfunction:: raft::random::discrete - :project: RAFT - - + :members: + :content-only: