Preprocessing

Binary Quantizer

enum cuvsBinaryQuantizerThreshold

In the cuvsBinaryQuantizerTransform function, a bit is set if the corresponding element in the dataset vector is greater than the corresponding element in the threshold vector. The mean and sampling_median thresholds are calculated separately for each dimension.

Values:

enumerator ZERO

enumerator MEAN

enumerator SAMPLING_MEDIAN

typedef struct cuvsBinaryQuantizerParams *cuvsBinaryQuantizerParams_t

typedef cuvsBinaryQuantizer *cuvsBinaryQuantizer_t

cuvsError_t cuvsBinaryQuantizerParamsCreate(

cuvsBinaryQuantizerParams_t *params

)

Allocate Binary Quantizer params, and populate with default values.

Parameters:

params – [in] cuvsBinaryQuantizerParams_t to allocate

Returns:

cuvsError_t

cuvsError_t cuvsBinaryQuantizerParamsDestroy(

cuvsBinaryQuantizerParams_t params

)

De-allocate Binary Quantizer params.

Parameters:

params – [in]

Returns:

cuvsError_t

cuvsError_t cuvsBinaryQuantizerCreate(

cuvsBinaryQuantizer_t *quantizer

)

Allocate Binary Quantizer and populate with default values.

Parameters:

quantizer – [in] cuvsBinaryQuantizer_t to allocate

Returns:

cuvsError_t

cuvsError_t cuvsBinaryQuantizerDestroy(

cuvsBinaryQuantizer_t quantizer

)

De-allocate Binary Quantizer.

Parameters:

quantizer – [in]

Returns:

cuvsError_t

cuvsError_t cuvsBinaryQuantizerTrain(

cuvsResources_t res,

cuvsBinaryQuantizerParams_t params,

DLManagedTensor *dataset,

cuvsBinaryQuantizer_t quantizer

)

Trains a binary quantizer to be used later for quantizing the dataset.

Parameters:

• res – [in] raft resource

• params – [in] configure binary quantizer, e.g. threshold

• dataset – [in] a row-major host or device matrix

• quantizer – [out] trained binary quantizer

cuvsError_t cuvsBinaryQuantizerTransform(

cuvsResources_t res,

DLManagedTensor *dataset,

DLManagedTensor *out

)

Applies binary quantization transform to the given dataset.

This applies binary quantization to a dataset, changing any positive values to a bitwise 1. This is useful for searching with the BitwiseHamming distance type.

Parameters:

• res – [in] raft resource

• dataset – [in] a row-major host or device matrix to transform

• out – [out] a row-major host or device matrix to store transformed data

cuvsError_t cuvsBinaryQuantizerTransformWithParams(

cuvsResources_t res,

cuvsBinaryQuantizer_t quantizer,

DLManagedTensor *dataset,

DLManagedTensor *out

)

Applies binary quantization transform to the given dataset.

This applies binary quantization to a dataset, changing any values that are larger than the threshold specified in the param to a bitwise 1. This is useful for searching with the BitwiseHamming distance type.

Parameters:

• res – [in] raft resource

• quantizer – [in] binary quantizer

• dataset – [in] a row-major host or device matrix to transform

• out – [out] a row-major host or device matrix to store transformed data

struct cuvsBinaryQuantizerParams

#include <binary.h>

Binary quantizer parameters.

struct cuvsBinaryQuantizer

#include <binary.h>

Defines and stores threshold for quantization upon training.

The quantization is performed by a linear mapping of an interval in the float data type to the full range of the quantized int type.

Product Quantizer

typedef struct cuvsProductQuantizerParams *cuvsProductQuantizerParams_t

typedef cuvsProductQuantizer *cuvsProductQuantizer_t

cuvsError_t cuvsProductQuantizerParamsCreate(

cuvsProductQuantizerParams_t *params

)

Allocate Product Quantizer params, and populate with default values.

Parameters:

params – [in] cuvsProductQuantizerParams_t to allocate

Returns:

cuvsError_t

cuvsError_t cuvsProductQuantizerParamsDestroy(

cuvsProductQuantizerParams_t params

)

De-allocate Product Quantizer params.

Parameters:

params – [in]

Returns:

cuvsError_t

cuvsError_t cuvsProductQuantizerCreate(

cuvsProductQuantizer_t *quantizer

)

Allocate Product Quantizer.

Parameters:

quantizer – [in] cuvsProductQuantizer_t to allocate

Returns:

cuvsError_t

cuvsError_t cuvsProductQuantizerDestroy(

cuvsProductQuantizer_t quantizer

)

De-allocate Product Quantizer.

Parameters:

quantizer – [in]

Returns:

cuvsError_t

cuvsError_t cuvsProductQuantizerBuild(

cuvsResources_t res,

cuvsProductQuantizerParams_t params,

DLManagedTensor *dataset,

cuvsProductQuantizer_t quantizer

)

Builds a product quantizer to be used later for quantizing the dataset.

Parameters:

• res – [in] raft resource

• params – [in] Parameters for product quantizer training

• dataset – [in] a row-major host or device matrix

• quantizer – [out] trained product quantizer

cuvsError_t cuvsProductQuantizerTransform(

cuvsResources_t res,

cuvsProductQuantizer_t quantizer,

DLManagedTensor *dataset,

DLManagedTensor *codes_out,

DLManagedTensor *vq_labels

)

Applies product quantization transform to the given dataset.

This applies product quantization to a dataset.

Parameters:

• res – [in] raft resource

• quantizer – [in] product quantizer

• dataset – [in] a row-major host or device matrix to transform

• codes_out – [out] a row-major device matrix to store transformed data

• vq_labels – [out] a device vector to store VQ labels. Optional, can be NULL.

cuvsError_t cuvsProductQuantizerInverseTransform(

cuvsResources_t res,

cuvsProductQuantizer_t quantizer,

DLManagedTensor *pq_codes,

DLManagedTensor *out,

DLManagedTensor *vq_labels

)

Applies product quantization inverse transform to the given quantized codes.

This applies product quantization inverse transform to the given quantized codes.

Parameters:

• res – [in] raft resource

• quantizer – [in] product quantizer

• pq_codes – [in] a row-major device matrix of quantized codes

• out – [out] a row-major device matrix to store the original data

• vq_labels – [out] a device vector containing the VQ labels when VQ is used. Optional, can be NULL.

cuvsError_t cuvsProductQuantizerGetPqBits(

cuvsProductQuantizer_t quantizer,

uint32_t *pq_bits

)

Get the bit length of the vector element after compression by PQ.

Parameters:

• quantizer – [in] product quantizer

• pq_bits – [out] bit length of the vector element after compression by PQ

cuvsError_t cuvsProductQuantizerGetPqDim(

cuvsProductQuantizer_t quantizer,

uint32_t *pq_dim

)

Get the dimensionality of the vector after compression by PQ.

Parameters:

• quantizer – [in] product quantizer

• pq_dim – [out] dimensionality of the vector after compression by PQ

cuvsError_t cuvsProductQuantizerGetPqCodebook(

cuvsProductQuantizer_t quantizer,

DLManagedTensor *pq_codebook

)

Get the PQ codebook.

Parameters:

• quantizer – [in] product quantizer

• pq_codebook – [out] PQ codebook

cuvsError_t cuvsProductQuantizerGetVqCodebook(

cuvsProductQuantizer_t quantizer,

DLManagedTensor *vq_codebook

)

Get the VQ codebook.

Parameters:

• quantizer – [in] product quantizer

• vq_codebook – [out] VQ codebook

cuvsError_t cuvsProductQuantizerGetEncodedDim(

cuvsProductQuantizer_t quantizer,

uint32_t *encoded_dim

)

Get the encoded dimension of the quantized dataset.

Parameters:

• quantizer – [in] product quantizer

• encoded_dim – [out] encoded dimension of the quantized dataset

cuvsError_t cuvsProductQuantizerGetUseVq(

cuvsProductQuantizer_t quantizer,

bool *use_vq

)

Get whether VQ is used.

Parameters:

• quantizer – [in] product quantizer

• use_vq – [out] whether VQ is used

struct cuvsProductQuantizerParams

#include <pq.h>

Product quantizer parameters.

Public Members

uint32_t pq_bits

The bit length of the vector element after compression by PQ.

Possible values: within [4, 16].

Hint: the smaller the ‘pq_bits’, the smaller the index size and the better the search performance, but the lower the recall.

uint32_t pq_dim

The dimensionality of the vector after compression by PQ. When zero, an optimal value is selected using a heuristic.

TODO: at the moment dim must be a multiple pq_dim.

bool use_subspaces

Whether to use subspaces for product quantization (PQ). When true, one PQ codebook is used for each subspace. Otherwise, a single PQ codebook is used.

bool use_vq

Whether to use Vector Quantization (KMeans) before product quantization (PQ). When true, VQ is used before PQ. When false, only product quantization is used.

uint32_t vq_n_centers

Vector Quantization (VQ) codebook size - number of “coarse cluster centers”. When zero, an optimal value is selected using a heuristic. When one, only product quantization is used.

uint32_t kmeans_n_iters

The number of iterations searching for kmeans centers (both VQ & PQ phases).

cuvsKMeansType pq_kmeans_type

The type of kmeans algorithm to use for PQ training.

uint32_t max_train_points_per_pq_code

The max number of data points to use per PQ code during PQ codebook training. Using more data points per PQ code may increase the quality of PQ codebook but may also increase the build time. We will use pq_n_centers * max_train_points_per_pq_code training points to train each PQ codebook.

uint32_t max_train_points_per_vq_cluster

The max number of data points to use per VQ cluster.

struct cuvsProductQuantizer

#include <pq.h>

Defines and stores product quantizer upon training.

The quantization is performed by a linear mapping of an interval in the float data type to the full range of the quantized int type.

Scalar Quantizer

typedef struct cuvsScalarQuantizerParams *cuvsScalarQuantizerParams_t

typedef cuvsScalarQuantizer *cuvsScalarQuantizer_t

cuvsError_t cuvsScalarQuantizerParamsCreate(

cuvsScalarQuantizerParams_t *params

)

Allocate Scalar Quantizer params, and populate with default values.

Parameters:

params – [in] cuvsScalarQuantizerParams_t to allocate

Returns:

cuvsError_t

cuvsError_t cuvsScalarQuantizerParamsDestroy(

cuvsScalarQuantizerParams_t params

)

De-allocate Scalar Quantizer params.

Parameters:

params – [in]

Returns:

cuvsError_t

cuvsError_t cuvsScalarQuantizerCreate(

cuvsScalarQuantizer_t *quantizer

)

Allocate Scalar Quantizer and populate with default values.

Parameters:

quantizer – [in] cuvsScalarQuantizer_t to allocate

Returns:

cuvsError_t

cuvsError_t cuvsScalarQuantizerDestroy(

cuvsScalarQuantizer_t quantizer

)

De-allocate Scalar Quantizer.

Parameters:

quantizer – [in]

Returns:

cuvsError_t

cuvsError_t cuvsScalarQuantizerTrain(

cuvsResources_t res,

cuvsScalarQuantizerParams_t params,

DLManagedTensor *dataset,

cuvsScalarQuantizer_t quantizer

)

Trains a scalar quantizer to be used later for quantizing the dataset.

Parameters:

• res – [in] raft resource

• params – [in] configure scalar quantizer, e.g. quantile

• dataset – [in] a row-major host or device matrix

• quantizer – [out] trained scalar quantizer

cuvsError_t cuvsScalarQuantizerTransform(

cuvsResources_t res,

cuvsScalarQuantizer_t quantizer,

DLManagedTensor *dataset,

DLManagedTensor *out

)

Applies quantization transform to given dataset.

Parameters:

• res – [in] raft resource

• quantizer – [in] a scalar quantizer

• dataset – [in] a row-major host or device matrix to transform

• out – [out] a row-major host or device matrix to store transformed data

cuvsError_t cuvsScalarQuantizerInverseTransform(

cuvsResources_t res,

cuvsScalarQuantizer_t quantizer,

DLManagedTensor *dataset,

DLManagedTensor *out

)

Perform inverse quantization step on previously quantized dataset.

Note that depending on the chosen data types train dataset the conversion is not lossless.

Parameters:

• res – [in] raft resource

• quantizer – [in] a scalar quantizer

• dataset – [in] a row-major host or device matrix

• out – [out] a row-major host or device matrix

struct cuvsScalarQuantizerParams

#include <scalar.h>

Scalar quantizer parameters.

struct cuvsScalarQuantizer

#include <scalar.h>

Defines and stores scalar for quantisation upon training.

The quantization is performed by a linear mapping of an interval in the float data type to the full range of the quantized int type.