Neighbors Vamana

Source header: cuvs/neighbors/vamana.h

C API for Vamana index build

cuvsVamanaIndexParams

Supplemental parameters to build Vamana Index

1 struct cuvsVamanaIndexParams { ... };

Fields

Name	Type	Description
`metric`	`cuvsDistanceType`	Distance type.
`graph_degree`	`uint32_t`	Maximum degree of graph; corresponds to the R parameter of Vamana algorithm in the literature.
`visited_size`	`uint32_t`	Maximum number of visited nodes per search during Vamana algorithm. Loosely corresponds to the L parameter in the literature.
`vamana_iters`	`float`	The number of times all vectors are inserted into the graph. If > 1, all vectors are re-inserted to improve graph quality.
`alpha`	`float`	Used to determine how aggressive the pruning will be.
`max_fraction`	`float`	The maximum batch size is this fraction of the total dataset size. Larger gives faster build but lower graph quality.
`batch_base`	`float`	Base of growth rate of batch sizes *
`queue_size`	`uint32_t`	Size of candidate queue structure - should be (2^x)-1
`reverse_batchsize`	`uint32_t`	Max batchsize of reverse edge processing (reduces memory footprint)

cuvsVamanaIndexParamsCreate

Allocate Vamana Index params, and populate with default values

1 CUVS_EXPORT cuvsError_t cuvsVamanaIndexParamsCreate(cuvsVamanaIndexParams_t* params);

Parameters

Name	Direction	Type	Description
`params`	in	`cuvsVamanaIndexParams_t*`	cuvsVamanaIndexParams_t to allocate

Returns

CUVS_EXPORT cuvsError_t

cuvsVamanaIndexParamsDestroy

De-allocate Vamana Index params

1 CUVS_EXPORT cuvsError_t cuvsVamanaIndexParamsDestroy(cuvsVamanaIndexParams_t params);

Parameters

Name	Direction	Type	Description
`params`	in	`cuvsVamanaIndexParams_t`	cuvsVamanaIndexParams_t to de-allocate

Returns

CUVS_EXPORT cuvsError_t

Vamana index

cuvsVamanaIndex

Struct to hold address of cuvs::neighbors::vamana::index and its active trained dtype

1 typedef struct { ... } cuvsVamanaIndex;

Fields

Name	Type	Description
`addr`	`uintptr_t`
`dtype`	`DLDataType`

cuvsVamanaIndexCreate

Allocate Vamana index

1 CUVS_EXPORT cuvsError_t cuvsVamanaIndexCreate(cuvsVamanaIndex_t* index);

Parameters

Name	Direction	Type	Description
`index`	in	`cuvsVamanaIndex_t*`	cuvsVamanaIndex_t to allocate

Returns

CUVS_EXPORT cuvsError_t

cuvsVamanaIndexDestroy

De-allocate Vamana index

1 CUVS_EXPORT cuvsError_t cuvsVamanaIndexDestroy(cuvsVamanaIndex_t index);

Parameters

Name	Direction	Type	Description
`index`	in	`cuvsVamanaIndex_t`	cuvsVamanaIndex_t to de-allocate

Returns

CUVS_EXPORT cuvsError_t

cuvsVamanaIndexGetDims

Get the dimension of the index

1 CUVS_EXPORT cuvsError_t cuvsVamanaIndexGetDims(cuvsVamanaIndex_t index, int* dim);

Parameters

Name	Direction	Type	Description
`index`	in	`cuvsVamanaIndex_t`	cuvsVamanaIndex_t to get dimension of
`dim`	out	`int*`	pointer to dimension to set

Returns

CUVS_EXPORT cuvsError_t

Vamana index build

cuvsVamanaBuild

Build Vamana index

1 CUVS_EXPORT cuvsError_t cuvsVamanaBuild(cuvsResources_t res,
2 cuvsVamanaIndexParams_t params,
3 DLManagedTensor* dataset,
4 cuvsVamanaIndex_t index);

Build the index from the dataset for efficient DiskANN search.

The build uses the Vamana insertion-based algorithm to create the graph. The algorithm starts with an empty graph and iteratively inserts batches of nodes. Each batch involves performing a greedy search for each vector to be inserted, and inserting it with edges to all nodes traversed during the search. Reverse edges are also inserted and robustPrune is applied to improve graph quality. The index_params struct controls the degree of the final graph.

The following distance metrics are supported:

Usage example:

Parameters

Name	Direction	Type	Description
`res`	in	`cuvsResources_t`	cuvsResources_t opaque C handle
`params`	in	`cuvsVamanaIndexParams_t`	cuvsVamanaIndexParams_t used to build Vamana index
`dataset`	in	`DLManagedTensor*`	DLManagedTensor* training dataset
`index`	out	`cuvsVamanaIndex_t`	cuvsVamanaIndex_t Vamana index

Returns

CUVS_EXPORT cuvsError_t

Vamana index serialize

cuvsVamanaSerialize

Save Vamana index to file

1 CUVS_EXPORT cuvsError_t cuvsVamanaSerialize(cuvsResources_t res,
2 const char* filename,
3 cuvsVamanaIndex_t index,
4 bool include_dataset);

Matches the file format used by the DiskANN open-source repository, allowing cross-compatibility.

Serialized Index is to be used by the DiskANN open-source repository for graph search.

Parameters

Name	Direction	Type	Description
`res`	in	`cuvsResources_t`	cuvsResources_t opaque C handle
`filename`	in	`const char*`	the file prefix for where the index is saved
`index`	in	`cuvsVamanaIndex_t`	cuvsVamanaIndex_t to serialize
`include_dataset`	in	`bool`	whether to include the dataset in the serialized index

Returns

CUVS_EXPORT cuvsError_t