[DO NOT MERGE] IVF-Binary

cpp/CMakeLists.txt

@@ -1476,6 +1476,8 @@ if(NOT BUILD_CPU_ONLY)
     src/neighbors/composite/index.cu
     $<$<BOOL:${BUILD_CAGRA_HNSWLIB}>:src/neighbors/cagra.cpp>
     $<$<BOOL:${BUILD_CAGRA_HNSWLIB}>:src/neighbors/hnsw.cpp>
+    src/neighbors/ivf_binary_index.cpp
+    src/neighbors/ivf_binary/ivf_binary.cu
     src/neighbors/ivf_common.cu
     src/neighbors/ivf_flat_index.cpp
     ${ivf_flat_build_extend_inst_files}

cpp/include/cuvs/cluster/kmeans.hpp

@@ -216,6 +216,19 @@ struct balanced_params : base_params {
    * average cluster size; in that mode, `balance_upper_tolerance` does not control donor selection.
    */
   balanced_donor_selection donor_selection = balanced_donor_selection::SizeSorted;
+
+  /**
+   * If true, treats uint8_t input data as bit-packed binary data where each byte contains 8 bits.
+   * Bits are expanded on-the-fly, least-significant bit first, to {-1, +1} floats
+   * during training and prediction. Other input types are rejected when this flag is set.
+   * When enabled:
+   *   - Input data dimension represents packed dimension (actual_dim / 8)
+   *   - Output centroids dimension is expanded (packed_dim * 8)
+   *   - The metric operates on the expanded floating-point vectors (for example L2Expanded),
+   *     not on the packed bytes; BitwiseHamming is not a balanced k-means training metric.
+   *   - CosineExpanded is not supported.
+   */
+  bool is_packed_binary = false;
 };
 
 /**
@@ -717,6 +730,12 @@ void fit(const raft::resources& handle,
 /**
  * @brief Find balanced clusters with k-means algorithm.
  *
+ * @note When `params.is_packed_binary` is true, `X.extent(1)` counts packed bytes,
+ * and centroids must have `8 * X.extent(1)` floating-point coordinates. Bits are
+ * expanded least-significant bit first to {-1, +1}; the selected metric operates
+ * on those expanded vectors. CosineExpanded is not supported in packed binary mode.
+ * With the flag disabled, uint8_t values are numeric.
+ *
  * @code{.cpp}
  *   #include <raft/core/resources.hpp>
  *   #include <cuvs/cluster/kmeans.hpp>
@@ -1215,6 +1234,12 @@ void predict(const raft::resources& handle,
 /**
  * @brief Predict the closest cluster each sample in X belongs to.
  *
+ * @note When `params.is_packed_binary` is true, `X.extent(1)` counts packed bytes,
+ * and centroids must have `8 * X.extent(1)` floating-point coordinates. Bits are
+ * expanded least-significant bit first to {-1, +1}; the selected metric operates
+ * on those expanded vectors. CosineExpanded is not supported in packed binary mode.
+ * With the flag disabled, uint8_t values are numeric.
+ *
  * @code{.cpp}
  *   #include <raft/core/resources.hpp>
  *   #include <cuvs/cluster/kmeans.hpp>

cpp/include/cuvs/core/dataset/binary.hpp

@@ -0,0 +1,98 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <cuvs/core/export.hpp>
+#include <cuvs/preprocessing/quantize/binary.hpp>
+
+#include <raft/core/device_mdspan.hpp>
+#include <raft/core/error.hpp>
+
+#include <cstdint>
+
+namespace CUVS_EXPORT cuvs {
+
+/**
+ * @brief Non-owning view of the dictionary that binarizes a dataset: the per-dimension thresholds
+ * of a binary quantizer. An empty threshold vector stands for the zero threshold.
+ */
+template <typename MathT>
+struct binary_dictionary_view {
+  raft::device_vector_view<const MathT, int64_t> threshold;
+};
+
+/**
+ * @brief Non-owning view of a binary-quantized dataset.
+ *
+ * The data are bit-packed codes, `ceil(dim / 8)` bytes per row; bit `i` of a row is stored in bit
+ * `i % 8` of byte `i / 8`, and the unused bits of the last byte are zero. The dictionary is the
+ * quantizer that produced the codes, so the logical dimension `dim` (the number of bits) never has
+ * to be guessed from the padded byte width.
+ *
+ * @tparam MathT the type of the source (unquantized) values
+ * @tparam IdxT the type of the row indices
+ */
+template <typename MathT, typename IdxT>
+struct device_binary_dataset_view {
+  using value_type           = MathT;
+  using index_type           = IdxT;
+  using code_type            = uint8_t;
+  using data_view_type       = raft::device_matrix_view<const code_type, int64_t, raft::row_major>;
+  using dictionary_view_type = binary_dictionary_view<MathT>;
+
+  /**
+   * @param codes row-major codes [n_rows, ceil(dim / 8)]
+   * @param dictionary the thresholds used to produce the codes; empty or of size `dim`
+   * @param dim the number of bits in each vector
+   */
+  device_binary_dataset_view(data_view_type codes, dictionary_view_type dictionary, uint32_t dim)
+    : codes_{codes}, dictionary_{dictionary}, dim_{dim}
+  {
+    RAFT_EXPECTS(dim > 0, "The dimension of a binary dataset must be positive");
+    RAFT_EXPECTS(static_cast<int64_t>((uint64_t{dim} + 7) / 8) == codes.extent(1),
+                 "The row length of the codes must be ceil(dim / 8) bytes");
+    RAFT_EXPECTS(dictionary.threshold.extent(0) == 0 ||
+                   dictionary.threshold.extent(0) == static_cast<int64_t>(dim),
+                 "The threshold vector must be empty or have one element per dimension");
+  }
+
+  /** The number of vectors. */
+  [[nodiscard]] auto n_rows() const noexcept -> index_type
+  {
+    return static_cast<index_type>(codes_.extent(0));
+  }
+  /** The number of bits in each vector. */
+  [[nodiscard]] auto dim() const noexcept -> uint32_t { return dim_; }
+  /** The number of bytes in each row of the codes. */
+  [[nodiscard]] auto encoded_row_length() const noexcept -> int64_t { return codes_.extent(1); }
+
+  [[nodiscard]] auto data_const_view() const noexcept -> data_view_type { return codes_; }
+  [[nodiscard]] auto const_dictionary_view() const noexcept -> dictionary_view_type
+  {
+    return dictionary_;
+  }
+
+ private:
+  data_view_type codes_;
+  dictionary_view_type dictionary_;
+  uint32_t dim_;
+};
+
+/**
+ * @brief View the codes produced by `preprocessing::quantize::binary::transform` together with the
+ * quantizer that produced them.
+ */
+template <typename IdxT, typename MathT>
+auto make_device_binary_dataset_view(
+  raft::device_matrix_view<const uint8_t, int64_t, raft::row_major> codes,
+  const preprocessing::quantize::binary::quantizer<MathT>& quantizer,
+  uint32_t dim) -> device_binary_dataset_view<MathT, IdxT>
+{
+  return device_binary_dataset_view<MathT, IdxT>{
+    codes, binary_dictionary_view<MathT>{quantizer.threshold.view()}, dim};
+}
+
+}  // namespace CUVS_EXPORT cuvs

cpp/include/cuvs/detail/jit_lto/common_fragments.hpp

@@ -12,6 +12,7 @@ struct tag_h {};
 struct tag_d {};
 struct tag_i8 {};
 struct tag_u8 {};
+struct tag_u32 {};
 struct tag_filter_none {};
 struct tag_filter_bitset {};
 struct tag_filter_bloom_filter {};

cpp/include/cuvs/detail/jit_lto/ivf_flat/interleaved_scan_fragments.hpp

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
 
@@ -16,6 +16,7 @@ struct tag_acc_u32 {};
 // Tag types for distance metrics
 struct tag_metric_euclidean {};
 struct tag_metric_inner_product {};
+struct tag_metric_bitwise_hamming {};
 struct tag_metric_custom_udf {};
 
 // Tag types for post-processing

cpp/include/cuvs/detail/jit_lto/pairwise_matrix/pairwise_matrix_fragments.hpp

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
 
@@ -13,6 +13,7 @@ struct tag_layout_col {};
 struct tag_fin_op_identity {};
 struct tag_fin_op_rbf {};
 
+struct tag_distance_bitwise_hamming {};
 struct tag_distance_canberra {};
 struct tag_distance_correlation {};
 struct tag_distance_cosine {};