From e8519035f0cd4f8b1355851ea5c80bc0c6f3787c Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Wed, 6 Mar 2024 19:28:08 -0500 Subject: [PATCH 01/25] Getting a start on the docs --- cpp/doxygen/Doxyfile | 1 + cpp/include/cuvs/core/c_api.h | 14 +++++++------- cpp/include/cuvs/neighbors/cagra.h | 18 +++++++++--------- docs/source/api_docs.rst | 11 +++++++++++ docs/source/c_api.rst | 6 +++--- docs/source/c_api/core_c_api.rst | 9 +++++---- docs/source/c_api/neighbors_cagra_c.rst | 9 +++++---- docs/source/cpp_api.rst | 6 +++--- docs/source/cpp_api/core_interop.rst | 1 - docs/source/cpp_api/neighbors.rst | 6 ++---- docs/source/cpp_api/neighbors_cagra.rst | 4 +--- docs/source/index.rst | 3 +-- docs/source/python_api.rst | 6 +++--- docs/source/rust_api.rst | 8 ++++++++ docs/source/sphinxext/github_link.py | 2 +- 15 files changed, 60 insertions(+), 44 deletions(-) create mode 100644 docs/source/api_docs.rst create mode 100644 docs/source/rust_api.rst diff --git a/cpp/doxygen/Doxyfile b/cpp/doxygen/Doxyfile index 94304afe0..faa31c25d 100644 --- a/cpp/doxygen/Doxyfile +++ b/cpp/doxygen/Doxyfile @@ -864,6 +864,7 @@ INPUT_ENCODING = UTF-8 # *.vhdl, *.ucf, *.qsf and *.ice. FILE_PATTERNS = *.hpp \ + *.h \ *.cuh # The RECURSIVE tag can be used to specify whether or not subdirectories should diff --git a/cpp/include/cuvs/core/c_api.h b/cpp/include/cuvs/core/c_api.h index eceb917ff..3d854fcec 100644 --- a/cpp/include/cuvs/core/c_api.h +++ b/cpp/include/cuvs/core/c_api.h @@ -16,19 +16,18 @@ #pragma once +#include #include -#include +#ifdef __cplusplus +extern "C" { +#endif /** * @defgroup c_api C API Core Types and Functions * @{ */ -#ifdef __cplusplus -extern "C" { -#endif - /** * @brief An opaque C handle for C++ type `raft::resources` * @@ -77,8 +76,9 @@ const char* cuvsGetLastErrorText(); * clears any previously seen error message. */ void cuvsSetLastErrorText(const char* error); + +/** @} */ + #ifdef __cplusplus } #endif - -/** @} */ diff --git a/cpp/include/cuvs/neighbors/cagra.h b/cpp/include/cuvs/neighbors/cagra.h index 64a26b924..d0b239062 100644 --- a/cpp/include/cuvs/neighbors/cagra.h +++ b/cpp/include/cuvs/neighbors/cagra.h @@ -20,15 +20,15 @@ #include #include +#ifdef __cplusplus +extern "C" { +#endif + /** * @defgroup cagra_c C API for CUDA ANN Graph-based nearest neighbor search * @{ */ -#ifdef __cplusplus -extern "C" { -#endif - /** * @brief Enum to denote which ANN algorithm is used to build CAGRA graph * @@ -71,7 +71,7 @@ cuvsError_t cuvsCagraIndexParamsCreate(cuvsCagraIndexParams_t* params); * @param[in] params * @return cuvsError_t */ -cuvsError_t cuvsCagraIndexParamsDestroy(cuvsCagraIndexParams_t index); +cuvsError_t cuvsCagraIndexParamsDestroy(cuvsCagraIndexParams_t params); /** * @brief Enum to denote algorithm used to search CAGRA Index @@ -281,10 +281,10 @@ cuvsError_t cuvsCagraSearch(cuvsResources_t res, DLManagedTensor* neighbors, DLManagedTensor* distances); -#ifdef __cplusplus -} -#endif - /** * @} */ + +#ifdef __cplusplus +} +#endif diff --git a/docs/source/api_docs.rst b/docs/source/api_docs.rst new file mode 100644 index 000000000..2a5a867e0 --- /dev/null +++ b/docs/source/api_docs.rst @@ -0,0 +1,11 @@ +API Documentation +================= + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + c_api.rst + cpp_api.rst + python_api.rst + rust_api.rst diff --git a/docs/source/c_api.rst b/docs/source/c_api.rst index 4daaa84df..2a7bcf512 100644 --- a/docs/source/c_api.rst +++ b/docs/source/c_api.rst @@ -1,6 +1,6 @@ -~~~~~ -C API -~~~~~ +~~~~~~~~~~~~~~~~~~~ +C API Documentation +~~~~~~~~~~~~~~~~~~~ .. _api: diff --git a/docs/source/c_api/core_c_api.rst b/docs/source/c_api/core_c_api.rst index e0060bd5d..9cbaaa5f5 100644 --- a/docs/source/c_api/core_c_api.rst +++ b/docs/source/c_api/core_c_api.rst @@ -1,14 +1,15 @@ -C-API -===== +Core Routines +============= + + .. role:: py(code) :language: c :class: highlight - ``#include `` .. doxygengroup:: c_api - :project: RAFT + :project: cuvs :members: :content-only: diff --git a/docs/source/c_api/neighbors_cagra_c.rst b/docs/source/c_api/neighbors_cagra_c.rst index d4b7b0bf2..0a2bb3830 100644 --- a/docs/source/c_api/neighbors_cagra_c.rst +++ b/docs/source/c_api/neighbors_cagra_c.rst @@ -1,7 +1,8 @@ -CAGRA C-API -=========== +CAGRA +===== + +CAGRA is a graph-based nearest neighbors algorithm that was built from the ground up for GPU acceleration. CAGRA demonstrates state-of-the art index build and query performance for both small- and large-batch sized search. -CAGRA is a graph-based nearest neighbors implementation with state-of-the art query performance for both small- and large-batch sized search. .. role:: py(code) :language: c @@ -10,6 +11,6 @@ CAGRA is a graph-based nearest neighbors implementation with state-of-the art qu ``#include `` .. doxygengroup:: cagra_c - :project: RAFT + :project: cuvs :members: :content-only: diff --git a/docs/source/cpp_api.rst b/docs/source/cpp_api.rst index 1916abde1..67bc7f65b 100644 --- a/docs/source/cpp_api.rst +++ b/docs/source/cpp_api.rst @@ -1,6 +1,6 @@ -~~~~~~~ -C++ API -~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~ +C++ API Documentation +~~~~~~~~~~~~~~~~~~~~~ .. _api: diff --git a/docs/source/cpp_api/core_interop.rst b/docs/source/cpp_api/core_interop.rst index b2ef05f27..a8fcb2890 100644 --- a/docs/source/cpp_api/core_interop.rst +++ b/docs/source/cpp_api/core_interop.rst @@ -5,7 +5,6 @@ Interop :language: c++ :class: highlight - ``#include `` namespace *cuvs::core* diff --git a/docs/source/cpp_api/neighbors.rst b/docs/source/cpp_api/neighbors.rst index 6ba001444..61898cec8 100644 --- a/docs/source/cpp_api/neighbors.rst +++ b/docs/source/cpp_api/neighbors.rst @@ -1,7 +1,5 @@ -Neighbors -========= - -This page provides C++ class references for the publicly-exposed elements of the neighbors package. +Nearest Neighbors +================= .. role:: py(code) :language: c++ diff --git a/docs/source/cpp_api/neighbors_cagra.rst b/docs/source/cpp_api/neighbors_cagra.rst index 65fdcb2bc..439d11b7a 100644 --- a/docs/source/cpp_api/neighbors_cagra.rst +++ b/docs/source/cpp_api/neighbors_cagra.rst @@ -1,9 +1,7 @@ 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. +CAGRA is a graph-based nearest neighbors algorithm that was built from the ground up for GPU acceleration. CAGRA demonstrates state-of-the art index build and query performance for both small- and large-batch sized search. .. role:: py(code) :language: c++ diff --git a/docs/source/index.rst b/docs/source/index.rst index bf9790610..bbb6f93f2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -23,8 +23,7 @@ cuVS is a library for vector search and clustering on the GPU. quick_start.md build.md - cpp_api.rst - python_api.rst + api_docs.rst developer_guide.md contributing.md diff --git a/docs/source/python_api.rst b/docs/source/python_api.rst index fba4d96ba..05b509132 100644 --- a/docs/source/python_api.rst +++ b/docs/source/python_api.rst @@ -1,6 +1,6 @@ -~~~~~~~~~~ -Python API -~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~ +Python API Documentation +~~~~~~~~~~~~~~~~~~~~~~~~ .. _api: diff --git a/docs/source/rust_api.rst b/docs/source/rust_api.rst new file mode 100644 index 000000000..254136e3a --- /dev/null +++ b/docs/source/rust_api.rst @@ -0,0 +1,8 @@ +~~~~~~~~~~~~~~~~~~~~~~ +Rust API Documentation +~~~~~~~~~~~~~~~~~~~~~~ + +.. _api: + +.. toctree:: + :maxdepth: 4 diff --git a/docs/source/sphinxext/github_link.py b/docs/source/sphinxext/github_link.py index a7a46fdd9..2c52488ca 100644 --- a/docs/source/sphinxext/github_link.py +++ b/docs/source/sphinxext/github_link.py @@ -96,7 +96,7 @@ def _linkcode_resolve(domain, info, package, url_fmt, revision): # fn is expected to be the absolute path. fn = os.path.relpath(source_file, start=package) print("{}:{}".format( - os.path.abspath(os.path.join("..", "python", "cuml", fn)), + os.path.abspath(os.path.join("..", "python", "cuvs", fn)), lineno)) else: return From 73fa0c8977d8eb1108126c5b8598f722baebf256 Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Thu, 7 Mar 2024 13:59:28 -0500 Subject: [PATCH 02/25] Progress --- docs/source/c_api.rst | 2 +- docs/source/c_api/neighbors.rst | 12 +++++++++++ docs/source/cpp_api/neighbors_cagra.rst | 12 ----------- docs/source/python_api.rst | 2 ++ docs/source/python_api/neighbors.rst | 12 +++++++++++ docs/source/python_api/neighbors_cagra.rst | 24 ++++++++++++++++++++++ 6 files changed, 51 insertions(+), 13 deletions(-) create mode 100644 docs/source/c_api/neighbors.rst create mode 100644 docs/source/python_api/neighbors.rst create mode 100644 docs/source/python_api/neighbors_cagra.rst diff --git a/docs/source/c_api.rst b/docs/source/c_api.rst index 2a7bcf512..3359a5dbe 100644 --- a/docs/source/c_api.rst +++ b/docs/source/c_api.rst @@ -8,4 +8,4 @@ C API Documentation :maxdepth: 4 c_api/core_c_api.rst - c_api/neighbors_cagra_c.rst + c_api/neighbors.rst diff --git a/docs/source/c_api/neighbors.rst b/docs/source/c_api/neighbors.rst new file mode 100644 index 000000000..6ab4b1c61 --- /dev/null +++ b/docs/source/c_api/neighbors.rst @@ -0,0 +1,12 @@ +Nearest Neighbors +================= + +.. role:: py(code) + :language: c + :class: highlight + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + neighbors_cagra_c.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 index 439d11b7a..1cdad7b8d 100644 --- a/docs/source/cpp_api/neighbors_cagra.rst +++ b/docs/source/cpp_api/neighbors_cagra.rst @@ -15,15 +15,3 @@ namespace *cuvs::neighbors::cagra* :project: cuvs :members: :content-only: - - -Serializer Methods ------------------- -``#include `` - -namespace *cuvs::neighbors::cagra* - -.. doxygengroup:: cagra_serialize - :project: cuvs - :members: - :content-only: diff --git a/docs/source/python_api.rst b/docs/source/python_api.rst index 05b509132..999c40fd3 100644 --- a/docs/source/python_api.rst +++ b/docs/source/python_api.rst @@ -6,3 +6,5 @@ Python API Documentation .. toctree:: :maxdepth: 4 + + python_api/neighbors.rst \ No newline at end of file diff --git a/docs/source/python_api/neighbors.rst b/docs/source/python_api/neighbors.rst new file mode 100644 index 000000000..14e907002 --- /dev/null +++ b/docs/source/python_api/neighbors.rst @@ -0,0 +1,12 @@ +Nearest Neighbors +================= + +.. role:: py(code) + :language: python + :class: highlight + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + neighbors_cagra.rst \ No newline at end of file diff --git a/docs/source/python_api/neighbors_cagra.rst b/docs/source/python_api/neighbors_cagra.rst new file mode 100644 index 000000000..8525819ac --- /dev/null +++ b/docs/source/python_api/neighbors_cagra.rst @@ -0,0 +1,24 @@ +CAGRA +===== + +CAGRA is a graph-based nearest neighbors algorithm that was built from the ground up for GPU acceleration. CAGRA demonstrates state-of-the art index build and query performance for both small- and large-batch sized search. + +.. role:: py(code) + :language: python + :class: highlight + +Index configuration parameters +------------------------------ + +.. autoclass:: cuvs.neighbors.cagra.IndexParams + :members: + +.. autoclass:: cuvs.neighbors.cagra.SearchParams + :members: + +Index build and search +---------------------- + +.. autofunction:: cuvs.neighbors.cagra.build_index + +.. autofunction:: cuvs.neighbors.cagra.search \ No newline at end of file From 8e4838237e4909a5567ee3b434e3b475df031005 Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Thu, 7 Mar 2024 17:45:26 -0500 Subject: [PATCH 03/25] Getting CAGRA C++ docs to build --- cpp/include/cuvs/neighbors/cagra.h | 37 +++- cpp/include/cuvs/neighbors/cagra.hpp | 241 +++++++++++++++++------- docs/source/c_api/neighbors.rst | 2 + docs/source/c_api/neighbors_cagra_c.rst | 39 +++- docs/source/cpp_api/neighbors_cagra.rst | 38 +++- 5 files changed, 288 insertions(+), 69 deletions(-) diff --git a/cpp/include/cuvs/neighbors/cagra.h b/cpp/include/cuvs/neighbors/cagra.h index d0b239062..ae8f8ea01 100644 --- a/cpp/include/cuvs/neighbors/cagra.h +++ b/cpp/include/cuvs/neighbors/cagra.h @@ -25,7 +25,7 @@ extern "C" { #endif /** - * @defgroup cagra_c C API for CUDA ANN Graph-based nearest neighbor search + * @defgroup cagra_c_index_params C API for CUDA ANN Graph-based nearest neighbor search * @{ */ @@ -73,6 +73,15 @@ cuvsError_t cuvsCagraIndexParamsCreate(cuvsCagraIndexParams_t* params); */ cuvsError_t cuvsCagraIndexParamsDestroy(cuvsCagraIndexParams_t params); +/** + * @} + */ + +/** + * @defgroup cagra_c_search_params C API for CUDA ANN Graph-based nearest neighbor search + * @{ + */ + /** * @brief Enum to denote algorithm used to search CAGRA Index * @@ -158,6 +167,15 @@ cuvsError_t cuvsCagraSearchParamsCreate(cuvsCagraSearchParams_t* params); */ cuvsError_t cuvsCagraSearchParamsDestroy(cuvsCagraSearchParams_t params); +/** + * @} + */ + +/** + * @defgroup cagra_c_index C API for CUDA ANN Graph-based nearest neighbor search + * @{ + */ + /** * @brief Struct to hold address of cuvs::neighbors::cagra::index and its active trained dtype * @@ -185,6 +203,15 @@ cuvsError_t cuvsCagraIndexCreate(cuvsCagraIndex_t* index); */ cuvsError_t cuvsCagraIndexDestroy(cuvsCagraIndex_t index); +/** + * @} + */ + +/** + * @defgroup cagra_c_index_build C API for CUDA ANN Graph-based nearest neighbor search + * @{ + */ + /** * @brief Build a CAGRA index with a `DLManagedTensor` which has underlying * `DLDeviceType` equal to `kDLCUDA`, `kDLCUDAHost`, `kDLCUDAManaged`, @@ -232,6 +259,14 @@ cuvsError_t cuvsCagraBuild(cuvsResources_t res, DLManagedTensor* dataset, cuvsCagraIndex_t index); +/** + * @} + */ + +/** + * @defgroup cagra_c_index_search C API for CUDA ANN Graph-based nearest neighbor search + * @{ + */ /** * @brief Search a CAGRA index with a `DLManagedTensor` which has underlying * `DLDeviceType` equal to `kDLCUDA`, `kDLCUDAHost`, `kDLCUDAManaged`. diff --git a/cpp/include/cuvs/neighbors/cagra.hpp b/cpp/include/cuvs/neighbors/cagra.hpp index 3a0c60b78..0f2919ff4 100644 --- a/cpp/include/cuvs/neighbors/cagra.hpp +++ b/cpp/include/cuvs/neighbors/cagra.hpp @@ -27,7 +27,7 @@ namespace cuvs::neighbors::cagra { /** - * @addtogroup cagra + * @defgroup cagra_cpp_index_params CAGRA index build parameters * @{ */ @@ -68,6 +68,15 @@ struct index_params : ann::index_params { } }; +/** + * @} + */ + +/** + * @defgroup cagra_cpp_search_params CAGRA index search parameters + * @{ + */ + enum class search_algo { /** For large batch sizes. */ SINGLE_CTA, @@ -144,9 +153,17 @@ struct search_params : ann::search_params { } }; +/** + * @} + */ static_assert(std::is_aggregate_v); static_assert(std::is_aggregate_v); +/** + * @defgroup cagra_cpp_index CAGRA index type + * @{ + */ + /** * @brief CAGRA index. * @@ -344,70 +361,162 @@ struct index : ann::index { std::unique_ptr> raft_index_; }; -// Using device and host_matrix_view avoids needing to typedef multiple mdspans based on accessors -#define CUVS_INST_CAGRA_FUNCS(T, IdxT) \ - auto build(raft::resources const& handle, \ - const cuvs::neighbors::cagra::index_params& params, \ - raft::device_matrix_view dataset) \ - ->cuvs::neighbors::cagra::index; \ - \ - auto build(raft::resources const& handle, \ - const cuvs::neighbors::cagra::index_params& params, \ - raft::host_matrix_view dataset) \ - ->cuvs::neighbors::cagra::index; \ - \ - void build_device(raft::resources const& handle, \ - const cuvs::neighbors::cagra::index_params& params, \ - raft::device_matrix_view dataset, \ - cuvs::neighbors::cagra::index& idx); \ - \ - void build_host(raft::resources const& handle, \ - const cuvs::neighbors::cagra::index_params& params, \ - raft::host_matrix_view dataset, \ - cuvs::neighbors::cagra::index& idx); \ - \ - void search(raft::resources const& handle, \ - cuvs::neighbors::cagra::search_params const& params, \ - const cuvs::neighbors::cagra::index& index, \ - raft::device_matrix_view queries, \ - raft::device_matrix_view neighbors, \ - raft::device_matrix_view distances); \ - void serialize_file(raft::resources const& handle, \ - const std::string& filename, \ - const cuvs::neighbors::cagra::index& index, \ - bool include_dataset = true); \ - \ - void deserialize_file(raft::resources const& handle, \ - const std::string& filename, \ - cuvs::neighbors::cagra::index* index); \ - void serialize(raft::resources const& handle, \ - std::string& str, \ - const cuvs::neighbors::cagra::index& index, \ - bool include_dataset = true); \ - \ - void deserialize(raft::resources const& handle, \ - const std::string& str, \ - cuvs::neighbors::cagra::index* index); - -CUVS_INST_CAGRA_FUNCS(float, uint32_t); -CUVS_INST_CAGRA_FUNCS(int8_t, uint32_t); -CUVS_INST_CAGRA_FUNCS(uint8_t, uint32_t); - -#undef CUVS_INST_CAGRA_FUNCS - -#define CUVS_INST_CAGRA_OPTIMIZE(IdxT) \ - void optimize_device(raft::resources const& res, \ - raft::device_matrix_view knn_graph, \ - raft::host_matrix_view new_graph); \ - \ - void optimize_host(raft::resources const& res, \ - raft::host_matrix_view knn_graph, \ - raft::host_matrix_view new_graph); - -CUVS_INST_CAGRA_OPTIMIZE(uint32_t); - -#undef CUVS_INST_CAGRA_OPTIMIZE - -/** @} */ +/** + * @} + */ + +/** + * @defgroup cagra_cpp_index_build CAGRA index build functions + * @{ + */ +auto build(raft::resources const& handle, + const cuvs::neighbors::cagra::index_params& params, + raft::device_matrix_view dataset) + -> cuvs::neighbors::cagra::index; + +auto build(raft::resources const& handle, + const cuvs::neighbors::cagra::index_params& params, + raft::host_matrix_view dataset) + -> cuvs::neighbors::cagra::index; + +auto build(raft::resources const& handle, + const cuvs::neighbors::cagra::index_params& params, + raft::device_matrix_view dataset) + -> cuvs::neighbors::cagra::index; + +auto build(raft::resources const& handle, + const cuvs::neighbors::cagra::index_params& params, + raft::host_matrix_view dataset) + -> cuvs::neighbors::cagra::index; + +auto build(raft::resources const& handle, + const cuvs::neighbors::cagra::index_params& params, + raft::device_matrix_view dataset) + -> cuvs::neighbors::cagra::index; + +auto build(raft::resources const& handle, + const cuvs::neighbors::cagra::index_params& params, + raft::host_matrix_view dataset) + -> cuvs::neighbors::cagra::index; +/** + * @} + */ + +void build_device(raft::resources const& handle, + const cuvs::neighbors::cagra::index_params& params, + raft::device_matrix_view dataset, + cuvs::neighbors::cagra::index& idx); + +void build_host(raft::resources const& handle, + const cuvs::neighbors::cagra::index_params& params, + raft::host_matrix_view dataset, + cuvs::neighbors::cagra::index& idx); + +void build_device(raft::resources const& handle, + const cuvs::neighbors::cagra::index_params& params, + raft::device_matrix_view dataset, + cuvs::neighbors::cagra::index& idx); + +void build_host(raft::resources const& handle, + const cuvs::neighbors::cagra::index_params& params, + raft::host_matrix_view dataset, + cuvs::neighbors::cagra::index& idx); + +void build_device(raft::resources const& handle, + const cuvs::neighbors::cagra::index_params& params, + raft::device_matrix_view dataset, + cuvs::neighbors::cagra::index& idx); + +void build_host(raft::resources const& handle, + const cuvs::neighbors::cagra::index_params& params, + raft::host_matrix_view dataset, + cuvs::neighbors::cagra::index& idx); + +/** + * @defgroup cagra_cpp_index_search CAGRA search functions + * @{ + */ + +void search(raft::resources const& handle, + cuvs::neighbors::cagra::search_params const& params, + const cuvs::neighbors::cagra::index& index, + raft::device_matrix_view queries, + raft::device_matrix_view neighbors, + raft::device_matrix_view distances); + +void search(raft::resources const& handle, + cuvs::neighbors::cagra::search_params const& params, + const cuvs::neighbors::cagra::index& index, + raft::device_matrix_view queries, + raft::device_matrix_view neighbors, + raft::device_matrix_view distances); + +void search(raft::resources const& handle, + cuvs::neighbors::cagra::search_params const& params, + const cuvs::neighbors::cagra::index& index, + raft::device_matrix_view queries, + raft::device_matrix_view neighbors, + raft::device_matrix_view distances); +/** + * @} + */ + +/** + * @defgroup cagra_cpp_serialize CAGRA serialize functions + * @{ + */ +void serialize_file(raft::resources const& handle, + const std::string& filename, + const cuvs::neighbors::cagra::index& index, + bool include_dataset = true); + +void deserialize_file(raft::resources const& handle, + const std::string& filename, + cuvs::neighbors::cagra::index* index); +void serialize(raft::resources const& handle, + std::string& str, + const cuvs::neighbors::cagra::index& index, + bool include_dataset = true); + +void deserialize(raft::resources const& handle, + const std::string& str, + cuvs::neighbors::cagra::index* index); + +void serialize_file(raft::resources const& handle, + const std::string& filename, + const cuvs::neighbors::cagra::index& index, + bool include_dataset = true); + +void deserialize_file(raft::resources const& handle, + const std::string& filename, + cuvs::neighbors::cagra::index* index); +void serialize(raft::resources const& handle, + std::string& str, + const cuvs::neighbors::cagra::index& index, + bool include_dataset = true); + +void deserialize(raft::resources const& handle, + const std::string& str, + cuvs::neighbors::cagra::index* index); + +void serialize_file(raft::resources const& handle, + const std::string& filename, + const cuvs::neighbors::cagra::index& index, + bool include_dataset = true); + +void deserialize_file(raft::resources const& handle, + const std::string& filename, + cuvs::neighbors::cagra::index* index); +void serialize(raft::resources const& handle, + std::string& str, + const cuvs::neighbors::cagra::index& index, + bool include_dataset = true); + +void deserialize(raft::resources const& handle, + const std::string& str, + cuvs::neighbors::cagra::index* index); +/** + * @} + */ } // namespace cuvs::neighbors::cagra diff --git a/docs/source/c_api/neighbors.rst b/docs/source/c_api/neighbors.rst index 6ab4b1c61..6bbd3cc7f 100644 --- a/docs/source/c_api/neighbors.rst +++ b/docs/source/c_api/neighbors.rst @@ -9,4 +9,6 @@ Nearest Neighbors :maxdepth: 2 :caption: Contents: + + neighbors_cagra_c.rst \ No newline at end of file diff --git a/docs/source/c_api/neighbors_cagra_c.rst b/docs/source/c_api/neighbors_cagra_c.rst index 0a2bb3830..eb40d5578 100644 --- a/docs/source/c_api/neighbors_cagra_c.rst +++ b/docs/source/c_api/neighbors_cagra_c.rst @@ -10,7 +10,44 @@ CAGRA is a graph-based nearest neighbors algorithm that was built from the groun ``#include `` -.. doxygengroup:: cagra_c +Index build parameters +---------------------- + +.. doxygengroup:: cagra_c_index_params + :project: cuvs + :members: + :content-only: + +Index search parameters +----------------------- + +.. doxygengroup:: cagra_c_search_params :project: cuvs :members: :content-only: + +Index +----- + +.. doxygengroup:: cagra_c_index + :project: cuvs + :members: + :content-only: + +Index build +----------- + +.. doxygengroup:: cagra_c_index_build + :project: cuvs + :members: + :content-only: + +Index search +------------ + +.. doxygengroup:: cagra_c_index_search + :project: cuvs + :members: + :content-only: + + diff --git a/docs/source/cpp_api/neighbors_cagra.rst b/docs/source/cpp_api/neighbors_cagra.rst index 1cdad7b8d..aed843dad 100644 --- a/docs/source/cpp_api/neighbors_cagra.rst +++ b/docs/source/cpp_api/neighbors_cagra.rst @@ -11,7 +11,43 @@ CAGRA is a graph-based nearest neighbors algorithm that was built from the groun namespace *cuvs::neighbors::cagra* -.. doxygengroup:: cagra +Index build parameters +---------------------- + +.. doxygengroup:: cagra_cpp_index_params + :project: cuvs + :members: + :content-only: + +Index search parameters +----------------------- + +.. doxygengroup:: cagra_cpp_search_params + :project: cuvs + :members: + :content-only: + +Index +----- + +.. doxygengroup:: cagra_cpp_index :project: cuvs :members: :content-only: + +Index build +----------- + +.. doxygengroup:: cagra_cpp_index_build + :project: cuvs + :members: + :content-only: + +Index search +------------ + +.. doxygengroup:: cagra_cpp_index_search + :project: cuvs + :members: + :content-only: + From ca465e67ac95fc0dfb7934127907c3ad5f727c34 Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Fri, 8 Mar 2024 12:20:55 -0500 Subject: [PATCH 04/25] Updating --- cpp/include/cuvs/core/c_api.h | 40 +++++++++++++--------- docs/source/c_api/core_c_api.rst | 15 ++++++-- docs/source/python_api/neighbors_cagra.rst | 22 +++++++++--- 3 files changed, 52 insertions(+), 25 deletions(-) diff --git a/cpp/include/cuvs/core/c_api.h b/cpp/include/cuvs/core/c_api.h index 3d854fcec..a15d7cd5c 100644 --- a/cpp/include/cuvs/core/c_api.h +++ b/cpp/include/cuvs/core/c_api.h @@ -24,21 +24,38 @@ extern "C" { #endif /** - * @defgroup c_api C API Core Types and Functions + * @defgroup error_c cuVS Error Messages * @{ */ - /** - * @brief An opaque C handle for C++ type `raft::resources` + * @brief An enum denoting return values for function calls * */ -typedef uintptr_t cuvsResources_t; +typedef enum { CUVS_ERROR, CUVS_SUCCESS } cuvsError_t; + +/** @brief Returns a string describing the last seen error on this thread, or + * NULL if the last function succeeded. + */ +const char* cuvsGetLastErrorText(); /** - * @brief An enum denoting return values for function calls + * @brief Sets a string describing an error seen on the thread. Passing NULL + * clears any previously seen error message. + */ +void cuvsSetLastErrorText(const char* error); + +/** @} */ + +/** + * @defgroup resources_c cuVS Resources Handle + * @{ + */ + +/** + * @brief An opaque C handle for C++ type `raft::resources` * */ -typedef enum { CUVS_ERROR, CUVS_SUCCESS } cuvsError_t; +typedef uintptr_t cuvsResources_t; /** * @brief Create an Initialized opaque C handle for C++ type `raft::resources` @@ -66,17 +83,6 @@ cuvsError_t cuvsResourcesDestroy(cuvsResources_t res); */ cuvsError_t cuvsStreamSet(cuvsResources_t res, cudaStream_t stream); -/** @brief Returns a string describing the last seen error on this thread, or - * NULL if the last function succeeded. - */ -const char* cuvsGetLastErrorText(); - -/** - * @brief Sets a string describing an error seen on the thread. Passing NULL - * clears any previously seen error message. - */ -void cuvsSetLastErrorText(const char* error); - /** @} */ #ifdef __cplusplus diff --git a/docs/source/c_api/core_c_api.rst b/docs/source/c_api/core_c_api.rst index 9cbaaa5f5..e2796700f 100644 --- a/docs/source/c_api/core_c_api.rst +++ b/docs/source/c_api/core_c_api.rst @@ -1,15 +1,24 @@ Core Routines ============= - - .. role:: py(code) :language: c :class: highlight ``#include `` -.. doxygengroup:: c_api +Resources Handle +---------------- + +.. doxygengroup:: resources_c + :project: cuvs + :members: + :content-only: + +Error Handling +-------------- + +.. doxygengroup:: error_c :project: cuvs :members: :content-only: diff --git a/docs/source/python_api/neighbors_cagra.rst b/docs/source/python_api/neighbors_cagra.rst index 8525819ac..d93a57cc2 100644 --- a/docs/source/python_api/neighbors_cagra.rst +++ b/docs/source/python_api/neighbors_cagra.rst @@ -7,18 +7,30 @@ CAGRA is a graph-based nearest neighbors algorithm that was built from the groun :language: python :class: highlight -Index configuration parameters ------------------------------- +Index build parameters +---------------------- .. autoclass:: cuvs.neighbors.cagra.IndexParams :members: +Index search parameters +----------------------- + .. autoclass:: cuvs.neighbors.cagra.SearchParams :members: -Index build and search ----------------------- +Index +----- + +.. autoclass:: cuvs.neighbors.cagra.Index + :members: + +Index build +----------- .. autofunction:: cuvs.neighbors.cagra.build_index -.. autofunction:: cuvs.neighbors.cagra.search \ No newline at end of file +Index search +------------ + +.. autofunction:: cuvs.neighbors.cagra.search From 58743b50b39f8a6a4b9527f6ff30f70378a7077a Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Fri, 8 Mar 2024 12:58:03 -0500 Subject: [PATCH 05/25] Checking in --- docs/source/conf.py | 8 ++++---- docs/source/python_api/neighbors_cagra.rst | 10 +++++----- python/cuvs/cuvs/neighbors/cagra/cagra.pyx | 7 +++++++ 3 files changed, 16 insertions(+), 9 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 1a5c9dfe8..1089f6a5c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -23,11 +23,11 @@ # ones. extensions = [ "numpydoc", + "sphinx.ext.linkcode", "sphinx.ext.autodoc", "sphinx.ext.autosummary", "sphinx.ext.doctest", "sphinx.ext.intersphinx", - "sphinx.ext.linkcode", "IPython.sphinxext.ipython_console_highlighting", "IPython.sphinxext.ipython_directive", "breathe", @@ -59,7 +59,7 @@ # General information about the project. project = "cuvs" -copyright = "2023, NVIDIA Corporation" +copyright = "2024, NVIDIA Corporation" author = "NVIDIA Corporation" # The version info for the project you're documenting, acts as replacement for @@ -193,8 +193,8 @@ def setup(app): # The following is used by sphinx.ext.linkcode to provide links to github linkcode_resolve = make_linkcode_resolve( "cuvs", - "https://github.com/rapidsai/cuvs" - "cuvs/blob/{revision}/python/cuvs" + "https://github.com/rapidsai/cuvs/" + "blob/{revision}/python/cuvs/cuvs/" "{package}/{path}#L{lineno}", ) diff --git a/docs/source/python_api/neighbors_cagra.rst b/docs/source/python_api/neighbors_cagra.rst index d93a57cc2..6f64f7763 100644 --- a/docs/source/python_api/neighbors_cagra.rst +++ b/docs/source/python_api/neighbors_cagra.rst @@ -8,29 +8,29 @@ CAGRA is a graph-based nearest neighbors algorithm that was built from the groun :class: highlight Index build parameters ----------------------- +###################### .. autoclass:: cuvs.neighbors.cagra.IndexParams :members: Index search parameters ------------------------ +####################### .. autoclass:: cuvs.neighbors.cagra.SearchParams :members: Index ------ +##### .. autoclass:: cuvs.neighbors.cagra.Index :members: Index build ------------ +########### .. autofunction:: cuvs.neighbors.cagra.build_index Index search ------------- +############ .. autofunction:: cuvs.neighbors.cagra.search diff --git a/python/cuvs/cuvs/neighbors/cagra/cagra.pyx b/python/cuvs/cuvs/neighbors/cagra/cagra.pyx index 04031414e..d64ac72ee 100644 --- a/python/cuvs/cuvs/neighbors/cagra/cagra.pyx +++ b/python/cuvs/cuvs/neighbors/cagra/cagra.pyx @@ -77,6 +77,7 @@ cdef class IndexParams: building the knn graph. It is expected to be generally faster than ivf_pq. """ + cdef cuvsCagraIndexParams* params def __init__(self, *, @@ -122,6 +123,11 @@ cdef class IndexParams: cdef class Index: + """ + CAGRA index object. This object stores the trained CAGRA index state + which can be used to perform nearest neighbors searches. + """ + cdef cuvsCagraIndex_t index cdef bool trained @@ -268,6 +274,7 @@ cdef class SearchParams: rand_xor_mask: int, default = 0x128394 Bit mask used for initial random seed node selection. """ + cdef cuvsCagraSearchParams params def __init__(self, *, From d2dd4cc173185d0c7330360b00ec7858141c16b5 Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Fri, 8 Mar 2024 16:21:28 -0500 Subject: [PATCH 06/25] New docs --- docs/source/build.md | 312 +++++------------- {cpp/examples => examples/cpp}/CMakeLists.txt | 0 {cpp/examples => examples/cpp}/README.md | 5 +- {cpp/examples => examples/cpp}/build.sh | 0 .../cpp}/cmake/thirdparty/fetch_rapids.cmake | 0 .../cpp}/cmake/thirdparty/get_cuvs.cmake | 0 .../cpp}/src/cagra_example.cu | 0 {cpp/examples => examples/cpp}/src/common.cuh | 0 8 files changed, 91 insertions(+), 226 deletions(-) rename {cpp/examples => examples/cpp}/CMakeLists.txt (100%) rename {cpp/examples => examples/cpp}/README.md (93%) rename {cpp/examples => examples/cpp}/build.sh (100%) rename {cpp/examples => examples/cpp}/cmake/thirdparty/fetch_rapids.cmake (100%) rename {cpp/examples => examples/cpp}/cmake/thirdparty/get_cuvs.cmake (100%) rename {cpp/examples => examples/cpp}/src/cagra_example.cu (100%) rename {cpp/examples => examples/cpp}/src/common.cuh (100%) diff --git a/docs/source/build.md b/docs/source/build.md index 31de69b46..939f1db34 100644 --- a/docs/source/build.md +++ b/docs/source/build.md @@ -1,318 +1,184 @@ -# Installation +**# Installation -RAFT currently provides libraries for C++ and Python. The C++ libraries, including the header-only and optional shared library, can be installed with Conda. +The cuVS software development kit provides APIs for C, C++, Python, and Rust languages. These Both the C++ and Python APIs require CMake to build from source. ## Table of Contents -- [Install C++ and Python through Conda](#installing-c-and-python-through-conda) -- [Installing Python through Pip](#installing-python-through-pip) -- [Building C++ and Python from source](#building-c-and-python-from-source) - - [CUDA/GPU requirements](#cudagpu-requirements) - - [Build dependencies](#build-dependencies) - - [Required](#required) - - [Optional](#optional) - - [Conda environment scripts](#conda-environment-scripts) - - [Header-only C++](#header-only-c) - - [C++ shared library](#c-shared-library-optional) - - [ccache and sccache](#ccache-and-sccache) - - [C++ tests](#c-tests) - - [C++ primitives microbenchmarks](#c-primitives-microbenchmarks) - - [Python libraries](#python-libraries) -- [Using CMake directly](#using-cmake-directly) -- [Build documentation](#build-documentation) -- [Using RAFT in downstream projects](#using-raft-c-in-downstream-projects) - - [CMake targets](#cmake-targets) +- [Install pre-compiled packages](#installing-precompiled-packages) + - [C, C++, and Python through Conda](#installing-through-conda) + - [Python through Pip](#installing-python-through-pip) + - [Rust through crates.io](#installing-rust-through-crates) +- [Build from source](#building-c-and-python-from-source) + - [Prerequisites](#build-prerequisites) + - [CUDA/GPU requirements](#cudagpu-requirements) + - [Build dependencies](#build-dependencies) + - [Required](#required) + - [Create a build environment](#creating-a-build-environment) + - [ccache and sccache](#ccache-and-sccache) + - [C/C++ Libraries](#c-library) + - [Building the Googletests](#building-the-googletests) + - [Python Library](#python-library) + - [Rust Library](#rust-library) + - [Using Cmake Directly](#using-cmake-directly) +- [Build Documentation](#build-documentation) +- [Use cuVS in your application](#use-cuvs-in-your-application) + +[//]: # (- [Using cuVS in downstream projects](#using-raft-c-in-downstream-projects)) + +[//]: # ( - [CMake targets](#cmake-targets)_) ------ -## Installing C++ and Python through Conda +## Installing Pre-compiled Packages -The easiest way to install RAFT is through conda and several packages are provided. -- `libraft-headers` C++ headers -- `libraft` (optional) C++ shared library containing pre-compiled template instantiations and runtime API. -- `pylibraft` (optional) Python library -- `raft-dask` (optional) Python library for deployment of multi-node multi-GPU algorithms that use the RAFT `raft::comms` abstraction layer in Dask clusters. -- `raft-ann-bench` (optional) Benchmarking tool for easily producing benchmarks that compare RAFT's vector search algorithms against other state-of-the-art implementations. -- `raft-ann-bench-cpu` (optional) Reproducible benchmarking tool similar to above, but doesn't require CUDA to be installed on the machine. Can be used to test in environments with competitive CPUs. +### C, C++, and Python through Conda -Use the following command, depending on your CUDA version, to install all of the RAFT packages with conda (replace `rapidsai` with `rapidsai-nightly` to install more up-to-date but less stable nightly packages). `mamba` is preferred over the `conda` command. +The easiest way to install the pre-compiled C, C++, and Python packages is through [conda](https://docs.anaconda.com/free/miniconda/index.html). Use the following commands, depending on your CUDA version, to install cuVS packages (replace `rapidsai` with `rapidsai-nightly` to install more up-to-date but less stable nightly packages). `mamba` is preferred over the `conda` command. + +#### C++ Package ```bash -# for CUDA 11.8 -mamba install -c rapidsai -c conda-forge -c nvidia raft-dask pylibraft cuda-version=11.8 +mamba install -c rapidsai -c conda-forge -c nvidia libcuvs cuda-version=11.8 ``` +#### C Package ```bash -# for CUDA 12.0 -mamba install -c rapidsai -c conda-forge -c nvidia raft-dask pylibraft cuda-version=12.0 +mamba install -c rapidsai -c conda-forge -c nvidia libcuvs_c cuda-version=11.8 ``` -Note that the above commands will also install `libraft-headers` and `libraft`. - -You can also install the conda packages individually using the `mamba` command above. For example, if you'd like to install RAFT's headers and pre-compiled shared library to use in your project: +#### Python Package ```bash -# for CUDA 12.0 -mamba install -c rapidsai -c conda-forge -c nvidia libraft libraft-headers cuda-version=12.0 +mamba install -c rapidsai -c conda-forge -c nvidia pycuvs cuda-version=11.8 ``` -If installing the C++ APIs Please see [using libraft](https://docs.rapids.ai/api/raft/nightly/using_libraft/) for more information on using the pre-compiled shared library. You can also refer to the [example C++ template project](https://github.com/rapidsai/raft/tree/branch-24.04/cpp/template) for a ready-to-go CMake configuration that you can drop into your project and build against installed RAFT development artifacts above. +### Python through Pip -## Installing Python through Pip - -`pylibraft` and `raft-dask` both have packages that can be [installed through pip](https://rapids.ai/pip.html#install). +The cuVS Python package can also be [installed through pip](https://rapids.ai/pip.html#install). For CUDA 11 packages: ```bash -pip install pylibraft-cu11 --extra-index-url=https://pypi.nvidia.com -pip install raft-dask-cu11 --extra-index-url=https://pypi.nvidia.com +pip install pycuvs-cu11 --extra-index-url=https://pypi.nvidia.com ``` And CUDA 12 packages: ```bash -pip install pylibraft-cu12 --extra-index-url=https://pypi.nvidia.com -pip install raft-dask-cu12 --extra-index-url=https://pypi.nvidia.com +pip install pycuvs-cu12 --extra-index-url=https://pypi.nvidia.com ``` -These packages statically build RAFT's pre-compiled instantiations, so the C++ headers and pre-compiled shared library won't be readily available to use in your code. +Note: these packages statically links the C and C++ libraries so the `libcuvs` and `libcuvs_c` shared libraries won't be readily available to use in your code. -## Building C++ and Python from source +### Rust through crates.io -### CUDA/GPU Requirements -- cmake 3.26.4+ -- GCC 9.3+ (9.5.0+ recommended) -- CUDA Toolkit 11.2+ -- NVIDIA driver 450.80.02+ -- Pascal architecture or better (compute capability >= 6.0) +## Build from source -### Build Dependencies +The core cuVS source code is written in C++ and wrapped through a C API. The C API is wrapped around the C++ APIs and the other supported languages are built around the C API. -In addition to the libraries included with cudatoolkit 11.0+, there are some other dependencies below for building RAFT from source. Many of the dependencies are optional and depend only on the primitives being used. All of these can be installed with cmake or [rapids-cpm](https://github.com/rapidsai/rapids-cmake#cpm) and many of them can be installed with [conda](https://anaconda.org). -#### Required -- [RMM](https://github.com/rapidsai/rmm) corresponding to RAFT version. -- [Thrust](https://github.com/NVIDIA/thrust) v1.17 / [CUB](https://github.com/NVIDIA/cub) -- [cuCollections](https://github.com/NVIDIA/cuCollections) - Used in `raft::sparse::distance` API. -- [CUTLASS](https://github.com/NVIDIA/cutlass) v2.9.1 - Used in `raft::distance` API. +### Prerequisites -#### Optional -- [NCCL](https://github.com/NVIDIA/nccl) - Used in `raft::comms` API and needed to build `raft-dask`. -- [UCX](https://github.com/openucx/ucx) - Used in `raft::comms` API and needed to build `raft-dask`. -- [Googletest](https://github.com/google/googletest) - Needed to build tests -- [Googlebench](https://github.com/google/benchmark) - Needed to build benchmarks -- [Doxygen](https://github.com/doxygen/doxygen) - Needed to build docs +- Cmake 3.26.4+ +- GCC 9.3+ (11.4+ recommended) +- CUDA Toolkit 11.4+ +- Volta architecture or better (compute capability >= 7.0) -#### Conda environment scripts +### Create a build environment -Conda environment scripts are provided for installing the necessary dependencies to build both the C++ and Python libraries from source. It is preferred to use `mamba`, as it provides significant speedup over `conda`: +[Conda](https://docs.anaconda.com/free/miniconda/index.html) environment scripts are provided for installing the necessary dependencies to build cuVS from source. It is preferred to use `mamba`, as it provides significant speedup over `conda`: ```bash -mamba env create --name rapids_raft -f conda/environments/all_cuda-120_arch-x86_64.yaml -mamba activate rapids_raft +mamba env create --name cuvs -f conda/environments/all_cuda-120_arch-x86_64.yaml +mamba activate cuvs ``` -All of RAFT's C++ APIs can be used header-only and optional pre-compiled shared libraries provide some host-accessible runtime APIs and template instantiations to accelerate compile times. - The process for building from source with CUDA 11 differs slightly in that your host system will also need to have CUDA toolkit installed which is greater than, or equal to, the version you install into you conda environment. Installing CUDA toolkit into your host system is necessary because `nvcc` is not provided with Conda's cudatoolkit dependencies for CUDA 11. The following example will install create and install dependencies for a CUDA 11.8 conda environment ```bash -mamba env create --name rapids_raft -f conda/environments/all_cuda-118_arch-x86_64.yaml -mamba activate rapids_raft +mamba env create --name cuvs -f conda/environments/all_cuda-118_arch-x86_64.yaml +mamba activate cuvs ``` -The recommended way to build and install RAFT from source is to use the `build.sh` script in the root of the repository. This script can build both the C++ and Python artifacts and provides CMake options for building and installing the headers, tests, benchmarks, and the pre-compiled shared library. - -### Header-only C++ - -`build.sh` uses [rapids-cmake](https://github.com/rapidsai/rapids-cmake), which will automatically download any dependencies which are not already installed. It's important to note that while all the headers will be installed and available, some parts of the RAFT API depend on libraries like CUTLASS, which will need to be explicitly enabled in `build.sh`. - -The following example will download the needed dependencies and install the RAFT headers into `$INSTALL_PREFIX/include/raft`. -```bash -./build.sh libraft -``` -The `-n` flag can be passed to just have the build download the needed dependencies. Since RAFT's C++ headers are primarily used during build-time in downstream projects, the dependencies will never be installed by the RAFT build. -```bash -./build.sh libraft -n -``` +The recommended way to build and install cuVS from source is to use the `build.sh` script in the root of the repository. This script can build both the C++ and Python artifacts and provides CMake options for building and installing the headers, tests, benchmarks, and the pre-compiled shared library. -Once installed, `libraft` headers (and dependencies which were downloaded and installed using `rapids-cmake`) can be uninstalled also using `build.sh`: -```bash -./build.sh libraft --uninstall -``` -### C++ Shared Library (optional) +### C and C++ libraries -A shared library can be built for speeding up compile times. The shared library also contains a runtime API that allows you to invoke RAFT APIs directly from C++ source files (without `nvcc`). The shared library can also significantly improve re-compile times both while developing RAFT and using its APIs to develop applications. Pass the `--compile-lib` flag to `build.sh` to build the library: +The C and C++ shared libraries are built together using the following arguments to `build.sh`: ```bash -./build.sh libraft --compile-lib +./build.sh libcuvs ``` -In above example the shared library is installed by default into `$INSTALL_PREFIX/lib`. To disable this, pass `-n` flag. +In above example the `libcuvs.so` and `libcuvs_c.so` shared libraries are installed by default into `$INSTALL_PREFIX/lib`. To disable this, pass `-n` flag. -Once installed, the shared library, headers (and any dependencies downloaded and installed via `rapids-cmake`) can be uninstalled using `build.sh`: +Once installed, the shared libraries, headers (and any dependencies downloaded and installed via `rapids-cmake`) can be uninstalled using `build.sh`: ```bash -./build.sh libraft --uninstall +./build.sh libcuvs --uninstall ``` -### ccache and sccache +#### Building the Googletests -`ccache` and `sccache` can be used to better cache parts of the build when rebuilding frequently, such as when working on a new feature. You can also use `ccache` or `sccache` with `build.sh`: +Compile the C and C++ Googletests using the `tests` target in `build.sh`. ```bash -./build.sh libraft --cache-tool=ccache +./build.sh libcuvs tests ``` -### C++ Tests +The tests will be written to the build directory, which is `cpp/build/` by default, and they will be named `*_TEST`. -Compile the tests using the `tests` target in `build.sh`. +It can take sometime to compile all of the tests. You can build individual tests by providing a semicolon-separated list to the `--limit-tests` option in `build.sh`. Make sure to pass the `-n` flag so the tests are not installed. ```bash -./build.sh libraft tests +./build.sh libcuvs tests -n --limit-tests=NEIGHBORS_TEST;CLUSTER_TEST ``` -Test compile times can be improved significantly by using the optional shared libraries. If installed, they will be used automatically when building the tests but `--compile-libs` can be used to add additional compilation units and compile them with the tests. +### Python library -```bash -./build.sh libraft tests --compile-lib -``` - -The tests are broken apart by algorithm category, so you will find several binaries in `cpp/build/` named `*_TEST`. +The Python library should be built and installed using the `build.sh` script: -For example, to run the distance tests: ```bash -./cpp/build/DISTANCE_TEST +./build.sh python ``` -It can take sometime to compile all of the tests. You can build individual tests by providing a semicolon-separated list to the `--limit-tests` option in `build.sh`: - -```bash -./build.sh libraft tests -n --limit-tests=NEIGHBORS_TEST;DISTANCE_TEST;MATRIX_TEST -``` - -### C++ Primitives Microbenchmarks - -The benchmarks are broken apart by algorithm category, so you will find several binaries in `cpp/build/` named `*_PRIMS_BENCH`. -```bash -./build.sh libraft bench-prims -``` - -It can take sometime to compile all of the benchmarks. You can build individual benchmarks by providing a semicolon-separated list to the `--limit-bench-prims` option in `build.sh`: - -```bash -./build.sh libraft bench-prims -n --limit-bench=NEIGHBORS_PRIMS_BENCH;DISTANCE_PRIMS_BENCH;LINALG_PRIMS_BENCH -``` - -In addition to microbenchmarks for individual primitives, RAFT contains a reproducible benchmarking tool for evaluating the performance of RAFT's vector search algorithms against the existing state-of-the-art. Please refer to the [RAFT ANN Benchmarks](https://docs.rapids.ai/api/raft/nightly/raft_ann_benchmarks/) guide for more information on this tool. - -### Python libraries - -The Python libraries can be built and installed using the `build.sh` script: - -```bash -# to build pylibraft -./build.sh libraft pylibraft --compile-lib -# to build raft-dask (depends on pylibraft) -./build.sh libraft pylibraft raft-dask --compile-lib -``` - -`setup.py` can also be used to build the Python libraries manually: - +The Python packages can also be uninstalled using the `build.sh` script: ```bash -cd python/raft-dask -python setup.py build_ext --inplace -python setup.py install - -cd python/pylibraft -python setup.py build_ext --inplace -python setup.py install +./build.sh python --uninstall ``` -Python tests are automatically installed with the corresponding libraries. To run Python tests: -```bash -cd python/raft-dask -py.test -s -v +### Rust library -cd python/pylibraft -py.test -s -v -``` -The Python packages can also be uninstalled using the `build.sh` script: -```bash -./build.sh pylibraft raft-dask --uninstall -``` ### Using CMake directly -When building RAFT from source, the `build.sh` script offers a nice wrapper around the `cmake` commands to ease the burdens of manually configuring the various available cmake options. When more fine-grained control over the CMake configuration is desired, the `cmake` command can be invoked directly as the below example demonstrates. +When building cuVS from source, the `build.sh` script offers a nice wrapper around the `cmake` commands to ease the burdens of manually configuring the various available cmake options. When more fine-grained control over the CMake configuration is desired, the `cmake` command can be invoked directly as the below example demonstrates. -The `CMAKE_INSTALL_PREFIX` installs RAFT into a specific location. The example below installs RAFT into the current Conda environment: +The `CMAKE_INSTALL_PREFIX` installs cuVS into a specific location. The example below installs cuVS into the current Conda environment: ```bash cd cpp mkdir build cd build -cmake -D BUILD_TESTS=ON -DRAFT_COMPILE_LIBRARY=ON -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX ../ +cmake -D BUILD_TESTS=ON -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX ../ make -j install ``` -RAFT's CMake has the following configurable flags available: - -| Flag | Possible Values | Default Value | Behavior | -|---------------------------------|----------------------| --- |------------------------------------------------------------------------------| -| BUILD_TESTS | ON, OFF | ON | Compile Googletests | -| BUILD_PRIMS_BENCH | ON, OFF | OFF | Compile benchmarks | -| BUILD_ANN_BENCH | ON, OFF | OFF | Compile end-to-end ANN benchmarks | -| CUDA_ENABLE_KERNELINFO | ON, OFF | OFF | Enables `kernelinfo` in nvcc. This is useful for `compute-sanitizer` | -| CUDA_ENABLE_LINEINFO | ON, OFF | OFF | Enable the -lineinfo option for nvcc | -| CUDA_STATIC_RUNTIME | ON, OFF | OFF | Statically link the CUDA runtime | -| DETECT_CONDA_ENV | ON, OFF | ON | Enable detection of conda environment for dependencies | -| raft_FIND_COMPONENTS | compiled distributed | | Configures the optional components as a space-separated list | -| RAFT_COMPILE_LIBRARY | ON, OFF | ON if either BUILD_TESTS or BUILD_PRIMS_BENCH is ON; otherwise OFF | Compiles all `libraft` shared libraries (these are required for Googletests) | -| RAFT_ENABLE_CUBLAS_DEPENDENCY | ON, OFF | ON | Link against cublas library in `raft::raft` | -| RAFT_ENABLE_CUSOLVER_DEPENDENCY | ON, OFF | ON | Link against cusolver library in `raft::raft` | -| RAFT_ENABLE_CUSPARSE_DEPENDENCY | ON, OFF | ON | Link against cusparse library in `raft::raft` | -| RAFT_ENABLE_CUSOLVER_DEPENDENCY | ON, OFF | ON | Link against curand library in `raft::raft` | -| RAFT_NVTX | ON, OFF | OFF | Enable NVTX Markers | - -### Build documentation +cuVS has the following configurable cmake flags available: -The documentation requires that the C++ and Python libraries have been built and installed. The following will build the docs along with the C++ and Python packages: - -``` -./build.sh libraft pylibraft raft-dask docs --compile-lib -``` +| Flag | Possible Values | Default Value | Behavior | +|------------------------|----------------------| --- |------------------------------------------------------------------------------| +| BUILD_TESTS | ON, OFF | ON | Compile Googletests | +| CUDA_ENABLE_KERNELINFO | ON, OFF | OFF | Enables `kernelinfo` in nvcc. This is useful for `compute-sanitizer` | +| CUDA_ENABLE_LINEINFO | ON, OFF | OFF | Enable the -lineinfo option for nvcc | +| CUDA_STATIC_RUNTIME | ON, OFF | OFF | Statically link the CUDA runtime | +| DETECT_CONDA_ENV | ON, OFF | ON | Enable detection of conda environment for dependencies | +| CUVS_NVTX | ON, OFF | OFF | Enable NVTX Markers | -## Using RAFT C++ in downstream projects - -There are a few different strategies for including RAFT in downstream projects, depending on whether the [required build dependencies](#build-dependencies) have already been installed and are available on the `lib` and `include` search paths. +### Build documentation -When using the GPU parts of RAFT, you will need to enable CUDA support in your CMake project declaration: -```cmake -project(YOUR_PROJECT VERSION 0.1 LANGUAGES CXX CUDA) -``` +The documentation requires that the C, C++ and Python libraries have been built and installed. The following will build the docs along with the necessary libraries: -Note that some additional compiler flags might need to be added when building against RAFT. For example, if you see an error like this `The experimental flag '--expt-relaxed-constexpr' can be used to allow this.`. The necessary flags can be set with CMake: -```cmake -target_compile_options(your_target_name PRIVATE $<$:--expt-extended-lambda --expt-relaxed-constexpr>) ``` - -Further, it's important that the language level be set to at least C++ 17. This can be done with cmake: -```cmake -set_target_properties(your_target_name -PROPERTIES CXX_STANDARD 17 - CXX_STANDARD_REQUIRED ON - CUDA_STANDARD 17 - CUDA_STANDARD_REQUIRED ON - POSITION_INDEPENDENT_CODE ON - INTERFACE_POSITION_INDEPENDENT_CODE ON) +./build.sh libcuvs python docs ``` -The [C++ example template project](https://github.com/rapidsai/raft/tree/HEAD/cpp/template) provides an end-to-end buildable example of what a `CMakeLists.txt` that uses RAFT should look like. The items below point out some of the needed details. - -#### CMake Targets - -The `raft::raft` CMake target is made available when including RAFT into your CMake project but additional CMake targets can be made available by adding to the `COMPONENTS` option in CMake's `find_package(raft)` (refer to [CMake docs](https://cmake.org/cmake/help/latest/command/find_package.html#basic-signature) to learn more). The components should be separated by spaces. The `raft::raft` target will always be available. Note that the `distributed` component also exports additional dependencies. +## Use cuVS in your application -| Component | Target | Description | Base Dependencies | -|-------------|---------------------|----------------------------------------------------------|----------------------------------------| -| n/a | `raft::raft` | Full RAFT header library | CUDA toolkit, RMM, NVTX, CCCL, CUTLASS | -| compiled | `raft::compiled` | Pre-compiled template instantiations and runtime library | raft::raft | -| distributed | `raft::distributed` | Dependencies for `raft::comms` APIs | raft::raft, UCX, NCCL +The [examples/](https://github.com/rapidsai/raft/tree/HEAD/examples) directory at the root of the cuVS repository has self-contains drop-in projects to build and use the cuVS SDK in your applications. \ No newline at end of file diff --git a/cpp/examples/CMakeLists.txt b/examples/cpp/CMakeLists.txt similarity index 100% rename from cpp/examples/CMakeLists.txt rename to examples/cpp/CMakeLists.txt diff --git a/cpp/examples/README.md b/examples/cpp/README.md similarity index 93% rename from cpp/examples/README.md rename to examples/cpp/README.md index 125c6dba2..5a98dd390 100644 --- a/cpp/examples/README.md +++ b/examples/cpp/README.md @@ -6,7 +6,7 @@ First, please refer to our [installation docs](https://docs.rapids.ai/api/cuvs/s Once the minimum requirements are satisfied, this example template application can be built with the provided `build.sh` script. This is a bash script that calls the appropriate CMake commands, so you can look into it to see the typical CMake based build workflow. -This directory (`CUVS_SOURCE/cpp/examples`) can be copied directly in order to build a new application with CUVS. +This directory (`CUVS_SOURCE/examples/cpp`) can be copied directly in order to build a new application with CUVS. cuVS can be integrated into an existing CMake project by copying the contents in the `configure rapids-cmake` and `configure cuvs` sections of the provided `CMakeLists.txt` into your project, along with `cmake/thirdparty/get_cuvs.cmake`. @@ -14,5 +14,4 @@ Make sure to link against the appropriate Cmake targets. Use `cuvs::cuvs` to uti ```cmake target_link_libraries(your_app_target PRIVATE cuvs::cuvs) -``` - +``` \ No newline at end of file diff --git a/cpp/examples/build.sh b/examples/cpp/build.sh similarity index 100% rename from cpp/examples/build.sh rename to examples/cpp/build.sh diff --git a/cpp/examples/cmake/thirdparty/fetch_rapids.cmake b/examples/cpp/cmake/thirdparty/fetch_rapids.cmake similarity index 100% rename from cpp/examples/cmake/thirdparty/fetch_rapids.cmake rename to examples/cpp/cmake/thirdparty/fetch_rapids.cmake diff --git a/cpp/examples/cmake/thirdparty/get_cuvs.cmake b/examples/cpp/cmake/thirdparty/get_cuvs.cmake similarity index 100% rename from cpp/examples/cmake/thirdparty/get_cuvs.cmake rename to examples/cpp/cmake/thirdparty/get_cuvs.cmake diff --git a/cpp/examples/src/cagra_example.cu b/examples/cpp/src/cagra_example.cu similarity index 100% rename from cpp/examples/src/cagra_example.cu rename to examples/cpp/src/cagra_example.cu diff --git a/cpp/examples/src/common.cuh b/examples/cpp/src/common.cuh similarity index 100% rename from cpp/examples/src/common.cuh rename to examples/cpp/src/common.cuh From 19319d7887d064f18bec4af971bb142500bc74df Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Fri, 8 Mar 2024 16:23:01 -0500 Subject: [PATCH 07/25] Updating build.sh to build the examples --- build.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build.sh b/build.sh index c6e09c5bf..1822e739e 100755 --- a/build.sh +++ b/build.sh @@ -439,7 +439,7 @@ fi # Initiate build for c++ examples (if needed) if hasArg examples; then - pushd ${REPODIR}/cpp/examples + pushd ${REPODIR}/examples/cpp ./build.sh popd fi From 358df758cf1b2aeb27fd3878f3cdf4a26eb0c5c2 Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Fri, 8 Mar 2024 17:32:08 -0500 Subject: [PATCH 08/25] Fixing docs per review --- docs/source/build.md | 22 ++++++++-------------- 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/docs/source/build.md b/docs/source/build.md index 939f1db34..249612964 100644 --- a/docs/source/build.md +++ b/docs/source/build.md @@ -1,8 +1,6 @@ -**# Installation +# Installation -The cuVS software development kit provides APIs for C, C++, Python, and Rust languages. These - -Both the C++ and Python APIs require CMake to build from source. +The cuVS software development kit provides APIs for C, C++, Python, and Rust languages. This guide outlines how to install the pre-compiled packages, build it from source, and use it in downstream applications. ## Table of Contents @@ -25,10 +23,6 @@ Both the C++ and Python APIs require CMake to build from source. - [Build Documentation](#build-documentation) - [Use cuVS in your application](#use-cuvs-in-your-application) -[//]: # (- [Using cuVS in downstream projects](#using-raft-c-in-downstream-projects)) - -[//]: # ( - [CMake targets](#cmake-targets)_) - ------ ## Installing Pre-compiled Packages @@ -39,17 +33,17 @@ The easiest way to install the pre-compiled C, C++, and Python packages is throu #### C++ Package ```bash -mamba install -c rapidsai -c conda-forge -c nvidia libcuvs cuda-version=11.8 +mamba install -c rapidsai -c conda-forge -c nvidia libcuvs cuda-version=12.0 ``` #### C Package ```bash -mamba install -c rapidsai -c conda-forge -c nvidia libcuvs_c cuda-version=11.8 +mamba install -c rapidsai -c conda-forge -c nvidia libcuvs_c cuda-version=12.0 ``` #### Python Package ```bash -mamba install -c rapidsai -c conda-forge -c nvidia pycuvs cuda-version=11.8 +mamba install -c rapidsai -c conda-forge -c nvidia pycuvs cuda-version=12.0 ``` ### Python through Pip @@ -66,7 +60,7 @@ And CUDA 12 packages: pip install pycuvs-cu12 --extra-index-url=https://pypi.nvidia.com ``` -Note: these packages statically links the C and C++ libraries so the `libcuvs` and `libcuvs_c` shared libraries won't be readily available to use in your code. +Note: these packages statically link the C and C++ libraries so the `libcuvs` and `libcuvs_c` shared libraries won't be readily available to use in your code. ### Rust through crates.io @@ -124,10 +118,10 @@ Compile the C and C++ Googletests using the `tests` target in `build.sh`. The tests will be written to the build directory, which is `cpp/build/` by default, and they will be named `*_TEST`. -It can take sometime to compile all of the tests. You can build individual tests by providing a semicolon-separated list to the `--limit-tests` option in `build.sh`. Make sure to pass the `-n` flag so the tests are not installed. +It can take some time to compile all of the tests. You can build individual tests by providing a semicolon-separated list to the `--limit-tests` option in `build.sh`. Make sure to pass the `-n` flag so the tests are not installed. ```bash -./build.sh libcuvs tests -n --limit-tests=NEIGHBORS_TEST;CLUSTER_TEST +./build.sh libcuvs tests -n --limit-tests=NEIGHBORS_TEST;CAGRA_C_TEST ``` ### Python library From 64d594b9c6254e44ec723025b3557ecc50da41b0 Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Fri, 8 Mar 2024 17:39:19 -0500 Subject: [PATCH 09/25] Removing developer guide. That's unneeded int the docs --- docs/source/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index bbb6f93f2..ce8a8e1d2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -24,7 +24,6 @@ cuVS is a library for vector search and clustering on the GPU. quick_start.md build.md api_docs.rst - developer_guide.md contributing.md From 620e0808b2b00e50b96069f1b21d99c9e8d43c76 Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Fri, 8 Mar 2024 18:03:49 -0500 Subject: [PATCH 10/25] Stubbing out quick start guide --- docs/source/conf.py | 1 + docs/source/quick_start.md | 125 ++++++++++--------------------------- 2 files changed, 34 insertions(+), 92 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 1089f6a5c..5674dda3c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -27,6 +27,7 @@ "sphinx.ext.autodoc", "sphinx.ext.autosummary", "sphinx.ext.doctest", + "sphinxcontrib-osexample", "sphinx.ext.intersphinx", "IPython.sphinxext.ipython_console_highlighting", "IPython.sphinxext.ipython_directive", diff --git a/docs/source/quick_start.md b/docs/source/quick_start.md index 3909b40f2..a1dd31db1 100644 --- a/docs/source/quick_start.md +++ b/docs/source/quick_start.md @@ -1,14 +1,34 @@ # Quick Start -This guide is meant to provide a quick-start tutorial for interacting with RAFT's C++ & Python APIs. +This guide is meant to provide a quick-start primer for using the various different APIs in the cuVS software development kit. -## RAPIDS Memory Manager (RMM) +## Table of Contents -RAFT relies heavily on the [RMM](https://github.com/rapidsai/rmm) library which eases the burden of configuring different allocation strategies globally across the libraries that use it. +- [Resource management](#resource-management) +- [Memory management](#memory-management) +- [Multi-dimensional array formats and interoperability](#multi-dimensional-array-formats-and-interoperability) + - [C++ multi-dimensional span (mdspan)](#c-multi-dimensional-span-mdspan) + - [DLPack](#dlpack) + - [CUDA array interface](#cuda-array-interface) +- [Working with ANN indexes](#working-with-ann-indexes) + - [Building an index](#building-an-index) + - [Searching an index](#searching-an-index) + - [CPU/GPU Interoperability](#cpu-gpu-interoperability) + - [Serializing an index](#serializing-an-index) -## Multi-dimensional Spans and Arrays +------ -Most of the APIs in RAFT accept [mdspan](https://arxiv.org/abs/2010.06474) multi-dimensional array view for representing data in higher dimensions similar to the `ndarray` in the Numpy Python library. RAFT also contains the corresponding owning `mdarray` structure, which simplifies the allocation and management of multi-dimensional data in both host and device (GPU) memory. +## Resource management + +## Memory management + +cuVS relies heavily on the [RMM](https://github.com/rapidsai/rmm) library which eases the burden of configuring different allocation strategies globally across the libraries that use it. + +## Multi-dimensional array formats and interoperability + +### C++ multi-dimensional span (mdspan) + +Most of the C++ APIs in cuVS accept [mdspan](https://arxiv.org/abs/2010.06474) multi-dimensional array view for representing data in higher dimensions similar to the `ndarray` in the Numpy Python library. RAFT also contains the corresponding owning `mdarray` structure, which simplifies the allocation and management of multi-dimensional data in both host and device (GPU) memory. The `mdarray` is an owning object that forms a convenience layer over RMM and can be constructed in RAFT using a number of different helper functions: @@ -23,7 +43,7 @@ auto vector = raft::make_device_vector(handle, n_cols); auto matrix = raft::make_device_matrix(handle, n_rows, n_cols); ``` -The `mdspan` is a lightweight non-owning view that can wrap around any pointer, maintaining shape, layout, and indexing information for accessing elements. +The `mdspan` is a lightweight non-owning view that can wrap around any pointer, maintaining shape, layout, and indexing information for accessing elements. We can construct `mdspan` instances directly from the above `mdarray` instances: @@ -89,95 +109,16 @@ int stride = 10; auto vector = raft::make_device_vector_view(vector_ptr, raft::make_vector_strided_layout(n_elements, stride)); ``` +### DLPack -## C++ Example - -Most of the primitives in RAFT accept a `raft::handle_t` object for the management of resources which are expensive to create, such CUDA streams, stream pools, and handles to other CUDA libraries like `cublas` and `cusolver`. - -The example below demonstrates creating a RAFT handle and using it with `device_matrix` and `device_vector` to allocate memory, generating random clusters, and computing -pairwise Euclidean distances: - -```c++ -#include -#include -#include -#include - -raft::handle_t handle; - -int n_samples = 5000; -int n_features = 50; - -auto input = raft::make_device_matrix(handle, n_samples, n_features); -auto labels = raft::make_device_vector(handle, n_samples); -auto output = raft::make_device_matrix(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); -``` - -## Python Example - -The `pylibraft` package contains a Python API for RAFT algorithms and primitives. `pylibraft` integrates nicely into other libraries by being very lightweight with minimal dependencies and accepting any object that supports the `__cuda_array_interface__`, such as [CuPy's ndarray](https://docs.cupy.dev/en/stable/user_guide/interoperability.html#rmm). The number of RAFT algorithms exposed in this package is continuing to grow from release to release. - -The example below demonstrates computing the pairwise Euclidean distances between CuPy arrays. Note that CuPy is not a required dependency for `pylibraft`. - -```python -import cupy as cp - -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), dtype=cp.float32) - -output = pairwise_distance(in1, in2, metric="euclidean") -``` - -The `output` array in the above example is of type `raft.common.device_ndarray`, which supports [__cuda_array_interface__](https://numba.pydata.org/numba-doc/dev/cuda/cuda_array_interface.html#cuda-array-interface-version-2) making it interoperable with other libraries like CuPy, Numba, and PyTorch that also support it. CuPy supports DLPack, which also enables zero-copy conversion from `raft.common.device_ndarray` to JAX and Tensorflow. - -Below is an example of converting the output `pylibraft.common.device_ndarray` to a CuPy array: -```python -cupy_array = cp.asarray(output) -``` +### CUDA array interface -And converting to a PyTorch tensor: -```python -import torch +## Working with ANN indexes -torch_tensor = torch.as_tensor(output, device='cuda') -``` +### Building an index -When the corresponding library has been installed and available in your environment, this conversion can also be done automatically by all RAFT compute APIs by setting a global configuration option: -```python -import pylibraft.config -pylibraft.config.set_output_as("cupy") # All compute APIs will return cupy arrays -pylibraft.config.set_output_as("torch") # All compute APIs will return torch tensors -``` - -You can also specify a `callable` that accepts a `pylibraft.common.device_ndarray` and performs a custom conversion. The following example converts all output to `numpy` arrays: -```python -pylibraft.config.set_output_as(lambda device_ndarray: return device_ndarray.copy_to_host()) -``` - - -`pylibraft` also supports writing to a pre-allocated output array so any `__cuda_array_interface__` supported array can be written to in-place: +### Searching an index -```python -import cupy as cp +### CPU/GPU interoperability -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), dtype=cp.float32) -output = cp.empty((n_samples, n_samples), dtype=cp.float32) - -pairwise_distance(in1, in2, out=output, metric="euclidean") -``` +### Serializing an index \ No newline at end of file From f1f671f87ceccab0a61598496fc6a98a250fb739 Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Mon, 11 Mar 2024 13:33:47 -0400 Subject: [PATCH 11/25] Adding quick start --- .../all_cuda-118_arch-aarch64.yaml | 1 + .../all_cuda-118_arch-x86_64.yaml | 1 + .../all_cuda-122_arch-aarch64.yaml | 1 + .../all_cuda-122_arch-x86_64.yaml | 1 + dependencies.yaml | 1 + docs/source/api_docs.rst | 4 +- docs/source/build.md | 8 ++-- docs/source/index.rst | 1 + docs/source/integrations.md | 9 ++++ docs/source/quick_start.md | 44 +++++++------------ 10 files changed, 36 insertions(+), 35 deletions(-) create mode 100644 docs/source/integrations.md diff --git a/conda/environments/all_cuda-118_arch-aarch64.yaml b/conda/environments/all_cuda-118_arch-aarch64.yaml index d711fc555..091c5b8d8 100644 --- a/conda/environments/all_cuda-118_arch-aarch64.yaml +++ b/conda/environments/all_cuda-118_arch-aarch64.yaml @@ -51,5 +51,6 @@ dependencies: - scikit-learn - sphinx-copybutton - sphinx-markdown-tables +- sphinxcontrib - sysroot_linux-aarch64==2.17 name: all_cuda-118_arch-aarch64 diff --git a/conda/environments/all_cuda-118_arch-x86_64.yaml b/conda/environments/all_cuda-118_arch-x86_64.yaml index b4c2c6857..1e9afc53d 100644 --- a/conda/environments/all_cuda-118_arch-x86_64.yaml +++ b/conda/environments/all_cuda-118_arch-x86_64.yaml @@ -51,5 +51,6 @@ dependencies: - scikit-learn - sphinx-copybutton - sphinx-markdown-tables +- sphinxcontrib - sysroot_linux-64==2.17 name: all_cuda-118_arch-x86_64 diff --git a/conda/environments/all_cuda-122_arch-aarch64.yaml b/conda/environments/all_cuda-122_arch-aarch64.yaml index 85d96e5c9..a2623b895 100644 --- a/conda/environments/all_cuda-122_arch-aarch64.yaml +++ b/conda/environments/all_cuda-122_arch-aarch64.yaml @@ -47,5 +47,6 @@ dependencies: - scikit-learn - sphinx-copybutton - sphinx-markdown-tables +- sphinxcontrib - sysroot_linux-aarch64==2.17 name: all_cuda-122_arch-aarch64 diff --git a/conda/environments/all_cuda-122_arch-x86_64.yaml b/conda/environments/all_cuda-122_arch-x86_64.yaml index 16cc655c6..91e90cd08 100644 --- a/conda/environments/all_cuda-122_arch-x86_64.yaml +++ b/conda/environments/all_cuda-122_arch-x86_64.yaml @@ -47,5 +47,6 @@ dependencies: - scikit-learn - sphinx-copybutton - sphinx-markdown-tables +- sphinxcontrib - sysroot_linux-64==2.17 name: all_cuda-122_arch-x86_64 diff --git a/dependencies.yaml b/dependencies.yaml index 7fff7811a..1e35f5d96 100644 --- a/dependencies.yaml +++ b/dependencies.yaml @@ -315,6 +315,7 @@ dependencies: - recommonmark - sphinx-copybutton - sphinx-markdown-tables + - sphinxcontrib rust: common: - output_types: [conda] diff --git a/docs/source/api_docs.rst b/docs/source/api_docs.rst index 2a5a867e0..f0b7a94fd 100644 --- a/docs/source/api_docs.rst +++ b/docs/source/api_docs.rst @@ -1,5 +1,5 @@ -API Documentation -================= +API Docs +======== .. toctree:: :maxdepth: 1 diff --git a/docs/source/build.md b/docs/source/build.md index 976482725..3ee5a7159 100644 --- a/docs/source/build.md +++ b/docs/source/build.md @@ -1,4 +1,4 @@ -**# Installation +# Installation The cuVS software development kit provides APIs for C, C++, Python, and Rust languages. This guide outlines how to install the pre-compiled packages, build it from source, and use it in downstream applications. @@ -43,7 +43,7 @@ mamba install -c rapidsai -c conda-forge -c nvidia libcuvs_c cuda-version=12.0 #### Python Package ```bash -mamba install -c rapidsai -c conda-forge -c nvidia pycuvs cuda-version=12.0 +mamba install -c rapidsai -c conda-forge -c nvidia cuvs cuda-version=12.0 ``` ### Python through Pip @@ -52,12 +52,12 @@ The cuVS Python package can also be [installed through pip](https://rapids.ai/pi For CUDA 11 packages: ```bash -pip install pycuvs-cu11 --extra-index-url=https://pypi.nvidia.com +pip install cuvs-cu11 --extra-index-url=https://pypi.nvidia.com ``` And CUDA 12 packages: ```bash -pip install pycuvs-cu12 --extra-index-url=https://pypi.nvidia.com +pip install cuvs-cu12 --extra-index-url=https://pypi.nvidia.com ``` Note: these packages statically link the C and C++ libraries so the `libcuvs` and `libcuvs_c` shared libraries won't be readily available to use in your code. diff --git a/docs/source/index.rst b/docs/source/index.rst index ce8a8e1d2..b467be5ba 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -23,6 +23,7 @@ cuVS is a library for vector search and clustering on the GPU. quick_start.md build.md + integrations.md api_docs.rst contributing.md diff --git a/docs/source/integrations.md b/docs/source/integrations.md new file mode 100644 index 000000000..90fb8df56 --- /dev/null +++ b/docs/source/integrations.md @@ -0,0 +1,9 @@ +# Integrations + +FAISS + +Milvus + +Kinetica + +Lucene \ No newline at end of file diff --git a/docs/source/quick_start.md b/docs/source/quick_start.md index a1dd31db1..d2672e6cb 100644 --- a/docs/source/quick_start.md +++ b/docs/source/quick_start.md @@ -6,10 +6,10 @@ This guide is meant to provide a quick-start primer for using the various differ - [Resource management](#resource-management) - [Memory management](#memory-management) -- [Multi-dimensional array formats and interoperability](#multi-dimensional-array-formats-and-interoperability) - - [C++ multi-dimensional span (mdspan)](#c-multi-dimensional-span-mdspan) - - [DLPack](#dlpack) - - [CUDA array interface](#cuda-array-interface) +- [Interoperability](#multi-dimensional-array-formats-and-interoperability) + - [DLPack (C)](#dlpack-c) + - [Multi-dimensional span (C++)](#multi-dimensional-span-c) + - [CUDA array interface (Python)](#cuda-array-interface-python) - [Working with ANN indexes](#working-with-ann-indexes) - [Building an index](#building-an-index) - [Searching an index](#searching-an-index) @@ -20,15 +20,22 @@ This guide is meant to provide a quick-start primer for using the various differ ## Resource management +cuVS uses + ## Memory management cuVS relies heavily on the [RMM](https://github.com/rapidsai/rmm) library which eases the burden of configuring different allocation strategies globally across the libraries that use it. ## Multi-dimensional array formats and interoperability -### C++ multi-dimensional span (mdspan) -Most of the C++ APIs in cuVS accept [mdspan](https://arxiv.org/abs/2010.06474) multi-dimensional array view for representing data in higher dimensions similar to the `ndarray` in the Numpy Python library. RAFT also contains the corresponding owning `mdarray` structure, which simplifies the allocation and management of multi-dimensional data in both host and device (GPU) memory. +### DLPack + + + +### Multi-dimensional span (C++) + +cuVS is built on top of the GPU-accelerated machine learning and data mining primitives in the [RAFT](https://github.com/rapidsai/raft) library. Most of the C++ APIs in cuVS accept [mdspan](https://arxiv.org/abs/2010.06474) multi-dimensional array view for representing data in higher dimensions similar to the `ndarray` in the Numpy Python library. RAFT also contains the corresponding owning `mdarray` structure, which simplifies the allocation and management of multi-dimensional data in both host and device (GPU) memory. The `mdarray` is an owning object that forms a convenience layer over RMM and can be constructed in RAFT using a number of different helper functions: @@ -45,7 +52,6 @@ auto matrix = raft::make_device_matrix(handle, n_rows, n_cols); The `mdspan` is a lightweight non-owning view that can wrap around any pointer, maintaining shape, layout, and indexing information for accessing elements. - We can construct `mdspan` instances directly from the above `mdarray` instances: ```c++ @@ -86,32 +92,12 @@ auto vector_view = raft::make_host_vector_view(vector.data_handle(), vector.exte auto matrix_view = raft::make_host_matrix_view(matrix.data_handle(), matrix.extent(0), matrix.extent(1)); ``` -And `managed` variants: - -```c++ -#include - -int n_rows = 10; -int n_cols = 10; - -auto matrix = raft::make_managed_mdspan(managed_ptr, raft::make_matrix_extents(n_rows, n_cols)); -``` - -You can also create strided mdspans: - -```c++ - -#include +Please refer to RAFT's `mdspan` [documentation](https://docs.rapids.ai/api/raft/stable/cpp_api/mdspan/) to learn more. -int n_elements = 10; -int stride = 10; -auto vector = raft::make_device_vector_view(vector_ptr, raft::make_vector_strided_layout(n_elements, stride)); -``` +### CUDA array interface -### DLPack -### CUDA array interface ## Working with ANN indexes From 31d014c082a7190fb94b729a4cf3654f511905fc Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Mon, 11 Mar 2024 20:19:11 -0400 Subject: [PATCH 12/25] Checking in --- docs/source/quick_start.md | 82 ++++++++++++++++++++++++++++++++++---- 1 file changed, 75 insertions(+), 7 deletions(-) diff --git a/docs/source/quick_start.md b/docs/source/quick_start.md index d2672e6cb..53401d1e3 100644 --- a/docs/source/quick_start.md +++ b/docs/source/quick_start.md @@ -1,11 +1,11 @@ # Quick Start -This guide is meant to provide a quick-start primer for using the various different APIs in the cuVS software development kit. +This guide is meant to provide a quick-start primer for using the various different APIs and tools used in the cuVS software development kit. ## Table of Contents -- [Resource management](#resource-management) - [Memory management](#memory-management) +- [Resource management](#resource-management) - [Interoperability](#multi-dimensional-array-formats-and-interoperability) - [DLPack (C)](#dlpack-c) - [Multi-dimensional span (C++)](#multi-dimensional-span-c) @@ -18,18 +18,84 @@ This guide is meant to provide a quick-start primer for using the various differ ------ +## Memory management + +Centralized memory management allows flexible configuration of allocation strategies, such as sharing the same CUDA memory pool across library boundaries. cuVS uses the [RMM](https://github.com/rapidsai/rmm) library, which eases the burden of configuring different allocation strategies globally across GPU-accelerated libraries. + +RMM currently has APIs for C++ and Python. + +### C++ + +Here's an example of configuring RMM to use a pool allocator in C++ (derived from the RMM example [here](https://github.com/rapidsai/rmm?tab=readme-ov-file#example)): + +```c++ +rmm::mr::cuda_memory_resource cuda_mr; +// Construct a resource that uses a coalescing best-fit pool allocator +// With the pool initially half of available device memory +auto initial_size = rmm::percent_of_free_device_memory(50); +rmm::mr::pool_memory_resource pool_mr{&cuda_mr, initial_size}; +rmm::mr::set_current_device_resource(&pool_mr); // Updates the current device resource pointer to `pool_mr` +rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource(); // Points to `pool_mr` +``` + +### Python + +And the corresponding code in Python (derived from the RMM example [here](https://github.com/rapidsai/rmm?tab=readme-ov-file#memoryresource-objects)): +```python +import rmm +pool = rmm.mr.PoolMemoryResource( + rmm.mr.CudaMemoryResource(), + initial_pool_size=2**30, + maximum_pool_size=2**32) +rmm.mr.set_current_device_resource(pool) +``` + + ## Resource management -cuVS uses +cuVS uses an API from the [RAFT](https://github.com/rapidsai/raft) library of ML and data mining primitives to centralize and reuse expensive resources, such as memory management. The below code examples demonstrate how to create these resources for use throughout this guide. + +See RAFT's [resource API documentation](https://docs.rapids.ai/api/raft/nightly/cpp_api/core_resources/) for more information. + +### C + +```c +#include +#include + +cuvsResources_t res; +cuvsResourcesCreate(&res); + +// ... do some processing ... + +cuvsResourcesDestroy(res); +``` + +### C++ + +```c++ +#include + +raft::device_resources res; +``` + +### Python + +```Python +import pylibraft + +res = pylibraft.common.DeviceResources() +``` + +### Rust + -## Memory management -cuVS relies heavily on the [RMM](https://github.com/rapidsai/rmm) library which eases the burden of configuring different allocation strategies globally across the libraries that use it. ## Multi-dimensional array formats and interoperability -### DLPack +### DLPack (C) @@ -95,12 +161,14 @@ auto matrix_view = raft::make_host_matrix_view(matrix.data_handle(), matrix.exte Please refer to RAFT's `mdspan` [documentation](https://docs.rapids.ai/api/raft/stable/cpp_api/mdspan/) to learn more. -### CUDA array interface +### CUDA array interface (Python) ## Working with ANN indexes + + ### Building an index ### Searching an index From f69e86e1a5e8306d4a672b5a9b07c989603ef3d9 Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Tue, 12 Mar 2024 01:03:12 -0400 Subject: [PATCH 13/25] Renaming quick_start to getting started --- docs/source/{quick_start.md => getting_started.md} | 2 +- docs/source/index.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) rename docs/source/{quick_start.md => getting_started.md} (99%) diff --git a/docs/source/quick_start.md b/docs/source/getting_started.md similarity index 99% rename from docs/source/quick_start.md rename to docs/source/getting_started.md index 53401d1e3..f60d15be4 100644 --- a/docs/source/quick_start.md +++ b/docs/source/getting_started.md @@ -1,4 +1,4 @@ -# Quick Start +# Getting Started This guide is meant to provide a quick-start primer for using the various different APIs and tools used in the cuVS software development kit. diff --git a/docs/source/index.rst b/docs/source/index.rst index b467be5ba..1b4309429 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -21,7 +21,7 @@ cuVS is a library for vector search and clustering on the GPU. :maxdepth: 1 :caption: Contents: - quick_start.md + getting_started.md build.md integrations.md api_docs.rst From 0afe86bcaf854d7e45f286e02cc4401c66410bd6 Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Tue, 12 Mar 2024 12:11:05 -0400 Subject: [PATCH 14/25] Removing osexamples --- docs/source/conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 5674dda3c..1089f6a5c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -27,7 +27,6 @@ "sphinx.ext.autodoc", "sphinx.ext.autosummary", "sphinx.ext.doctest", - "sphinxcontrib-osexample", "sphinx.ext.intersphinx", "IPython.sphinxext.ipython_console_highlighting", "IPython.sphinxext.ipython_directive", From 929e9b49bd5a1fcf94c3b8de987a1dec3c563077 Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Tue, 12 Mar 2024 15:52:17 -0400 Subject: [PATCH 15/25] Fixing package issuey --- conda/environments/all_cuda-118_arch-aarch64.yaml | 1 - conda/environments/all_cuda-118_arch-x86_64.yaml | 1 - conda/environments/all_cuda-122_arch-aarch64.yaml | 1 - conda/environments/all_cuda-122_arch-x86_64.yaml | 1 - dependencies.yaml | 1 - docs/source/api_docs.rst | 4 ++-- docs/source/getting_started.md | 2 +- docs/source/index.rst | 1 - docs/source/integrations.md | 8 ++++---- 9 files changed, 7 insertions(+), 13 deletions(-) diff --git a/conda/environments/all_cuda-118_arch-aarch64.yaml b/conda/environments/all_cuda-118_arch-aarch64.yaml index 091c5b8d8..d711fc555 100644 --- a/conda/environments/all_cuda-118_arch-aarch64.yaml +++ b/conda/environments/all_cuda-118_arch-aarch64.yaml @@ -51,6 +51,5 @@ dependencies: - scikit-learn - sphinx-copybutton - sphinx-markdown-tables -- sphinxcontrib - sysroot_linux-aarch64==2.17 name: all_cuda-118_arch-aarch64 diff --git a/conda/environments/all_cuda-118_arch-x86_64.yaml b/conda/environments/all_cuda-118_arch-x86_64.yaml index 1e9afc53d..b4c2c6857 100644 --- a/conda/environments/all_cuda-118_arch-x86_64.yaml +++ b/conda/environments/all_cuda-118_arch-x86_64.yaml @@ -51,6 +51,5 @@ dependencies: - scikit-learn - sphinx-copybutton - sphinx-markdown-tables -- sphinxcontrib - sysroot_linux-64==2.17 name: all_cuda-118_arch-x86_64 diff --git a/conda/environments/all_cuda-122_arch-aarch64.yaml b/conda/environments/all_cuda-122_arch-aarch64.yaml index a2623b895..85d96e5c9 100644 --- a/conda/environments/all_cuda-122_arch-aarch64.yaml +++ b/conda/environments/all_cuda-122_arch-aarch64.yaml @@ -47,6 +47,5 @@ dependencies: - scikit-learn - sphinx-copybutton - sphinx-markdown-tables -- sphinxcontrib - sysroot_linux-aarch64==2.17 name: all_cuda-122_arch-aarch64 diff --git a/conda/environments/all_cuda-122_arch-x86_64.yaml b/conda/environments/all_cuda-122_arch-x86_64.yaml index 91e90cd08..16cc655c6 100644 --- a/conda/environments/all_cuda-122_arch-x86_64.yaml +++ b/conda/environments/all_cuda-122_arch-x86_64.yaml @@ -47,6 +47,5 @@ dependencies: - scikit-learn - sphinx-copybutton - sphinx-markdown-tables -- sphinxcontrib - sysroot_linux-64==2.17 name: all_cuda-122_arch-x86_64 diff --git a/dependencies.yaml b/dependencies.yaml index 1e35f5d96..7fff7811a 100644 --- a/dependencies.yaml +++ b/dependencies.yaml @@ -315,7 +315,6 @@ dependencies: - recommonmark - sphinx-copybutton - sphinx-markdown-tables - - sphinxcontrib rust: common: - output_types: [conda] diff --git a/docs/source/api_docs.rst b/docs/source/api_docs.rst index f0b7a94fd..c911539b9 100644 --- a/docs/source/api_docs.rst +++ b/docs/source/api_docs.rst @@ -1,5 +1,5 @@ -API Docs -======== +API Reference +============= .. toctree:: :maxdepth: 1 diff --git a/docs/source/getting_started.md b/docs/source/getting_started.md index f60d15be4..2baf251f3 100644 --- a/docs/source/getting_started.md +++ b/docs/source/getting_started.md @@ -1,6 +1,6 @@ # Getting Started -This guide is meant to provide a quick-start primer for using the various different APIs and tools used in the cuVS software development kit. +This guide provides an initial starting point for using the various different features and APIs in the cuVS software development kit. ## Table of Contents diff --git a/docs/source/index.rst b/docs/source/index.rst index 1b4309429..da92786a0 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -23,7 +23,6 @@ cuVS is a library for vector search and clustering on the GPU. getting_started.md build.md - integrations.md api_docs.rst contributing.md diff --git a/docs/source/integrations.md b/docs/source/integrations.md index 90fb8df56..56f93535d 100644 --- a/docs/source/integrations.md +++ b/docs/source/integrations.md @@ -1,9 +1,9 @@ # Integrations -FAISS +In addition to using cuVS through any one of its different language APIs -Milvus +## FAISS -Kinetica +## Milvus -Lucene \ No newline at end of file +## Kinetica From 77e1cbe785bb7f46c6c8e64a9bbdd2f710c088d0 Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Tue, 12 Mar 2024 16:08:26 -0400 Subject: [PATCH 16/25] Breaking apart getting started guide --- docs/source/basics.md | 81 +++++++++++ docs/source/getting_started.md | 179 +----------------------- docs/source/interoperability.md | 78 +++++++++++ docs/source/working_with_ann_indexes.md | 21 +++ 4 files changed, 186 insertions(+), 173 deletions(-) create mode 100644 docs/source/basics.md create mode 100644 docs/source/interoperability.md create mode 100644 docs/source/working_with_ann_indexes.md diff --git a/docs/source/basics.md b/docs/source/basics.md new file mode 100644 index 000000000..df2e533bd --- /dev/null +++ b/docs/source/basics.md @@ -0,0 +1,81 @@ +# cuVS API Basics + +## Contents + +- [Memory management](#memory-management) +- [Resource management](#resource-management) + +------ + +## Memory management + +Centralized memory management allows flexible configuration of allocation strategies, such as sharing the same CUDA memory pool across library boundaries. cuVS uses the [RMM](https://github.com/rapidsai/rmm) library, which eases the burden of configuring different allocation strategies globally across GPU-accelerated libraries. + +RMM currently has APIs for C++ and Python. + +### C++ + +Here's an example of configuring RMM to use a pool allocator in C++ (derived from the RMM example [here](https://github.com/rapidsai/rmm?tab=readme-ov-file#example)): + +```c++ +rmm::mr::cuda_memory_resource cuda_mr; +// Construct a resource that uses a coalescing best-fit pool allocator +// With the pool initially half of available device memory +auto initial_size = rmm::percent_of_free_device_memory(50); +rmm::mr::pool_memory_resource pool_mr{&cuda_mr, initial_size}; +rmm::mr::set_current_device_resource(&pool_mr); // Updates the current device resource pointer to `pool_mr` +rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource(); // Points to `pool_mr` +``` + +### Python + +And the corresponding code in Python (derived from the RMM example [here](https://github.com/rapidsai/rmm?tab=readme-ov-file#memoryresource-objects)): +```python +import rmm +pool = rmm.mr.PoolMemoryResource( + rmm.mr.CudaMemoryResource(), + initial_pool_size=2**30, + maximum_pool_size=2**32) +rmm.mr.set_current_device_resource(pool) +``` + + +## Resource management + +cuVS uses an API from the [RAFT](https://github.com/rapidsai/raft) library of ML and data mining primitives to centralize and reuse expensive resources, such as memory management. The below code examples demonstrate how to create these resources for use throughout this guide. + +See RAFT's [resource API documentation](https://docs.rapids.ai/api/raft/nightly/cpp_api/core_resources/) for more information. + +### C + +```c +#include +#include + +cuvsResources_t res; +cuvsResourcesCreate(&res); + +// ... do some processing ... + +cuvsResourcesDestroy(res); +``` + +### C++ + +```c++ +#include + +raft::device_resources res; +``` + +### Python + +```Python +import pylibraft + +res = pylibraft.common.DeviceResources() +``` + +### Rust + + diff --git a/docs/source/getting_started.md b/docs/source/getting_started.md index 2baf251f3..d9a536000 100644 --- a/docs/source/getting_started.md +++ b/docs/source/getting_started.md @@ -1,178 +1,11 @@ # Getting Started -This guide provides an initial starting point for using the various different features and APIs in the cuVS software development kit. +This guide provides an initial starting point of the basic concepts and using the various APIs in the cuVS software development kit. -## Table of Contents +## Contents -- [Memory management](#memory-management) -- [Resource management](#resource-management) -- [Interoperability](#multi-dimensional-array-formats-and-interoperability) - - [DLPack (C)](#dlpack-c) - - [Multi-dimensional span (C++)](#multi-dimensional-span-c) - - [CUDA array interface (Python)](#cuda-array-interface-python) -- [Working with ANN indexes](#working-with-ann-indexes) - - [Building an index](#building-an-index) - - [Searching an index](#searching-an-index) - - [CPU/GPU Interoperability](#cpu-gpu-interoperability) - - [Serializing an index](#serializing-an-index) +- [cuVS API Basics](basics.md) +- [Interoperability](interoperability.md) +- [Working with ANN indexes](working_with_ann_indexes.md) ------- - -## Memory management - -Centralized memory management allows flexible configuration of allocation strategies, such as sharing the same CUDA memory pool across library boundaries. cuVS uses the [RMM](https://github.com/rapidsai/rmm) library, which eases the burden of configuring different allocation strategies globally across GPU-accelerated libraries. - -RMM currently has APIs for C++ and Python. - -### C++ - -Here's an example of configuring RMM to use a pool allocator in C++ (derived from the RMM example [here](https://github.com/rapidsai/rmm?tab=readme-ov-file#example)): - -```c++ -rmm::mr::cuda_memory_resource cuda_mr; -// Construct a resource that uses a coalescing best-fit pool allocator -// With the pool initially half of available device memory -auto initial_size = rmm::percent_of_free_device_memory(50); -rmm::mr::pool_memory_resource pool_mr{&cuda_mr, initial_size}; -rmm::mr::set_current_device_resource(&pool_mr); // Updates the current device resource pointer to `pool_mr` -rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource(); // Points to `pool_mr` -``` - -### Python - -And the corresponding code in Python (derived from the RMM example [here](https://github.com/rapidsai/rmm?tab=readme-ov-file#memoryresource-objects)): -```python -import rmm -pool = rmm.mr.PoolMemoryResource( - rmm.mr.CudaMemoryResource(), - initial_pool_size=2**30, - maximum_pool_size=2**32) -rmm.mr.set_current_device_resource(pool) -``` - - -## Resource management - -cuVS uses an API from the [RAFT](https://github.com/rapidsai/raft) library of ML and data mining primitives to centralize and reuse expensive resources, such as memory management. The below code examples demonstrate how to create these resources for use throughout this guide. - -See RAFT's [resource API documentation](https://docs.rapids.ai/api/raft/nightly/cpp_api/core_resources/) for more information. - -### C - -```c -#include -#include - -cuvsResources_t res; -cuvsResourcesCreate(&res); - -// ... do some processing ... - -cuvsResourcesDestroy(res); -``` - -### C++ - -```c++ -#include - -raft::device_resources res; -``` - -### Python - -```Python -import pylibraft - -res = pylibraft.common.DeviceResources() -``` - -### Rust - - - - -## Multi-dimensional array formats and interoperability - - -### DLPack (C) - - - -### Multi-dimensional span (C++) - -cuVS is built on top of the GPU-accelerated machine learning and data mining primitives in the [RAFT](https://github.com/rapidsai/raft) library. Most of the C++ APIs in cuVS accept [mdspan](https://arxiv.org/abs/2010.06474) multi-dimensional array view for representing data in higher dimensions similar to the `ndarray` in the Numpy Python library. RAFT also contains the corresponding owning `mdarray` structure, which simplifies the allocation and management of multi-dimensional data in both host and device (GPU) memory. - -The `mdarray` is an owning object that forms a convenience layer over RMM and can be constructed in RAFT using a number of different helper functions: - -```c++ -#include - -int n_rows = 10; -int n_cols = 10; - -auto scalar = raft::make_device_scalar(handle, 1.0); -auto vector = raft::make_device_vector(handle, n_cols); -auto matrix = raft::make_device_matrix(handle, n_rows, n_cols); -``` - -The `mdspan` is a lightweight non-owning view that can wrap around any pointer, maintaining shape, layout, and indexing information for accessing elements. - -We can construct `mdspan` instances directly from the above `mdarray` instances: - -```c++ -// Scalar mdspan on device -auto scalar_view = scalar.view(); - -// Vector mdspan on device -auto vector_view = vector.view(); - -// Matrix mdspan on device -auto matrix_view = matrix.view(); -``` -Since the `mdspan` is just a lightweight wrapper, we can also construct it from the underlying data handles in the `mdarray` instances above. We use the extent to get information about the `mdarray` or `mdspan`'s shape. - -```c++ -#include - -auto scalar_view = raft::make_device_scalar_view(scalar.data_handle()); -auto vector_view = raft::make_device_vector_view(vector.data_handle(), vector.extent(0)); -auto matrix_view = raft::make_device_matrix_view(matrix.data_handle(), matrix.extent(0), matrix.extent(1)); -``` - -Of course, RAFT's `mdspan`/`mdarray` APIs aren't just limited to the `device`. You can also create `host` variants: - -```c++ -#include -#include - -int n_rows = 10; -int n_cols = 10; - -auto scalar = raft::make_host_scalar(handle, 1.0); -auto vector = raft::make_host_vector(handle, n_cols); -auto matrix = raft::make_host_matrix(handle, n_rows, n_cols); - -auto scalar_view = raft::make_host_scalar_view(scalar.data_handle()); -auto vector_view = raft::make_host_vector_view(vector.data_handle(), vector.extent(0)); -auto matrix_view = raft::make_host_matrix_view(matrix.data_handle(), matrix.extent(0), matrix.extent(1)); -``` - -Please refer to RAFT's `mdspan` [documentation](https://docs.rapids.ai/api/raft/stable/cpp_api/mdspan/) to learn more. - - -### CUDA array interface (Python) - - - -## Working with ANN indexes - - - -### Building an index - -### Searching an index - -### CPU/GPU interoperability - -### Serializing an index \ No newline at end of file +------ \ No newline at end of file diff --git a/docs/source/interoperability.md b/docs/source/interoperability.md new file mode 100644 index 000000000..b5604baec --- /dev/null +++ b/docs/source/interoperability.md @@ -0,0 +1,78 @@ +# Interoperability + +## Contents + +- [DLPack (C)](#dlpack-c) +- [Multi-dimensional span (C++)](#multi-dimensional-span-c) +- [CUDA array interface (Python)](#cuda-array-interface-python) + +------ + +## Interoperability + +### DLPack (C) + +### Multi-dimensional span (C++) + +cuVS is built on top of the GPU-accelerated machine learning and data mining primitives in the [RAFT](https://github.com/rapidsai/raft) library. Most of the C++ APIs in cuVS accept [mdspan](https://arxiv.org/abs/2010.06474) multi-dimensional array view for representing data in higher dimensions similar to the `ndarray` in the Numpy Python library. RAFT also contains the corresponding owning `mdarray` structure, which simplifies the allocation and management of multi-dimensional data in both host and device (GPU) memory. + +The `mdarray` is an owning object that forms a convenience layer over RMM and can be constructed in RAFT using a number of different helper functions: + +```c++ +#include + +int n_rows = 10; +int n_cols = 10; + +auto scalar = raft::make_device_scalar(handle, 1.0); +auto vector = raft::make_device_vector(handle, n_cols); +auto matrix = raft::make_device_matrix(handle, n_rows, n_cols); +``` + +The `mdspan` is a lightweight non-owning view that can wrap around any pointer, maintaining shape, layout, and indexing information for accessing elements. + +We can construct `mdspan` instances directly from the above `mdarray` instances: + +```c++ +// Scalar mdspan on device +auto scalar_view = scalar.view(); + +// Vector mdspan on device +auto vector_view = vector.view(); + +// Matrix mdspan on device +auto matrix_view = matrix.view(); +``` +Since the `mdspan` is just a lightweight wrapper, we can also construct it from the underlying data handles in the `mdarray` instances above. We use the extent to get information about the `mdarray` or `mdspan`'s shape. + +```c++ +#include + +auto scalar_view = raft::make_device_scalar_view(scalar.data_handle()); +auto vector_view = raft::make_device_vector_view(vector.data_handle(), vector.extent(0)); +auto matrix_view = raft::make_device_matrix_view(matrix.data_handle(), matrix.extent(0), matrix.extent(1)); +``` + +Of course, RAFT's `mdspan`/`mdarray` APIs aren't just limited to the `device`. You can also create `host` variants: + +```c++ +#include +#include + +int n_rows = 10; +int n_cols = 10; + +auto scalar = raft::make_host_scalar(handle, 1.0); +auto vector = raft::make_host_vector(handle, n_cols); +auto matrix = raft::make_host_matrix(handle, n_rows, n_cols); + +auto scalar_view = raft::make_host_scalar_view(scalar.data_handle()); +auto vector_view = raft::make_host_vector_view(vector.data_handle(), vector.extent(0)); +auto matrix_view = raft::make_host_matrix_view(matrix.data_handle(), matrix.extent(0), matrix.extent(1)); +``` + +Please refer to RAFT's `mdspan` [documentation](https://docs.rapids.ai/api/raft/stable/cpp_api/mdspan/) to learn more. + + +### CUDA array interface (Python) + diff --git a/docs/source/working_with_ann_indexes.md b/docs/source/working_with_ann_indexes.md new file mode 100644 index 000000000..58f9a20bf --- /dev/null +++ b/docs/source/working_with_ann_indexes.md @@ -0,0 +1,21 @@ +# Working with ANN Indexes + +## Table of Contents + +- [Working with ANN indexes](#working-with-ann-indexes) + - [Building an index](#building-an-index) + - [Searching an index](#searching-an-index) + - [CPU/GPU Interoperability](#cpu-gpu-interoperability) + - [Serializing an index](#serializing-an-index) + +------ + +## Working with ANN indexes + +### Building an index + +### Searching an index + +### CPU/GPU interoperability + +### Serializing an index \ No newline at end of file From 3a79601c7db648895b6c768f4b87c831d1604ee1 Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Tue, 12 Mar 2024 16:35:38 -0400 Subject: [PATCH 17/25] MOre updates --- docs/source/basics.md | 81 --------------------- docs/source/basics.rst | 91 ++++++++++++++++++++++++ docs/source/getting_started.md | 11 --- docs/source/getting_started.rst | 12 ++++ docs/source/index.rst | 3 +- docs/source/integrations.md | 9 --- docs/source/integrations.rst | 13 ++++ docs/source/interoperability.md | 78 -------------------- docs/source/interoperability.rst | 72 +++++++++++++++++++ docs/source/working_with_ann_indexes.md | 21 ------ docs/source/working_with_ann_indexes.rst | 19 +++++ 11 files changed, 209 insertions(+), 201 deletions(-) delete mode 100644 docs/source/basics.md create mode 100644 docs/source/basics.rst delete mode 100644 docs/source/getting_started.md create mode 100644 docs/source/getting_started.rst delete mode 100644 docs/source/integrations.md create mode 100644 docs/source/integrations.rst delete mode 100644 docs/source/interoperability.md create mode 100644 docs/source/interoperability.rst delete mode 100644 docs/source/working_with_ann_indexes.md create mode 100644 docs/source/working_with_ann_indexes.rst diff --git a/docs/source/basics.md b/docs/source/basics.md deleted file mode 100644 index df2e533bd..000000000 --- a/docs/source/basics.md +++ /dev/null @@ -1,81 +0,0 @@ -# cuVS API Basics - -## Contents - -- [Memory management](#memory-management) -- [Resource management](#resource-management) - ------- - -## Memory management - -Centralized memory management allows flexible configuration of allocation strategies, such as sharing the same CUDA memory pool across library boundaries. cuVS uses the [RMM](https://github.com/rapidsai/rmm) library, which eases the burden of configuring different allocation strategies globally across GPU-accelerated libraries. - -RMM currently has APIs for C++ and Python. - -### C++ - -Here's an example of configuring RMM to use a pool allocator in C++ (derived from the RMM example [here](https://github.com/rapidsai/rmm?tab=readme-ov-file#example)): - -```c++ -rmm::mr::cuda_memory_resource cuda_mr; -// Construct a resource that uses a coalescing best-fit pool allocator -// With the pool initially half of available device memory -auto initial_size = rmm::percent_of_free_device_memory(50); -rmm::mr::pool_memory_resource pool_mr{&cuda_mr, initial_size}; -rmm::mr::set_current_device_resource(&pool_mr); // Updates the current device resource pointer to `pool_mr` -rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource(); // Points to `pool_mr` -``` - -### Python - -And the corresponding code in Python (derived from the RMM example [here](https://github.com/rapidsai/rmm?tab=readme-ov-file#memoryresource-objects)): -```python -import rmm -pool = rmm.mr.PoolMemoryResource( - rmm.mr.CudaMemoryResource(), - initial_pool_size=2**30, - maximum_pool_size=2**32) -rmm.mr.set_current_device_resource(pool) -``` - - -## Resource management - -cuVS uses an API from the [RAFT](https://github.com/rapidsai/raft) library of ML and data mining primitives to centralize and reuse expensive resources, such as memory management. The below code examples demonstrate how to create these resources for use throughout this guide. - -See RAFT's [resource API documentation](https://docs.rapids.ai/api/raft/nightly/cpp_api/core_resources/) for more information. - -### C - -```c -#include -#include - -cuvsResources_t res; -cuvsResourcesCreate(&res); - -// ... do some processing ... - -cuvsResourcesDestroy(res); -``` - -### C++ - -```c++ -#include - -raft::device_resources res; -``` - -### Python - -```Python -import pylibraft - -res = pylibraft.common.DeviceResources() -``` - -### Rust - - diff --git a/docs/source/basics.rst b/docs/source/basics.rst new file mode 100644 index 000000000..920e2c59e --- /dev/null +++ b/docs/source/basics.rst @@ -0,0 +1,91 @@ +cuVS API Basics +=============== + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + `Memory management`_ + `Resource management`_ + +Memory management +----------------- + +Centralized memory management allows flexible configuration of allocation strategies, such as sharing the same CUDA memory pool across library boundaries. cuVS uses the [RMM](https://github.com/rapidsai/rmm) library, which eases the burden of configuring different allocation strategies globally across GPU-accelerated libraries. + +RMM currently has APIs for C++ and Python. + +C++ +^^^ + +Here's an example of configuring RMM to use a pool allocator in C++ (derived from the RMM example [here](https://github.com/rapidsai/rmm?tab=readme-ov-file#example)): + +.. code-block:: c++ + + rmm::mr::cuda_memory_resource cuda_mr; + // Construct a resource that uses a coalescing best-fit pool allocator + // With the pool initially half of available device memory + auto initial_size = rmm::percent_of_free_device_memory(50); + rmm::mr::pool_memory_resource pool_mr{&cuda_mr, initial_size}; + rmm::mr::set_current_device_resource(&pool_mr); // Updates the current device resource pointer to `pool_mr` + rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource(); // Points to `pool_mr` + +Python +^^^^^^ + +And the corresponding code in Python (derived from the RMM example [here](https://github.com/rapidsai/rmm?tab=readme-ov-file#memoryresource-objects)): + +.. code-block:: python + + import rmm + pool = rmm.mr.PoolMemoryResource( + rmm.mr.CudaMemoryResource(), + initial_pool_size=2**30, + maximum_pool_size=2**32) + rmm.mr.set_current_device_resource(pool) + + +Resource management +------------------- + +cuVS uses an API from the [RAFT](https://github.com/rapidsai/raft) library of ML and data mining primitives to centralize and reuse expensive resources, such as memory management. The below code examples demonstrate how to create these resources for use throughout this guide. + +See RAFT's [resource API documentation](https://docs.rapids.ai/api/raft/nightly/cpp_api/core_resources/) for more information. + +C +^ + +.. code-block:: c + + #include + #include + + cuvsResources_t res; + cuvsResourcesCreate(&res); + + // ... do some processing ... + + cuvsResourcesDestroy(res); + +C++ +^^^ + +.. code-block:: c++ + + #include + + raft::device_resources res; + +Python +^^^^^^ + +.. code-block:: python + + import pylibraft + + res = pylibraft.common.DeviceResources() + + +Rust +^^^^ + diff --git a/docs/source/getting_started.md b/docs/source/getting_started.md deleted file mode 100644 index d9a536000..000000000 --- a/docs/source/getting_started.md +++ /dev/null @@ -1,11 +0,0 @@ -# Getting Started - -This guide provides an initial starting point of the basic concepts and using the various APIs in the cuVS software development kit. - -## Contents - -- [cuVS API Basics](basics.md) -- [Interoperability](interoperability.md) -- [Working with ANN indexes](working_with_ann_indexes.md) - ------- \ No newline at end of file diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst new file mode 100644 index 000000000..79b35c2d5 --- /dev/null +++ b/docs/source/getting_started.rst @@ -0,0 +1,12 @@ +Getting Started +=============== + +This guide provides an initial starting point of the basic concepts and using the various APIs in the cuVS software development kit. + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + basics.rst + interoperability.rst + working_with_ann_indexes.rst \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index da92786a0..d06929eec 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -21,7 +21,8 @@ cuVS is a library for vector search and clustering on the GPU. :maxdepth: 1 :caption: Contents: - getting_started.md + getting_started.rst + integrations.rst build.md api_docs.rst contributing.md diff --git a/docs/source/integrations.md b/docs/source/integrations.md deleted file mode 100644 index 56f93535d..000000000 --- a/docs/source/integrations.md +++ /dev/null @@ -1,9 +0,0 @@ -# Integrations - -In addition to using cuVS through any one of its different language APIs - -## FAISS - -## Milvus - -## Kinetica diff --git a/docs/source/integrations.rst b/docs/source/integrations.rst new file mode 100644 index 000000000..a5a28d819 --- /dev/null +++ b/docs/source/integrations.rst @@ -0,0 +1,13 @@ +Integrations +============ + +In addition to using cuVS through any one of its different language APIs + +FAISS +----- + +Milvus +------ + +Kinetica +-------- diff --git a/docs/source/interoperability.md b/docs/source/interoperability.md deleted file mode 100644 index b5604baec..000000000 --- a/docs/source/interoperability.md +++ /dev/null @@ -1,78 +0,0 @@ -# Interoperability - -## Contents - -- [DLPack (C)](#dlpack-c) -- [Multi-dimensional span (C++)](#multi-dimensional-span-c) -- [CUDA array interface (Python)](#cuda-array-interface-python) - ------- - -## Interoperability - -### DLPack (C) - -### Multi-dimensional span (C++) - -cuVS is built on top of the GPU-accelerated machine learning and data mining primitives in the [RAFT](https://github.com/rapidsai/raft) library. Most of the C++ APIs in cuVS accept [mdspan](https://arxiv.org/abs/2010.06474) multi-dimensional array view for representing data in higher dimensions similar to the `ndarray` in the Numpy Python library. RAFT also contains the corresponding owning `mdarray` structure, which simplifies the allocation and management of multi-dimensional data in both host and device (GPU) memory. - -The `mdarray` is an owning object that forms a convenience layer over RMM and can be constructed in RAFT using a number of different helper functions: - -```c++ -#include - -int n_rows = 10; -int n_cols = 10; - -auto scalar = raft::make_device_scalar(handle, 1.0); -auto vector = raft::make_device_vector(handle, n_cols); -auto matrix = raft::make_device_matrix(handle, n_rows, n_cols); -``` - -The `mdspan` is a lightweight non-owning view that can wrap around any pointer, maintaining shape, layout, and indexing information for accessing elements. - -We can construct `mdspan` instances directly from the above `mdarray` instances: - -```c++ -// Scalar mdspan on device -auto scalar_view = scalar.view(); - -// Vector mdspan on device -auto vector_view = vector.view(); - -// Matrix mdspan on device -auto matrix_view = matrix.view(); -``` -Since the `mdspan` is just a lightweight wrapper, we can also construct it from the underlying data handles in the `mdarray` instances above. We use the extent to get information about the `mdarray` or `mdspan`'s shape. - -```c++ -#include - -auto scalar_view = raft::make_device_scalar_view(scalar.data_handle()); -auto vector_view = raft::make_device_vector_view(vector.data_handle(), vector.extent(0)); -auto matrix_view = raft::make_device_matrix_view(matrix.data_handle(), matrix.extent(0), matrix.extent(1)); -``` - -Of course, RAFT's `mdspan`/`mdarray` APIs aren't just limited to the `device`. You can also create `host` variants: - -```c++ -#include -#include - -int n_rows = 10; -int n_cols = 10; - -auto scalar = raft::make_host_scalar(handle, 1.0); -auto vector = raft::make_host_vector(handle, n_cols); -auto matrix = raft::make_host_matrix(handle, n_rows, n_cols); - -auto scalar_view = raft::make_host_scalar_view(scalar.data_handle()); -auto vector_view = raft::make_host_vector_view(vector.data_handle(), vector.extent(0)); -auto matrix_view = raft::make_host_matrix_view(matrix.data_handle(), matrix.extent(0), matrix.extent(1)); -``` - -Please refer to RAFT's `mdspan` [documentation](https://docs.rapids.ai/api/raft/stable/cpp_api/mdspan/) to learn more. - - -### CUDA array interface (Python) - diff --git a/docs/source/interoperability.rst b/docs/source/interoperability.rst new file mode 100644 index 000000000..ac3c3f3ad --- /dev/null +++ b/docs/source/interoperability.rst @@ -0,0 +1,72 @@ +Interoperability +================ + +DLPack (C) +^^^^^^^^^^ + +Multi-dimensional span (C++) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +cuVS is built on top of the GPU-accelerated machine learning and data mining primitives in the [RAFT](https://github.com/rapidsai/raft) library. Most of the C++ APIs in cuVS accept [mdspan](https://arxiv.org/abs/2010.06474) multi-dimensional array view for representing data in higher dimensions similar to the `ndarray` in the Numpy Python library. RAFT also contains the corresponding owning `mdarray` structure, which simplifies the allocation and management of multi-dimensional data in both host and device (GPU) memory. + +The `mdarray` is an owning object that forms a convenience layer over RMM and can be constructed in RAFT using a number of different helper functions: + +.. code-block:: c++ + + #include + + int n_rows = 10; + int n_cols = 10; + + auto scalar = raft::make_device_scalar(handle, 1.0); + auto vector = raft::make_device_vector(handle, n_cols); + auto matrix = raft::make_device_matrix(handle, n_rows, n_cols); + +The `mdspan` is a lightweight non-owning view that can wrap around any pointer, maintaining shape, layout, and indexing information for accessing elements. + +We can construct `mdspan` instances directly from the above `mdarray` instances: + +.. code-block:: c++ + + // Scalar mdspan on device + auto scalar_view = scalar.view(); + + // Vector mdspan on device + auto vector_view = vector.view(); + + // Matrix mdspan on device + auto matrix_view = matrix.view(); + +Since the `mdspan` is just a lightweight wrapper, we can also construct it from the underlying data handles in the `mdarray` instances above. We use the extent to get information about the `mdarray` or `mdspan`'s shape. + +.. code-block:: c++ + + #include + + auto scalar_view = raft::make_device_scalar_view(scalar.data_handle()); + auto vector_view = raft::make_device_vector_view(vector.data_handle(), vector.extent(0)); + auto matrix_view = raft::make_device_matrix_view(matrix.data_handle(), matrix.extent(0), matrix.extent(1)); + +Of course, RAFT's `mdspan`/`mdarray` APIs aren't just limited to the `device`. You can also create `host` variants: + +.. code-block:: c++ + + #include + #include + + int n_rows = 10; + int n_cols = 10; + + auto scalar = raft::make_host_scalar(handle, 1.0); + auto vector = raft::make_host_vector(handle, n_cols); + auto matrix = raft::make_host_matrix(handle, n_rows, n_cols); + + auto scalar_view = raft::make_host_scalar_view(scalar.data_handle()); + auto vector_view = raft::make_host_vector_view(vector.data_handle(), vector.extent(0)); + auto matrix_view = raft::make_host_matrix_view(matrix.data_handle(), matrix.extent(0), matrix.extent(1)); + +Please refer to RAFT's `mdspan` [documentation](https://docs.rapids.ai/api/raft/stable/cpp_api/mdspan/) to learn more. + + +CUDA array interface (Python) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/source/working_with_ann_indexes.md b/docs/source/working_with_ann_indexes.md deleted file mode 100644 index 58f9a20bf..000000000 --- a/docs/source/working_with_ann_indexes.md +++ /dev/null @@ -1,21 +0,0 @@ -# Working with ANN Indexes - -## Table of Contents - -- [Working with ANN indexes](#working-with-ann-indexes) - - [Building an index](#building-an-index) - - [Searching an index](#searching-an-index) - - [CPU/GPU Interoperability](#cpu-gpu-interoperability) - - [Serializing an index](#serializing-an-index) - ------- - -## Working with ANN indexes - -### Building an index - -### Searching an index - -### CPU/GPU interoperability - -### Serializing an index \ No newline at end of file diff --git a/docs/source/working_with_ann_indexes.rst b/docs/source/working_with_ann_indexes.rst new file mode 100644 index 000000000..ad4ebfcce --- /dev/null +++ b/docs/source/working_with_ann_indexes.rst @@ -0,0 +1,19 @@ +Working with ANN Indexes +======================== + +- `Building an index`_ +- `Searching an index`_ +- `CPU/GPU Interoperability`_ +- `Serializing an index`_ + +Building an index +----------------- + +Searching an index +------------------ + +CPU/GPU interoperability +------------------------ + +Serializing an index +-------------------- \ No newline at end of file From ba7c1a72c973bf24a7b67e12324a107290b1685b Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Tue, 12 Mar 2024 19:04:25 -0400 Subject: [PATCH 18/25] Adding integrations page --- README.md | 9 ++++----- docs/source/basics.rst | 3 +-- docs/source/getting_started.rst | 2 +- docs/source/index.rst | 2 +- docs/source/integrations.rst | 33 ++++++++++++++++++++++++++++++++- 5 files changed, 39 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 14bb02812..38b545ab7 100755 --- a/README.md +++ b/README.md @@ -8,13 +8,12 @@ 4. [Getting Started](#getting-started) 5. [Contributing](#contributing) 6. [References](#references) - +` ## Useful Resources -- [cuVS Reference Documentation](https://docs.rapids.ai/api/cuvs/stable/): API Documentation. -- [cuVS Getting Started](./docs/source/quick_start.md): Getting started with RAFT. -- [Build and Install cuVS](./docs/source/build.md): Instructions for installing and building cuVS. -- [Example Notebooks](./notebooks): Example jupyer notebooks +- [API Reference Documentation](https://docs.rapids.ai/api/cuvs/nightly/api_docs): API Documentation. +- [Getting Started Guide](https://docs.rapids.ai/api/cuvs/nightly/getting_started): Getting started with RAFT. +- [Build and Install Guide](https://docs.rapids.ai/api/cuvs/nightly/build): Instructions for installing and building cuVS. - [RAPIDS Community](https://rapids.ai/community.html): Get help, contribute, and collaborate. - [GitHub repository](https://github.com/rapidsai/cuvs): Download the cuVS source code. - [Issue tracker](https://github.com/rapidsai/cuvs/issues): Report issues or request features. diff --git a/docs/source/basics.rst b/docs/source/basics.rst index 920e2c59e..fb3eb57cc 100644 --- a/docs/source/basics.rst +++ b/docs/source/basics.rst @@ -3,7 +3,7 @@ cuVS API Basics .. toctree:: :maxdepth: 1 - :caption: Contents: + :caption: Table of contents: `Memory management`_ `Resource management`_ @@ -88,4 +88,3 @@ Python Rust ^^^^ - diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 79b35c2d5..2d6f2bd59 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -5,7 +5,7 @@ This guide provides an initial starting point of the basic concepts and using th .. toctree:: :maxdepth: 1 - :caption: Contents: + :caption: Table of contents: basics.rst interoperability.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index d06929eec..afb4847da 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -19,7 +19,7 @@ cuVS is a library for vector search and clustering on the GPU. .. toctree:: :maxdepth: 1 - :caption: Contents: + :caption: Table of contents: getting_started.rst integrations.rst diff --git a/docs/source/integrations.rst b/docs/source/integrations.rst index a5a28d819..770d32faa 100644 --- a/docs/source/integrations.rst +++ b/docs/source/integrations.rst @@ -1,13 +1,44 @@ Integrations ============ -In addition to using cuVS through any one of its different language APIs +Aside from using cuVS directly, it can be consumed through a number of sdk and vector database integrations. + +.. toctree:: + :maxdepth: 1 + :caption: Table of contents: + + `FAISS`_ + `Milvus`_ + `Kinetica`_ FAISS ----- +FAISS v1.8 provides a special conda package that enables a RAFT backend for the Flat, IVF-Flat and IVF-PQ indexes on the GPU. Like the classical FAISS GPU indexes, the RAFT backend also enables interoperability between FAISS CPU indexes, allowing an index to be trained on GPU, searched on CPU, and vice versa. + +The RAFT backend can be enabled by building FAISS from source with the `FAISS_USE_RAFT` cmake flag enabled and setting the `use_raft` configuration option for the RAFT-enabled GPU indexes. + +A pre-compiled conda package can also be installed using the following command: + +.. code-block:: bash + + conda install -c conda-forge -c pytorch -c rapidsai -c nvidia -c "nvidia/label/cuda-11.8.0" faiss-gpu-raft + +The next release of FAISS will feature cuVS support as we continue to migrate the vector search algorithms from RAFT to cuVS. + Milvus ------ +In version 2.3, Milvus released support for IVF-Flat and IVF-PQ indexes on the GPU through RAFT. Version 2.4 adds support for brute-force and the graph-based CAGRA index on the GPU. Please refer to the `Milvus documentation ` to install Milvus with GPU support. + +The GPU indexes can be enabled by using the index types prefixed with `GPU_`, as outlined in the `Milvus index build guide `. + +Milvus will be migrating their GPU support from RAFT to cuVS as we continue to move the vector search algorithms out of RAFT and into cuVS. + + Kinetica -------- + +Starting with release 7.2, Kinetica supports the graph-based the CAGRA algorithm from RAFT. Kinetica will continue to improve its support over coming versions, while also migrating to cuVS as we work to move the vector search algorithms out of RAFT and into cuVS. + +Kinetica currently offers the ability to create a CAGRA index in a SQL `CREATE_TABLE` statement, as outlined in their `vector search indexing docs `. Kinetica is not open source, but the RAFT indexes can be enabled in the developer edition, which can be installed `here `. \ No newline at end of file From ed5b81cdac810cc3dea6f3f89229ff7028ff8b07 Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Tue, 12 Mar 2024 19:42:36 -0400 Subject: [PATCH 19/25] More updates to integrations --- .gitignore | 1 + docs/source/basics.rst | 8 ++------ docs/source/getting_started.rst | 2 +- docs/source/index.rst | 2 +- docs/source/integrations.rst | 10 +++------- 5 files changed, 8 insertions(+), 15 deletions(-) diff --git a/.gitignore b/.gitignore index 8cac2b5ae..1624aadbb 100644 --- a/.gitignore +++ b/.gitignore @@ -61,6 +61,7 @@ _xml # sphinx _html _text +_static/rust # clang tooling compile_commands.json diff --git a/docs/source/basics.rst b/docs/source/basics.rst index fb3eb57cc..9d0bbeec1 100644 --- a/docs/source/basics.rst +++ b/docs/source/basics.rst @@ -1,12 +1,8 @@ cuVS API Basics =============== -.. toctree:: - :maxdepth: 1 - :caption: Table of contents: - - `Memory management`_ - `Resource management`_ +- `Memory management`_ +- `Resource management`_ Memory management ----------------- diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 2d6f2bd59..79b35c2d5 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -5,7 +5,7 @@ This guide provides an initial starting point of the basic concepts and using th .. toctree:: :maxdepth: 1 - :caption: Table of contents: + :caption: Contents: basics.rst interoperability.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index afb4847da..d06929eec 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -19,7 +19,7 @@ cuVS is a library for vector search and clustering on the GPU. .. toctree:: :maxdepth: 1 - :caption: Table of contents: + :caption: Contents: getting_started.rst integrations.rst diff --git a/docs/source/integrations.rst b/docs/source/integrations.rst index 770d32faa..d61a7bb92 100644 --- a/docs/source/integrations.rst +++ b/docs/source/integrations.rst @@ -3,13 +3,9 @@ Integrations Aside from using cuVS directly, it can be consumed through a number of sdk and vector database integrations. -.. toctree:: - :maxdepth: 1 - :caption: Table of contents: - - `FAISS`_ - `Milvus`_ - `Kinetica`_ +- `FAISS`_ +- `Milvus`_ +- `Kinetica`_ FAISS ----- From 3841bad966141c02b152caec8e277fca07abdd9e Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Tue, 12 Mar 2024 19:43:20 -0400 Subject: [PATCH 20/25] Exlcluding rust docs dir --- .gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 1624aadbb..9fcde3fb3 100644 --- a/.gitignore +++ b/.gitignore @@ -61,7 +61,7 @@ _xml # sphinx _html _text -_static/rust +docs/source/_static/rust # clang tooling compile_commands.json From 841d5ec1ccd3cf63946278336258d918b2a8fec3 Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Tue, 12 Mar 2024 19:46:28 -0400 Subject: [PATCH 21/25] Fixing links --- docs/source/integrations.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/integrations.rst b/docs/source/integrations.rst index d61a7bb92..6c6e2ce8c 100644 --- a/docs/source/integrations.rst +++ b/docs/source/integrations.rst @@ -25,9 +25,9 @@ The next release of FAISS will feature cuVS support as we continue to migrate th Milvus ------ -In version 2.3, Milvus released support for IVF-Flat and IVF-PQ indexes on the GPU through RAFT. Version 2.4 adds support for brute-force and the graph-based CAGRA index on the GPU. Please refer to the `Milvus documentation ` to install Milvus with GPU support. +In version 2.3, Milvus released support for IVF-Flat and IVF-PQ indexes on the GPU through RAFT. Version 2.4 adds support for brute-force and the graph-based CAGRA index on the GPU. Please refer to the `Milvus documentation `_ to install Milvus with GPU support. -The GPU indexes can be enabled by using the index types prefixed with `GPU_`, as outlined in the `Milvus index build guide `. +The GPU indexes can be enabled by using the index types prefixed with `GPU_`, as outlined in the `Milvus index build guide `_. Milvus will be migrating their GPU support from RAFT to cuVS as we continue to move the vector search algorithms out of RAFT and into cuVS. @@ -37,4 +37,4 @@ Kinetica Starting with release 7.2, Kinetica supports the graph-based the CAGRA algorithm from RAFT. Kinetica will continue to improve its support over coming versions, while also migrating to cuVS as we work to move the vector search algorithms out of RAFT and into cuVS. -Kinetica currently offers the ability to create a CAGRA index in a SQL `CREATE_TABLE` statement, as outlined in their `vector search indexing docs `. Kinetica is not open source, but the RAFT indexes can be enabled in the developer edition, which can be installed `here `. \ No newline at end of file +Kinetica currently offers the ability to create a CAGRA index in a SQL `CREATE_TABLE` statement, as outlined in their `vector search indexing docs `_. Kinetica is not open source, but the RAFT indexes can be enabled in the developer edition, which can be installed `here `_. \ No newline at end of file From 011af028539d401df2e53ed8ff957c1cc514b7ff Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Tue, 12 Mar 2024 19:48:21 -0400 Subject: [PATCH 22/25] Fixing more links --- docs/source/basics.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/basics.rst b/docs/source/basics.rst index 9d0bbeec1..94418f636 100644 --- a/docs/source/basics.rst +++ b/docs/source/basics.rst @@ -14,7 +14,7 @@ RMM currently has APIs for C++ and Python. C++ ^^^ -Here's an example of configuring RMM to use a pool allocator in C++ (derived from the RMM example [here](https://github.com/rapidsai/rmm?tab=readme-ov-file#example)): +Here's an example of configuring RMM to use a pool allocator in C++ (derived from the RMM example `here `_): .. code-block:: c++ @@ -29,7 +29,7 @@ Here's an example of configuring RMM to use a pool allocator in C++ (derived fro Python ^^^^^^ -And the corresponding code in Python (derived from the RMM example [here](https://github.com/rapidsai/rmm?tab=readme-ov-file#memoryresource-objects)): +And the corresponding code in Python (derived from the RMM example `here `_): .. code-block:: python @@ -44,9 +44,9 @@ And the corresponding code in Python (derived from the RMM example [here](https: Resource management ------------------- -cuVS uses an API from the [RAFT](https://github.com/rapidsai/raft) library of ML and data mining primitives to centralize and reuse expensive resources, such as memory management. The below code examples demonstrate how to create these resources for use throughout this guide. +cuVS uses an API from the `RAFT `_ library of ML and data mining primitives to centralize and reuse expensive resources, such as memory management. The below code examples demonstrate how to create these resources for use throughout this guide. -See RAFT's [resource API documentation](https://docs.rapids.ai/api/raft/nightly/cpp_api/core_resources/) for more information. +See RAFT's `resource API documentation `_ for more information. C ^ From b121d328173ff1d3167a2d7b2fc4954411523a9e Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Tue, 12 Mar 2024 20:20:28 -0400 Subject: [PATCH 23/25] Converting build and install guide to rst --- README.md | 3 +- docs/source/build.md | 178 ----------------------- docs/source/build.rst | 233 +++++++++++++++++++++++++++++++ docs/source/index.rst | 4 +- docs/source/interoperability.rst | 4 +- 5 files changed, 239 insertions(+), 183 deletions(-) delete mode 100644 docs/source/build.md create mode 100644 docs/source/build.rst diff --git a/README.md b/README.md index 38b545ab7..4a2d2de16 100755 --- a/README.md +++ b/README.md @@ -8,9 +8,10 @@ 4. [Getting Started](#getting-started) 5. [Contributing](#contributing) 6. [References](#references) -` + ## Useful Resources +- [Code Examples](https://github.com/rapidsai/cuvs/tree/HEAD/examples): Self-contained Code Examples. - [API Reference Documentation](https://docs.rapids.ai/api/cuvs/nightly/api_docs): API Documentation. - [Getting Started Guide](https://docs.rapids.ai/api/cuvs/nightly/getting_started): Getting started with RAFT. - [Build and Install Guide](https://docs.rapids.ai/api/cuvs/nightly/build): Instructions for installing and building cuVS. diff --git a/docs/source/build.md b/docs/source/build.md deleted file mode 100644 index 5b36f12fc..000000000 --- a/docs/source/build.md +++ /dev/null @@ -1,178 +0,0 @@ -# Installation - -The cuVS software development kit provides APIs for C, C++, Python, and Rust languages. This guide outlines how to install the pre-compiled packages, build it from source, and use it in downstream applications. - -## Table of Contents - -- [Install pre-compiled packages](#installing-precompiled-packages) - - [C, C++, and Python through Conda](#installing-through-conda) - - [Python through Pip](#installing-python-through-pip) - - [Rust through crates.io](#installing-rust-through-crates) -- [Build from source](#building-c-and-python-from-source) - - [Prerequisites](#build-prerequisites) - - [CUDA/GPU requirements](#cudagpu-requirements) - - [Build dependencies](#build-dependencies) - - [Required](#required) - - [Create a build environment](#creating-a-build-environment) - - [ccache and sccache](#ccache-and-sccache) - - [C/C++ Libraries](#c-library) - - [Building the Googletests](#building-the-googletests) - - [Python Library](#python-library) - - [Rust Library](#rust-library) - - [Using Cmake Directly](#using-cmake-directly) -- [Build Documentation](#build-documentation) -- [Use cuVS in your application](#use-cuvs-in-your-application) - ------- - -## Installing Pre-compiled Packages - -### C, C++, and Python through Conda - -The easiest way to install the pre-compiled C, C++, and Python packages is through [conda](https://docs.anaconda.com/free/miniconda/index.html). Use the following commands, depending on your CUDA version, to install cuVS packages (replace `rapidsai` with `rapidsai-nightly` to install more up-to-date but less stable nightly packages). `mamba` is preferred over the `conda` command. - -#### C++ Package -```bash -mamba install -c rapidsai -c conda-forge -c nvidia libcuvs cuda-version=12.0 -``` - -#### C Package -```bash -mamba install -c rapidsai -c conda-forge -c nvidia libcuvs_c cuda-version=12.0 -``` - -#### Python Package -```bash -mamba install -c rapidsai -c conda-forge -c nvidia cuvs cuda-version=12.0 -``` - -### Python through Pip - -The cuVS Python package can also be [installed through pip](https://rapids.ai/pip.html#install). - -For CUDA 11 packages: -```bash -pip install cuvs-cu11 --extra-index-url=https://pypi.nvidia.com -``` - -And CUDA 12 packages: -```bash -pip install cuvs-cu12 --extra-index-url=https://pypi.nvidia.com -``` - -Note: these packages statically link the C and C++ libraries so the `libcuvs` and `libcuvs_c` shared libraries won't be readily available to use in your code. - -### Rust through crates.io - -## Build from source - -The core cuVS source code is written in C++ and wrapped through a C API. The C API is wrapped around the C++ APIs and the other supported languages are built around the C API. - - -### Prerequisites - -- Cmake 3.26.4+ -- GCC 9.3+ (11.4+ recommended) -- CUDA Toolkit 11.4+ -- Volta architecture or better (compute capability >= 7.0) - -### Create a build environment - -[Conda](https://docs.anaconda.com/free/miniconda/index.html) environment scripts are provided for installing the necessary dependencies to build cuVS from source. It is preferred to use `mamba`, as it provides significant speedup over `conda`: -```bash -mamba env create --name cuvs -f conda/environments/all_cuda-120_arch-x86_64.yaml -mamba activate cuvs -``` - -The process for building from source with CUDA 11 differs slightly in that your host system will also need to have CUDA toolkit installed which is greater than, or equal to, the version you install into you conda environment. Installing CUDA toolkit into your host system is necessary because `nvcc` is not provided with Conda's cudatoolkit dependencies for CUDA 11. The following example will install create and install dependencies for a CUDA 11.8 conda environment -```bash -mamba env create --name cuvs -f conda/environments/all_cuda-118_arch-x86_64.yaml -mamba activate cuvs -``` - -The recommended way to build and install cuVS from source is to use the `build.sh` script in the root of the repository. This script can build both the C++ and Python artifacts and provides CMake options for building and installing the headers, tests, benchmarks, and the pre-compiled shared library. - - -### C and C++ libraries - -The C and C++ shared libraries are built together using the following arguments to `build.sh`: -```bash -./build.sh libcuvs -``` - -In above example the `libcuvs.so` and `libcuvs_c.so` shared libraries are installed by default into `$INSTALL_PREFIX/lib`. To disable this, pass `-n` flag. - -Once installed, the shared libraries, headers (and any dependencies downloaded and installed via `rapids-cmake`) can be uninstalled using `build.sh`: -```bash -./build.sh libcuvs --uninstall -``` - - -#### Building the Googletests - -Compile the C and C++ Googletests using the `tests` target in `build.sh`. - -```bash -./build.sh libcuvs tests -``` - -The tests will be written to the build directory, which is `cpp/build/` by default, and they will be named `*_TEST`. - -It can take some time to compile all of the tests. You can build individual tests by providing a semicolon-separated list to the `--limit-tests` option in `build.sh`. Make sure to pass the `-n` flag so the tests are not installed. - -```bash -./build.sh libcuvs tests -n --limit-tests=NEIGHBORS_TEST;CAGRA_C_TEST -``` - -### Python library - -The Python library should be built and installed using the `build.sh` script: - -```bash -./build.sh python -``` - -The Python packages can also be uninstalled using the `build.sh` script: -```bash -./build.sh python --uninstall -``` - -### Rust library - - - -### Using CMake directly - -When building cuVS from source, the `build.sh` script offers a nice wrapper around the `cmake` commands to ease the burdens of manually configuring the various available cmake options. When more fine-grained control over the CMake configuration is desired, the `cmake` command can be invoked directly as the below example demonstrates. - -The `CMAKE_INSTALL_PREFIX` installs cuVS into a specific location. The example below installs cuVS into the current Conda environment: -```bash -cd cpp -mkdir build -cd build -cmake -D BUILD_TESTS=ON -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX ../ -make -j install -``` - -cuVS has the following configurable cmake flags available: - -| Flag | Possible Values | Default Value | Behavior | -|------------------------|----------------------| --- |------------------------------------------------------------------------------| -| BUILD_TESTS | ON, OFF | ON | Compile Googletests | -| CUDA_ENABLE_KERNELINFO | ON, OFF | OFF | Enables `kernelinfo` in nvcc. This is useful for `compute-sanitizer` | -| CUDA_ENABLE_LINEINFO | ON, OFF | OFF | Enable the -lineinfo option for nvcc | -| CUDA_STATIC_RUNTIME | ON, OFF | OFF | Statically link the CUDA runtime | -| DETECT_CONDA_ENV | ON, OFF | ON | Enable detection of conda environment for dependencies | -| CUVS_NVTX | ON, OFF | OFF | Enable NVTX Markers | - -### Build documentation - -The documentation requires that the C, C++ and Python libraries have been built and installed. The following will build the docs along with the necessary libraries: - -``` -./build.sh libcuvs python docs -``` - -## Use cuVS in your application - -The [examples/](https://github.com/rapidsai/raft/tree/HEAD/examples) directory at the root of the cuVS repository has self-contains drop-in projects to build and use the cuVS SDK in your applications. diff --git a/docs/source/build.rst b/docs/source/build.rst new file mode 100644 index 000000000..814022465 --- /dev/null +++ b/docs/source/build.rst @@ -0,0 +1,233 @@ +Installation +============ + +The cuVS software development kit provides APIs for C, C++, Python, and Rust languages. This guide outlines how to install the pre-compiled packages, build it from source, and use it in downstream applications. + +- `Installing pre-compiled packages`_ + + * `C, C++, and Python through Conda`_ + + * `Python through Pip`_ + + * `Rust through crates.io`_ + +- `Build from source`_ + + * `Prerequisites`_ + + * `Create a build environment`_ + + * `C and C++ Libraries`_ + + * `Building the Googletests`_ + + * `Python Library`_ + + * `Rust Library`_ + + * `Using Cmake Directly`_ + +- `Build Documentation`_ + + +Installing Pre-compiled Packages +-------------------------------- + +C, C++, and Python through Conda +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The easiest way to install the pre-compiled C, C++, and Python packages is through `conda `_. Use the following commands, depending on your CUDA version, to install cuVS packages (replace `rapidsai` with `rapidsai-nightly` to install more up-to-date but less stable nightly packages). `mamba` is preferred over the `conda` command. + +C++ Package +~~~~~~~~~~~ + +.. code-block:: bash + + mamba install -c rapidsai -c conda-forge -c nvidia libcuvs cuda-version=12.0 + +C Package +~~~~~~~~~ + +.. code-block:: bash + + mamba install -c rapidsai -c conda-forge -c nvidia libcuvs_c cuda-version=12.0 + +Python Package +~~~~~~~~~~~~~~ + +.. code-block:: bash + + mamba install -c rapidsai -c conda-forge -c nvidia cuvs cuda-version=12.0 + +Python through Pip +^^^^^^^^^^^^^^^^^^ + +The cuVS Python package can also be `installed through pip `_. + +For CUDA 11 packages: + +.. code-block:: bash + + pip install cuvs-cu11 --extra-index-url=https://pypi.nvidia.com + +And CUDA 12 packages: + +.. code-block:: bash + + pip install cuvs-cu12 --extra-index-url=https://pypi.nvidia.com + +Note: these packages statically link the C and C++ libraries so the `libcuvs` and `libcuvs_c` shared libraries won't be readily available to use in your code. + +Rust through crates.io +^^^^^^^^^^^^^^^^^^^^^^ + +Build from source +----------------- + +The core cuVS source code is written in C++ and wrapped through a C API. The C API is wrapped around the C++ APIs and the other supported languages are built around the C API. + + +Prerequisites +^^^^^^^^^^^^^ + +- Cmake 3.26.4+ +- GCC 9.3+ (11.4+ recommended) +- CUDA Toolkit 11.4+ +- Volta architecture or better (compute capability >= 7.0) + +Create a build environment +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +`Conda `_ environment scripts are provided for installing the necessary dependencies to build cuVS from source. It is preferred to use `mamba`, as it provides significant speedup over `conda`: + +.. code-block:: bash + + mamba env create --name cuvs -f conda/environments/all_cuda-120_arch-x86_64.yaml + mamba activate cuvs + +The process for building from source with CUDA 11 differs slightly in that your host system will also need to have CUDA toolkit installed which is greater than, or equal to, the version you install into you conda environment. Installing CUDA toolkit into your host system is necessary because `nvcc` is not provided with Conda's cudatoolkit dependencies for CUDA 11. The following example will install create and install dependencies for a CUDA 11.8 conda environment + +.. code-block:: bash + + mamba env create --name cuvs -f conda/environments/all_cuda-118_arch-x86_64.yaml + mamba activate cuvs + +The recommended way to build and install cuVS from source is to use the `build.sh` script in the root of the repository. This script can build both the C++ and Python artifacts and provides CMake options for building and installing the headers, tests, benchmarks, and the pre-compiled shared library. + + +C and C++ libraries +^^^^^^^^^^^^^^^^^^^ + +The C and C++ shared libraries are built together using the following arguments to `build.sh`: + +.. code-block:: bash + + ./build.sh libcuvs + +In above example the `libcuvs.so` and `libcuvs_c.so` shared libraries are installed by default into `$INSTALL_PREFIX/lib`. To disable this, pass `-n` flag. + +Once installed, the shared libraries, headers (and any dependencies downloaded and installed via `rapids-cmake`) can be uninstalled using `build.sh`: + +.. code-block:: bash + + ./build.sh libcuvs --uninstall + + +Building the Googletests +~~~~~~~~~~~~~~~~~~~~~~~~ + +Compile the C and C++ Googletests using the `tests` target in `build.sh`. + +.. code-block:: bash + + ./build.sh libcuvs tests + +The tests will be written to the build directory, which is `cpp/build/` by default, and they will be named `*_TEST`. + +It can take some time to compile all of the tests. You can build individual tests by providing a semicolon-separated list to the `--limit-tests` option in `build.sh`. Make sure to pass the `-n` flag so the tests are not installed. + +.. code-block:: bash + + ./build.sh libcuvs tests -n --limit-tests=NEIGHBORS_TEST;CAGRA_C_TEST + +Python library +^^^^^^^^^^^^^^ + +The Python library should be built and installed using the `build.sh` script: + +.. code-block:: bash + + ./build.sh python + +The Python packages can also be uninstalled using the `build.sh` script: + +.. code-block:: bash + + ./build.sh python --uninstall + +Rust library +^^^^^^^^^^^^ + +Using CMake directly +^^^^^^^^^^^^^^^^^^^^ + +When building cuVS from source, the `build.sh` script offers a nice wrapper around the `cmake` commands to ease the burdens of manually configuring the various available cmake options. When more fine-grained control over the CMake configuration is desired, the `cmake` command can be invoked directly as the below example demonstrates. + +The `CMAKE_INSTALL_PREFIX` installs cuVS into a specific location. The example below installs cuVS into the current Conda environment: + +.. code-block:: bash + + cd cpp + mkdir build + cd build + cmake -D BUILD_TESTS=ON -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX ../ + make -j install + +cuVS has the following configurable cmake flags available: + +.. list-table:: Cmake Flags + + * - Flag + - Possible Values + - Default Value + - Behavior + + * - BUILD_TESTS + - ON, OFF + - ON + - Compile Googletests + + * - CUDA_ENABLE_KERNELINFO + - ON, OFF + - OFF + - Enables `kernelinfo` in nvcc. This is useful for `compute-sanitizer` + + * - CUDA_ENABLE_LINEINFO + - ON, OFF + - OFF + - Enable the `-lineinfo` option for nvcc + + * - CUDA_STATIC_RUNTIME + - ON, OFF + - OFF + - Statically link the CUDA runtime + + * - DETECT_CONDA_ENV + - ON, OFF + - ON + - Enable detection of conda environment for dependencies + + * - CUVS_NVTX + - ON, OFF + - OFF + - Enable NVTX markers + + +Build documentation +^^^^^^^^^^^^^^^^^^^ + +The documentation requires that the C, C++ and Python libraries have been built and installed. The following will build the docs along with the necessary libraries: + +.. code-block:: bash + + ./build.sh libcuvs python docs diff --git a/docs/source/index.rst b/docs/source/index.rst index d06929eec..b8334e858 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -6,7 +6,7 @@ Useful Resources .. _cuvs_reference: https://docs.rapids.ai/api/cuvs/stable/ -- `Example Notebooks `_: Example Jupyter notebooks +- `Example Notebooks `_: Self-contained Code examples - `RAPIDS Community `_: Get help, contribute, and collaborate. - `GitHub repository `_: Download the cuVS source code. - `Issue tracker `_: Report issues or request features. @@ -22,8 +22,8 @@ cuVS is a library for vector search and clustering on the GPU. :caption: Contents: getting_started.rst - integrations.rst build.md + integrations.rst api_docs.rst contributing.md diff --git a/docs/source/interoperability.rst b/docs/source/interoperability.rst index ac3c3f3ad..fc8d19ef4 100644 --- a/docs/source/interoperability.rst +++ b/docs/source/interoperability.rst @@ -7,7 +7,7 @@ DLPack (C) Multi-dimensional span (C++) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -cuVS is built on top of the GPU-accelerated machine learning and data mining primitives in the [RAFT](https://github.com/rapidsai/raft) library. Most of the C++ APIs in cuVS accept [mdspan](https://arxiv.org/abs/2010.06474) multi-dimensional array view for representing data in higher dimensions similar to the `ndarray` in the Numpy Python library. RAFT also contains the corresponding owning `mdarray` structure, which simplifies the allocation and management of multi-dimensional data in both host and device (GPU) memory. +cuVS is built on top of the GPU-accelerated machine learning and data mining primitives in the `RAFT `_ library. Most of the C++ APIs in cuVS accept `mdspan `_ multi-dimensional array view for representing data in higher dimensions similar to the `ndarray` in the Numpy Python library. RAFT also contains the corresponding owning `mdarray` structure, which simplifies the allocation and management of multi-dimensional data in both host and device (GPU) memory. The `mdarray` is an owning object that forms a convenience layer over RMM and can be constructed in RAFT using a number of different helper functions: @@ -65,7 +65,7 @@ Of course, RAFT's `mdspan`/`mdarray` APIs aren't just limited to the `device`. Y auto vector_view = raft::make_host_vector_view(vector.data_handle(), vector.extent(0)); auto matrix_view = raft::make_host_matrix_view(matrix.data_handle(), matrix.extent(0), matrix.extent(1)); -Please refer to RAFT's `mdspan` [documentation](https://docs.rapids.ai/api/raft/stable/cpp_api/mdspan/) to learn more. +Please refer to RAFT's `mdspan` `documentation `_ to learn more. CUDA array interface (Python) From 866193a7d048eee031a22b4f2f76a019cac32eb5 Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Tue, 12 Mar 2024 20:27:10 -0400 Subject: [PATCH 24/25] Adding rust --- docs/source/basics.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source/basics.rst b/docs/source/basics.rst index 94418f636..4842e2788 100644 --- a/docs/source/basics.rst +++ b/docs/source/basics.rst @@ -84,3 +84,7 @@ Python Rust ^^^^ + +.. code-block:: rust + + let res = cuvs::Resources::new()?; \ No newline at end of file From 80959bc4b752556e319b245b6ef0e8c80656d27b Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Tue, 12 Mar 2024 20:59:48 -0400 Subject: [PATCH 25/25] MOre updates --- docs/source/working_with_ann_indexes.rst | 83 ++++++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/docs/source/working_with_ann_indexes.rst b/docs/source/working_with_ann_indexes.rst index ad4ebfcce..f347a2f42 100644 --- a/docs/source/working_with_ann_indexes.rst +++ b/docs/source/working_with_ann_indexes.rst @@ -9,9 +9,92 @@ Working with ANN Indexes Building an index ----------------- +C +^ + +.. code-block:: c + + #include + + cuvsResources_t res; + cuvsCagraIndexParams_t index_params; + cuvsCagraIndex_t index; + + DLManagedTensor *dataset; + load_dataset(dataset); + + cuvsResourcesCreate(&res); + cuvsCagraIndexParamsCreate(&index_params); + cuvsCagraIndexCreate(&index); + + cuvsCagraBuild(res, index_params, dataset, index); + + cuvsCagraIndexDestroy(index); + cuvsCagraIndexParamsDestroy(index_params); + cuvsResourcesDestroy(res); + +C++ +^^^ + +.. code-block:: c++ + + #include + + using namespace cuvs::neighbors; + + raft::device_matrix_view dataset = load_dataset(); + raft::device_resources res; + + cagra::index_params index_params; + + auto index = cagra::build(res, index_params, dataset); + + +Python +^^^^^^ + +.. code-block:: python + + from cuvs.neighbors import cagra + + dataset = load_data() + index_params = cagra.IndexParams() + + index = cagra.build_index(build_params, dataset) + +Rust +^^^^ + +.. code-block:: rust + + use cuvs::cagra::{Index, IndexParams}; + use cuvs::{Resources, Result}; + + use ndarray_rand::rand_distr::Uniform; + use ndarray_rand::RandomExt; + + /// Example showing how to index and search data with CAGRA + fn cagra_example() -> Result<()> { + let res = Resources::new()?; + + // Create a new random dataset to index + let n_datapoints = 65536; + let n_features = 512; + let dataset = + ndarray::Array::::random((n_datapoints, n_features), Uniform::new(0., 1.0)); + + // build the cagra index + let build_params = IndexParams::new()?; + let index = Index::build(&res, &build_params, &dataset)?; + + Ok(()) + } + + Searching an index ------------------ + CPU/GPU interoperability ------------------------