### Basic cuVS Go Example Usage

Source: https://github.com/rapidsai/cuvs/blob/main/examples/go/README.md

A minimal Go program demonstrating the import of cuVS Go bindings. This serves as a starting point for integrating cuVS functionality.

```go
package main

import (
    "github.com/rapidsai/cuvs/go"
    "github.com/rapidsai/cuvs/go/cagra"
)

func main() {
    // Example code showing how to use the library
}
```

--------------------------------

### Algorithm File Example

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/jit_lto_guide.md

An example of an algorithm file containing a device function implementation. This code performs a divisibility check.

```c++
template <typename T, T Divisor>
__device__ bool is_divisible_impl(T value)
{
  return value % Divisor == 0;
}
```

--------------------------------

### Adapter File Example

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/jit_lto_guide.md

An example of an adapter file that wraps an algorithm function. It uses build-time substitutions for template parameters, reducing caller complexity.

```c++
#include "device_functions.cuh"  // is_divisible
#include "is_divisible_impl.cuh" // is_divisible_impl

namespace { 

using data_t             = @data_type@;
constexpr data_t divisor = @divisor@;

}  // namespace

template <> 
__device__ bool is_divisible<data_t>(data_t value)
{
  return is_divisible_impl<data_t, divisor>(value);
}
```

--------------------------------

### Run Bruteforce Example

Source: https://github.com/rapidsai/cuvs/blob/main/java/examples/README.md

Build and run the Bruteforce example using Maven. Ensure CuVS libraries and the CuVS-Java API are built and accessible.

```bash
mvn package && java --enable-native-access=ALL-UNNAMED -cp target/cuvs-java-examples-26.06.0.jar:$HOME/.m2/repository/com/nvidia/cuvs/cuvs-java/26.06.0/cuvs-java-26.06.0.jar com.nvidia.cuvs.examples.BruteForceExample
```

--------------------------------

### Install Dependencies

Source: https://github.com/rapidsai/cuvs/blob/main/notebooks/tutorial_ivf_pq.ipynb

Installs necessary Python packages for the tutorial, including cuVS dependencies and visualization tools.

```python
!pip install adjustText h5py matplotlib
```

--------------------------------

### Multiple Algorithm Files Example

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/jit_lto_guide.md

Two examples of algorithm files, each providing a different implementation of a 'filter' function. These are intended to be used with a conditional include in an adapter file.

```c++
// greater_than_impl.cuh
#include "device_impl_functions.cuh" // filter

template <typename T, T Comparand>
__device__ bool filter(T value)
{
  return value > Comparand;
}
```

```c++
// less_than_impl.cuh
#include "device_impl_functions.cuh" // filter

template <typename T, T Comparand>
__device__ bool filter(T value)
{
  return value < Comparand;
}
```

--------------------------------

### Run HNSW Example

Source: https://github.com/rapidsai/cuvs/blob/main/java/examples/README.md

Build and run the HNSW example using Maven. Ensure CuVS libraries and the CuVS-Java API are built and accessible.

```bash
mvn package && java --enable-native-access=ALL-UNNAMED -cp target/cuvs-java-examples-26.06.0.jar:$HOME/.m2/repository/com/nvidia/cuvs/cuvs-java/26.06.0/cuvs-java-26.06.0.jar com.nvidia.cuvs.examples.HnswExample
```

--------------------------------

### Install cuVS Go Module

Source: https://github.com/rapidsai/cuvs/blob/main/examples/go/README.md

Installs the cuVS Go module using 'go get'. Replace 'v26.06.00' with your desired version.

```bash
go get github.com/rapidsai/cuvs/go@v26.06.00
```

--------------------------------

### Install C API Library and Headers

Source: https://github.com/rapidsai/cuvs/blob/main/c/CMakeLists.txt

Installs the 'cuvs_c' target library, its associated headers, and the generated configuration header to the appropriate locations based on the build type and installation prefix. This makes the C API available for external use.

```cmake
install(
  TARGETS cuvs_c
  DESTINATION ${lib_dir}
  COMPONENT c_api
  EXPORT cuvs-c-exports
)
install(
  DIRECTORY include/cuvs
  COMPONENT c_api
  DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
)
install(
  FILES ${CMAKE_CURRENT_BINARY_DIR}/include/cuvs/core/c_config.h
  COMPONENT c_api
  DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/cuvs/core/
)
```

--------------------------------

### Run CAGRA Example

Source: https://github.com/rapidsai/cuvs/blob/main/java/examples/README.md

Build and run the CAGRA example using Maven. Ensure CuVS libraries and the CuVS-Java API are built and accessible.

```bash
mvn package && java --enable-native-access=ALL-UNNAMED -cp target/cuvs-java-examples-26.06.0.jar:$HOME/.m2/repository/com/nvidia/cuvs/cuvs-java/26.06.0/cuvs-java-26.06.0.jar com.nvidia.cuvs.examples.CagraExample
```

--------------------------------

### cuvs_cagra Algorithm Configuration Example (YAML)

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/cuvs_bench/index.rst

Example of an algorithm configuration for 'cuvs_cagra' in YAML format. Includes constraints for build and search, and defines parameter groups for different benchmark scenarios.

```yaml
name: cuvs_cagra
constraints:
  build: cuvs_bench.config.algos.constraints.cuvs_cagra_build
  search: cuvs_bench.config.algos.constraints.cuvs_cagra_search
groups:
  base:
    build:
      graph_degree: [32, 64]
      intermediate_graph_degree: [64, 96]
      graph_build_algo: ["NN_DESCENT"]
    search:
      itopk: [32, 64, 128]

  large:
    build:
      graph_degree: [32, 64]
    search:
      itopk: [32, 64, 128]
```

--------------------------------

### Dataset Configuration Example (YAML)

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/cuvs_bench/index.rst

Example of a dataset configuration entry in YAML format. Specify dataset name, file paths for base, query, and groundtruth, along with dimensions and distance metric.

```yaml
- name: sift-128-euclidean
  base_file: sift-128-euclidean/base.fbin
  query_file: sift-128-euclidean/query.fbin
  groundtruth_neighbors_file: sift-128-euclidean/groundtruth.neighbors.ibin
  dims: 128
  distance: euclidean
```

--------------------------------

### Install ANN_BENCH Executable

Source: https://github.com/rapidsai/cuvs/blob/main/cpp/bench/ann/CMakeLists.txt

Installs the ANN_BENCH executable to the 'bin/ann' directory as part of the 'ann_bench' component, excluding it from the default build.

```cmake
install(
  TARGETS ANN_BENCH
  COMPONENT ann_bench
  DESTINATION bin/ann
  EXCLUDE_FROM_ALL
)
```

--------------------------------

### HnswLib JSON Configuration Example

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/cuvs_bench/index.rst

An example of a JSON configuration object for the HnswLib algorithm, specifying build and search parameters. This format is generated from YAML and used by the benchmark program.

```json
{
  "name" : "hnswlib.M12.ef500.th32",
  "algo" : "hnswlib",
  "build_param": {"M":12, "efConstruction":500, "numThreads":32},
  "file" : "/path/to/file",
  "search_params" : [
    {"ef":10, "numThreads":1},
    {"ef":20, "numThreads":1},
    {"ef":40, "numThreads":1},
  ],
  "search_result_file" : "/path/to/file"
}
```

--------------------------------

### Install Dependencies

Source: https://github.com/rapidsai/cuvs/blob/main/notebooks/VectorSearch_QuestionRetrieval_Milvus.ipynb

Installs necessary Python packages for Sentence Transformers, PyMilvus, Dask, and PyTorch. Includes a note for Hopper-based GPUs.

```python
!pip install sentence_transformers torch pymilvus pymilvus[bulk_writer] dask dask[distributed]

# Note: if you have a Hopper based GPU, like an H100, use these to install:
# pip install torch --index-url https://download.pytorch.org/whl/cu118
# pip install sentence_transformers
```

--------------------------------

### IVF-PQ Build Configuration Example

Source: https://github.com/rapidsai/cuvs/blob/main/notebooks/tutorial_ivf_pq.ipynb

Placeholder comment indicating where to insert code for trying different IVF-PQ build configurations. No actual code is provided in the source.

```python
# Let's try a few build configurations.
```

--------------------------------

### Build Python Library

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/build.rst

Build and install the Python library using the build.sh script.

```bash
./build.sh python
```

--------------------------------

### Milvus Client and Collection Setup

Source: https://github.com/rapidsai/cuvs/blob/main/notebooks/VectorSearch_QuestionRetrieval_Milvus.ipynb

Initializes the Milvus client, defines collection schema with ID and embedding fields, creates the collection if it doesn't exist, and releases it for further operations.

```python
DIM = 768
MILVUS_PORT = 30004
MILVUS_HOST = f"http://localhost:{MILVUS_PORT}"
ID_FIELD = "id"
EMBEDDING_FIELD = "embedding"

collection_name = "simple_wiki"


def get_milvus_client():
    return pymilvus.MilvusClient(uri=MILVUS_HOST)


client = get_milvus_client()

fields = [
    pymilvus.FieldSchema(
        name=ID_FIELD, dtype=pymilvus.DataType.INT64, is_primary=True
    ),
    pymilvus.FieldSchema(
        name=EMBEDDING_FIELD, dtype=pymilvus.DataType.FLOAT_VECTOR, dim=DIM
    ),
]

schema = pymilvus.CollectionSchema(fields)
schema.verify()

if collection_name in client.list_collections():
    print(
        f"Collection '{collection_name}' already exists. Deleting collection..."
    )
    client.drop_collection(collection_name)

client.create_collection(
    collection_name, 
    schema=schema,
    dimension=DIM,
    vector_field_name=EMBEDDING_FIELD,
)
collection = pymilvus.Collection(name=collection_name, using=client._using)
collection.release()
collection.drop_index()
```

--------------------------------

### Install pre-commit using Pip

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/contributing.md

Install the pre-commit package using Pip. This tool helps maintain code quality by running linters and formatters.

```bash
pip install pre-commit
```

--------------------------------

### Install Sentence Transformers and PyTorch

Source: https://github.com/rapidsai/cuvs/blob/main/notebooks/VectorSearch_QuestionRetrieval.ipynb

Installs the necessary libraries for sentence embeddings and deep learning. Includes specific instructions for Hopper-based GPUs.

```python
!pip install sentence_transformers torch

# Note: if you have a Hopper based GPU, like an H100, use these to install:
# pip install torch --index-url https://download.pytorch.org/whl/cu118
# pip install sentence_transformers
```

--------------------------------

### Define Example Executables

Source: https://github.com/rapidsai/cuvs/blob/main/examples/cpp/CMakeLists.txt

Defines various example executables for CUVs, specifying their source files. These are typically CUDA (.cu) files.

```cmake
add_executable(BRUTE_FORCE_EXAMPLE src/brute_force_bitmap.cu)
add_executable(CAGRA_EXAMPLE src/cagra_example.cu)
add_executable(CAGRA_HNSW_ACE_EXAMPLE src/cagra_hnsw_ace_example.cu)
add_executable(CAGRA_PERSISTENT_EXAMPLE src/cagra_persistent_example.cu)
add_executable(DYNAMIC_BATCHING_EXAMPLE src/dynamic_batching_example.cu)
add_executable(HNSW_ACE_EXAMPLE src/hnsw_ace_example.cu)
add_executable(IVF_FLAT_EXAMPLE src/ivf_flat_example.cu)
add_executable(IVF_PQ_EXAMPLE src/ivf_pq_example.cu)
add_executable(VAMANA_EXAMPLE src/vamana_example.cu)
add_executable(SCANN_EXAMPLE src/scann_example.cu)
```

--------------------------------

### Example CMake Target Configuration for HNSWLIB

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/cuvs_bench/index.rst

An example of how to use the ConfigureAnnBench CMake function to add a benchmark target for the HNSWLIB algorithm. This sets up the necessary build configurations.

```cmake
ConfigureAnnBench(
  NAME HNSWLIB PATH bench/ann/src/hnswlib/hnswlib_benchmark.cpp INCLUDES
  ${CMAKE_CURRENT_BINARY_DIR}/_deps/hnswlib-src/hnswlib CXXFLAGS "${HNSW_CXX_FLAGS}"
)
```

--------------------------------

### Install cuVS and Optuna Packages

Source: https://github.com/rapidsai/cuvs/blob/main/notebooks/cuvs_hpo_example.ipynb

Installs the cuVS and Optuna libraries using mamba, along with the cupy package using pip. Ensure you have the correct channels configured for rapidsai-nightly.

```python
# Install Required Packages
%mamba install -c rapidsai-nightly -c conda-forge cuvs optuna -y
%pip install cupy
```

--------------------------------

### Perform IVF-PQ Search Example

Source: https://github.com/rapidsai/cuvs/blob/main/notebooks/VectorSearch_QuestionRetrieval.ipynb

Executes a search query using the IVF-PQ index.

```python
%%time
search_cuvs_pq(query="Who was Grace Hopper?")
```

--------------------------------

### Perform IVF-PQ Search Example

Source: https://github.com/rapidsai/cuvs/blob/main/notebooks/VectorSearch_QuestionRetrieval.ipynb

Executes a search query using the IVF-PQ index.

```python
%%time
search_cuvs_pq(query="Who was Alan Turing?")
```

--------------------------------

### Perform IVF-PQ Search Example

Source: https://github.com/rapidsai/cuvs/blob/main/notebooks/VectorSearch_QuestionRetrieval.ipynb

Executes a search query using the IVF-PQ index.

```python
%%time
search_cuvs_pq(query="What is creating tides?")
```

--------------------------------

### Perform IVF-FLAT Search Example

Source: https://github.com/rapidsai/cuvs/blob/main/notebooks/VectorSearch_QuestionRetrieval.ipynb

Executes a search query using the IVF-FLAT index.

```python
%%time
search_cuvs_flat(query="Who was Grace Hopper?")
```

--------------------------------

### Perform IVF-FLAT Search Example

Source: https://github.com/rapidsai/cuvs/blob/main/notebooks/VectorSearch_QuestionRetrieval.ipynb

Executes a search query using the IVF-FLAT index.

```python
%%time
search_cuvs_flat(query="Who was Alan Turing?")
```

--------------------------------

### Perform IVF-FLAT Search Example

Source: https://github.com/rapidsai/cuvs/blob/main/notebooks/VectorSearch_QuestionRetrieval.ipynb

Executes a search query using the IVF-FLAT index.

```python
%%time
search_cuvs_flat(query="What is creating tides?")
```

--------------------------------

### Index and Search with CAGRA in Rust

Source: https://github.com/rapidsai/cuvs/blob/main/README.md

This Rust example demonstrates indexing and searching data with the CAGRA algorithm. It includes creating a dataset, building the index, and performing a search, with results copied back to host memory.

```rust
use cuvs::cagra::{Index, IndexParams, SearchParams};
use cuvs::{ManagedTensor, Resources, Result};

use ndarray::s;
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::<f32, _>::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)?;
    println!(
        "Indexed {}x{} datapoints into cagra index",
        n_datapoints,
        n_features
    );

    // use the first 4 points from the dataset as queries : will test that we get them back
    // as their own nearest neighbor
    let n_queries = 4;
    let queries = dataset.slice(s![0..n_queries, ..]);

    let k = 10;

    // CAGRA search API requires queries and outputs to be on device memory
    // copy query data over, and allocate new device memory for the distances/ neighbors
    // outputs
    let queries = ManagedTensor::from(&queries).to_device(&res)?;
    let mut neighbors_host = ndarray::Array::<u32, _>::zeros((n_queries, k));
    let neighbors = ManagedTensor::from(&neighbors_host).to_device(&res)?;

    let mut distances_host = ndarray::Array::<f32, _>::zeros((n_queries, k));
    let distances = ManagedTensor::from(&distances_host).to_device(&res)?;

    let search_params = SearchParams::new()?;

    index.search(&res, &search_params, &queries, &neighbors, &distances)?;

    // Copy back to host memory
    distances.to_host(&res, &mut distances_host)?;
    neighbors.to_host(&res, &mut neighbors_host)?;

    // nearest neighbors should be themselves, since queries are from the
    // dataset
    println!("Neighbors {:?}", neighbors_host);
    println!("Distances {:?}", distances_host);
    Ok(())
}
```

--------------------------------

### Elasticsearch Backend Example: Config Loader

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/cuvs_bench/pluggable_backend.rst

An example of a configuration loader for an Elasticsearch backend. It defines how to load dataset information and benchmark configurations, including index details and backend-specific connection parameters.

```python
from cuvs_bench.orchestrator.config_loaders import (
    ConfigLoader,
    DatasetConfig,
    BenchmarkConfig,
    IndexConfig,
)

class ElasticsearchConfigLoader(ConfigLoader):
    @property
    def backend_type(self) -> str:
        return "elasticsearch"

    def load(self, dataset, dataset_path, algorithms, count=10, batch_size=10000, **kwargs):
        path_to_base = ...  # path to base vectors (e.g. from dataset_path/dataset)
        path_to_queries = ...  # path to query vectors
        path_to_groundtruth = ...  # path to groundtruth file
        path_to_index = ...  # path or id for the index
        dataset_config = DatasetConfig(
            name=dataset,
            base_file=path_to_base,
            query_file=path_to_queries,
            groundtruth_neighbors_file=path_to_groundtruth,
            distance="euclidean",
            dims=kwargs.get("dims", 128),
        )
        index = IndexConfig(
            name=f"{algorithms}.es",
            algo=algorithms,
            build_param={{}},
            search_params=[{"ef_search": 100}],
            file=path_to_index,
        )
        benchmark_config = BenchmarkConfig(
            indexes=[index],
            backend_config={
                "host": ...,  # Elasticsearch host
                "port": ...,  # Elasticsearch port

```

--------------------------------

### Create Conda Environment for cuVS Go Bindings

Source: https://github.com/rapidsai/cuvs/blob/main/examples/go/README.md

Sets up the necessary build environment using Conda. Ensure you have Conda or Mamba installed.

```bash
conda env create --name go -f conda/environments/go_cuda-131_arch-$(uname -m).yaml
conda activate go
```

--------------------------------

### Custom Config Loader Implementation

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/cuvs_bench/pluggable_backend.rst

Shows how to implement a custom config loader by extending the base ConfigLoader class. This example defines a minimal configuration for a dataset and a single index with one search parameter set.

```python
from cuvs_bench.orchestrator.config_loaders import (
    ConfigLoader,
    DatasetConfig,
    BenchmarkConfig,
    IndexConfig,
)

class MyConfigLoader(ConfigLoader):
    @property
    def backend_type(self) -> str:
        return "my_backend"

    def load(self, dataset, dataset_path, algorithms, count=10, batch_size=10000, **kwargs):
        path_to_base = ...  # path to base vectors file
        path_to_queries = ...  # path to query file
        path_to_groundtruth = ...  # path to groundtruth neighbors file
        path_to_index = ...  # path or id where the index is stored
        dataset_config = DatasetConfig(
            name=dataset,
            base_file=path_to_base,
            query_file=path_to_queries,
            groundtruth_neighbors_file=path_to_groundtruth,
            distance="euclidean",
            dims=128,
        )
        index = IndexConfig(
            name=f"{algorithms}.default",
            algo=algorithms,

```

--------------------------------

### Install pre-commit hooks for Git

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/contributing.md

Set up pre-commit hooks to automatically run on each git commit. This enforces code standards before code is committed.

```bash
pre-commit install
```

--------------------------------

### Perform CAGRA Search Example

Source: https://github.com/rapidsai/cuvs/blob/main/notebooks/VectorSearch_QuestionRetrieval.ipynb

Executes a search query using the CAGRA index.

```python
%time 
search_cuvs_cagra(query="Who was Grace Hopper?")
```

--------------------------------

### Build cuVS C and C++ Libraries

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/build.rst

Builds the C and C++ shared libraries for cuVS using the build.sh script. Libraries are installed to $INSTALL_PREFIX/lib by default.

```bash
./build.sh libcuvs
```

--------------------------------

### Implement Elasticsearch Backend

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/cuvs_bench/pluggable_backend.rst

Example implementation of a custom backend for Elasticsearch. This class stubs the build and search methods, which in a real scenario would interact with an Elasticsearch instance.

```python
import numpy as np
from cuvs_bench.backends.base import (
    BenchmarkBackend,
    Dataset,
    BuildResult,
    SearchResult,
)
from cuvs_bench.orchestrator.config_loaders import IndexConfig

class ElasticsearchBackend(BenchmarkBackend):
    @property
    def algo(self) -> str:
        return self.config.get("algo", "elasticsearch")

    def build(self, dataset, indexes, force=False, dry_run=False):
        # Stub: in practice, create ES index and bulk-index dataset.base_vectors
        return BuildResult(
            index_path=indexes[0].file if indexes else "",
            build_time_seconds=0.0,
            index_size_bytes=0,
            algorithm=self.algo,
            build_params=indexes[0].build_param if indexes else {},
            metadata={},
            success=True,
        )

    def search(self, dataset, indexes, k, batch_size=10000, mode="latency", force=False, search_threads=None, dry_run=False):
        # Stub: in practice, run ES kNN search and compute recall
        n_queries = dataset.n_queries
        return SearchResult(
            neighbors=np.zeros((n_queries, k), dtype=np.int64),
            distances=np.zeros((n_queries, k), dtype=np.float32),
            search_time_ms=0.0,
            queries_per_second=0.0,
            recall=0.0,
            algorithm=self.algo,
            search_params=indexes[0].search_params if indexes else [],
            success=True,
        )
```

--------------------------------

### Conditional Algorithm Selection in C++

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/cuvs_bench/index.rst

Example of how to select an algorithm based on the 'algo' string in the configuration. This is typically done within the create_algo() function in the benchmark C++ code.

```c++
// JSON configuration file contains a line like:  "algo" : "hnswlib"
if (algo == "hnswlib") {
   // ...
}
```

--------------------------------

### Build Documentation

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/build.rst

Build the documentation along with the necessary C, C++, and Python libraries.

```bash
./build.sh libcuvs python docs
```

--------------------------------

### Run cuVS Benchmarks (Small Scale)

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/cuvs_bench/index.rst

Example command to run smaller-scale benchmarks (1M to 10M vectors) using the cuVS benchmark tool. Datasets are stored in RAPIDS_DATASET_ROOT_DIR or a local 'datasets' sub-folder.

```bash

```

--------------------------------

### Default Docker Build

Source: https://github.com/rapidsai/cuvs/blob/main/java/docker-build/README.md

Executes the default build process using CUDA 12.9.1, Rocky Linux 9, and all GPU architectures. This is the simplest way to start building.

```bash
./build-in-docker
```

--------------------------------

### Set Up Working Directory

Source: https://github.com/rapidsai/cuvs/blob/main/notebooks/tutorial_ivf_pq.ipynb

Creates a temporary directory to store the index and dataset files. Ensures the directory exists before proceeding.

```python
# We'll need to load store some data in this tutorial
WORK_FOLDER = os.path.join(tempfile.gettempdir(), "cuvs_ivf_pq_tutorial")

if not os.path.exists(WORK_FOLDER):
    os.makedirs(WORK_FOLDER)
print("The index and data will be saved in", WORK_FOLDER)
```

--------------------------------

### Build cuVS with CMake Directly

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/build.rst

Invoke the cmake command directly for fine-grained control over configuration. This example 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<parallel_level> install
```

--------------------------------

### Open Documentation

Source: https://github.com/rapidsai/cuvs/blob/main/docs/README.md

After the build process completes, open the generated index file to view the documentation.

```shell
xdg-open build/html/index.html
```

--------------------------------

### Install Relocatable Test

Source: https://github.com/rapidsai/cuvs/blob/main/cpp/tests/CMakeLists.txt

Configures a relocatable installation test for the cuvs project. Use this to verify that the installed components can be found and used correctly after installation.

```cmake
rapids_test_install_relocatable(INSTALL_COMPONENT_SET testing DESTINATION bin/gtests/libcuvs)
```

--------------------------------

### Run Benchmark with Default Backend

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/cuvs_bench/pluggable_backend.rst

Demonstrates how to initialize and use the BenchmarkOrchestrator with the default 'cpp_gbench' backend to run a benchmark. This is the standard way to execute benchmarks.

```python
from cuvs_bench.orchestrator import BenchmarkOrchestrator

orchestrator = BenchmarkOrchestrator(backend_type="cpp_gbench")
results = orchestrator.run_benchmark(
    dataset="deep-image-96-inner",
    algorithms="cuvs_cagra",
    count=10,
    batch_size=10,
    build=True,
    search=True,
)
```

--------------------------------

### Validate Installed Headers

Source: https://github.com/rapidsai/cuvs/blob/main/c/tests/CMakeLists.txt

Uses the `cuvs_c_add_header_check` macro to verify that installed headers are correctly listed in `all.h`. This ensures header integrity after installation.

```cmake
include(cmake/header_check.cmake)
cuvs_c_add_header_check("${CUVS_C_SOURCE_DIR}" "cuvs/core/all.h" INSTALL_COMPONENT_SET testing)
```

--------------------------------

### Generate Documentation

Source: https://github.com/rapidsai/cuvs/blob/main/docs/README.md

Run this script to generate the documentation. The output will be located in the build/html directory.

```shell
bash build.sh docs
```

--------------------------------

### Install Tests

Source: https://github.com/rapidsai/cuvs/blob/main/c/tests/CMakeLists.txt

Installs the test executables to a relocatable location when the project is at the top level. This makes tests available in the build output.

```cmake
if(PROJECT_IS_TOP_LEVEL)
  rapids_test_install_relocatable(INSTALL_COMPONENT_SET testing DESTINATION bin/gtests/libcuvs)
endif()
```

--------------------------------

### Download Wiki-all Subsets

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/cuvs_bench/wiki_all_dataset.rst

Downloads the 1M and 10M subsets of the wiki-all dataset. These subsets are smaller alternatives for testing and development.

```bash
curl -s https://data.rapids.ai/raft/datasets/wiki_all_1M/wiki_all_1M.tar
curl -s https://data.rapids.ai/raft/datasets/wiki_all_10M/wiki_all_10M.tar
```

--------------------------------

### Install cuVS Python Package via Conda

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/build.rst

Installs the cuVS Python package using conda. Specify the CUDA version for compatibility.

```bash
# CUDA 13
conda install -c rapidsai -c conda-forge cuvs cuda-version=13.1
```

```bash
# CUDA 12
conda install -c rapidsai -c conda-forge cuvs cuda-version=12.9
```

--------------------------------

### Install cuVS C/C++ Package via Conda

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/build.rst

Installs the cuVS C/C++ library using conda. Ensure your CUDA version is specified.

```bash
# CUDA 13
conda install -c rapidsai -c conda-forge libcuvs cuda-version=13.1
```

```bash
# CUDA 12
conda install -c rapidsai -c conda-forge libcuvs cuda-version=12.9
```

--------------------------------

### Install pre-commit using Conda

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/contributing.md

Install the pre-commit package using Conda. This tool helps maintain code quality by running linters and formatters.

```bash
conda install -c conda-forge pre-commit
```

--------------------------------

### Basic Multi-GPU Index Build and Search

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/python_api/neighbors_multi_gpu.rst

Demonstrates how to build and search an index using multi-GPU capabilities. Ensure dataset is in host memory. Supports sharded distribution and load balancing search.

```python
import numpy as np
from cuvs.neighbors import mg_cagra

# Create dataset in host memory
n_samples = 100000
n_features = 128
dataset = np.random.random_sample((n_samples, n_features), dtype=np.float32)

# Build multi-GPU index
build_params = mg_cagra.IndexParams(
    distribution_mode="sharded",
    metric="sqeuclidean"
)
index = mg_cagra.build(build_params, dataset)

# Search with multi-GPU
queries = np.random.random_sample((1000, n_features), dtype=np.float32)
search_params = mg_cagra.SearchParams(
    search_mode="load_balancer",
    merge_mode="merge_on_root_rank"
)
distances, neighbors = mg_cagra.search(search_params, index, queries, k=10)
```

--------------------------------

### Initialize IVF-PQ Index Parameters

Source: https://github.com/rapidsai/cuvs/blob/main/notebooks/tutorial_ivf_pq.ipynb

Sets up the parameters for the IVF-PQ index, including the number of lists and the product quantization dimension (pq_dim). The pq_dim is determined to be suitable for GPU performance.

```python
# cuVS' Resources controls the GPU, cuda stream, memory policies etc.
# For now, we just create a default instance.
resources = Resources()

# First, we need to initialize the build/indexing parameters.
# One of the more important parameters is the product quantisation (PQ) dim.
# Effectively, this parameter says
#      "shrink the dataset to this dimensionality to reduce the index size".
# It must be not bigger than the dataset dim,
# and it should be divisible by 32 for better GPU performance.
pq_dim = 1
while pq_dim * 2 < dataset.shape[1]:
    pq_dim = pq_dim * 2
# We'll use the ANN-benchmarks-provided metric and sensible defaults for the rest of parameters.
index_params = ivf_pq.IndexParams(n_lists=1024, metric=metric, pq_dim=pq_dim)

show_properties(index_params)
```

--------------------------------

### Build Go Library

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/build.rst

Build the Golang library after building the C and C++ libraries. Ensure CUDA_HOME and other environment variables are set correctly.

```bash
export CUDA_HOME="/usr/local/cuda" # or wherever your CUDA installation is.
export CGO_CFLAGS="-I${CONDA_PREFIX}/include -I${CUDA_HOME}/include"
export CGO_LDFLAGS="-L${CONDA_PREFIX}/lib -lcuvs -lcuvs_c"
export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$LD_LIBRARY_PATH"
export CC=clang

./build.sh go
```

--------------------------------

### Link Libraries to Examples

Source: https://github.com/rapidsai/cuvs/blob/main/examples/cpp/CMakeLists.txt

Links the 'cuvs::cuvs' target and optionally 'conda_env' and 'Threads::Threads' to the example executables. The generator expression ensures conda environment targets are handled correctly.

```cmake
target_link_libraries(BRUTE_FORCE_EXAMPLE PRIVATE cuvs::cuvs $<TARGET_NAME_IF_EXISTS:conda_env>)
target_link_libraries(CAGRA_EXAMPLE PRIVATE cuvs::cuvs $<TARGET_NAME_IF_EXISTS:conda_env>)
target_link_libraries(CAGRA_HNSW_ACE_EXAMPLE PRIVATE cuvs::cuvs $<TARGET_NAME_IF_EXISTS:conda_env>)
target_link_libraries(
  CAGRA_PERSISTENT_EXAMPLE PRIVATE cuvs::cuvs $<TARGET_NAME_IF_EXISTS:conda_env> Threads::Threads
)
target_link_libraries(
  DYNAMIC_BATCHING_EXAMPLE PRIVATE cuvs::cuvs $<TARGET_NAME_IF_EXISTS:conda_env> Threads::Threads
)
target_link_libraries(HNSW_ACE_EXAMPLE PRIVATE cuvs::cuvs $<TARGET_NAME_IF_EXISTS:conda_env>)
target_link_libraries(IVF_PQ_EXAMPLE PRIVATE cuvs::cuvs $<TARGET_NAME_IF_EXISTS:conda_env>)
target_link_libraries(IVF_FLAT_EXAMPLE PRIVATE cuvs::cuvs $<TARGET_NAME_IF_EXISTS:conda_env>)
target_link_libraries(VAMANA_EXAMPLE PRIVATE cuvs::cuvs $<TARGET_NAME_IF_EXISTS:conda_env>)
target_link_libraries(SCANN_EXAMPLE PRIVATE cuvs::cuvs $<TARGET_NAME_IF_EXISTS:conda_env>)
```

--------------------------------

### Run a Single Test Suite with Maven

Source: https://github.com/rapidsai/cuvs/blob/main/java/README.md

Execute a specific test suite using Maven. Ensure the LD_LIBRARY_PATH is set correctly and Panama bindings are up-to-date.

```sh
cd cuvs-java/
mvn clean integration-test -Dit.test=com.nvidia.cuvs.CagraBuildAndSearchIT
```

--------------------------------

### Correct Stateless C++ API Exposure (IVF-PQ)

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/developer_guide.md

This example shows a correct approach to exposing the IVF-PQ API by using free functions within a namespace. This pattern avoids exposing stateful C++ class objects directly in the public API.

```cpp
namespace raft::ivf_pq {

template<typename value_t, typename value_idx>
void ivf_pq_train(raft::resources const& res, const raft::ivf_pq_params &params, raft::ivf_pq_index &index,
raft::device_matrix<value_t, idx_t, raft::row_major> dataset);

template<typename value_t, typename value_idx>
void ivf_pq_search(raft::resources const& res, raft::ivf_pq_params const&params, raft::ivf_pq_index const & index,
raft::device_matrix<value_t, idx_t, raft::row_major> queries,
raft::device_matrix<value_t, idx_t, raft::row_major> out_inds,
raft::device_matrix<value_t, idx_t, raft::row_major> out_dists);
}

```

--------------------------------

### Install cuVS Python Package via Pip

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/build.rst

Installs the cuVS Python package using pip. The package name includes the CUDA version. Note that these packages statically link C/C++ libraries.

```bash
# CUDA 13
pip install cuvs-cu13 --extra-index-url=https://pypi.nvidia.com
```

```bash
# CUDA 12
pip install cuvs-cu12 --extra-index-url=https://pypi.nvidia.com
```

--------------------------------

### Install cuVS Benchmarks using Conda

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/cuvs_bench/index.rst

Installs the cuVS benchmarks package and its dependencies using Conda. Use the GPU package for GPU systems and the CPU package for CPU-only systems. The channel can be changed to 'rapidsai-nightly' for nightly builds.

```bash
conda create --name cuvs_benchmarks
conda activate cuvs_benchmarks
```

```bash
# to install GPU package:
conda install -c rapidsai -c conda-forge cuvs-bench=<rapids_version> cuda-version=13.1*
```

```bash
# to install CPU package for usage in CPU-only systems:
conda install -c rapidsai -c conda-forge  cuvs-bench-cpu
```

--------------------------------

### Download Full Wiki-all Dataset

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/cuvs_bench/wiki_all_dataset.rst

Downloads all 10 parts of the full wiki-all dataset and extracts them into the 'wiki_all_88M' directory. This command is useful for obtaining the complete dataset for benchmarking.

```bash
curl -s https://data.rapids.ai/raft/datasets/wiki_all/wiki_all.tar.{00..9} | tar -xf - -C wiki_all_88M/
```

--------------------------------

### Build Rust Library

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/build.rst

Build the Rust bindings using the build.sh script.

```bash
./build.sh rust
```

--------------------------------

### Initiate Dataset Download

Source: https://github.com/rapidsai/cuvs/blob/main/notebooks/cuvs_hpo_example.ipynb

Calls the download_files function to download and extract the Wiki-1M dataset. This prepares the data for subsequent loading and processing.

```python
extracted_path = download_files(
    "https://data.rapids.ai/raft/datasets/wiki_all_1M/wiki_all_1M.tar",
    "wiki_all_1M.tar",
)
```

--------------------------------

### Download Dataset with cuvs_bench

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/cuvs_bench/index.rst

Use this command to download and prepare a dataset for benchmarking. Ensure the dataset name and normalization options are correctly specified.

```python
# (1) Prepare dataset.
python -m cuvs_bench.get_dataset --dataset deep-image-96-angular --normalize
```

--------------------------------

### Uninstall cuVS Libraries

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/build.rst

Uninstalls the cuVS libraries, headers, and any dependencies installed via rapids-cmake using the build.sh script.

```bash
./build.sh libcuvs --uninstall
```

--------------------------------

### Add cuVS to System Library Path

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/build.rst

Appends the cuVS installation directory to the LD_LIBRARY_PATH environment variable. This should be added to your shell profile for persistence.

```bash
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/folder
```

--------------------------------

### Get Dataset Dimensions

Source: https://github.com/rapidsai/cuvs/blob/main/notebooks/cuvs_hpo_example.ipynb

Calculates and stores the dataset size (number of vectors) and the dimension of each vector. This information is useful for configuring the cuVS index.

```python
# Get the dataset size of database vectors
dataset_size = vectors.shape[0]
dim = vectors.shape[1]
```

--------------------------------

### Get CUDA Stream from Resources

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/developer_guide.md

Retrieve the default CUDA stream from raft::resources. This is used when an implementation requires only one CUDA stream.

```cpp
#include <raft/core/resources.hpp>
#include <raft/core/resource/cuda_stream.hpp>

void foo(const raft::resources& res, ...)
{
    cudaStream_t stream = get_cuda_stream(res);
}
```

--------------------------------

### Build Individual Googletests

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/build.rst

Build specific tests by providing a semicolon-separated list to the --limit-tests option. Use the -n flag to prevent installation.

```bash
./build.sh libcuvs tests -n --limit-tests=NEIGHBORS_TEST;CAGRA_C_TEST
```

--------------------------------

### Configure Include Directories

Source: https://github.com/rapidsai/cuvs/blob/main/c/CMakeLists.txt

Specifies public and interface include directories for the 'cuvs_c' target. This ensures that headers from dependencies and the project itself are found during compilation and installation.

```cmake
target_include_directories(
  cuvs_c
  PUBLIC "$<BUILD_INTERFACE:${DLPACK_INCLUDE_DIR}>"
         "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>"
         "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>"
  INTERFACE "$<INSTALL_INTERFACE:include>"
)
```

--------------------------------

### Build and Search Index with BenchmarkOrchestrator

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/cuvs_bench/index.rst

Instantiate BenchmarkOrchestrator to build and search an index. Specify the backend type, dataset, algorithms, and benchmark parameters like count, batch_size, build, and search.

```python
# (2) Build and search index.
from cuvs_bench.orchestrator import BenchmarkOrchestrator

orchestrator = BenchmarkOrchestrator(backend_type="cpp_gbench")
results = orchestrator.run_benchmark(
    dataset="deep-image-96-inner",
    algorithms="cuvs_cagra",
    count=10,
    batch_size=10,
    build=True,
    search=True,
)
```

--------------------------------

### Import cuVS Libraries

Source: https://github.com/rapidsai/cuvs/blob/main/notebooks/ivf_flat_example.ipynb

Imports necessary libraries for cuVS, including common resources, IVF-flat, and utilities for benchmarking and dataset loading. Ensure these libraries are installed.

```python
import os
import cupy as cp
import numpy as np
from cuvs.common import Resources
from cuvs.neighbors import ivf_flat
import matplotlib.pyplot as plt
import tempfile
from utils import BenchmarkTimer, calc_recall, load_dataset
```

--------------------------------

### Register Elasticsearch Backend and ConfigLoader

Source: https://github.com/rapidsai/cuvs/blob/main/docs/source/cuvs_bench/pluggable_backend.rst

Demonstrates how to register a custom backend and its associated configuration loader with the cuVS Bench framework.

```python
from cuvs_bench.orchestrator import register_config_loader
from cuvs_bench.backends import get_registry

register_config_loader("elasticsearch", ElasticsearchConfigLoader)
get_registry().register("elasticsearch", ElasticsearchBackend)
```