deglib 0.2.3__tar.gz → 0.2.5__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deglib
-Version: 0.2.3
+Version: 0.2.5
 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.5}/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.5}/lib/deglib/include/deglib/distance/fp32_ip.h

@@ -143,17 +143,20 @@ class InnerProductFloat_AVX512 {
             }
 
             if constexpr (HasDualSimd) {
-                const size_t nc16 = dim / 16;
-                offset = nc16 * 16;
+                const size_t nc32 = dim / 32;
+                offset = nc32 * 32;
 
-                for (size_t c = 0; c < nc16; ++c) {
-                    size_t idx = c * 16;
-                    __m512 q_vec = _mm512_loadu_ps(&query[idx]);
+                for (size_t c = 0; c < nc32; ++c) {
+                    size_t idx = c * 32;
+                    __m512 q_vec_lo = _mm512_loadu_ps(&query[idx]);
+                    __m512 q_vec_hi = _mm512_loadu_ps(&query[idx + 16]);
 
                     for (size_t j = 0; j < BATCH_SIZE; ++j) {
                         const float* db_ = static_cast<const float*>(db[j]);
-                        __m512 db_vec = _mm512_loadu_ps(&db_[idx]);
-                        s[j] = _mm512_fmadd_ps(q_vec, db_vec, s[j]);
+                        __m512 db_vec_lo = _mm512_loadu_ps(&db_[idx]);
+                        __m512 db_vec_hi = _mm512_loadu_ps(&db_[idx + 16]);
+                        s[j] = _mm512_fmadd_ps(q_vec_lo, db_vec_lo, s[j]);
+                        s[j] = _mm512_fmadd_ps(q_vec_hi, db_vec_hi, s[j]);
                     }
                 }
             }
@@ -265,17 +268,20 @@ class InnerProductFloat_AVX2 {
             }
 
             if constexpr (HasDualSimd) {
-                const size_t nc8 = dim / 8;
-                offset = nc8 * 8;
+                const size_t nc16 = dim / 16;
+                offset = nc16 * 16;
 
-                for (size_t c = 0; c < nc8; ++c) {
-                    size_t idx = c * 8;
-                    __m256 q_vec = _mm256_loadu_ps(&query[idx]);
+                for (size_t c = 0; c < nc16; ++c) {
+                    size_t idx = c * 16;
+                    __m256 q_vec_lo = _mm256_loadu_ps(&query[idx]);
+                    __m256 q_vec_hi = _mm256_loadu_ps(&query[idx + 8]);
 
                     for (size_t j = 0; j < BATCH_SIZE; ++j) {
                         const float* db_ = static_cast<const float*>(db[j]);
-                        __m256 db_vec = _mm256_loadu_ps(&db_[idx]);
-                        s[j] = _mm256_fmadd_ps(q_vec, db_vec, s[j]);
+                        __m256 db_vec_lo = _mm256_loadu_ps(&db_[idx]);
+                        __m256 db_vec_hi = _mm256_loadu_ps(&db_[idx + 8]);
+                        s[j] = _mm256_fmadd_ps(q_vec_lo, db_vec_lo, s[j]);
+                        s[j] = _mm256_fmadd_ps(q_vec_hi, db_vec_hi, s[j]);
                     }
                 }
             }

{deglib-0.2.3 → deglib-0.2.5}/lib/deglib/include/deglib/distance/fp32_l2.h

@@ -142,17 +142,20 @@ class L2Float_AVX512 {
             }
 
             if constexpr (HasDualSimd) {
-                const size_t nc16 = dim / 16;
-                offset = nc16 * 16;
+                const size_t nc32 = dim / 32;
+                offset = nc32 * 32;
 
-                for (size_t c = 0; c < nc16; ++c) {
-                    size_t idx = c * 16;
-                    __m512 q_vec = _mm512_loadu_ps(&query[idx]);
+                for (size_t c = 0; c < nc32; ++c) {
+                    size_t idx = c * 32;
+                    __m512 q_vec_lo = _mm512_loadu_ps(&query[idx]);
+                    __m512 q_vec_hi = _mm512_loadu_ps(&query[idx + 16]);
 
                     for (size_t j = 0; j < BATCH_SIZE; ++j) {
                         const float* db_ = static_cast<const float*>(db[j]);
-                        __m512 diff = _mm512_sub_ps(q_vec, _mm512_loadu_ps(&db_[idx]));
-                        s[j] = _mm512_fmadd_ps(diff, diff, s[j]);
+                        __m512 diff_lo = _mm512_sub_ps(q_vec_lo, _mm512_loadu_ps(&db_[idx]));
+                        __m512 diff_hi = _mm512_sub_ps(q_vec_hi, _mm512_loadu_ps(&db_[idx + 16]));
+                        s[j] = _mm512_fmadd_ps(diff_lo, diff_lo, s[j]);
+                        s[j] = _mm512_fmadd_ps(diff_hi, diff_hi, s[j]);
                     }
                 }
             }
@@ -264,17 +267,20 @@ class L2Float_AVX2 {
             }
 
             if constexpr (HasDualSimd) {
-                const size_t nc8 = dim / 8;
-                offset = nc8 * 8;
+                const size_t nc16 = dim / 16;
+                offset = nc16 * 16;
 
-                for (size_t c = 0; c < nc8; ++c) {
-                    size_t idx = c * 8;
-                    __m256 q_vec = _mm256_loadu_ps(&query[idx]);
+                for (size_t c = 0; c < nc16; ++c) {
+                    size_t idx = c * 16;
+                    __m256 q_vec_lo = _mm256_loadu_ps(&query[idx]);
+                    __m256 q_vec_hi = _mm256_loadu_ps(&query[idx + 8]);
 
                     for (size_t j = 0; j < BATCH_SIZE; ++j) {
                         const float* db_ = static_cast<const float*>(db[j]);
-                        __m256 diff = _mm256_sub_ps(q_vec, _mm256_loadu_ps(&db_[idx]));
-                        s[j] = _mm256_fmadd_ps(diff, diff, s[j]);
+                        __m256 diff_lo = _mm256_sub_ps(q_vec_lo, _mm256_loadu_ps(&db_[idx]));
+                        __m256 diff_hi = _mm256_sub_ps(q_vec_hi, _mm256_loadu_ps(&db_[idx + 8]));
+                        s[j] = _mm256_fmadd_ps(diff_lo, diff_lo, s[j]);
+                        s[j] = _mm256_fmadd_ps(diff_hi, diff_hi, s[j]);
                     }
                 }
             }

{deglib-0.2.3 → deglib-0.2.5}/lib/deglib/include/deglib/distance/int8_l2.h

@@ -169,19 +169,24 @@ class L2Int8_AVX512 {
             }
 
             if constexpr (HasDualSimd) {
-                const size_t nc32 = dim / 32;
-                offset = nc32 * 32;
+                const size_t nc64 = dim / 64;
+                offset = nc64 * 64;
 
-                for (size_t c = 0; c < nc32; ++c) {
-                    size_t idx = c * 32;
-                    __m256i q_raw = _mm256_loadu_si256(reinterpret_cast<const __m256i*>(&query[idx]));
-                    __m512i q_vec = _mm512_cvtepi8_epi16(q_raw);
+                for (size_t c = 0; c < nc64; ++c) {
+                    size_t idx = c * 64;
+                    __m256i q_raw_lo = _mm256_loadu_si256(reinterpret_cast<const __m256i*>(&query[idx]));
+                    __m256i q_raw_hi = _mm256_loadu_si256(reinterpret_cast<const __m256i*>(&query[idx + 32]));
+                    __m512i q_vec_lo = _mm512_cvtepi8_epi16(q_raw_lo);
+                    __m512i q_vec_hi = _mm512_cvtepi8_epi16(q_raw_hi);
 
                     for (size_t j = 0; j < BATCH_SIZE; ++j) {
                         const int8_t* db_ = static_cast<const int8_t*>(db[j]);
-                        __m256i r_raw = _mm256_loadu_si256(reinterpret_cast<const __m256i*>(&db_[idx]));
-                        __m512i diff = _mm512_sub_epi16(q_vec, _mm512_cvtepi8_epi16(r_raw));
-                        s[j] = _mm512_add_epi32(s[j], _mm512_madd_epi16(diff, diff));
+                        __m256i r_raw_lo = _mm256_loadu_si256(reinterpret_cast<const __m256i*>(&db_[idx]));
+                        __m256i r_raw_hi = _mm256_loadu_si256(reinterpret_cast<const __m256i*>(&db_[idx + 32]));
+                        __m512i diff_lo = _mm512_sub_epi16(q_vec_lo, _mm512_cvtepi8_epi16(r_raw_lo));
+                        __m512i diff_hi = _mm512_sub_epi16(q_vec_hi, _mm512_cvtepi8_epi16(r_raw_hi));
+                        s[j] = _mm512_add_epi32(s[j], _mm512_madd_epi16(diff_lo, diff_lo));
+                        s[j] = _mm512_add_epi32(s[j], _mm512_madd_epi16(diff_hi, diff_hi));
                     }
                 }
             }
@@ -290,19 +295,24 @@ class L2Int8_AVX2 {
             }
 
             if constexpr (HasDualSimd) {
-                const size_t nc16 = dim / 16;
-                offset = nc16 * 16;
+                const size_t nc32 = dim / 32;
+                offset = nc32 * 32;
 
-                for (size_t c = 0; c < nc16; ++c) {
-                    size_t idx = c * 16;
-                    __m128i q_raw = _mm_loadu_si128(reinterpret_cast<const __m128i*>(&query[idx]));
-                    __m256i q_vec = _mm256_cvtepi8_epi16(q_raw);
+                for (size_t c = 0; c < nc32; ++c) {
+                    size_t idx = c * 32;
+                    __m128i q_raw_lo = _mm_loadu_si128(reinterpret_cast<const __m128i*>(&query[idx]));
+                    __m128i q_raw_hi = _mm_loadu_si128(reinterpret_cast<const __m128i*>(&query[idx + 16]));
+                    __m256i q_vec_lo = _mm256_cvtepi8_epi16(q_raw_lo);
+                    __m256i q_vec_hi = _mm256_cvtepi8_epi16(q_raw_hi);
 
                     for (size_t j = 0; j < BATCH_SIZE; ++j) {
                         const int8_t* db_ = static_cast<const int8_t*>(db[j]);
-                        __m128i r_raw = _mm_loadu_si128(reinterpret_cast<const __m128i*>(&db_[idx]));
-                        __m256i diff = _mm256_sub_epi16(q_vec, _mm256_cvtepi8_epi16(r_raw));
-                        s[j] = _mm256_add_epi32(s[j], _mm256_madd_epi16(diff, diff));
+                        __m128i r_raw_lo = _mm_loadu_si128(reinterpret_cast<const __m128i*>(&db_[idx]));
+                        __m128i r_raw_hi = _mm_loadu_si128(reinterpret_cast<const __m128i*>(&db_[idx + 16]));
+                        __m256i diff_lo = _mm256_sub_epi16(q_vec_lo, _mm256_cvtepi8_epi16(r_raw_lo));
+                        __m256i diff_hi = _mm256_sub_epi16(q_vec_hi, _mm256_cvtepi8_epi16(r_raw_hi));
+                        s[j] = _mm256_add_epi32(s[j], _mm256_madd_epi16(diff_lo, diff_lo));
+                        s[j] = _mm256_add_epi32(s[j], _mm256_madd_epi16(diff_hi, diff_hi));
                     }
                 }
             }

{deglib-0.2.3 → deglib-0.2.5}/lib/deglib/include/deglib/distance/uint8_l2.h

@@ -173,19 +173,24 @@ class L2Uint8_AVX512 {
             }
 
             if constexpr (HasDualSimd) {
-                const size_t nc32 = dim / 32;
-                offset = nc32 * 32;
+                const size_t nc64 = dim / 64;
+                offset = nc64 * 64;
 
-                for (size_t c = 0; c < nc32; ++c) {
-                    size_t idx = c * 32;
-                    __m256i q_raw = _mm256_loadu_si256(reinterpret_cast<const __m256i*>(&query[idx]));
-                    __m512i q_vec = _mm512_cvtepu8_epi16(q_raw);
+                for (size_t c = 0; c < nc64; ++c) {
+                    size_t idx = c * 64;
+                    __m256i q_raw_lo = _mm256_loadu_si256(reinterpret_cast<const __m256i*>(&query[idx]));
+                    __m256i q_raw_hi = _mm256_loadu_si256(reinterpret_cast<const __m256i*>(&query[idx + 32]));
+                    __m512i q_vec_lo = _mm512_cvtepu8_epi16(q_raw_lo);
+                    __m512i q_vec_hi = _mm512_cvtepu8_epi16(q_raw_hi);
 
                     for (size_t j = 0; j < BATCH_SIZE; ++j) {
                         const unsigned char* db_ = static_cast<const unsigned char*>(db[j]);
-                        __m256i r_raw = _mm256_loadu_si256(reinterpret_cast<const __m256i*>(&db_[idx]));
-                        __m512i diff = _mm512_sub_epi16(q_vec, _mm512_cvtepu8_epi16(r_raw));
-                        s[j] = _mm512_add_epi32(s[j], _mm512_madd_epi16(diff, diff));
+                        __m256i r_raw_lo = _mm256_loadu_si256(reinterpret_cast<const __m256i*>(&db_[idx]));
+                        __m256i r_raw_hi = _mm256_loadu_si256(reinterpret_cast<const __m256i*>(&db_[idx + 32]));
+                        __m512i diff_lo = _mm512_sub_epi16(q_vec_lo, _mm512_cvtepu8_epi16(r_raw_lo));
+                        __m512i diff_hi = _mm512_sub_epi16(q_vec_hi, _mm512_cvtepu8_epi16(r_raw_hi));
+                        s[j] = _mm512_add_epi32(s[j], _mm512_madd_epi16(diff_lo, diff_lo));
+                        s[j] = _mm512_add_epi32(s[j], _mm512_madd_epi16(diff_hi, diff_hi));
                     }
                 }
             }
@@ -294,19 +299,24 @@ class L2Uint8_AVX2 {
             }
 
             if constexpr (HasDualSimd) {
-                const size_t nc16 = dim / 16;
-                offset = nc16 * 16;
+                const size_t nc32 = dim / 32;
+                offset = nc32 * 32;
 
-                for (size_t c = 0; c < nc16; ++c) {
-                    size_t idx = c * 16;
-                    __m128i q_raw = _mm_loadu_si128(reinterpret_cast<const __m128i*>(&query[idx]));
-                    __m256i q_vec = _mm256_cvtepu8_epi16(q_raw);
+                for (size_t c = 0; c < nc32; ++c) {
+                    size_t idx = c * 32;
+                    __m128i q_raw_lo = _mm_loadu_si128(reinterpret_cast<const __m128i*>(&query[idx]));
+                    __m128i q_raw_hi = _mm_loadu_si128(reinterpret_cast<const __m128i*>(&query[idx + 16]));
+                    __m256i q_vec_lo = _mm256_cvtepu8_epi16(q_raw_lo);
+                    __m256i q_vec_hi = _mm256_cvtepu8_epi16(q_raw_hi);
 
                     for (size_t j = 0; j < BATCH_SIZE; ++j) {
                         const unsigned char* db_ = static_cast<const unsigned char*>(db[j]);
-                        __m128i r_raw = _mm_loadu_si128(reinterpret_cast<const __m128i*>(&db_[idx]));
-                        __m256i diff = _mm256_sub_epi16(q_vec, _mm256_cvtepu8_epi16(r_raw));
-                        s[j] = _mm256_add_epi32(s[j], _mm256_madd_epi16(diff, diff));
+                        __m128i r_raw_lo = _mm_loadu_si128(reinterpret_cast<const __m128i*>(&db_[idx]));
+                        __m128i r_raw_hi = _mm_loadu_si128(reinterpret_cast<const __m128i*>(&db_[idx + 16]));
+                        __m256i diff_lo = _mm256_sub_epi16(q_vec_lo, _mm256_cvtepu8_epi16(r_raw_lo));
+                        __m256i diff_hi = _mm256_sub_epi16(q_vec_hi, _mm256_cvtepu8_epi16(r_raw_hi));
+                        s[j] = _mm256_add_epi32(s[j], _mm256_madd_epi16(diff_lo, diff_lo));
+                        s[j] = _mm256_add_epi32(s[j], _mm256_madd_epi16(diff_hi, diff_hi));
                     }
                 }
             }

{deglib-0.2.3 → deglib-0.2.5}/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