deglib 0.2.3__tar.gz → 0.2.4__tar.gz

{deglib-0.2.3/src/deglib.egg-info → deglib-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deglib
-Version: 0.2.3
+Version: 0.2.4
 Summary: Python bindings for the Dynamic Exploration Graph library by Nico Hezel
 Author: Nico Hezel
 Author-email: Bruno Schilling <bruno.schilling@htw-berlin.de>
@@ -216,17 +216,17 @@ explored_labels, distances = graph.explore(entry_external_label=105, k=10, eps=0
 
 ### Graph Optimization, Quantization & Reranking Pipeline
 
-A complete end-to-end pipeline demonstrating **FLAS pre-sorting**, **multithreaded graph building**, **RNG edge pruning**, **Int8 quantization**, **ReadOnlyGraph conversion**, and **exact FP32 candidate reranking**:
+A complete end-to-end pipeline demonstrating **FLAS pre-sorting**, **multithreaded graph building**, **RNG edge pruning**, **Int8 quantization**, **ReadOnlyGraph conversion**, and deployment with **`Searcher`** for automatic query quantization and high-precision reranking:
 
 ```python
 import numpy as np
 import deglib
 from deglib.optimization import presort, prune_non_rng_edges, ScalarQuantizerInt8
-from deglib.search import rerank
+from deglib.search import create_searcher
 
 num_vectors, dims = 10_000, 128
 data = np.random.randn(num_vectors, dims).astype(np.float32)
-query = np.random.randn(1, dims).astype(np.float32)
+query = np.random.randn(dims).astype(np.float32)
 
 # 1. Pre-sort vectors using FLAS for improved memory locality and index construction speed
 perm = presort(data, metric=deglib.Metric.FP32_InnerProduct, callback="progress")
@@ -253,23 +253,19 @@ int8_space = deglib.FloatSpace.create(dims, deglib.Metric.Int8_InnerProduct)
 # 5. Convert mutable graph to a compact ReadOnlyGraph equipped with the quantized features
 readonly_graph = graph.to_readonly(feature_space=int8_space, custom_features=quant_int8_data)
 
-# 6. Quantize query using the EXACT SAME calibrated scale, then search
-quant_query = quantizer.quantize(query)
-candidate_indices = readonly_graph.search(quant_query, k=20, eps=0.1, return_distances=False)
-
-# 7. Exact distance reranking of top candidates on original float32 data
-fp32_space = deglib.FloatSpace.create(dims, deglib.Metric.FP32_InnerProduct)
-final_top_indices, distances = rerank(
-    space=fp32_space,
-    queries=query,
-    candidate_indices=candidate_indices,
-    base_vectors=sorted_data,
-    k_top=10,
-    return_distances=True,
+# 6. Create high-performance Searcher equipped with base vectors for exact candidate reranking
+rerank_space = deglib.FloatSpace.create(dims, deglib.Metric.FP32_InnerProduct)
+searcher = create_searcher(
+    graph=readonly_graph,
+    quantizer=quantizer,
+    refine_space=rerank_space,
+    refine_data=sorted_data,
 )
 
-print("Top-10 nearest neighbor indices:", final_top_indices[0])
-print("Top-10 exact distances:", distances[0])
+# 7. Query search (query is automatically quantized and top candidates are reranked)
+indices, distances = searcher.search(query, k=10, eps=0.1, rerank_factor=1.5, return_distances=True)
+print("Top-10 nearest neighbor indices:", indices)
+print("Top-10 exact distances:", distances)
 ```
 
 ---

{deglib-0.2.3 → deglib-0.2.4}/README.md

@@ -188,17 +188,17 @@ explored_labels, distances = graph.explore(entry_external_label=105, k=10, eps=0
 
 ### Graph Optimization, Quantization & Reranking Pipeline
 
-A complete end-to-end pipeline demonstrating **FLAS pre-sorting**, **multithreaded graph building**, **RNG edge pruning**, **Int8 quantization**, **ReadOnlyGraph conversion**, and **exact FP32 candidate reranking**:
+A complete end-to-end pipeline demonstrating **FLAS pre-sorting**, **multithreaded graph building**, **RNG edge pruning**, **Int8 quantization**, **ReadOnlyGraph conversion**, and deployment with **`Searcher`** for automatic query quantization and high-precision reranking:
 
 ```python
 import numpy as np
 import deglib
 from deglib.optimization import presort, prune_non_rng_edges, ScalarQuantizerInt8
-from deglib.search import rerank
+from deglib.search import create_searcher
 
 num_vectors, dims = 10_000, 128
 data = np.random.randn(num_vectors, dims).astype(np.float32)
-query = np.random.randn(1, dims).astype(np.float32)
+query = np.random.randn(dims).astype(np.float32)
 
 # 1. Pre-sort vectors using FLAS for improved memory locality and index construction speed
 perm = presort(data, metric=deglib.Metric.FP32_InnerProduct, callback="progress")
@@ -225,23 +225,19 @@ int8_space = deglib.FloatSpace.create(dims, deglib.Metric.Int8_InnerProduct)
 # 5. Convert mutable graph to a compact ReadOnlyGraph equipped with the quantized features
 readonly_graph = graph.to_readonly(feature_space=int8_space, custom_features=quant_int8_data)
 
-# 6. Quantize query using the EXACT SAME calibrated scale, then search
-quant_query = quantizer.quantize(query)
-candidate_indices = readonly_graph.search(quant_query, k=20, eps=0.1, return_distances=False)
-
-# 7. Exact distance reranking of top candidates on original float32 data
-fp32_space = deglib.FloatSpace.create(dims, deglib.Metric.FP32_InnerProduct)
-final_top_indices, distances = rerank(
-    space=fp32_space,
-    queries=query,
-    candidate_indices=candidate_indices,
-    base_vectors=sorted_data,
-    k_top=10,
-    return_distances=True,
+# 6. Create high-performance Searcher equipped with base vectors for exact candidate reranking
+rerank_space = deglib.FloatSpace.create(dims, deglib.Metric.FP32_InnerProduct)
+searcher = create_searcher(
+    graph=readonly_graph,
+    quantizer=quantizer,
+    refine_space=rerank_space,
+    refine_data=sorted_data,
 )
 
-print("Top-10 nearest neighbor indices:", final_top_indices[0])
-print("Top-10 exact distances:", distances[0])
+# 7. Query search (query is automatically quantized and top candidates are reranked)
+indices, distances = searcher.search(query, k=10, eps=0.1, rerank_factor=1.5, return_distances=True)
+print("Top-10 nearest neighbor indices:", indices)
+print("Top-10 exact distances:", distances)
 ```
 
 ---

{deglib-0.2.3 → deglib-0.2.4}/lib/deglib/include/deglib/optimization/quantization/evp_quantize.h

@@ -17,17 +17,17 @@ namespace deglib::quantization::evp {
 // ============================================================================
 
 /**
- * Quantizes a single fp32 vector to EVP bytes.
+ * Quantizes a single fp32 vector directly into a pre-allocated EVP byte buffer.
  *
  * Layout: [ones (dim/8 bytes)][negative_ones (dim/8 bytes)]
  *
  * @param embedding  Pointer to dim float values (row-major)
  * @param dim        Dimension (must be divisible by 8)
  * @param non_zeros  Number of top-K elements by absolute value
- * @return std::vector<std::byte> with 2 * dim/8 bytes
+ * @param out_bytes  Pointer to buffer of at least 2 * dim/8 bytes
  * @throws std::invalid_argument if dim % 8 != 0 or non_zeros >= dim
  */
-inline std::vector<std::byte> quantize_single(const float* embedding, uint32_t dim, uint32_t non_zeros) {
+inline void quantize_single_into(const float* embedding, uint32_t dim, uint32_t non_zeros, std::byte* out_bytes) {
     if (dim % 8 != 0) {
         throw std::invalid_argument("quantize_single: dim must be divisible by 8, got " + std::to_string(dim));
     }
@@ -36,8 +36,6 @@ inline std::vector<std::byte> quantize_single(const float* embedding, uint32_t d
     }
 
     const size_t mask_bytes = dim / 8;
-    std::vector<std::byte> result(2 * mask_bytes);
-
     std::vector<std::pair<float, uint32_t>> abs_vals(dim);
     for (uint32_t i = 0; i < dim; ++i) {
         abs_vals[i] = {std::abs(embedding[i]), i};
@@ -51,8 +49,8 @@ inline std::vector<std::byte> quantize_single(const float* embedding, uint32_t d
         is_top[abs_vals[j].second] = 1;
     }
 
-    std::byte* ones_dst = result.data();
-    std::byte* negs_dst = result.data() + mask_bytes;
+    std::byte* ones_dst = out_bytes;
+    std::byte* negs_dst = out_bytes + mask_bytes;
 
     for (uint32_t byte_idx = 0; byte_idx < mask_bytes; ++byte_idx) {
         int byte_val = 0;
@@ -77,7 +75,23 @@ inline std::vector<std::byte> quantize_single(const float* embedding, uint32_t d
         }
         negs_dst[byte_idx] = static_cast<std::byte>(byte_val);
     }
+}
 
+/**
+ * Quantizes a single fp32 vector to EVP bytes.
+ *
+ * Layout: [ones (dim/8 bytes)][negative_ones (dim/8 bytes)]
+ *
+ * @param embedding  Pointer to dim float values (row-major)
+ * @param dim        Dimension (must be divisible by 8)
+ * @param non_zeros  Number of top-K elements by absolute value
+ * @return std::vector<std::byte> with 2 * dim/8 bytes
+ * @throws std::invalid_argument if dim % 8 != 0 or non_zeros >= dim
+ */
+inline std::vector<std::byte> quantize_single(const float* embedding, uint32_t dim, uint32_t non_zeros) {
+    const size_t mask_bytes = dim / 8;
+    std::vector<std::byte> result(2 * mask_bytes);
+    quantize_single_into(embedding, dim, non_zeros, result.data());
     return result;
 }
 
@@ -378,11 +392,69 @@ inline std::vector<std::byte> quantize_batch(const std::vector<std::vector<std::
     return result;
 }
 
+/**
+ * Quantizes a single FP16 (uint16_t) vector directly into a pre-allocated EVP byte buffer.
+ *
+ * Layout: [ones (dim/8 bytes)][negative_ones (dim/8 bytes)]
+ */
+inline void quantize_single_into(const uint16_t* embedding, uint32_t dim, uint32_t non_zeros, std::byte* out_bytes) {
+    if (dim % 8 != 0) {
+        throw std::invalid_argument("quantize_single: dim must be divisible by 8, got " + std::to_string(dim));
+    }
+    if (non_zeros >= dim) {
+        throw std::invalid_argument("quantize_single: non_zeros must be < dim");
+    }
+
+    const size_t mask_bytes = dim / 8;
+    std::vector<std::pair<uint16_t, uint32_t>> abs_vals(dim);
+    for (uint32_t i = 0; i < dim; ++i) {
+        abs_vals[i] = {static_cast<uint16_t>(embedding[i] & 0x7FFFu), i};
+    }
+    std::nth_element(abs_vals.begin(), abs_vals.begin() + (dim - non_zeros), abs_vals.end(), [](const auto& a, const auto& b) {
+        return a.first != b.first ? a.first < b.first : a.second < b.second;
+    });
+
+    std::vector<uint8_t> is_top(dim, 0);
+    for (uint32_t j = dim - non_zeros; j < dim; ++j) {
+        is_top[abs_vals[j].second] = 1;
+    }
+
+    std::byte* ones_dst = out_bytes;
+    std::byte* negs_dst = out_bytes + mask_bytes;
+
+    for (uint32_t byte_idx = 0; byte_idx < mask_bytes; ++byte_idx) {
+        int bv = 0;
+        for (int bit = 0; bit < 8; ++bit) {
+            const uint32_t bit_idx = byte_idx * 8 + bit;
+            if (bit_idx >= dim) break;
+            if (is_top[bit_idx] && (embedding[bit_idx] & 0x8000u) == 0 && (embedding[bit_idx] & 0x7FFFu) > 0) {
+                bv |= (1 << bit);
+            }
+        }
+        ones_dst[byte_idx] = static_cast<std::byte>(bv);
+    }
+
+    for (uint32_t byte_idx = 0; byte_idx < mask_bytes; ++byte_idx) {
+        int bv = 0;
+        for (int bit = 0; bit < 8; ++bit) {
+            const uint32_t bit_idx = byte_idx * 8 + bit;
+            if (bit_idx >= dim) break;
+            if (is_top[bit_idx] && (embedding[bit_idx] & 0x8000u) != 0 && (embedding[bit_idx] & 0x7FFFu) > 0) {
+                bv |= (1 << bit);
+            }
+        }
+        negs_dst[byte_idx] = static_cast<std::byte>(bv);
+    }
+}
+
 /**
  * Quantizes a single FP16 (uint16_t) vector to EVP bytes.
  */
 inline std::vector<std::byte> quantize_single(const uint16_t* embedding, uint32_t dim, uint32_t non_zeros) {
-    return quantize_batch(embedding, 1, dim, non_zeros, 1);
+    const size_t mask_bytes = dim / 8;
+    std::vector<std::byte> result(2 * mask_bytes);
+    quantize_single_into(embedding, dim, non_zeros, result.data());
+    return result;
 }
 
 }  // namespace deglib::quantization::evp