Quantize#

This page provides C++ class references for the publicly-exposed elements of the cuvs/preprocessing/quantize package.

Binary Quantizer#

#include <cuvs/preprocessing/quantize/binary.hpp>

namespace cuvs::preprocessing::quantize::binary

enum class bit_threshold#

quantizer algorithms. The mean and sampling_median thresholds are calculated separately for each dimension.

Values:

enumerator zero#
enumerator mean#
enumerator sampling_median#
quantizer<double> train(
raft::resources const &res,
const params params,
raft::device_matrix_view<const double, int64_t> dataset
)#

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

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::binary::params params;
auto quantizer = cuvs::preprocessing::quantize::binary::train(handle, params, dataset);

Parameters:

  • res – [in] raft resource

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

  • dataset – [in] a row-major matrix view on device

Returns:

quantizer

quantizer<double> train(
raft::resources const &res,
const params params,
raft::host_matrix_view<const double, int64_t> dataset
)#

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

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::binary::params params;
auto quantizer = cuvs::preprocessing::quantize::binary::train(handle, params, dataset);

Parameters:

  • res – [in] raft resource

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

  • dataset – [in] a row-major matrix view on host

Returns:

quantizer

void transform(
raft::resources const &res,
const quantizer<double> &quantizer,
raft::device_matrix_view<const double, int64_t> dataset,
raft::device_matrix_view<uint8_t, int64_t> out
)#

Applies binary quantization transform to given dataset. If a dataset element is positive, set the corresponding bit to 1.

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::binary::params params;
auto quantized_dataset = raft::make_device_matrix<uint8_t, int64_t>(handle, samples,
features);
auto quantizer = cuvs::preprocessing::quantize::binary::train(handle, params,
raft::make_const_mdspan(dataset.view()));
cuvs::preprocessing::quantize::binary::transform(handle, quantizer,
raft::make_const_mdspan(dataset.view()), quantized_dataset.view());

Parameters:

  • res – [in] raft resource

  • quantizer – [in] a binary quantizer

  • dataset – [in] a row-major matrix view on device

  • out – [out] a row-major matrix view on device

void transform(
raft::resources const &res,
const quantizer<double> &quantizer,
raft::host_matrix_view<const double, int64_t> dataset,
raft::host_matrix_view<uint8_t, int64_t> out
)#

Applies binary quantization transform to given dataset. If a dataset element is positive, set the corresponding bit to 1.

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::binary::params params;
auto quantized_dataset = raft::make_host_matrix<uint8_t, int64_t>(handle, samples,
features);
auto quantizer = cuvs::preprocessing::quantize::binary::train(handle, params,
raft::make_const_mdspan(dataset.view()));
cuvs::preprocessing::quantize::binary::transform(handle, quantizer,
raft::make_const_mdspan(dataset.view()), quantized_dataset.view());

Parameters:

  • res – [in] raft resource

  • quantizer – [in] a binary quantizer

  • dataset – [in] a row-major matrix view on host

  • out – [out] a row-major matrix view on host

quantizer<float> train(
raft::resources const &res,
const params params,
raft::device_matrix_view<const float, int64_t> dataset
)#

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

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::binary::params params;
auto quantizer = cuvs::preprocessing::quantize::binary::train(handle, params, dataset);

Parameters:

  • res – [in] raft resource

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

  • dataset – [in] a row-major matrix view on device

Returns:

quantizer

quantizer<float> train(
raft::resources const &res,
const params params,
raft::host_matrix_view<const float, int64_t> dataset
)#

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

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::binary::params params;
auto quantizer = cuvs::preprocessing::quantize::binary::train(handle, params, dataset);

Parameters:

  • res – [in] raft resource

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

  • dataset – [in] a row-major matrix view on host

Returns:

quantizer

void transform(
raft::resources const &res,
const quantizer<float> &quantizer,
raft::device_matrix_view<const float, int64_t> dataset,
raft::device_matrix_view<uint8_t, int64_t> out
)#

Applies binary quantization transform to given dataset. If a dataset element is positive, set the corresponding bit to 1.

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::binary::params params;
raft::device_matrix<float, uint64_t> dataset = read_dataset(filename);
int64_t quantized_dim = raft::div_rounding_up_safe(dataset.extent(1), sizeof(uint8_t) * 8);
auto quantized_dataset = raft::make_device_matrix<uint8_t, int64_t>(
   handle, dataset.extent(0), quantized_dim);
auto quantizer = cuvs::preprocessing::quantize::binary::train(handle, params,
raft::make_const_mdspan(dataset.view()));
cuvs::preprocessing::quantize::binary::transform(handle, quantizer,
raft::make_const_mdspan(dataset.view()), quantized_dataset.view());

Parameters:

  • res – [in] raft resource

  • quantizer – [in] a binary quantizer

  • dataset – [in] a row-major matrix view on device

  • out – [out] a row-major matrix view on device

void transform(
raft::resources const &res,
const quantizer<float> &quantizer,
raft::host_matrix_view<const float, int64_t> dataset,
raft::host_matrix_view<uint8_t, int64_t> out
)#

Applies binary quantization transform to given dataset. If a dataset element is positive, set the corresponding bit to 1.

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::binary::params params;
raft::host_matrix<float, uint64_t> dataset = read_dataset(filename);
int64_t quantized_dim = raft::div_rounding_up_safe(dataset.extent(1), sizeof(uint8_t) * 8);
auto quantized_dataset = raft::make_host_matrix<uint8_t, int64_t>(
   handle, params, dataset.extent(0), quantized_dim);
auto quantizer = cuvs::preprocessing::quantize::binary::train(handle, params,
raft::make_const_mdspan(dataset.view()));
cuvs::preprocessing::quantize::binary::transform(handle, quantizer,
raft::make_const_mdspan(dataset.view()), quantized_dataset.view());

Parameters:

  • res – [in] raft resource

  • quantizer – [in] a binary quantizer

  • dataset – [in] a row-major matrix view on host

  • out – [out] a row-major matrix view on host

quantizer<half> train(
raft::resources const &res,
const params params,
raft::device_matrix_view<const half, int64_t> dataset
)#

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

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::binary::params params;
auto quantizer = cuvs::preprocessing::quantize::binary::train(handle, params, dataset);

Parameters:

  • res – [in] raft resource

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

  • dataset – [in] a row-major matrix view on device

Returns:

quantizer

quantizer<half> train(
raft::resources const &res,
const params params,
raft::host_matrix_view<const half, int64_t> dataset
)#

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

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::binary::params params;
auto quantizer = cuvs::preprocessing::quantize::binary::train(handle, params, dataset);

Parameters:

  • res – [in] raft resource

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

  • dataset – [in] a row-major matrix view on host

Returns:

quantizer

void transform(
raft::resources const &res,
const quantizer<half> &quantizer,
raft::device_matrix_view<const half, int64_t> dataset,
raft::device_matrix_view<uint8_t, int64_t> out
)#

Applies binary quantization transform to given dataset.

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::binary::params params;
raft::device_matrix<half, uint64_t> dataset = read_dataset(filename);
int64_t quantized_dim = raft::div_rounding_up_safe(dataset.extent(1), sizeof(uint8_t) * 8);
auto quantized_dataset = raft::make_device_matrix<uint8_t, int64_t>(
   handle, params, dataset.extent(0), quantized_dim);
auto quantizer = cuvs::preprocessing::quantize::binary::train(handle, params,
raft::make_const_mdspan(dataset.view()));
cuvs::preprocessing::quantize::binary::transform(handle, quantizer,
raft::make_const_mdspan(dataset.view()), quantized_dataset.view());

Parameters:

  • res – [in] raft resource

  • quantizer – [in] a binary quantizer

  • dataset – [in] a row-major matrix view on device

  • out – [out] a row-major matrix view on device

void transform(
raft::resources const &res,
const quantizer<half> &quantizer,
raft::host_matrix_view<const half, int64_t> dataset,
raft::host_matrix_view<uint8_t, int64_t> out
)#

Applies binary quantization transform to given dataset.

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::binary::params params;
raft::host_matrix<half, uint64_t> dataset = read_dataset(filename);
int64_t quantized_dim = raft::div_rounding_up_safe(dataset.extent(1), sizeof(uint8_t) * 8);
auto quantized_dataset = raft::make_host_matrix<uint8_t, int64_t>(
   handle, params, dataset.extent(0), quantized_dim);
auto quantizer = cuvs::preprocessing::quantize::binary::train(handle, params,
raft::make_const_mdspan(dataset.view()));
cuvs::preprocessing::quantize::binary::transform(handle, quantizer,
raft::make_const_mdspan(dataset.view()), quantized_dataset.view());

Parameters:

  • res – [in] raft resource

  • quantizer – [in] a binary quantizer

  • dataset – [in] a row-major matrix view on host

  • out – [out] a row-major matrix view on host

void transform(
raft::resources const &res,
raft::device_matrix_view<const double, int64_t> dataset,
raft::device_matrix_view<uint8_t, int64_t> out
)#

[deprecated] Applies binary quantization transform to given dataset. If a dataset element is positive, set the corresponding bit to 1.

Parameters:

  • res – [in] raft resource

  • dataset – [in] a row-major matrix view on device

  • out – [out] a row-major matrix view on device

void transform(
raft::resources const &res,
raft::host_matrix_view<const double, int64_t> dataset,
raft::host_matrix_view<uint8_t, int64_t> out
)#

[deprecated] Applies binary quantization transform to given dataset. If a dataset element is positive, set the corresponding bit to 1.

Parameters:

  • res – [in] raft resource

  • dataset – [in] a row-major matrix view on host

  • out – [out] a row-major matrix view on host

void transform(
raft::resources const &res,
raft::device_matrix_view<const float, int64_t> dataset,
raft::device_matrix_view<uint8_t, int64_t> out
)#

[deprecated] Applies binary quantization transform to given dataset. If a dataset element is positive, set the corresponding bit to 1.

Parameters:

  • res – [in] raft resource

  • dataset – [in] a row-major matrix view on device

  • out – [out] a row-major matrix view on device

void transform(
raft::resources const &res,
raft::host_matrix_view<const float, int64_t> dataset,
raft::host_matrix_view<uint8_t, int64_t> out
)#

[deprecated] Applies binary quantization transform to given dataset. If a dataset element is positive, set the corresponding bit to 1.

Parameters:

  • res – [in] raft resource

  • dataset – [in] a row-major matrix view on host

  • out – [out] a row-major matrix view on host

void transform(
raft::resources const &res,
raft::device_matrix_view<const half, int64_t> dataset,
raft::device_matrix_view<uint8_t, int64_t> out
)#

[deprecated] Applies binary quantization transform to given dataset. If a dataset element is positive, set the corresponding bit to 1.

Parameters:

  • res – [in] raft resource

  • dataset – [in] a row-major matrix view on device

  • out – [out] a row-major matrix view on device

void transform(
raft::resources const &res,
raft::host_matrix_view<const half, int64_t> dataset,
raft::host_matrix_view<uint8_t, int64_t> out
)#

[deprecated] Applies binary quantization transform to given dataset. If a dataset element is positive, set the corresponding bit to 1.

Parameters:

  • res – [in] raft resource

  • dataset – [in] a row-major matrix view on host

  • out – [out] a row-major matrix view on host

struct params#
#include <binary.hpp>

quantizer parameters.

Public Members

bit_threshold threshold = bit_threshold::mean#

Threshold method for binarization.

float sampling_ratio = 0.1#

Specifies the sampling ratio.

template<typename T>
struct quantizer#
#include <binary.hpp>

Store the threshold vector for quantization. In the binary::transform function, a bit is set if the corresponding element in the dataset vector is greater than the corresponding element in the threshold vector.

Template Parameters:

T – data element type

Public Functions

inline quantizer(raft::resources const &res)#

Construct a quantizer with an empty threshold vector.

Public Members

raft::device_vector<T, int64_t> threshold#

Threshold vector used for binarization.

Product Quantizer#

#include <cuvs/preprocessing/quantize/pq.hpp>

namespace cuvs::preprocessing::quantize::pq

quantizer<float> build(
raft::resources const &res,
const params params,
raft::device_matrix_view<const float, int64_t> dataset
)#

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

The use of a pool memory resource is recommended for more consistent training performance.

Usage example: 

raft::handle_t handle;
// Set the workspace memory resource to a pool with 2 GiB upper limit.
raft::resource::set_workspace_to_pool_resource(handle, 2 * 1024 * 1024 * 1024ull);
cuvs::preprocessing::quantize::pq::params params;
auto quantizer = cuvs::preprocessing::quantize::pq::build(handle, params, dataset);

Parameters:

  • res – [in] raft resource

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

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

Returns:

quantizer

quantizer<float> build(
raft::resources const &res,
const params params,
raft::host_matrix_view<const float, int64_t> dataset
)#

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

The use of a pool memory resource is recommended for more consistent training performance.

Usage example: 

raft::handle_t handle;
// Set the workspace memory resource to a pool with 2 GiB upper limit.
raft::resource::set_workspace_to_pool_resource(handle, 2 * 1024 * 1024 * 1024ull);
cuvs::preprocessing::quantize::pq::params params;
auto quantizer = cuvs::preprocessing::quantize::pq::build(handle, params, dataset);

Parameters:

  • res – [in] raft resource

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

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

Returns:

quantizer

void transform(
raft::resources const &res,
const quantizer<float> &quant,
raft::device_matrix_view<const float, int64_t> dataset,
raft::device_matrix_view<uint8_t, int64_t> codes_out,
std::optional<raft::device_vector_view<uint32_t, int64_t>> vq_labels = std::nullopt
)#

Applies quantization transform to given dataset.

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::pq::params params;
auto quantizer = cuvs::preprocessing::quantize::pq::build(handle, params, dataset);
auto quantized_dim = get_quantized_dim(quantizer.params_quantizer);
auto quantized_dataset =
  raft::make_device_matrix<uint8_t, int64_t>(handle, samples, quantized_dim);
cuvs::preprocessing::quantize::pq::transform(handle, quantizer, dataset,
  quantized_dataset.view());

Parameters:

  • res – [in] raft resource

  • quant – [in] a product quantizer

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

  • codes_out – [out] a row-major matrix view on device containing the PQ codes

  • vq_labels – [out] a vector view on device containing the VQ labels when VQ is used, optional

void transform(
raft::resources const &res,
const quantizer<float> &quant,
raft::host_matrix_view<const float, int64_t> dataset,
raft::device_matrix_view<uint8_t, int64_t> codes_out,
std::optional<raft::device_vector_view<uint32_t, int64_t>> vq_labels = std::nullopt
)#

Applies quantization transform to given dataset.

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::pq::params params;
auto quantizer = cuvs::preprocessing::quantize::pq::build(handle, params, dataset);
auto quantized_dim = get_quantized_dim(quantizer.params_quantizer);
auto quantized_dataset =
  raft::make_device_matrix<uint8_t, int64_t>(handle, samples, quantized_dim);
cuvs::preprocessing::quantize::pq::transform(handle, quantizer, dataset,
  quantized_dataset.view());

Parameters:

  • res – [in] raft resource

  • quant – [in] a product quantizer

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

  • codes_out – [out] a row-major matrix view on device containing the PQ codes

  • vq_labels – [out] a vector view on device containing the VQ labels when VQ is used, optional

inline int64_t get_quantized_dim(const params &config)#

Get the dimension of the quantized dataset (in bytes)

Parameters:

config – [in] product quantizer parameters

Returns:

the dimension of the quantized dataset

void inverse_transform(
raft::resources const &res,
const quantizer<float> &quant,
raft::device_matrix_view<const uint8_t, int64_t> pq_codes,
raft::device_matrix_view<float, int64_t> out,
std::optional<raft::device_vector_view<const uint32_t, int64_t>> vq_labels = std::nullopt
)#

Applies inverse quantization transform to given dataset.

Parameters:

  • res – [in] raft resource

  • quant – [in] a product quantizer

  • pq_codes – [in] a row-major matrix view on device containing the PQ codes

  • out – [out] a row-major matrix view on device

  • vq_labels – [in] a vector view on device containing the VQ labels when VQ is used, optional

struct params#
#include <pq.hpp>

Product Quantizer parameters.

Public Members

uint32_t pq_bits = 8#

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

Possible value range: [4-16].

Hint: the smaller the ‘pq_bits’, the smaller the index size and the faster the fit/transform time, but the lower the recall.

uint32_t pq_dim = 0#

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 = true#

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 = false#

Whether to use Vector Quantization (KMeans) before product quantization (PQ). When true, VQ is used and PQ is trained on the residuals.

uint32_t vq_n_centers = 0#

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

uint32_t kmeans_n_iters = 25#

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

cuvs::cluster::kmeans::kmeans_type pq_kmeans_type = cuvs::cluster::kmeans::kmeans_type::KMeansBalanced#

Type of k-means algorithm for PQ training. Balanced k-means tends to be faster than regular k-means for PQ training, for problem sets where the number of points per cluster are approximately equal. Regular k-means may be better for skewed cluster distributions.

uint32_t max_train_points_per_pq_code = 256#

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 = 1024#

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

template<typename T>
struct quantizer#
#include <pq.hpp>

Defines and stores VPQ codebooks upon training.

Template Parameters:

T – data element type

Public Members

params params_quantizer#

Parameters used to build this quantizer.

cuvs::neighbors::vpq_dataset<T, int64_t> vpq_codebooks#

VPQ codebooks produced during training.

Scalar Quantizer#

#include <cuvs/preprocessing/quantize/scalar.hpp>

namespace cuvs::preprocessing::quantize::scalar

quantizer<double> train(
raft::resources const &res,
const params params,
raft::device_matrix_view<const double, int64_t> dataset
)

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

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::scalar::params params;
auto quantizer = cuvs::preprocessing::quantize::scalar::train(handle, params, dataset);

Parameters:

  • res – [in] raft resource

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

  • dataset – [in] a row-major matrix view on device

Returns:

quantizer

quantizer<double> train(
raft::resources const &res,
const params params,
raft::host_matrix_view<const double, int64_t> dataset
)

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

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::scalar::params params;
auto quantizer = cuvs::preprocessing::quantize::scalar::train(handle, params, dataset);

Parameters:

  • res – [in] raft resource

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

  • dataset – [in] a row-major matrix view on host

Returns:

quantizer

void transform(
raft::resources const &res,
const quantizer<double> &quantizer,
raft::device_matrix_view<const double, int64_t> dataset,
raft::device_matrix_view<int8_t, int64_t> out
)#

Applies quantization transform to given dataset.

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::scalar::params params;
auto quantizer = cuvs::preprocessing::quantize::scalar::train<double, int8_t>(handle, params,
dataset); auto quantized_dataset = raft::make_device_matrix<int8_t, int64_t>(handle, samples,
features); cuvs::preprocessing::quantize::scalar::transform(handle, quantizer, dataset,
quantized_dataset.view());

Parameters:

  • res – [in] raft resource

  • quantizer – [in] a scalar quantizer

  • dataset – [in] a row-major matrix view on device

  • out – [out] a row-major matrix view on device

void transform(
raft::resources const &res,
const quantizer<double> &quantizer,
raft::host_matrix_view<const double, int64_t> dataset,
raft::host_matrix_view<int8_t, int64_t> out
)#

Applies quantization transform to given dataset.

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::scalar::params params;
auto quantizer = cuvs::preprocessing::quantize::scalar::train<double, int8_t>(handle, params,
dataset); auto quantized_dataset = raft::make_host_matrix<int8_t, int64_t>(samples, features);
cuvs::preprocessing::quantize::scalar::transform(handle, quantizer, dataset,
quantized_dataset.view());

Parameters:

  • res – [in] raft resource

  • quantizer – [in] a scalar quantizer

  • dataset – [in] a row-major matrix view on host

  • out – [out] a row-major matrix view on host

void inverse_transform(
raft::resources const &res,
const quantizer<double> &quantizer,
raft::device_matrix_view<const int8_t, int64_t> dataset,
raft::device_matrix_view<double, int64_t> out
)#

Perform inverse quantization step on previously quantized dataset.

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

Usage example: 

auto quantized_dataset = raft::make_device_matrix<int8_t, int64_t>(handle, samples, features);
cuvs::preprocessing::quantize::scalar::transform(handle, quantizer, dataset,
quantized_dataset.view()); auto dataset_revert = raft::make_device_matrix<double,
int64_t>(handle, samples, features);
cuvs::preprocessing::quantize::scalar::inverse_transform(handle, quantizer,
dataset_revert.view());

Parameters:

  • res – [in] raft resource

  • quantizer – [in] a scalar quantizer

  • dataset – [in] a row-major matrix view on device

  • out – [out] a row-major matrix view on device

void inverse_transform(
raft::resources const &res,
const quantizer<double> &quantizer,
raft::host_matrix_view<const int8_t, int64_t> dataset,
raft::host_matrix_view<double, int64_t> out
)#

Perform inverse quantization step on previously quantized dataset.

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

Usage example: 

auto quantized_dataset = raft::make_host_matrix<int8_t, int64_t>(samples, features);
cuvs::preprocessing::quantize::scalar::transform(handle, quantizer, dataset,
quantized_dataset.view()); auto dataset_revert = raft::make_host_matrix<double, int64_t>(samples,
features); cuvs::preprocessing::quantize::scalar::inverse_transform(handle, quantizer,
dataset_revert.view());

Parameters:

  • res – [in] raft resource

  • quantizer – [in] a scalar quantizer

  • dataset – [in] a row-major matrix view on host

  • out – [out] a row-major matrix view on host

quantizer<float> train(
raft::resources const &res,
const params params,
raft::device_matrix_view<const float, int64_t> dataset
)

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

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::scalar::params params;
auto quantizer = cuvs::preprocessing::quantize::scalar::train(handle, params, dataset);

Parameters:

  • res – [in] raft resource

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

  • dataset – [in] a row-major matrix view on device

Returns:

quantizer

quantizer<float> train(
raft::resources const &res,
const params params,
raft::host_matrix_view<const float, int64_t> dataset
)

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

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::scalar::params params;
auto quantizer = cuvs::preprocessing::quantize::scalar::train(handle, params, dataset);

Parameters:

  • res – [in] raft resource

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

  • dataset – [in] a row-major matrix view on host

Returns:

quantizer

void transform(
raft::resources const &res,
const quantizer<float> &quantizer,
raft::device_matrix_view<const float, int64_t> dataset,
raft::device_matrix_view<int8_t, int64_t> out
)#

Applies quantization transform to given dataset.

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::scalar::params params;
auto quantizer = cuvs::preprocessing::quantize::scalar::train<float, int8_t>(handle, params,
dataset); auto quantized_dataset = raft::make_device_matrix<int8_t, int64_t>(handle, samples,
features); cuvs::preprocessing::quantize::scalar::transform(handle, quantizer, dataset,
quantized_dataset.view());

Parameters:

  • res – [in] raft resource

  • quantizer – [in] a scalar quantizer

  • dataset – [in] a row-major matrix view on device

  • out – [out] a row-major matrix view on device

void transform(
raft::resources const &res,
const quantizer<float> &quantizer,
raft::host_matrix_view<const float, int64_t> dataset,
raft::host_matrix_view<int8_t, int64_t> out
)#

Applies quantization transform to given dataset.

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::scalar::params params;
auto quantizer = cuvs::preprocessing::quantize::scalar::train<float, int8_t>(handle, params,
dataset); auto quantized_dataset = raft::make_host_matrix<int8_t, int64_t>(samples, features);
cuvs::preprocessing::quantize::scalar::transform(handle, quantizer, dataset,
quantized_dataset.view());

Parameters:

  • res – [in] raft resource

  • quantizer – [in] a scalar quantizer

  • dataset – [in] a row-major matrix view on host

  • out – [out] a row-major matrix view on host

void inverse_transform(
raft::resources const &res,
const quantizer<float> &quantizer,
raft::device_matrix_view<const int8_t, int64_t> dataset,
raft::device_matrix_view<float, int64_t> out
)#

Perform inverse quantization step on previously quantized dataset.

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

Usage example: 

auto quantized_dataset = raft::make_device_matrix<int8_t, int64_t>(handle, samples, features);
cuvs::preprocessing::quantize::scalar::transform(handle, quantizer, dataset,
quantized_dataset.view()); auto dataset_revert = raft::make_device_matrix<float, int64_t>(handle,
samples, features); cuvs::preprocessing::quantize::scalar::inverse_transform(handle, quantizer,
dataset_revert.view());

Parameters:

  • res – [in] raft resource

  • quantizer – [in] a scalar quantizer

  • dataset – [in] a row-major matrix view on device

  • out – [out] a row-major matrix view on device

void inverse_transform(
raft::resources const &res,
const quantizer<float> &quantizer,
raft::host_matrix_view<const int8_t, int64_t> dataset,
raft::host_matrix_view<float, int64_t> out
)#

Perform inverse quantization step on previously quantized dataset.

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

Usage example: 

auto quantized_dataset = raft::make_host_matrix<int8_t, int64_t>(samples, features);
cuvs::preprocessing::quantize::scalar::transform(handle, quantizer, dataset,
quantized_dataset.view()); auto dataset_revert = raft::make_host_matrix<float, int64_t>(samples,
features); cuvs::preprocessing::quantize::scalar::inverse_transform(handle, quantizer,
dataset_revert.view());

Parameters:

  • res – [in] raft resource

  • quantizer – [in] a scalar quantizer

  • dataset – [in] a row-major matrix view on host

  • out – [out] a row-major matrix view on host

quantizer<half> train(
raft::resources const &res,
const params params,
raft::device_matrix_view<const half, int64_t> dataset
)

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

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::scalar::params params;
auto quantizer = cuvs::preprocessing::quantize::scalar::train(handle, params, dataset);

Parameters:

  • res – [in] raft resource

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

  • dataset – [in] a row-major matrix view on device

Returns:

quantizer

quantizer<half> train(
raft::resources const &res,
const params params,
raft::host_matrix_view<const half, int64_t> dataset
)

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

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::scalar::params params;
auto quantizer = cuvs::preprocessing::quantize::scalar::train(handle, params, dataset);

Parameters:

  • res – [in] raft resource

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

  • dataset – [in] a row-major matrix view on host

Returns:

quantizer

void transform(
raft::resources const &res,
const quantizer<half> &quantizer,
raft::device_matrix_view<const half, int64_t> dataset,
raft::device_matrix_view<int8_t, int64_t> out
)#

Applies quantization transform to given dataset.

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::scalar::params params;
auto quantizer = cuvs::preprocessing::quantize::scalar::train<half, int8_t>(handle, params,
dataset); auto quantized_dataset = raft::make_device_matrix<int8_t, int64_t>(handle, samples,
features); cuvs::preprocessing::quantize::scalar::transform(handle, quantizer, dataset,
quantized_dataset.view());

Parameters:

  • res – [in] raft resource

  • quantizer – [in] a scalar quantizer

  • dataset – [in] a row-major matrix view on device

  • out – [out] a row-major matrix view on device

void transform(
raft::resources const &res,
const quantizer<half> &quantizer,
raft::host_matrix_view<const half, int64_t> dataset,
raft::host_matrix_view<int8_t, int64_t> out
)#

Applies quantization transform to given dataset.

Usage example: 

raft::handle_t handle;
cuvs::preprocessing::quantize::scalar::params params;
auto quantizer = cuvs::preprocessing::quantize::scalar::train<half, int8_t>(handle, params,
dataset); auto quantized_dataset = raft::make_host_matrix<int8_t, int64_t>(samples, features);
cuvs::preprocessing::quantize::scalar::transform(handle, quantizer, dataset,
quantized_dataset.view());

Parameters:

  • res – [in] raft resource

  • quantizer – [in] a scalar quantizer

  • dataset – [in] a row-major matrix view on host

  • out – [out] a row-major matrix view on host

void inverse_transform(
raft::resources const &res,
const quantizer<half> &quantizer,
raft::device_matrix_view<const int8_t, int64_t> dataset,
raft::device_matrix_view<half, int64_t> out
)#

Perform inverse quantization step on previously quantized dataset.

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

Usage example: 

auto quantized_dataset = raft::make_device_matrix<int8_t, int64_t>(handle, samples, features);
cuvs::preprocessing::quantize::scalar::transform(handle, quantizer, dataset,
quantized_dataset.view()); auto dataset_revert = raft::make_device_matrix<half, int64_t>(handle,
samples, features); cuvs::preprocessing::quantize::scalar::inverse_transform(handle, quantizer,
dataset_revert.view());

Parameters:

  • res – [in] raft resource

  • quantizer – [in] a scalar quantizer

  • dataset – [in] a row-major matrix view on device

  • out – [out] a row-major matrix view on device

void inverse_transform(
raft::resources const &res,
const quantizer<half> &quantizer,
raft::host_matrix_view<const int8_t, int64_t> dataset,
raft::host_matrix_view<half, int64_t> out
)#

Perform inverse quantization step on previously quantized dataset.

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

Usage example: 

auto quantized_dataset = raft::make_host_matrix<int8_t, int64_t>(samples, features);
cuvs::preprocessing::quantize::scalar::transform(handle, quantizer, dataset,
quantized_dataset.view()); auto dataset_revert = raft::make_host_matrix<half, int64_t>(samples,
features); cuvs::preprocessing::quantize::scalar::inverse_transform(handle, quantizer,
dataset_revert.view());

Parameters:

  • res – [in] raft resource

  • quantizer – [in] a scalar quantizer

  • dataset – [in] a row-major matrix view on host

  • out – [out] a row-major matrix view on host

struct params#
#include <scalar.hpp>

quantizer parameters.

Public Members

float quantile = 0.99#

Specifies how many outliers at top & bottom will be ignored. Needs to be within range of (0, 1].

template<typename T>
struct quantizer#
#include <scalar.hpp>

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.

Template Parameters:

T – data element type

Public Members

T min_#

Minimum value of the quantization range.

T max_#

Maximum value of the quantization range.