IVF SQ

Source header: cuvs/neighbors/ivf_sq.h

IVF-SQ index build parameters

cuvsIvfSqIndexParams

Supplemental parameters to build IVF-SQ Index

1 struct cuvsIvfSqIndexParams {
2   cuvsDistanceType metric;
3   float metric_arg;
4   bool add_data_on_build;
5   uint32_t n_lists;
6   uint32_t kmeans_n_iters;
7   uint32_t max_train_points_per_cluster;
8   bool conservative_memory_allocation;
9 };

Fields

Name	Type	Description
`metric`	`cuvsDistanceType`	Distance type.
`metric_arg`	`float`	The argument used by some distance metrics.
`add_data_on_build`	`bool`	Whether to add the dataset content to the index, i.e.: - `true` means the index is filled with the dataset vectors and ready to search after calling `build`. - `false` means `build` only trains the underlying model (e.g. quantizer or clustering), but the index is left empty; you’d need to call `extend` on the index afterwards to populate it.
`n_lists`	`uint32_t`	The number of inverted lists (clusters)
`kmeans_n_iters`	`uint32_t`	The number of iterations searching for kmeans centers (index building).
`max_train_points_per_cluster`	`uint32_t`	The number of data vectors per cluster to use during iterative kmeans building. The index uses at most `n_lists * max_train_points_per_cluster` rows for training.
`conservative_memory_allocation`	`bool`	By default, the algorithm allocates more space than necessary for individual clusters (`list_data`). This allows to amortize the cost of memory allocation and reduce the number of data copies during repeated calls to `extend` (extending the database). The alternative is the conservative allocation behavior; when enabled, the algorithm always allocates the minimum amount of memory required to store the given number of records. Set this flag to `true` if you prefer to use as little GPU memory for the database as possible.

cuvsIvfSqIndexParamsCreate

Allocate IVF-SQ Index params, and populate with default values

1 CUVS_EXPORT cuvsError_t cuvsIvfSqIndexParamsCreate(cuvsIvfSqIndexParams_t* index_params);

Parameters

Name	Direction	Type	Description
`index_params`	in	`cuvsIvfSqIndexParams_t*`	cuvsIvfSqIndexParams_t to allocate

Returns

CUVS_EXPORT cuvsError_t

cuvsIvfSqIndexParamsDestroy

De-allocate IVF-SQ Index params

1 CUVS_EXPORT cuvsError_t cuvsIvfSqIndexParamsDestroy(cuvsIvfSqIndexParams_t index_params);

Parameters

Name	Direction	Type	Description
`index_params`	in	`cuvsIvfSqIndexParams_t`

Returns

CUVS_EXPORT cuvsError_t

IVF-SQ index search parameters

cuvsIvfSqSearchParams

Supplemental parameters to search IVF-SQ index

1 struct cuvsIvfSqSearchParams {
2   uint32_t n_probes;
3 };

Fields

Name	Type	Description
`n_probes`	`uint32_t`	The number of clusters to search.

cuvsIvfSqSearchParamsCreate

Allocate IVF-SQ search params, and populate with default values

1 CUVS_EXPORT cuvsError_t cuvsIvfSqSearchParamsCreate(cuvsIvfSqSearchParams_t* params);

Parameters

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

Returns

CUVS_EXPORT cuvsError_t

cuvsIvfSqSearchParamsDestroy

De-allocate IVF-SQ search params

1 CUVS_EXPORT cuvsError_t cuvsIvfSqSearchParamsDestroy(cuvsIvfSqSearchParams_t params);

Parameters

Name	Direction	Type	Description
`params`	in	`cuvsIvfSqSearchParams_t`

Returns

CUVS_EXPORT cuvsError_t

IVF-SQ index

cuvsIvfSqIndex

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

1 typedef struct {
2   uintptr_t addr;
3   DLDataType dtype;
4 } cuvsIvfSqIndex;

Fields

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

cuvsIvfSqIndexCreate

Allocate IVF-SQ index

1 CUVS_EXPORT cuvsError_t cuvsIvfSqIndexCreate(cuvsIvfSqIndex_t* index);

Parameters

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

Returns

CUVS_EXPORT cuvsError_t

cuvsIvfSqIndexDestroy

De-allocate IVF-SQ index

1 CUVS_EXPORT cuvsError_t cuvsIvfSqIndexDestroy(cuvsIvfSqIndex_t index);

Parameters

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

Returns

CUVS_EXPORT cuvsError_t

cuvsIvfSqIndexGetNLists

Get the number of clusters/inverted lists

1 CUVS_EXPORT cuvsError_t cuvsIvfSqIndexGetNLists(cuvsIvfSqIndex_t index, int64_t* n_lists);

Parameters

Name	Direction	Type	Description
`index`		`cuvsIvfSqIndex_t`
`n_lists`		`int64_t*`

Returns

CUVS_EXPORT cuvsError_t

cuvsIvfSqIndexGetDim

Get the dimensionality of the data

1 CUVS_EXPORT cuvsError_t cuvsIvfSqIndexGetDim(cuvsIvfSqIndex_t index, int64_t* dim);

Parameters

Name	Direction	Type	Description
`index`		`cuvsIvfSqIndex_t`
`dim`		`int64_t*`

Returns

CUVS_EXPORT cuvsError_t

cuvsIvfSqIndexGetSize

Get the size of the index

1 CUVS_EXPORT cuvsError_t cuvsIvfSqIndexGetSize(cuvsIvfSqIndex_t index, int64_t* size);

Parameters

Name	Direction	Type	Description
`index`		`cuvsIvfSqIndex_t`
`size`		`int64_t*`

Returns

CUVS_EXPORT cuvsError_t

cuvsIvfSqIndexGetCenters

Get the cluster centers corresponding to the lists [n_lists, dim]

1 CUVS_EXPORT cuvsError_t cuvsIvfSqIndexGetCenters(cuvsIvfSqIndex_t index, DLManagedTensor* centers);

Parameters

Name	Direction	Type	Description
`index`	in	`cuvsIvfSqIndex_t`	cuvsIvfSqIndex_t Built Ivf-SQ Index
`centers`	out	`DLManagedTensor*`	Preallocated array on host or device memory to store output, [n_lists, dim]

Returns

CUVS_EXPORT cuvsError_t

IVF-SQ index build

cuvsIvfSqBuild

Build an IVF-SQ index with a DLManagedTensor which has underlying DLDeviceType equal to kDLCUDA, kDLCUDAHost, kDLCUDAManaged, or kDLCPU. Also, acceptable underlying types are: 1. kDLDataType.code == kDLFloat and kDLDataType.bits = 32 2. kDLDataType.code == kDLFloat and kDLDataType.bits = 16

1 CUVS_EXPORT cuvsError_t cuvsIvfSqBuild(cuvsResources_t res,
2 cuvsIvfSqIndexParams_t index_params,
3 DLManagedTensor* dataset,
4 cuvsIvfSqIndex_t index);

Parameters

Name	Direction	Type	Description
`res`	in	`cuvsResources_t`	cuvsResources_t opaque C handle
`index_params`	in	`cuvsIvfSqIndexParams_t`	cuvsIvfSqIndexParams_t used to build IVF-SQ index
`dataset`	in	`DLManagedTensor*`	DLManagedTensor* training dataset
`index`	out	`cuvsIvfSqIndex_t`	cuvsIvfSqIndex_t Newly built IVF-SQ index

Returns

CUVS_EXPORT cuvsError_t

IVF-SQ index search

cuvsIvfSqSearch

Search an IVF-SQ index with a DLManagedTensor which has underlying DLDeviceType equal to kDLCUDA, kDLCUDAHost, kDLCUDAManaged. Types for input are: 1. queries: kDLDataType.code == kDLFloat and kDLDataType.bits = 32 or 16 2. neighbors: kDLDataType.code == kDLInt and kDLDataType.bits = 64 3. distances: kDLDataType.code == kDLFloat and kDLDataType.bits = 32

1 CUVS_EXPORT cuvsError_t cuvsIvfSqSearch(cuvsResources_t res,
2 cuvsIvfSqSearchParams_t search_params,
3 cuvsIvfSqIndex_t index,
4 DLManagedTensor* queries,
5 DLManagedTensor* neighbors,
6 DLManagedTensor* distances,
7 cuvsFilter filter);

Parameters

Name	Direction	Type	Description
`res`	in	`cuvsResources_t`	cuvsResources_t opaque C handle
`search_params`	in	`cuvsIvfSqSearchParams_t`	cuvsIvfSqSearchParams_t used to search IVF-SQ index
`index`	in	`cuvsIvfSqIndex_t`	ivfSqIndex which has been returned by `cuvsIvfSqBuild`
`queries`	in	`DLManagedTensor*`	DLManagedTensor* queries dataset to search
`neighbors`	out	`DLManagedTensor*`	DLManagedTensor* output `k` neighbors for queries
`distances`	out	`DLManagedTensor*`	DLManagedTensor* output `k` distances for queries
`filter`	in	`cuvsFilter`	cuvsFilter input filter that can be used to filter queries and neighbors based on the given bitset.

Returns

CUVS_EXPORT cuvsError_t

IVF-SQ C-API serialize functions

cuvsIvfSqSerialize

Save the index to file.

1 CUVS_EXPORT cuvsError_t cuvsIvfSqSerialize(cuvsResources_t res, const char* filename, cuvsIvfSqIndex_t index);

Experimental, both the API and the serialization format are subject to change.

Parameters

Name	Direction	Type	Description
`res`	in	`cuvsResources_t`	cuvsResources_t opaque C handle
`filename`	in	`const char*`	the file name for saving the index
`index`	in	`cuvsIvfSqIndex_t`	IVF-SQ index

Returns

CUVS_EXPORT cuvsError_t

cuvsIvfSqDeserialize

Load index from file.

1 CUVS_EXPORT cuvsError_t cuvsIvfSqDeserialize(cuvsResources_t res,
2 const char* filename,
3 cuvsIvfSqIndex_t index);

Experimental, both the API and the serialization format are subject to change.

Parameters

Name	Direction	Type	Description
`res`	in	`cuvsResources_t`	cuvsResources_t opaque C handle
`filename`	in	`const char*`	the name of the file that stores the index
`index`	out	`cuvsIvfSqIndex_t`	IVF-SQ index loaded from disk

Returns

CUVS_EXPORT cuvsError_t

IVF-SQ index extend

cuvsIvfSqExtend

Extend the index with the new data.

1 CUVS_EXPORT cuvsError_t cuvsIvfSqExtend(cuvsResources_t res,
2 DLManagedTensor* new_vectors,
3 DLManagedTensor* new_indices,
4 cuvsIvfSqIndex_t index);

Parameters

Name	Direction	Type	Description
`res`	in	`cuvsResources_t`	cuvsResources_t opaque C handle
`new_vectors`	in	`DLManagedTensor*`	DLManagedTensor* the new vectors to add to the index
`new_indices`	in	`DLManagedTensor*`	DLManagedTensor* vector of new indices for the new vectors. If the index is empty, this can be NULL to imply a continuous range `[0...n_rows)`.
`index`	inout	`cuvsIvfSqIndex_t`	IVF-SQ index to be extended

Returns

CUVS_EXPORT cuvsError_t

1	struct cuvsIvfSqIndexParams {
2	cuvsDistanceType metric;
3	float metric_arg;
4	bool add_data_on_build;
5	uint32_t n_lists;
6	uint32_t kmeans_n_iters;
7	uint32_t max_train_points_per_cluster;
8	bool conservative_memory_allocation;
9	};

1	typedef struct {
2	uintptr_t addr;
3	DLDataType dtype;
4	} cuvsIvfSqIndex;

1	CUVS_EXPORT cuvsError_t cuvsIvfSqBuild(cuvsResources_t res,
2	cuvsIvfSqIndexParams_t index_params,
3	DLManagedTensor* dataset,
4	cuvsIvfSqIndex_t index);

1	CUVS_EXPORT cuvsError_t cuvsIvfSqSearch(cuvsResources_t res,
2	cuvsIvfSqSearchParams_t search_params,
3	cuvsIvfSqIndex_t index,
4	DLManagedTensor* queries,
5	DLManagedTensor* neighbors,
6	DLManagedTensor* distances,
7	cuvsFilter filter);

1	CUVS_EXPORT cuvsError_t cuvsIvfSqDeserialize(cuvsResources_t res,
2	const char* filename,
3	cuvsIvfSqIndex_t index);

1	CUVS_EXPORT cuvsError_t cuvsIvfSqExtend(cuvsResources_t res,
2	DLManagedTensor* new_vectors,
3	DLManagedTensor* new_indices,
4	cuvsIvfSqIndex_t index);