diff --git a/cpp/include/raft/core/device_mdspan.hpp b/cpp/include/raft/core/device_mdspan.hpp index 3386610224..f64f15d0d5 100644 --- a/cpp/include/raft/core/device_mdspan.hpp +++ b/cpp/include/raft/core/device_mdspan.hpp @@ -44,7 +44,6 @@ template > using managed_mdspan = mdspan>; -namespace detail { template struct is_device_mdspan : std::false_type { }; @@ -83,22 +82,20 @@ using is_input_managed_mdspan_t = is_managed_mdspan>; template using is_output_managed_mdspan_t = is_managed_mdspan>; -} // end namespace detail - /** * @\brief Boolean to determine if variadic template types Tn are either raft::device_mdspan or a * derived type */ template -inline constexpr bool is_device_mdspan_v = std::conjunction_v...>; +inline constexpr bool is_device_mdspan_v = std::conjunction_v...>; template inline constexpr bool is_input_device_mdspan_v = - std::conjunction_v...>; + std::conjunction_v...>; template inline constexpr bool is_output_device_mdspan_v = - std::conjunction_v...>; + std::conjunction_v...>; template using enable_if_device_mdspan = std::enable_if_t>; @@ -114,15 +111,15 @@ using enable_if_output_device_mdspan = std::enable_if_t -inline constexpr bool is_managed_mdspan_v = std::conjunction_v...>; +inline constexpr bool is_managed_mdspan_v = std::conjunction_v...>; template inline constexpr bool is_input_managed_mdspan_v = - std::conjunction_v...>; + std::conjunction_v...>; template inline constexpr bool is_output_managed_mdspan_v = - std::conjunction_v...>; + std::conjunction_v...>; template using enable_if_managed_mdspan = std::enable_if_t>; @@ -292,18 +289,6 @@ auto make_device_vector_view( return device_vector_view{ptr, mapping}; } -/** - * @brief Create a layout_stride mapping from extents and strides - * @param[in] extents the dimensionality of the layout - * @param[in] strides the strides between elements in the layout - * @return raft::layout_stride::mapping - */ -template -auto make_strided_layout(Extents extents, Strides strides) -{ - return layout_stride::mapping{extents, strides}; -} - /** * @brief Construct a strided vector layout mapping * diff --git a/cpp/include/raft/core/host_mdspan.hpp b/cpp/include/raft/core/host_mdspan.hpp index d3d6c53df3..1a0ea6432f 100644 --- a/cpp/include/raft/core/host_mdspan.hpp +++ b/cpp/include/raft/core/host_mdspan.hpp @@ -36,8 +36,6 @@ template > using host_mdspan = mdspan>; -namespace detail { - template struct is_host_mdspan : std::false_type { }; @@ -57,22 +55,18 @@ using is_input_host_mdspan_t = is_host_mdspan>; template using is_output_host_mdspan_t = is_host_mdspan>; -} // namespace detail - /** * @\brief Boolean to determine if variadic template types Tn are either raft::host_mdspan or a * derived type */ template -inline constexpr bool is_host_mdspan_v = std::conjunction_v...>; +inline constexpr bool is_host_mdspan_v = std::conjunction_v...>; template -inline constexpr bool is_input_host_mdspan_v = - std::conjunction_v...>; +inline constexpr bool is_input_host_mdspan_v = std::conjunction_v...>; template -inline constexpr bool is_output_host_mdspan_v = - std::conjunction_v...>; +inline constexpr bool is_output_host_mdspan_v = std::conjunction_v...>; template using enable_if_host_mdspan = std::enable_if_t>; diff --git a/cpp/include/raft/core/mdspan.hpp b/cpp/include/raft/core/mdspan.hpp index e7a9b256cb..786ce69f89 100644 --- a/cpp/include/raft/core/mdspan.hpp +++ b/cpp/include/raft/core/mdspan.hpp @@ -193,6 +193,18 @@ auto make_mdspan(ElementType* ptr, extents exts) return mdspan{ptr, exts}; } +/** + * @brief Create a layout_stride mapping from extents and strides + * @param[in] extents the dimensionality of the layout + * @param[in] strides the strides between elements in the layout + * @return raft::layout_stride::mapping + */ +template +auto make_strided_layout(Extents extents, Strides strides) +{ + return layout_stride::mapping{extents, strides}; +} + /** * @brief Create raft::extents to specify dimensionality * diff --git a/cpp/include/raft/random/detail/multi_variable_gaussian.cuh b/cpp/include/raft/random/detail/multi_variable_gaussian.cuh index 1edb9bf983..5bed71f2f4 100644 --- a/cpp/include/raft/random/detail/multi_variable_gaussian.cuh +++ b/cpp/include/raft/random/detail/multi_variable_gaussian.cuh @@ -16,7 +16,6 @@ #pragma once #include "curand_wrappers.hpp" -#include "random_types.hpp" #include #include #include @@ -26,6 +25,7 @@ #include #include #include +#include #include #include #include diff --git a/cpp/include/raft/random/detail/random_types.hpp b/cpp/include/raft/random/detail/random_types.hpp deleted file mode 100644 index 28108f9513..0000000000 --- a/cpp/include/raft/random/detail/random_types.hpp +++ /dev/null @@ -1,23 +0,0 @@ -/* - * Copyright (c) 2018-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. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -#pragma once - -namespace raft::random::detail { - -enum class multi_variable_gaussian_decomposition_method { CHOLESKY, JACOBI, QR }; - -}; // end of namespace raft::random::detail diff --git a/cpp/include/raft/random/multi_variable_gaussian.cuh b/cpp/include/raft/random/multi_variable_gaussian.cuh index bed16d8e48..6bee323007 100644 --- a/cpp/include/raft/random/multi_variable_gaussian.cuh +++ b/cpp/include/raft/random/multi_variable_gaussian.cuh @@ -20,6 +20,7 @@ #pragma once #include "detail/multi_variable_gaussian.cuh" +#include namespace raft::random { @@ -59,24 +60,6 @@ class multi_variable_gaussian : public detail::multi_variable_gaussian_impl { ~multi_variable_gaussian() { deinit(); } }; // end of multi_variable_gaussian -/** - * @brief Matrix decomposition method for `compute_multi_variable_gaussian` to use. - * - * `compute_multi_variable_gaussian` can use any of the following methods. - * - * - `CHOLESKY`: Uses Cholesky decomposition on the normal equations. - * This may be faster than the other two methods, but less accurate. - * - * - `JACOBI`: Uses the singular value decomposition (SVD) computed with - * cuSOLVER's gesvdj algorithm, which is based on the Jacobi method - * (sweeps of plane rotations). This exposes more parallelism - * for small and medium size matrices than the QR option below. - * - * - `QR`: Uses the SVD computed with cuSOLVER's gesvd algorithm, - * which is based on the QR algorithm. - */ -using detail::multi_variable_gaussian_decomposition_method; - template void compute_multi_variable_gaussian( const raft::handle_t& handle, diff --git a/cpp/include/raft/random/random_types.hpp b/cpp/include/raft/random/random_types.hpp new file mode 100644 index 0000000000..96b55a4727 --- /dev/null +++ b/cpp/include/raft/random/random_types.hpp @@ -0,0 +1,39 @@ +/* + * Copyright (c) 2018-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. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#pragma once + +namespace raft::random { + +/** + * @brief Matrix decomposition method for `compute_multi_variable_gaussian` to use. + * + * `compute_multi_variable_gaussian` can use any of the following methods. + * + * - `CHOLESKY`: Uses Cholesky decomposition on the normal equations. + * This may be faster than the other two methods, but less accurate. + * + * - `JACOBI`: Uses the singular value decomposition (SVD) computed with + * cuSOLVER's gesvdj algorithm, which is based on the Jacobi method + * (sweeps of plane rotations). This exposes more parallelism + * for small and medium size matrices than the QR option below. + * + * - `QR`: Uses the SVD computed with cuSOLVER's gesvd algorithm, + * which is based on the QR algorithm. + */ +enum class multi_variable_gaussian_decomposition_method { CHOLESKY, JACOBI, QR }; + +}; // end of namespace raft::random diff --git a/cpp/include/raft/random/rng.cuh b/cpp/include/raft/random/rng.cuh index 27672b077f..95bfe24a68 100644 --- a/cpp/include/raft/random/rng.cuh +++ b/cpp/include/raft/random/rng.cuh @@ -722,6 +722,11 @@ template using weight_t = typename weight_alias::type; } // namespace sample_without_replacement_impl +/** + * \defgroup sample_without_replacement Sampling without Replacement + * @{ + */ + /** * @brief Sample the input vector without replacement, optionally based on the * input weight vector for each element in the array. @@ -824,6 +829,7 @@ void sample_without_replacement(const raft::handle_t& handle, * compiler find the above overload, in case users pass in * `std::nullopt` for one or both of the optional arguments. * + * * Please see above for documentation of `sample_without_replacement`. */ template > @@ -832,6 +838,8 @@ void sample_without_replacement(Args... args) sample_without_replacement(std::forward(args)..., std::nullopt); } +/** @} */ + /** * @brief Legacy version of @c sample_without_replacement (see above) * that takes raw arrays instead of device mdspan. diff --git a/cpp/test/random/multi_variable_gaussian.cu b/cpp/test/random/multi_variable_gaussian.cu index 516fd9f28b..51a79ae04a 100644 --- a/cpp/test/random/multi_variable_gaussian.cu +++ b/cpp/test/random/multi_variable_gaussian.cu @@ -212,11 +212,11 @@ class MVGMdspanTest : public ::testing::TestWithParam> { static auto old_enum_to_new_enum(typename multi_variable_gaussian::Decomposer method) { if (method == multi_variable_gaussian::chol_decomp) { - return detail::multi_variable_gaussian_decomposition_method::CHOLESKY; + return multi_variable_gaussian_decomposition_method::CHOLESKY; } else if (method == multi_variable_gaussian::jacobi) { - return detail::multi_variable_gaussian_decomposition_method::JACOBI; + return multi_variable_gaussian_decomposition_method::JACOBI; } else { - return detail::multi_variable_gaussian_decomposition_method::QR; + return multi_variable_gaussian_decomposition_method::QR; } } diff --git a/docs/source/cpp_api.rst b/docs/source/cpp_api.rst index cf3829422d..569fd64061 100644 --- a/docs/source/cpp_api.rst +++ b/docs/source/cpp_api.rst @@ -2,8 +2,6 @@ C++ API Reference ~~~~~~~~~~~~~~~~~ - - .. _api: .. toctree:: diff --git a/docs/source/cpp_api/cluster.rst b/docs/source/cpp_api/cluster.rst index 90c430ace9..6fdc1c696f 100644 --- a/docs/source/cpp_api/cluster.rst +++ b/docs/source/cpp_api/cluster.rst @@ -4,25 +4,38 @@ Cluster This page provides C++ class references for the publicly-exposed elements of the `raft/cluster` headers. RAFT provides fundamental clustering algorithms which are, themselves, considered reusable building blocks for other algorithms. +.. role:: py(code) + :language: c++ + :class: highlight + K-Means -------- +####### + +Header: `raft/cluster/kmeans.cuh` .. doxygennamespace:: raft::cluster::kmeans :project: RAFT :members: + :content-only: Hierarchical Clustering ------------------------ +####################### + +Header: `raft/cluster/single_linkage.cuh` .. doxygennamespace:: raft::cluster::hierarchy :project: RAFT :members: + :content-only: Spectral Clustering -------------------- +################### + +Header: `raft/spectral/partition.cuh` .. doxygennamespace:: raft::spectral :project: RAFT :members: + :content-only: diff --git a/docs/source/cpp_api/core.rst b/docs/source/cpp_api/core.rst index 9e4ef412f7..68965053de 100644 --- a/docs/source/cpp_api/core.rst +++ b/docs/source/cpp_api/core.rst @@ -6,9 +6,16 @@ require minimal dependencies, can be compiled without `nvcc`, and thus are safe the headers in the `raft/core` include directory, any headers in the codebase with the suffix `_types.hpp` are also safe to expose in public APIs. +.. role:: py(code) + :language: c++ + :class: highlight + + handle_t ######## +Header: `raft/core/handle.hpp` + .. doxygenclass:: raft::handle_t :project: RAFT :members: @@ -17,6 +24,8 @@ handle_t Interruptible ############# +Header: `raft/core/interupptible.hpp` + .. doxygenclass:: raft::interruptible :project: RAFT :members: @@ -24,14 +33,19 @@ Interruptible NVTX #### +Header: `raft/core/nvtx.hpp` + .. doxygennamespace:: raft::common::nvtx :project: RAFT :members: + :content-only: Key-Value Pair ############## +Header: `raft/core/kvp.hpp` + .. doxygenstruct:: raft::KeyValuePair :project: RAFT :members: @@ -40,6 +54,8 @@ Key-Value Pair logger ###### +Header: `raft/core/logger.hpp` + .. doxygenclass:: raft::logger :project: RAFT :members: @@ -48,7 +64,10 @@ logger Multi-node Multi-GPU #################### +Header: `raft/core/comms.hpp` + .. doxygennamespace:: raft::comms :project: RAFT :members: + :content-only: diff --git a/docs/source/cpp_api/distance.rst b/docs/source/cpp_api/distance.rst index 2596361f6a..e77e311cdc 100644 --- a/docs/source/cpp_api/distance.rst +++ b/docs/source/cpp_api/distance.rst @@ -4,8 +4,16 @@ Distance This page provides C++ class references for the publicly-exposed elements of the `raft/distance` package. RAFT's distances have been highly optimized and support a wide assortment of different distance measures. +.. role:: py(code) + :language: c++ + :class: highlight + + Distance ######## +Header: `raft/distance/distance.cuh` + .. doxygennamespace:: raft::distance :project: RAFT + :members: diff --git a/docs/source/cpp_api/linalg.rst b/docs/source/cpp_api/linalg.rst index 5664e5b3dc..081eb40298 100644 --- a/docs/source/cpp_api/linalg.rst +++ b/docs/source/cpp_api/linalg.rst @@ -6,6 +6,12 @@ In addition to providing highly optimized arithmetic and matrix/vector operation by providing common BLAS routines, standard linear system solvers, factorization and eigenvalue solvers. Some of these routines hide the complexities of lower-level C-based libraries provided in the CUDA toolkit +.. role:: py(code) + :language: c++ + :class: highlight + + .. doxygennamespace:: raft::linalg :project: RAFT :members: + :content-only: diff --git a/docs/source/cpp_api/matrix.rst b/docs/source/cpp_api/matrix.rst index 945658eb7b..b032281a1c 100644 --- a/docs/source/cpp_api/matrix.rst +++ b/docs/source/cpp_api/matrix.rst @@ -4,6 +4,12 @@ Matrix This page provides C++ class references for the publicly-exposed elements of the `raft/matrix` headers. The `raft/matrix` headers cover many operations on matrices that are otherwise not covered by `raft/linalg`. +.. role:: py(code) + :language: c++ + :class: highlight + + .. doxygennamespace:: raft::matrix :project: RAFT :members: + :content-only: diff --git a/docs/source/cpp_api/mdspan.rst b/docs/source/cpp_api/mdspan.rst index a283da967b..511ead8573 100644 --- a/docs/source/cpp_api/mdspan.rst +++ b/docs/source/cpp_api/mdspan.rst @@ -1,23 +1,19 @@ -Multi-dimensional Span / Array -============================== +Multi-dimensional Data +====================== This page provides C++ class references for the RAFT's 1d span and multi-dimension owning (mdarray) and non-owning (mdspan) APIs. These headers can be found in the `raft/core` directory. -Representation -############## +.. role:: py(code) + :language: c++ + :class: highlight -.. doxygenstruct:: raft::host_device_accessor - :project: RAFT - :members: -.. doxygentypedef:: raft::host_accessor - :project: RAFT +Representation +############## -.. doxygentypedef:: raft::device_accessor - :project: RAFT -.. doxygentypedef:: raft::managed_accessor - :project: RAFT +Layouts +------- .. doxygentypedef:: raft::row_major :project: RAFT @@ -25,6 +21,10 @@ Representation .. doxygentypedef:: raft::col_major :project: RAFT + +Shapes +------ + .. doxygentypedef:: raft::matrix_extent :project: RAFT @@ -43,20 +43,38 @@ Representation .. doxygentypedef:: raft::extent_5d :project: RAFT -.. doxygentypedef:: raft::dynamic_extent +.. 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) + :project: RAFT + +.. doxygenfunction:: raft::reshape(const array_interface_type& mda, extents new_shape) :project: RAFT -.. doxygentypedef:: raft::extents + +Accessors +--------- + +.. doxygenstruct:: raft::host_device_accessor :project: RAFT + :members: -.. doxygenfunction:: raft::flatten +.. doxygentypedef:: raft::host_accessor :project: RAFT +.. doxygentypedef:: raft::device_accessor + :project: RAFT -.. doxygenfunction:: raft::reshape +.. doxygentypedef:: raft::managed_accessor :project: RAFT + + mdarray ####### @@ -81,7 +99,6 @@ Device Vocabulary .. doxygentypedef:: raft::device_mdarray :project: RAFT - .. doxygentypedef:: raft::device_matrix :project: RAFT @@ -136,42 +153,15 @@ mdspan .. doxygentypedef:: raft::mdspan :project: RAFT -.. doxygenstruct:: raft::is_mdspan - :project: RAFT - :members: - -.. doxygentypedef:: raft::is_mdspan_t - :project: RAFT - -.. doxygenstruct:: raft::is_input_mdspan - :project: RAFT - :members: - -.. doxygentypedef:: raft::is_input_mdspan_t - :project: RAFT - -.. doxygenstruct:: raft::is_output_mdspan - :project: RAFT - :members: - -.. doxygentypedef:: raft::is_output_mdspan_t - :project: RAFT - -.. doxygentypedef:: raft::enable_if_mdspan - :project: RAFT - -.. doxygentypedef:: raft::enable_if_input_mdspan - :project: RAFT - -.. doxygentypedef:: raft::enable_if_output_mdspan - :project: RAFT - .. doxygenfunction:: raft::make_mdspan :project: RAFT .. doxygenfunction:: raft::make_extents :project: RAFT +.. doxygenfunction:: raft::make_strided_layout(Extents extents, Strides strides) + :project: RAFT + .. doxygenfunction:: raft::unravel_index :project: RAFT @@ -185,13 +175,13 @@ Device Vocabulary .. doxygenstruct:: raft::is_device_mdspan :project: RAFT -.. doxygenstruct:: raft::is_device_mdspan_t +.. doxygentypedef:: raft::is_device_mdspan_t :project: RAFT -.. doxygenstruct:: raft::is_input_device_mdspan_t +.. doxygentypedef:: raft::is_input_device_mdspan_t :project: RAFT -.. doxygenstruct:: raft::is_output_device_mdspan_t +.. doxygentypedef:: raft::is_output_device_mdspan_t :project: RAFT .. doxygentypedef:: raft::enable_if_device_mdspan @@ -216,13 +206,10 @@ Device Vocabulary Device Factories ---------------- -.. doxygenfunction:: raft::make_device_mdspan - :project: RAFT - .. doxygenfunction:: raft::make_device_matrix_view :project: RAFT -.. doxygenfunction:: raft::make_device_vector_view +.. doxygenfunction:: raft::make_device_vector_view(ElementType* ptr, IndexType n) :project: RAFT .. doxygenfunction:: raft::make_device_scalar_view @@ -238,13 +225,13 @@ Managed Vocabulary .. doxygenstruct:: raft::is_managed_mdspan :project: RAFT -.. doxygenstruct:: raft::is_managed_mdspan_t +.. doxygentypedef:: raft::is_managed_mdspan_t :project: RAFT -.. doxygenstruct:: raft::is_input_managed_mdspan_t +.. doxygentypedef:: raft::is_input_managed_mdspan_t :project: RAFT -.. doxygenstruct:: raft::is_output_managed_mdspan_t +.. doxygentypedef:: raft::is_output_managed_mdspan_t :project: RAFT .. doxygentypedef:: raft::enable_if_managed_mdspan @@ -256,30 +243,11 @@ Managed Vocabulary .. doxygentypedef:: raft::enable_if_output_managed_mdspan :project: RAFT -.. doxygentypedef:: raft::managed_matrix_view - :project: RAFT - -.. doxygentypedef:: raft::managed_vector_view - :project: RAFT - -.. doxygentypedef:: raft::managed_scalar_view - :project: RAFT - Managed Factories ----------------- -.. doxygenfunction:: raft::make_managed_mdspan - :project: RAFT - -.. doxygenfunction:: raft::make_managed_matrix_view - :project: RAFT - -.. doxygenfunction:: raft::make_managed_vector_view - :project: RAFT - -.. doxygenfunction:: raft::make_managed_scalar_view - :project: RAFT +.. doxygenfunction:: make_managed_mdspan(ElementType* ptr, extents exts) Host Vocabulary @@ -291,13 +259,13 @@ Host Vocabulary .. doxygenstruct:: raft::is_host_mdspan :project: RAFT -.. doxygenstruct:: raft::is_host_mdspan_t +.. doxygentypedef:: raft::is_host_mdspan_t :project: RAFT -.. doxygenstruct:: raft::is_input_host_mdspan_t +.. doxygentypedef:: raft::is_input_host_mdspan_t :project: RAFT -.. doxygenstruct:: raft::is_output_host_mdspan_t +.. doxygentypedef:: raft::is_output_host_mdspan_t :project: RAFT .. doxygentypedef:: raft::enable_if_host_mdspan @@ -330,6 +298,40 @@ Host Factories .. doxygenfunction:: raft::make_device_scalar_view :project: RAFT + +Validation Routines +------------------- + +.. doxygenstruct:: raft::is_mdspan + :project: RAFT + :members: + +.. doxygentypedef:: raft::is_mdspan_t + :project: RAFT + +.. doxygenstruct:: raft::is_input_mdspan + :project: RAFT + :members: + +.. doxygentypedef:: raft::is_input_mdspan_t + :project: RAFT + +.. doxygenstruct:: raft::is_output_mdspan + :project: RAFT + :members: + +.. doxygentypedef:: raft::is_output_mdspan_t + :project: RAFT + +.. doxygentypedef:: raft::enable_if_mdspan + :project: RAFT + +.. doxygentypedef:: raft::enable_if_input_mdspan + :project: RAFT + +.. doxygentypedef:: raft::enable_if_output_mdspan + :project: RAFT + span #### diff --git a/docs/source/cpp_api/neighbors.rst b/docs/source/cpp_api/neighbors.rst index 962bbd1efe..93eecf68b4 100644 --- a/docs/source/cpp_api/neighbors.rst +++ b/docs/source/cpp_api/neighbors.rst @@ -3,41 +3,61 @@ Neighbors This page provides C++ class references for the publicly-exposed elements of the neighbors package. +.. role:: py(code) + :language: c++ + :class: highlight + Brute-force ----------- +Header: `raft/neighbors/brute_force.cuh` + .. doxygennamespace:: raft::neighbors::brute_force :project: RAFT + :members: + :content-only: IVF-Flat -------- +Header: `raft/neighbors/ivf_flat.cuh` + .. doxygennamespace:: raft::neighbors::ivf_flat :project: RAFT :members: + :content-only: IVF-PQ -------- +Header: `raft/neighbors/ivf_pq.cuh` + .. doxygennamespace:: raft::neighbors::ivf_pq :project: RAFT :members: + :content-only: Epsilon Neighborhood -------------------- +Header: `raft/neighbors/epsilon_neighborhood.cuh` + .. doxygennamespace:: raft::neighbors::epsilon_neighborhood :project: RAFT :members: + :content-only: Random Ball Cover ----------------- +Header: `raft/neighbors/ball_cover.cuh` + .. doxygennamespace:: raft::neighbors::ball_cover :project: RAFT :members: + :content-only: diff --git a/docs/source/cpp_api/random.rst b/docs/source/cpp_api/random.rst index be2c188617..353f783ed4 100644 --- a/docs/source/cpp_api/random.rst +++ b/docs/source/cpp_api/random.rst @@ -3,30 +3,109 @@ Random This page provides C++ class references for the publicly-exposed elements of the random package. +.. role:: py(code) + :language: c++ + :class: highlight + +Header: `raft/random/rng_state.hpp` + +.. doxygenstruct:: raft::random::RngState + :project: RAFT + :members: + + Data Generation ############### -.. doxygenfunction:: raft::random::make_blobs +make_blobs +---------- + +Header: `raft/random/make_blobs.cuh` + +.. doxygenfunction:: raft::random::make_blobs(raft::handle_t const& handle, raft::device_matrix_view out, raft::device_vector_view labels, IdxT n_clusters, std::optional> centers, std::optional> const cluster_std, const DataT cluster_std_scalar, bool shuffle, DataT center_box_min, DataT center_box_max, uint64_t seed, GeneratorType type) + :project: RAFT + +make_regression +--------------- + +Header: `raft/random/make_regression.cuh` + +.. doxygenfunction:: raft::random::make_regression(const raft::handle_t& handle, raft::device_matrix_view out, raft::device_matrix_view values, IdxT n_informative, std::optional> coef, DataT bias, IdxT effective_rank, DataT tail_strength, DataT noise, bool shuffle, uint64_t seed, GeneratorType type) + :project: RAFT + +rmat +---- + +Header: `raft/random/rmat_rectangular_generator.cuh` + +.. doxygenfunction:: raft::random::rmat_rectangular_gen(const raft::handle_t& handle, raft::random::RngState& r, raft::device_vector_view theta, raft::device_mdspan, raft::row_major> out, raft::device_vector_view out_src, raft::device_vector_view out_dst, IdxT r_scale, IdxT c_scale) + :project: RAFT + + +Random Sampling +############### + +Distributions +------------- + +Header: `raft/random/rng.cuh` + +.. doxygenfunction:: raft::random::uniform(const raft::handle_t& handle, RngState& rng_state, raft::device_vector_view out, OutputValueType start, OutputValueType end) :project: RAFT -.. doxygenfunction:: raft::random::make_regression +.. 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::rmat_rectangular_gen +.. 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 + + +Sampling Without Replacement +---------------------------- -Random Number Generation -######################## +Header: `raft/random/rng.cuh` -.. doxygenclass:: raft::random::Rng +.. doxygengroup:: sample_without_replacement :project: RAFT :members: + :content-only: -Useful Operations -################# +Header: `raft/random/permute.cuh` -.. doxygenfunction:: raft::random::permute +.. doxygenfunction:: raft::random::permute(const raft::handle_t& handle, raft::device_matrix_view in, std::optional> permsOut, std::optional> out) :project: RAFT diff --git a/docs/source/cpp_api/solver.rst b/docs/source/cpp_api/solver.rst index f7ca244dc8..d03f3bb1eb 100644 --- a/docs/source/cpp_api/solver.rst +++ b/docs/source/cpp_api/solver.rst @@ -3,10 +3,16 @@ Solvers This page provides C++ class references for the publicly-exposed elements of the iterative and combinatorial solvers package. +.. role:: py(code) + :language: c++ + :class: highlight + Linear Assignment Problem ######################### +Header: `raft/solver/linear_assignment.cuh` + .. doxygenclass:: raft::solver::LinearAssignmentProblem :project: RAFT :members: @@ -14,5 +20,7 @@ Linear Assignment Problem Minimum Spanning Tree ##################### +Header: `raft/sparse/solver/mst.cuh` + .. doxygenfunction:: raft::sparse::solver::mst :project: RAFT diff --git a/docs/source/cpp_api/sparse.rst b/docs/source/cpp_api/sparse.rst index a7c32cc65d..ea29dbebd0 100644 --- a/docs/source/cpp_api/sparse.rst +++ b/docs/source/cpp_api/sparse.rst @@ -3,6 +3,10 @@ Sparse This page provides C++ class references for the publicly-exposed elements of the sparse package. +.. role:: py(code) + :language: c++ + :class: highlight + Conversion ########## @@ -10,6 +14,7 @@ Conversion .. doxygennamespace:: raft::sparse::convert :project: RAFT :members: + :content-only: Distance ######## @@ -17,6 +22,7 @@ Distance .. doxygennamespace:: raft::sparse::distance :project: RAFT :members: + :content-only: Linear Algebra ############## @@ -24,6 +30,7 @@ Linear Algebra .. doxygennamespace:: raft::sparse::linalg :project: RAFT :members: + :content-only: Matrix Operations ################# @@ -31,10 +38,12 @@ Matrix Operations .. doxygennamespace:: raft::sparse::op :project: RAFT :members: + :content-only: -Nearest Neighbors -################# +Neighbors +######### .. doxygennamespace:: raft::sparse::neighbors :project: RAFT :members: + :content-only: diff --git a/docs/source/cpp_api/stats.rst b/docs/source/cpp_api/stats.rst index 8ad8b8a604..f795b9e84c 100644 --- a/docs/source/cpp_api/stats.rst +++ b/docs/source/cpp_api/stats.rst @@ -3,6 +3,12 @@ Stats This page provides C++ class references for the publicly-exposed elements of the stats package. +.. role:: py(code) + :language: c++ + :class: highlight + + .. doxygennamespace:: raft::stats :project: RAFT :members: + :content-only: diff --git a/docs/source/pylibraft_api.rst b/docs/source/pylibraft_api.rst index 4df0d9d01c..5c44c5f419 100644 --- a/docs/source/pylibraft_api.rst +++ b/docs/source/pylibraft_api.rst @@ -2,12 +2,13 @@ PyLibRAFT API Reference ~~~~~~~~~~~~~~~~~~~~~~~ -.. role:: py(code) - :language: python - :class: highlight +.. _api: +.. toctree:: + :maxdepth: 4 -Pairwise Distances -================== - -.. autofunction:: pylibraft.distance.pairwise_distance \ No newline at end of file + pylibraft_api/common.rst + pylibraft_api/cluster.rst + pylibraft_api/distance.rst + pylibraft_api/neighbors.rst + pylibraft_api/random.rst \ No newline at end of file diff --git a/docs/source/pylibraft_api/cluster.rst b/docs/source/pylibraft_api/cluster.rst new file mode 100644 index 0000000000..1a5aabf48a --- /dev/null +++ b/docs/source/pylibraft_api/cluster.rst @@ -0,0 +1,12 @@ +Cluster +======= + +This page provides pylibraft class references for the publicly-exposed elements of the `pylibraft.cluster` package. + +.. role:: py(code) + :language: python + :class: highlight + +.. autofunction:: pylibraft.cluster.compute_new_centroids + + diff --git a/docs/source/pylibraft_api/common.rst b/docs/source/pylibraft_api/common.rst new file mode 100644 index 0000000000..4070243b22 --- /dev/null +++ b/docs/source/pylibraft_api/common.rst @@ -0,0 +1,36 @@ +Common +====== + +This page provides `pylibraft` class references for the publicly-exposed elements of the `pylibraft.common` package. + + +.. role:: py(code) + :language: python + :class: highlight + + +Basic Vocabulary +################ + +.. autoclass:: pylibraft.common.Handle + :members: + +.. autoclass:: pylibraft.common.Stream + :members: + +.. autoclass:: pylibraft.common.device_ndarray + :members: + +Interruptible +############# + +.. autofunction:: pylibraft.common.interruptible.cuda_interruptible +.. autofunction:: pylibraft.common.interruptible.synchronize +.. autofunction:: pylibraft.common.interruptible.cuda_yield + + +CUDA Array Interface Helpers +############################ + +.. autoclass:: pylibraft.common.cai_wrapper + :members: diff --git a/docs/source/pylibraft_api/distance.rst b/docs/source/pylibraft_api/distance.rst new file mode 100644 index 0000000000..d14ed6fc08 --- /dev/null +++ b/docs/source/pylibraft_api/distance.rst @@ -0,0 +1,15 @@ +Distance +======== + +This page provides `pylibraft` class references for the publicly-exposed elements of the `pylibraft.distance` package. RAFT's +distances have been highly optimized and support a wide assortment of different distance measures. + + +.. role:: py(code) + :language: python + :class: highlight + +.. autofunction:: pylibraft.distance.pairwise_distance + +.. autofunction:: pylibraft.distance.fused_l2_nn_argmin + diff --git a/docs/source/pylibraft_api/neighbors.rst b/docs/source/pylibraft_api/neighbors.rst new file mode 100644 index 0000000000..7112a3878c --- /dev/null +++ b/docs/source/pylibraft_api/neighbors.rst @@ -0,0 +1,18 @@ +Neighbors +========= + +This page provides pylibraft class references for the publicly-exposed elements of the neighbors package. + +.. role:: py(code) + :language: python + :class: highlight + +.. autoclass:: pylibraft.neighbors.ivf_pq.IndexParams + +.. autofunction:: pylibraft.neighbors.ivf_pq.build + +.. autofunction:: pylibraft.neighbors.ivf_pq.extend + +.. autoclass:: pylibraft.neighbors.ivf_pq.SearchParams + +.. autofunction:: pylibraft.neighbors.ivf_pq.search diff --git a/docs/source/pylibraft_api/random.rst b/docs/source/pylibraft_api/random.rst new file mode 100644 index 0000000000..538d932757 --- /dev/null +++ b/docs/source/pylibraft_api/random.rst @@ -0,0 +1,12 @@ +Random +====== + +This page provides pylibraft class references for the publicly-exposed elements of the `pylibraft.random` package. + + +.. role:: py(code) + :language: python + :class: highlight + + +.. autofunction:: pylibraft.random.rmat \ No newline at end of file diff --git a/docs/source/quick_start.md b/docs/source/quick_start.md index 38ed031759..60071f2461 100644 --- a/docs/source/quick_start.md +++ b/docs/source/quick_start.md @@ -1,6 +1,6 @@ # Quick Start -This guide is meant to provide a quick-start tutorial for interacting with RAFT's C++ APIs. +This guide is meant to provide a quick-start tutorial for interacting with RAFT's C++ & Python APIs. ## RAPIDS Memory Manager (RMM) diff --git a/python/pylibraft/pylibraft/cluster/__init__.py b/python/pylibraft/pylibraft/cluster/__init__.py index 273b4497cc..89a403fce2 100644 --- a/python/pylibraft/pylibraft/cluster/__init__.py +++ b/python/pylibraft/pylibraft/cluster/__init__.py @@ -12,3 +12,5 @@ # See the License for the specific language governing permissions and # limitations under the License. # + +from .kmeans import compute_new_centroids diff --git a/python/pylibraft/pylibraft/distance/fused_l2_nn.pyx b/python/pylibraft/pylibraft/distance/fused_l2_nn.pyx index 32ee06e534..3f30e6d0a8 100644 --- a/python/pylibraft/pylibraft/distance/fused_l2_nn.pyx +++ b/python/pylibraft/pylibraft/distance/fused_l2_nn.pyx @@ -71,24 +71,20 @@ def fused_l2_nn_argmin(X, Y, out=None, sqrt=True, handle=None): Examples -------- - To compute the 1-nearest neighbors argmin: + .. code-block:: python import cupy as cp - from pylibraft.common import Handle from pylibraft.distance import fused_l2_nn_argmin - n_samples = 5000 n_clusters = 5 n_features = 50 - in1 = cp.random.random_sample((n_samples, n_features), dtype=cp.float32) in2 = cp.random.random_sample((n_clusters, n_features), dtype=cp.float32) - # A single RAFT handle can optionally be reused across # pylibraft functions. handle = Handle() @@ -101,23 +97,20 @@ def fused_l2_nn_argmin(X, Y, out=None, sqrt=True, handle=None): The output can also be computed in-place on a preallocated array: + .. code-block:: python import cupy as cp - from pylibraft.common import Handle from pylibraft.distance import fused_l2_nn_argmin - n_samples = 5000 n_clusters = 5 n_features = 50 - in1 = cp.random.random_sample((n_samples, n_features), dtype=cp.float32) in2 = cp.random.random_sample((n_clusters, n_features), dtype=cp.float32) output = cp.empty((n_samples, 1), dtype=cp.int32) - # A single RAFT handle can optionally be reused across # pylibraft functions. handle = Handle() diff --git a/python/pylibraft/pylibraft/distance/pairwise_distance.pyx b/python/pylibraft/pylibraft/distance/pairwise_distance.pyx index 7bdf52df99..76e70e3926 100644 --- a/python/pylibraft/pylibraft/distance/pairwise_distance.pyx +++ b/python/pylibraft/pylibraft/distance/pairwise_distance.pyx @@ -118,51 +118,63 @@ def distance(X, Y, out=None, metric="euclidean", p=2.0, handle=None): -------- To compute pairwise distances on cupy arrays: - >>> import cupy as cp - >>> from pylibraft.common import Handle - >>> from pylibraft.distance import pairwise_distance - >>> n_samples = 5000 - >>> n_features = 50 - >>> in1 = cp.random.random_sample((n_samples, n_features), + .. code-block:: python + + import cupy as cp + from pylibraft.common import Handle + from pylibraft.distance import pairwise_distance + n_samples = 5000 + n_features = 50 + in1 = cp.random.random_sample((n_samples, n_features), dtype=cp.float32) - >>> in2 = cp.random.random_sample((n_samples, n_features), + in2 = cp.random.random_sample((n_samples, n_features), dtype=cp.float32) A single RAFT handle can optionally be reused across pylibraft functions. - >>> handle = Handle() - >>> output = pairwise_distance(in1, in2, metric="euclidean", handle=handle) + .. code-block:: python + + handle = Handle() + output = pairwise_distance(in1, in2, metric="euclidean", handle=handle) pylibraft functions are often asynchronous so the handle needs to be explicitly synchronized - >>> handle.sync() + .. code-block:: python + + handle.sync() It's also possible to write to a pre-allocated output array: - >>> import cupy as cp - >>> from pylibraft.common import Handle - >>> from pylibraft.distance import pairwise_distance - >>> n_samples = 5000 - >>> n_features = 50 - >>> in1 = cp.random.random_sample((n_samples, n_features), + .. code-block:: python + + import cupy as cp + from pylibraft.common import Handle + from pylibraft.distance import pairwise_distance + n_samples = 5000 + n_features = 50 + in1 = cp.random.random_sample((n_samples, n_features), dtype=cp.float32) - >>> in2 = cp.random.random_sample((n_samples, n_features), + in2 = cp.random.random_sample((n_samples, n_features), dtype=cp.float32) - >>> output = cp.empty((n_samples, n_samples), dtype=cp.float32) + output = cp.empty((n_samples, n_samples), dtype=cp.float32) A single RAFT handle can optionally be reused across pylibraft functions. - >>> handle = Handle() - >>> pairwise_distance(in1, in2, out=output, + .. code-block:: python + + handle = Handle() + pairwise_distance(in1, in2, out=output, metric="euclidean", handle=handle) pylibraft functions are often asynchronous so the handle needs to be explicitly synchronized - >>> handle.sync() + .. code-block:: python + + handle.sync() """ x_cai = cai_wrapper(X)