Add mean and median threshold modes to binary quantization (#716)

The current binary quantization function sets a bit when the corresponding input dataset element is positive. This method (zero threshold mode) does not work well for, for example, a dataset where all elements are positive. This PR adds mean and median modes that set bits when the corresponding elements are larger than the dim-wise mean and median, respectively.

The new `transform` function requires NVIDIA/raft#2592 to be merged to support large datasets.

TODO:
- [x] C++
- [x] C
- [x] test
- [x] <del>python</del> The Python support will be added in a later PR, as the Python package build requires the C header file installed by `conda create` to include this update.

Authors:
  - tsuki (https://github.com/enp1s0)
  - Corey J. Nolet (https://github.com/cjnolet)

Approvers:
  - Tamas Bela Feher (https://github.com/tfeher)
  - Corey J. Nolet (https://github.com/cjnolet)

URL: #716

Author: enp1s0

cpp/include/cuvs/preprocessing/quantize/binary.h

@@ -24,6 +24,89 @@
 extern "C" {
 #endif
 
+/**
+ * @brief 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.
+ *
+ */
+enum cuvsBinaryQuantizerThreshold { ZERO, MEAN, SAMPLING_MEDIAN };
+
+/**
+ * @brief Binary quantizer parameters.
+ */
+struct cuvsBinaryQuantizerParams {
+  /*
+   * specifies the threshold to set a bit in cuvsBinaryQuantizerTransform
+   */
+  cuvsBinaryQuantizerThreshold threshold = MEAN;
+
+  /*
+   * specifies the sampling ratio
+   */
+  float sampling_ratio = 0.1;
+};
+
+typedef struct cuvsBinaryQuantizerParams* cuvsBinaryQuantizerParams_t;
+
+/**
+ * @brief Allocate Binary Quantizer params, and populate with default values
+ *
+ * @param[in] params cuvsBinaryQuantizerParams_t to allocate
+ * @return cuvsError_t
+ */
+cuvsError_t cuvsBinaryQuantizerParamsCreate(cuvsBinaryQuantizerParams_t* params);
+
+/**
+ * @brief De-allocate Binary Quantizer params
+ *
+ * @param[in] params
+ * @return cuvsError_t
+ */
+cuvsError_t cuvsBinaryQuantizerParamsDestroy(cuvsBinaryQuantizerParams_t params);
+
+/**
+ * @brief 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.
+ */
+typedef struct {
+  uintptr_t addr;
+  DLDataType dtype;
+} cuvsBinaryQuantizer;
+
+typedef cuvsBinaryQuantizer* cuvsBinaryQuantizer_t;
+
+/**
+ * @brief Allocate Binary Quantizer and populate with default values
+ *
+ * @param[in] quantizer cuvsBinaryQuantizer_t to allocate
+ * @return cuvsError_t
+ */
+cuvsError_t cuvsBinaryQuantizerCreate(cuvsBinaryQuantizer_t* quantizer);
+
+/**
+ * @brief De-allocate Binary Quantizer
+ *
+ * @param[in] quantizer
+ * @return cuvsError_t
+ */
+cuvsError_t cuvsBinaryQuantizerDestroy(cuvsBinaryQuantizer_t quantizer);
+
+/**
+ * @brief Trains a scalar quantizer to be used later for quantizing the dataset.
+ *
+ * @param[in] res raft resource
+ * @param[in] params configure binary quantizer, e.g. threshold
+ * @param[in] dataset a row-major host or device matrix
+ * @param[out] quantizer trained binary quantizer
+ */
+cuvsError_t cuvsBinaryQuantizerTrain(cuvsResources_t res,
+                                     cuvsBinaryQuantizerParams_t params,
+                                     DLManagedTensor* dataset,
+                                     cuvsBinaryQuantizer_t quantizer);
+
 /**
  * @brief Applies binary quantization transform to the given dataset
  *
@@ -39,6 +122,23 @@ cuvsError_t cuvsBinaryQuantizerTransform(cuvsResources_t res,
                                          DLManagedTensor* dataset,
                                          DLManagedTensor* out);
 
+/**
+ * @brief 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.
+ *
+ * @param[in] res raft resource
+ * @param[in] quantizer binary quantizer
+ * @param[in] dataset a row-major host or device matrix to transform
+ * @param[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);
+
 #ifdef __cplusplus
 }
 #endif