faiss 0.5.3 → 0.6.1

data/vendor/faiss/faiss/impl/RaBitQuantizer.h

@@ -103,10 +103,8 @@ struct RaBitQuantizer : Quantizer {
 //
 // 1. distance_to_code_1bit() - Fast 1-bit filtering using only sign bits
 // 2. distance_to_code_full() - Accurate multi-bit refinement using all bits
-// 3. lower_bound_distance() - Error-bounded adaptive filtering
-//                              (based on 1-bit estimator)
 //
-// These three methods implement RaBitQ's two-stage search pattern and are
+// These methods implement RaBitQ's two-stage search pattern and are
 // shared between the quantized (Q) and non-quantized (NotQ) query variants.
 // The intermediate class allows two-stage search code to work with both
 // variants via a single dynamic_cast.
@@ -116,8 +114,8 @@ struct RaBitQDistanceComputer : FlatCodesDistanceComputer {
     MetricType metric_type = MetricType::METRIC_L2;
     size_t nb_bits = 1;
 
-    // Query norm for lower bound computation (g_error in rabitq-library)
-    // This is the L2 norm of the rotated query: ||query - centroid||
+    // Query error factor for bound computation (g_error in rabitq-library)
+    // Used with f_error to compute error bounds for two-stage filtering
     float g_error = 0.0f;
 
     float symmetric_dis(idx_t /*i*/, idx_t /*j*/) override {
@@ -131,11 +129,6 @@ struct RaBitQDistanceComputer : FlatCodesDistanceComputer {
     // Compute full multi-bit distance (accurate)
     virtual float distance_to_code_full(const uint8_t* code) = 0;
 
-    // Compute lower bound of distance using error bounds
-    // Guarantees: actual_distance >= lower_bound_distance
-    // Used for adaptive filtering in two-stage search
-    virtual float lower_bound_distance(const uint8_t* code);
-
     // Override from FlatCodesDistanceComputer
     // Delegates to distance_to_code_full() for multi-bit distance computation
     float distance_to_code(const uint8_t* code) final {

data/vendor/faiss/faiss/impl/RaBitQuantizerMultiBit.cpp

@@ -180,9 +180,7 @@ void pack_multibit_codes(
  *
  * @param residual Original residual vector (data - centroid)
  * @param centroid Centroid vector (can be nullptr for zero centroid)
- * @param tmp_code Quantized ex-bit codes (before packing, after bit flipping)
  * @param d Dimensionality
- * @param ex_bits Number of extra bits
  * @param norm L2 norm of residual
  * @param ipnorm Unnormalized inner product between quantized and normalized
  * residual
@@ -192,9 +190,7 @@ void pack_multibit_codes(
 void compute_ex_factors(
         const float* residual,
         const float* centroid,
-        const int* tmp_code,
         size_t d,
-        size_t ex_bits,
         float norm,
         double ipnorm,
         ExtraBitsFactors& ex_factors,
@@ -210,45 +206,23 @@ void compute_ex_factors(
         ipnorm_inv = 1.0f;
     }
 
-    // Reconstruct xu_cb from total_code
-    // total_code was formed from: total_code[i] = (sign << ex_bits) +
-    // ex_code[i] Reconstruction: xu_cb[i] = total_code[i] + cb
-    const float cb = -(static_cast<float>(1 << ex_bits) - 0.5f);
-    std::vector<float> xu_cb(d);
-    for (size_t i = 0; i < d; i++) {
-        xu_cb[i] = static_cast<float>(tmp_code[i]) + cb;
-    }
-
     // Compute inner products needed for factors
-    float l2_sqr = norm * norm;
-    float ip_resi_xucb = fvec_inner_product(residual, xu_cb.data(), d);
+    float l2_sqr = norm * norm; // ||residual||^2 = ||x - c||^2
 
-    // Compute factors
     if (metric_type == MetricType::METRIC_L2) {
-        // For L2, no centroid correction needed in IVF setting
-        // because residual = x - centroid, distance computed in residual space
+        // For L2: f_add_ex = ||residual||^2
+        // No centroid correction needed in IVF setting because
+        // residual = x - centroid, distance computed in residual space
         ex_factors.f_add_ex = l2_sqr;
         ex_factors.f_rescale_ex = ipnorm_inv * -2.0f * norm;
     } else {
-        // For IP, centroid correction is needed
-        float ip_resi_cent = 0;
-        if (centroid != nullptr) {
-            ip_resi_cent = fvec_inner_product(residual, centroid, d);
-        }
-
-        float ip_cent_xucb = 0;
-        if (centroid != nullptr) {
-            ip_cent_xucb = fvec_inner_product(centroid, xu_cb.data(), d);
-        }
-
-        // When ip_resi_xucb is zero, the correction term should be zero
-        float correction_term = 0.0f;
-        if (ip_resi_xucb != 0.0f) {
-            correction_term = l2_sqr * ip_cent_xucb / ip_resi_xucb;
-        }
-
-        ex_factors.f_add_ex = 1 - ip_resi_cent + correction_term;
-        ex_factors.f_rescale_ex = ipnorm_inv * -norm;
+        // For IP: direct dot-product formulation
+        // f_add_ex = <c, r> (dot product of centroid and residual)
+        // f_rescale_ex = ||r|| / ipnorm (positive scaling)
+        float c_dot_r =
+                centroid ? fvec_inner_product(residual, centroid, d) : 0.0f;
+        ex_factors.f_add_ex = c_dot_r;
+        ex_factors.f_rescale_ex = ipnorm_inv * norm;
     }
 }
 
@@ -290,12 +264,14 @@ void quantize_ex_bits(
     float norm_sqr = fvec_norm_L2sqr(residual, d);
     float norm = std::sqrt(norm_sqr);
 
-    // Handle degenerate case
+    // Handle degenerate case: residual is (near-)zero, meaning x ≈ centroid.
+    // For both L2 and IP, f_add_ex and f_rescale_ex are trivially zero:
+    //   L2: ||r||² ≈ 0, IP: <c,r> ≈ 0 and ||r||/ipnorm ≈ 0
     if (norm < 1e-10f) {
         size_t code_size = (d * ex_bits + 7) / 8;
         memset(ex_code, 0, code_size);
         ex_factors.f_add_ex = 0.0f;
-        ex_factors.f_rescale_ex = 1.0f;
+        ex_factors.f_rescale_ex = 0.0f;
         return;
     }
 
@@ -349,9 +325,7 @@ void quantize_ex_bits(
     compute_ex_factors(
             residual,
             centroid, // Pass centroid for IP metric factor computation
-            total_code.data(),
             d,
-            ex_bits,
             norm,
             ipnorm,
             ex_factors,

data/vendor/faiss/faiss/impl/RaBitQuantizerMultiBit.h

@@ -60,9 +60,7 @@ void pack_multibit_codes(
  *
  * @param residual Original residual vector (data - centroid)
  * @param centroid Centroid vector (can be nullptr for zero centroid)
- * @param tmp_code Quantized ex-bit codes (unpacked integers)
  * @param d Dimensionality
- * @param ex_bits Number of extra bits
  * @param norm L2 norm of residual
  * @param ipnorm Unnormalized inner product
  * @param ex_factors Output factors structure
@@ -71,9 +69,7 @@ void pack_multibit_codes(
 void compute_ex_factors(
         const float* residual,
         const float* centroid,
-        const int* tmp_code,
         size_t d,
-        size_t ex_bits,
         float norm,
         double ipnorm,
         rabitq_utils::ExtraBitsFactors& ex_factors,

data/vendor/faiss/faiss/impl/ResidualQuantizer.cpp

@@ -18,6 +18,7 @@
 #include <faiss/VectorTransform.h>
 #include <faiss/impl/FaissAssert.h>
 #include <faiss/impl/residual_quantizer_encode_steps.h>
+#include <faiss/impl/simd_dispatch.h>
 #include <faiss/utils/distances.h>
 #include <faiss/utils/hamming.h>
 #include <faiss/utils/utils.h>
@@ -69,23 +70,26 @@ ResidualQuantizer::ResidualQuantizer() {
 }
 
 ResidualQuantizer::ResidualQuantizer(
-        size_t d,
-        const std::vector<size_t>& nbits,
-        Search_type_t search_type)
+        size_t d_in,
+        const std::vector<size_t>& nbits_in,
+        Search_type_t search_type_in)
         : ResidualQuantizer() {
-    this->search_type = search_type;
-    this->d = d;
-    M = nbits.size();
-    this->nbits = nbits;
+    this->search_type = search_type_in;
+    this->d = d_in;
+    M = nbits_in.size();
+    this->nbits = nbits_in;
     set_derived_values();
 }
 
 ResidualQuantizer::ResidualQuantizer(
-        size_t d,
-        size_t M,
-        size_t nbits,
-        Search_type_t search_type)
-        : ResidualQuantizer(d, std::vector<size_t>(M, nbits), search_type) {}
+        size_t d_in,
+        size_t M_in,
+        size_t nbits_in,
+        Search_type_t search_type_in)
+        : ResidualQuantizer(
+                  d_in,
+                  std::vector<size_t>(M_in, nbits_in),
+                  search_type_in) {}
 
 void ResidualQuantizer::initialize_from(
         const ResidualQuantizer& other,
@@ -141,7 +145,7 @@ void ResidualQuantizer::train(size_t n, const float* x) {
     double t0 = getmillisecs();
     double clustering_time = 0;
 
-    for (int m = 0; m < M; m++) {
+    for (size_t m = 0; m < M; m++) {
         int K = 1 << nbits[m];
 
         // on which residuals to train
@@ -156,7 +160,7 @@ void ResidualQuantizer::train(size_t n, const float* x) {
             }
             train_residuals = residuals1;
         }
-        std::vector<float> codebooks;
+        std::vector<float> cur_codebooks;
         float obj = 0;
 
         std::unique_ptr<Index> assign_index;
@@ -174,7 +178,7 @@ void ResidualQuantizer::train(size_t n, const float* x) {
                     train_residuals.size() / d,
                     train_residuals.data(),
                     *assign_index.get());
-            codebooks.swap(clus.centroids);
+            cur_codebooks.swap(clus.centroids);
             assign_index->reset();
             obj = clus.iteration_stats.back().obj;
         } else { // progressive dim clustering
@@ -184,14 +188,14 @@ void ResidualQuantizer::train(size_t n, const float* x) {
                     train_residuals.size() / d,
                     train_residuals.data(),
                     assign_index_factory ? *assign_index_factory : default_fac);
-            codebooks.swap(clus.centroids);
+            cur_codebooks.swap(clus.centroids);
             obj = clus.iteration_stats.back().obj;
         }
         clustering_time += (getmillisecs() - t1) / 1000;
 
         memcpy(this->codebooks.data() + codebook_offsets[m] * d,
-               codebooks.data(),
-               codebooks.size() * sizeof(codebooks[0]));
+               cur_codebooks.data(),
+               cur_codebooks.size() * sizeof(cur_codebooks[0]));
 
         // quantize using the new codebooks
 
@@ -220,7 +224,7 @@ void ResidualQuantizer::train(size_t n, const float* x) {
             beam_search_encode_step(
                     d,
                     K,
-                    codebooks.data(),
+                    cur_codebooks.data(),
                     i1 - i0,
                     cur_beam_size,
                     residuals.data() + i0 * cur_beam_size * d,
@@ -238,16 +242,16 @@ void ResidualQuantizer::train(size_t n, const float* x) {
         distances.swap(new_distances);
 
         float sum_distances = 0;
-        for (int j = 0; j < distances.size(); j++) {
+        for (size_t j = 0; j < distances.size(); j++) {
             sum_distances += distances[j];
         }
 
         if (verbose) {
-            printf("[%.3f s, %.3f s clustering] train stage %d, %d bits, kmeans objective %g, "
+            printf("[%.3f s, %.3f s clustering] train stage %zd, %d bits, kmeans objective %g, "
                    "total distance %g, beam_size %d->%d (batch size %zd)\n",
                    (getmillisecs() - t0) / 1000,
                    clustering_time,
-                   m,
+                   size_t(m),
                    int(nbits[m]),
                    obj,
                    sum_distances,
@@ -274,10 +278,12 @@ void ResidualQuantizer::train(size_t n, const float* x) {
     // find min and max norms
     std::vector<float> norms(n);
 
-    for (size_t i = 0; i < n; i++) {
-        norms[i] = fvec_L2sqr(
-                x + i * d, residuals.data() + i * cur_beam_size * d, d);
-    }
+    with_simd_level([&]<SIMDLevel SL>() {
+        for (size_t i = 0; i < n; i++) {
+            norms[i] = fvec_L2sqr<SL>(
+                    x + i * d, residuals.data() + i * cur_beam_size * d, d);
+        }
+    });
 
     // fvec_norms_L2sqr(norms.data(), x, d, n);
     train_norm(n, norms.data());
@@ -311,7 +317,7 @@ float ResidualQuantizer::retrain_AQ_codebook(size_t n, const float* x) {
     std::vector<float> C(n * total_codebook_size);
     for (size_t i = 0; i < n; i++) {
         BitstringReader bsr(codes.data() + i * code_size, code_size);
-        for (int m = 0; m < M; m++) {
+        for (size_t m = 0; m < M; m++) {
             int idx = bsr.read(nbits[m]);
             C[i + (codebook_offsets[m] + idx) * n] = 1;
         }
@@ -393,11 +399,13 @@ float ResidualQuantizer::retrain_AQ_codebook(size_t n, const float* x) {
     }
 
     float output_recons_error = 0;
-    for (size_t j = 0; j < d; j++) {
-        output_recons_error += fvec_norm_L2sqr(
-                xt.data() + total_codebook_size + n * j,
-                n - total_codebook_size);
-    }
+    with_simd_level([&]<SIMDLevel SL>() {
+        for (size_t j = 0; j < d; j++) {
+            output_recons_error += fvec_norm_L2sqr<SL>(
+                    xt.data() + total_codebook_size + n * j,
+                    n - total_codebook_size);
+        }
+    });
     if (verbose) {
         printf("  output quantization error %g\n", output_recons_error);
     }

data/vendor/faiss/faiss/impl/ResidualQuantizer.h

@@ -13,7 +13,7 @@
 #include <faiss/Clustering.h>
 #include <faiss/impl/AdditiveQuantizer.h>
 
-#include <faiss/utils/approx_topk/mode.h>
+#include <faiss/impl/approx_topk/approx_topk.h>
 
 namespace faiss {