Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
36 commits
Select commit Hold shift + click to select a range
bc6de04
Add per-dimension scalar quantized datasets
tarang-jain Nov 2, 2026
4aec0a9
Keep scalar reconstruction finite at FP32 limits
tarang-jain Nov 3, 2026
ce4d9f9
Unify scalar quantizer modes behind shared dataset APIs
tarang-jain Nov 3, 2026
9202b60
Document scalar quantizer field migration
tarang-jain Nov 3, 2026
9a356af
Align SQ builder arguments and generated API documentation
tarang-jain Nov 3, 2026
baecf69
Merge branch 'main' into scalar-quantized-dataset
tarang-jain Nov 3, 2026
e73cce0
Rename scalar quantizer offsets to shifts
tarang-jain Nov 3, 2026
e46013e
Construct scalar quantizers from bounds and align dataset tests
tarang-jain Nov 3, 2026
bfa2676
Merge branch 'main' into scalar-quantized-dataset
tarang-jain Nov 3, 2026
31081bd
Support floating input types and consolidate scalar quantization tests
tarang-jain Nov 3, 2026
715af3d
Merge branch 'main' into scalar-quantized-dataset
tarang-jain Nov 3, 2026
a038a48
Fix half scalar quantizer shared-library export
tarang-jain Nov 3, 2026
007a55c
Compute scalar quantization reconstruction bounds during training
tarang-jain Nov 4, 2026
8e0c620
Stream scalar quantized datasets from host memory
tarang-jain Nov 4, 2026
3c10b83
Remove scalar quantizer synchronization notes
tarang-jain Nov 4, 2026
a00df6c
Merge branch 'main' into scalar-quantized-dataset
tarang-jain Nov 4, 2026
053dce7
Unify scalar training and derive quantized limits from the code type
tarang-jain Nov 4, 2026
614a84b
Store global and per-dimension scalar shifts and scales
tarang-jain Nov 5, 2026
823726d
Restrict host scalar transforms to global parameters
tarang-jain Nov 5, 2026
6e0f0b0
Fix HNSW ACE example for global scalar transform API
tarang-jain Nov 5, 2026
4368cdc
Simplify scalar quantization tests into focused cases
tarang-jain Nov 6, 2026
1a0de8d
Restore quantizer arguments for host scalar transforms
tarang-jain Nov 6, 2026
3f9984c
Rename scalar quantizer shifts_type to per_dim_type
tarang-jain Nov 6, 2026
10728a7
Preserve original global scalar quantizer bounds
tarang-jain Nov 6, 2026
ea9e922
Store scalar quantizer bounds and align preprocessing views
tarang-jain Nov 6, 2026
9caac96
Simplify scalar quantization and add per-dimension C API
tarang-jain Nov 6, 2026
1f3237e
Use existing scalar C APIs for per-dimension quantization
tarang-jain Nov 6, 2026
ad742ea
Merge branch 'main' into scalar-quantized-dataset
tarang-jain Nov 6, 2026
643b31a
Simplify scalar quantization tests and reuse DLPack conversion
tarang-jain Nov 7, 2026
7d6341a
Merge branch 'main' into scalar-quantized-dataset
tarang-jain Nov 7, 2026
c9a01f7
Move SQ error bound to the dataset and unify per-dimension mapping
tarang-jain Nov 18, 2026
7dbd0ce
Round scalar quantizer codes in double and document the view conversion
tarang-jain Nov 18, 2026
fd5dd00
Merge branch 'main' into scalar-quantized-dataset
tarang-jain Nov 18, 2026
98fe472
Make the C scalar quantizer handle opaque
tarang-jain Nov 19, 2026
5fb9e6c
Hold only the C++ quantizer in the C scalar quantizer handle
tarang-jain Nov 19, 2026
84a51b7
Store the C scalar quantizer as addr and dtype, like the binary quant…
tarang-jain Nov 19, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 58 additions & 8 deletions c/include/cuvs/preprocessing/quantize/scalar.h
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION.
* SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
* SPDX-License-Identifier: Apache-2.0
*/

Expand All @@ -19,15 +19,24 @@ extern "C" {
* @defgroup preprocessing_c_scalar C API for Scalar Quantizer
* @{
*/
/** Select global or per-dimension scalar quantization bounds. */
enum cuvsScalarQuantizationMode {
CUVS_SCALAR_GLOBAL = 0,
CUVS_SCALAR_PER_DIMENSION = 1
};

/**
* @brief Scalar quantizer parameters.
* @brief Scalar quantizer parameters. Allocate with cuvsScalarQuantizerParamsCreate.
*/
struct cuvsScalarQuantizerParams {
/*
/**
* specifies how many outliers at top & bottom will be ignored
* needs to be within range of (0, 1]
*/
float quantile;

/** Quantization mode. Defaults to CUVS_SCALAR_GLOBAL. */
enum cuvsScalarQuantizationMode mode;
};

typedef struct cuvsScalarQuantizerParams* cuvsScalarQuantizerParams_t;
Expand All @@ -53,10 +62,13 @@ CUVS_EXPORT cuvsError_t cuvsScalarQuantizerParamsDestroy(cuvsScalarQuantizerPara
*
* 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.
* Allocate with cuvsScalarQuantizerCreate and release with cuvsScalarQuantizerDestroy.
* The quantizer owns its global or per-dimension bounds. Read and set global bounds with
* cuvsScalarQuantizerGetBounds and cuvsScalarQuantizerSetBounds.
*/
typedef struct {
double min_;
double max_;
uintptr_t addr;
DLDataType dtype;
} cuvsScalarQuantizer;

typedef cuvsScalarQuantizer* cuvsScalarQuantizer_t;
Expand All @@ -70,20 +82,54 @@ typedef cuvsScalarQuantizer* cuvsScalarQuantizer_t;
CUVS_EXPORT cuvsError_t cuvsScalarQuantizerCreate(cuvsScalarQuantizer_t* quantizer);

/**
* @brief De-allocate Scalar Quantizer
* @brief De-allocate Scalar Quantizer after outstanding stream work completes.
*
* @param[in] quantizer
* @return cuvsError_t
*/
CUVS_EXPORT cuvsError_t cuvsScalarQuantizerDestroy(cuvsScalarQuantizer_t quantizer);

/**
* @brief Get the global bounds of a scalar quantizer.
*
* Fails for a quantizer holding per-dimension bounds.
*
* @param[in] quantizer a scalar quantizer
* @param[out] min lower bound shared by all dimensions
* @param[out] max upper bound shared by all dimensions
* @return cuvsError_t
*/
CUVS_EXPORT cuvsError_t cuvsScalarQuantizerGetBounds(cuvsScalarQuantizer_t quantizer,
double* min,
double* max);

/**
* @brief Set global bounds on a scalar quantizer without training.
*
* Replaces any trained global or per-dimension bounds.
* Complete outstanding stream work using the quantizer before changing its bounds.
*
* @param[in,out] quantizer scalar quantizer allocated by cuvsScalarQuantizerCreate
* @param[in] min finite lower bound shared by all dimensions
* @param[in] max finite upper bound shared by all dimensions, with min <= max
* @return cuvsError_t
*/
CUVS_EXPORT cuvsError_t cuvsScalarQuantizerSetBounds(cuvsScalarQuantizer_t quantizer,
double min,
double max);

/**
* @brief Trains a scalar quantizer to be used later for quantizing the dataset.
*
* Supports float16, float32, and float64 in global or per-dimension mode.
* Per-dimension mode applies the quantile independently to each dimension using every row.
* Successful retraining replaces the previous bounds; failed training preserves them.
* Complete outstanding stream work using the quantizer before retraining.
*
* @param[in] res raft resource
* @param[in] params configure scalar quantizer, e.g. quantile
* @param[in] dataset a row-major host or device matrix
* @param[out] quantizer trained scalar quantizer
* @param[in,out] quantizer scalar quantizer allocated by cuvsScalarQuantizerCreate
*/
CUVS_EXPORT cuvsError_t cuvsScalarQuantizerTrain(cuvsResources_t res,
cuvsScalarQuantizerParams_t params,
Expand All @@ -93,6 +139,9 @@ CUVS_EXPORT cuvsError_t cuvsScalarQuantizerTrain(cuvsResources_t res,
/**
* @brief Applies quantization transform to given dataset
*
* Per-dimension mode requires device matrices with the same input type and width as training.
* The quantizer must outlive stream work using its bounds.
*
* @param[in] res raft resource
* @param[in] quantizer a scalar quantizer
* @param[in] dataset a row-major host or device matrix to transform
Expand All @@ -107,7 +156,8 @@ CUVS_EXPORT cuvsError_t cuvsScalarQuantizerTransform(cuvsResources_t res,
* @brief Perform inverse quantization step on previously quantized dataset
*
* Note that depending on the chosen data types train dataset the conversion is
* not lossless.
* not lossless. Per-dimension mode requires device matrices with the same output type and
* width as training. The quantizer must outlive stream work using its bounds.
*
* @param[in] res raft resource
* @param[in] quantizer a scalar quantizer
Expand Down
123 changes: 111 additions & 12 deletions c/src/preprocessing/quantize/scalar.cpp
Original file line number Diff line number Diff line change
@@ -1,10 +1,13 @@
/*
* SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION.
* SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
* SPDX-License-Identifier: Apache-2.0
*/

#include <cstdint>
#include <dlpack/dlpack.h>
#include <memory>
#include <optional>
#include <utility>

#include <cuvs/core/c_api.h>
#include <cuvs/preprocessing/quantize/scalar.h>
Expand All @@ -15,6 +18,69 @@

namespace {

namespace scalar = cuvs::preprocessing::quantize::scalar;

// The handle's addr points to a scalar::quantizer<T>, where dtype selects T.
template <typename Fn>
void with_held_type(cuvsScalarQuantizer_t quantizer, Fn&& fn)
{
RAFT_EXPECTS(quantizer->addr != 0, "quantizer must be allocated by cuvsScalarQuantizerCreate");
switch (quantizer->dtype.bits) {
case 16: fn.template operator()<half>(); break;
case 32: fn.template operator()<float>(); break;
case 64: fn.template operator()<double>(); break;
default: RAFT_FAIL("Unsupported quantizer dtype bits: %d", quantizer->dtype.bits);
}
}

void destroy(cuvsScalarQuantizer_t quantizer)
{
if (quantizer->addr == 0) { return; }
with_held_type(quantizer, [&]<typename T>() {
delete reinterpret_cast<scalar::quantizer<T>*>(quantizer->addr);
});
quantizer->addr = 0;
}

// Replaces the quantizer the handle owns.
template <typename T>
void reset(cuvsScalarQuantizer_t quantizer, scalar::quantizer<T>&& value)
{
auto owned = std::make_unique<scalar::quantizer<T>>(std::move(value));
destroy(quantizer);
quantizer->addr = reinterpret_cast<uintptr_t>(owned.release());
quantizer->dtype = DLDataType{kDLFloat, sizeof(T) * 8, 1};
}

// The global bounds held by the quantizer; empty for per-dimension bounds.
std::optional<std::pair<double, double>> global_bounds(cuvsScalarQuantizer_t quantizer)
{
std::optional<std::pair<double, double>> result;
with_held_type(quantizer, [&]<typename T>() {
auto const& value = reinterpret_cast<scalar::quantizer<T>*>(quantizer->addr)->value;
if (auto const* bounds = std::get_if<typename scalar::quantizer<T>::global_type>(&value)) {
result = std::pair{static_cast<double>(bounds->min), static_cast<double>(bounds->max)};
}
});
return result;
}

// The quantizer for data of type T. Global bounds apply to every floating-point type and are
// converted into `converted`; per-dimension bounds require the type they were trained on.
template <typename T>
const scalar::quantizer<T>& typed_quantizer(cuvsScalarQuantizer_t quantizer,
scalar::quantizer<T>& converted)
{
auto const bounds = global_bounds(quantizer);
if (quantizer->dtype.bits == sizeof(T) * 8) {
return *reinterpret_cast<scalar::quantizer<T>*>(quantizer->addr);
}
RAFT_EXPECTS(bounds.has_value(),
"The data type must match the one the per-dimension quantizer was trained on");
converted = scalar::quantizer<T>{static_cast<T>(bounds->first), static_cast<T>(bounds->second)};
return converted;
}

template <typename T>
void _train(cuvsResources_t res,
cuvsScalarQuantizerParams params,
Expand All @@ -27,6 +93,13 @@ void _train(cuvsResources_t res,

auto quantizer_params = cuvs::preprocessing::quantize::scalar::params();
quantizer_params.quantile = params.quantile;
switch (params.mode) {
case CUVS_SCALAR_GLOBAL: quantizer_params.range = scalar::quantization_mode::GLOBAL; break;
case CUVS_SCALAR_PER_DIMENSION:
quantizer_params.range = scalar::quantization_mode::PER_DIMENSION;
break;
default: RAFT_FAIL("Unsupported scalar quantization mode");
}

cuvs::preprocessing::quantize::scalar::quantizer<T> ret;

Expand All @@ -42,8 +115,7 @@ void _train(cuvsResources_t res,
RAFT_FAIL("dataset must be accessible on host or device memory");
}

quantizer->min_ = ret.min_;
quantizer->max_ = ret.max_;
reset(quantizer, std::move(ret));
}

template <typename T, typename OutputT = int8_t>
Expand All @@ -54,9 +126,8 @@ void _transform(cuvsResources_t res,
{
auto res_ptr = reinterpret_cast<raft::resources*>(res);

cuvs::preprocessing::quantize::scalar::quantizer<T> quantizer;
quantizer.min_ = quantizer_->min_;
quantizer.max_ = quantizer_->max_;
cuvs::preprocessing::quantize::scalar::quantizer<T> converted;
auto const& quantizer = typed_quantizer(quantizer_, converted);

auto dataset = dataset_tensor->dl_tensor;
if (cuvs::core::is_dlpack_device_compatible(dataset)) {
Expand Down Expand Up @@ -91,9 +162,8 @@ void _inverse_transform(cuvsResources_t res,
{
auto res_ptr = reinterpret_cast<raft::resources*>(res);

cuvs::preprocessing::quantize::scalar::quantizer<OutputT> quantizer;
quantizer.min_ = quantizer_->min_;
quantizer.max_ = quantizer_->max_;
cuvs::preprocessing::quantize::scalar::quantizer<OutputT> converted;
auto const& quantizer = typed_quantizer(quantizer_, converted);

auto dataset = dataset_tensor->dl_tensor;
if (cuvs::core::is_dlpack_device_compatible(dataset)) {
Expand Down Expand Up @@ -124,7 +194,7 @@ void _inverse_transform(cuvsResources_t res,
extern "C" cuvsError_t cuvsScalarQuantizerParamsCreate(cuvsScalarQuantizerParams_t* params)
{
return cuvs::core::translate_exceptions(
[=] { *params = new cuvsScalarQuantizerParams{.quantile = 0.99}; });
[=] { *params = new cuvsScalarQuantizerParams{.quantile = 0.99, .mode = CUVS_SCALAR_GLOBAL}; });
}

extern "C" cuvsError_t cuvsScalarQuantizerParamsDestroy(cuvsScalarQuantizerParams_t params)
Expand All @@ -134,12 +204,41 @@ extern "C" cuvsError_t cuvsScalarQuantizerParamsDestroy(cuvsScalarQuantizerParam

extern "C" cuvsError_t cuvsScalarQuantizerCreate(cuvsScalarQuantizer_t* quantizer)
{
return cuvs::core::translate_exceptions([=] { *quantizer = new cuvsScalarQuantizer{}; });
return cuvs::core::translate_exceptions([=] {
auto created = std::make_unique<cuvsScalarQuantizer>();
reset(created.get(), scalar::quantizer<double>{});
*quantizer = created.release();
});
}

extern "C" cuvsError_t cuvsScalarQuantizerDestroy(cuvsScalarQuantizer_t quantizer)
{
return cuvs::core::translate_exceptions([=] { delete quantizer; });
return cuvs::core::translate_exceptions([=] {
if (quantizer != nullptr) {
destroy(quantizer);
delete quantizer;
}
});
}

extern "C" cuvsError_t cuvsScalarQuantizerGetBounds(cuvsScalarQuantizer_t quantizer,
double* min,
double* max)
{
return cuvs::core::translate_exceptions([=] {
auto const bounds = global_bounds(quantizer);
RAFT_EXPECTS(bounds.has_value(), "A per-dimension quantizer has no global bounds");
*min = bounds->first;
*max = bounds->second;
});
}

extern "C" cuvsError_t cuvsScalarQuantizerSetBounds(cuvsScalarQuantizer_t quantizer,
double min,
double max)
{
return cuvs::core::translate_exceptions(
[=] { reset(quantizer, scalar::quantizer<double>{min, max}); });
}

extern "C" cuvsError_t cuvsScalarQuantizerTrain(cuvsResources_t res,
Expand Down
1 change: 1 addition & 0 deletions c/tests/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,7 @@ ConfigureTest(
)

ConfigureTest(NAME PCA_C_TEST PATH preprocessing/pca_c.cu)
ConfigureTest(NAME SCALAR_QUANTIZATION_C_TEST PATH preprocessing/scalar_c.cu)

if(BUILD_CAGRA_HNSWLIB)
ConfigureTest(NAME HNSW_C_TEST PATH neighbors/ann_hnsw_c.cu)
Expand Down
Loading
Loading