From 506c14387878c6eb2eef8e998ca52b47f9ad3a4d Mon Sep 17 00:00:00 2001 From: "Corey J. Nolet" Date: Fri, 8 Mar 2024 23:32:40 +0100 Subject: [PATCH] API Documentation (#44) Building out initial API documentation for all the supported languages and algorithms. Authors: - Corey J. Nolet (https://github.com/cjnolet) Approvers: - Ben Frederickson (https://github.com/benfred) URL: https://github.com/rapidsai/cuvs/pull/44 --- build.sh | 2 +- cpp/doxygen/Doxyfile | 1 + cpp/include/cuvs/core/c_api.h | 48 +-- cpp/include/cuvs/neighbors/cagra.h | 55 ++- cpp/include/cuvs/neighbors/cagra.hpp | 241 ++++++++++---- docs/source/api_docs.rst | 11 + docs/source/build.md | 312 +++++------------- docs/source/c_api.rst | 8 +- docs/source/c_api/core_c_api.rst | 20 +- docs/source/c_api/neighbors.rst | 14 + docs/source/c_api/neighbors_cagra_c.rst | 48 ++- docs/source/conf.py | 8 +- 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 | 40 ++- docs/source/index.rst | 3 +- docs/source/python_api.rst | 8 +- docs/source/python_api/neighbors.rst | 12 + docs/source/python_api/neighbors_cagra.rst | 36 ++ docs/source/rust_api.rst | 8 + docs/source/sphinxext/github_link.py | 2 +- {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 python/cuvs/cuvs/neighbors/cagra/cagra.pyx | 7 + 30 files changed, 537 insertions(+), 365 deletions(-) create mode 100644 docs/source/api_docs.rst 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 create mode 100644 docs/source/rust_api.rst 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/build.sh b/build.sh index d53f7c354..8571a574c 100755 --- a/build.sh +++ b/build.sh @@ -403,7 +403,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 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..a15d7cd5c 100644 --- a/cpp/include/cuvs/core/c_api.h +++ b/cpp/include/cuvs/core/c_api.h @@ -16,30 +16,46 @@ #pragma once +#include #include -#include +#ifdef __cplusplus +extern "C" { +#endif /** - * @defgroup c_api C API Core Types and Functions + * @defgroup error_c cuVS Error Messages * @{ */ +/** + * @brief An enum denoting return values for function calls + * + */ +typedef enum { CUVS_ERROR, CUVS_SUCCESS } cuvsError_t; -#ifdef __cplusplus -extern "C" { -#endif +/** @brief Returns a string describing the last seen error on this thread, or + * NULL if the last function succeeded. + */ +const char* cuvsGetLastErrorText(); /** - * @brief An opaque C handle for C++ type `raft::resources` - * + * @brief Sets a string describing an error seen on the thread. Passing NULL + * clears any previously seen error message. */ -typedef uintptr_t cuvsResources_t; +void cuvsSetLastErrorText(const char* error); + +/** @} */ /** - * @brief An enum denoting return values for function calls + * @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` @@ -67,18 +83,8 @@ 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 } #endif - -/** @} */ diff --git a/cpp/include/cuvs/neighbors/cagra.h b/cpp/include/cuvs/neighbors/cagra.h index 64a26b924..ae8f8ea01 100644 --- a/cpp/include/cuvs/neighbors/cagra.h +++ b/cpp/include/cuvs/neighbors/cagra.h @@ -20,15 +20,15 @@ #include #include -/** - * @defgroup cagra_c C API for CUDA ANN Graph-based nearest neighbor search - * @{ - */ - #ifdef __cplusplus extern "C" { #endif +/** + * @defgroup cagra_c_index_params C API for CUDA ANN Graph-based nearest neighbor search + * @{ + */ + /** * @brief Enum to denote which ANN algorithm is used to build CAGRA graph * @@ -71,7 +71,16 @@ cuvsError_t cuvsCagraIndexParamsCreate(cuvsCagraIndexParams_t* params); * @param[in] params * @return cuvsError_t */ -cuvsError_t cuvsCagraIndexParamsDestroy(cuvsCagraIndexParams_t index); +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`. @@ -281,10 +316,10 @@ cuvsError_t cuvsCagraSearch(cuvsResources_t res, DLManagedTensor* neighbors, DLManagedTensor* distances); -#ifdef __cplusplus -} -#endif - /** * @} */ + +#ifdef __cplusplus +} +#endif 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/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/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/docs/source/c_api.rst b/docs/source/c_api.rst index 4daaa84df..3359a5dbe 100644 --- a/docs/source/c_api.rst +++ b/docs/source/c_api.rst @@ -1,6 +1,6 @@ -~~~~~ -C API -~~~~~ +~~~~~~~~~~~~~~~~~~~ +C API Documentation +~~~~~~~~~~~~~~~~~~~ .. _api: @@ -8,4 +8,4 @@ C API :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/core_c_api.rst b/docs/source/c_api/core_c_api.rst index e0060bd5d..e2796700f 100644 --- a/docs/source/c_api/core_c_api.rst +++ b/docs/source/c_api/core_c_api.rst @@ -1,14 +1,24 @@ -C-API -===== +Core Routines +============= .. role:: py(code) :language: c :class: highlight - ``#include `` -.. doxygengroup:: c_api - :project: RAFT +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/c_api/neighbors.rst b/docs/source/c_api/neighbors.rst new file mode 100644 index 000000000..6bbd3cc7f --- /dev/null +++ b/docs/source/c_api/neighbors.rst @@ -0,0 +1,14 @@ +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/c_api/neighbors_cagra_c.rst b/docs/source/c_api/neighbors_cagra_c.rst index d4b7b0bf2..eb40d5578 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 @@ -9,7 +10,44 @@ CAGRA is a graph-based nearest neighbors implementation with state-of-the art qu ``#include `` -.. doxygengroup:: cagra_c - :project: RAFT +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/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/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..aed843dad 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++ @@ -13,19 +11,43 @@ Please note that the CAGRA implementation is currently experimental and the API namespace *cuvs::neighbors::cagra* -.. doxygengroup:: cagra +Index build parameters +---------------------- + +.. doxygengroup:: cagra_cpp_index_params :project: cuvs :members: :content-only: +Index search parameters +----------------------- -Serializer Methods ------------------- -``#include `` +.. doxygengroup:: cagra_cpp_search_params + :project: cuvs + :members: + :content-only: -namespace *cuvs::neighbors::cagra* +Index +----- -.. doxygengroup:: cagra_serialize +.. 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: + 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..999c40fd3 100644 --- a/docs/source/python_api.rst +++ b/docs/source/python_api.rst @@ -1,8 +1,10 @@ -~~~~~~~~~~ -Python API -~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~ +Python API Documentation +~~~~~~~~~~~~~~~~~~~~~~~~ .. _api: .. 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..6f64f7763 --- /dev/null +++ b/docs/source/python_api/neighbors_cagra.rst @@ -0,0 +1,36 @@ +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 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/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 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 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, *,