faiss 0.4.2 → 0.5.0

data/vendor/faiss/faiss/impl/IDSelector.h

@@ -116,7 +116,7 @@ struct IDSelectorBitmap : IDSelector {
 /** reverts the membership test of another selector */
 struct IDSelectorNot : IDSelector {
     const IDSelector* sel;
-    IDSelectorNot(const IDSelector* sel) : sel(sel) {}
+    explicit IDSelectorNot(const IDSelector* sel) : sel(sel) {}
     bool is_member(idx_t id) const final {
         return !sel->is_member(id);
     }

data/vendor/faiss/faiss/impl/LocalSearchQuantizer.cpp

@@ -30,7 +30,7 @@
 #endif
 
 extern "C" {
-// LU decomoposition of a general matrix
+// LU decomposition of a general matrix
 void sgetrf_(
         FINTEGER* m,
         FINTEGER* n,
@@ -65,7 +65,7 @@ int sgemm_(
         float* c,
         FINTEGER* ldc);
 
-// LU decomoposition of a general matrix
+// LU decomposition of a general matrix
 void dgetrf_(
         FINTEGER* m,
         FINTEGER* n,
@@ -189,7 +189,7 @@ void LocalSearchQuantizer::train(size_t n, const float* x) {
     std::vector<int32_t> codes(n * M); // [n, M]
     random_int32(codes, 0, K - 1, gen);
 
-    // compute standard derivations of each dimension
+    // compute standard deviations of each dimension
     std::vector<float> stddev(d, 0);
 
 #pragma omp parallel for
@@ -487,7 +487,7 @@ void LocalSearchQuantizer::update_codebooks(
  *     L = (X - \sum cj)^2, j = 1, ..., M
  *     L = X^2 - 2X * \sum cj + (\sum cj)^2
  *
- * X^2 is negligable since it is the same for all possible value
+ * X^2 is negligible since it is the same for all possible value
  * k of the m-th subcode.
  *
  * 2X * \sum cj is the unary term

data/vendor/faiss/faiss/impl/LocalSearchQuantizer.h

@@ -138,7 +138,7 @@ struct LocalSearchQuantizer : AdditiveQuantizer {
     /** Add some perturbation to codebooks
      *
      * @param T         temperature of simulated annealing
-     * @param stddev    standard derivations of each dimension in training data
+     * @param stddev    standard deviations of each dimension in training data
      */
     void perturb_codebooks(
             float T,

data/vendor/faiss/faiss/impl/LookupTableScaler.h

@@ -63,7 +63,7 @@ struct DummyScaler {
 };
 
 /// consumes 2x4 bits to encode a norm as a scalar additive quantizer
-/// the norm is scaled because its range if larger than other components
+/// the norm is scaled because its range is larger than other components
 struct NormTableScaler {
     static constexpr int nscale = 2;
     int scale_int;

data/vendor/faiss/faiss/impl/NNDescent.cpp

@@ -177,7 +177,7 @@ void NNDescent::join(DistanceComputer& qdis) {
     }
 }
 
-/// Sample neighbors for each node to peform local join later
+/// Sample neighbors for each node to perform local join later
 /// Store them in nn_new and nn_old
 void NNDescent::update() {
     // Step 1.

data/vendor/faiss/faiss/impl/NNDescent.h

@@ -34,7 +34,7 @@ namespace faiss {
  *
  *  Dong, Wei, Charikar Moses, and Kai Li, WWW 2011
  *
- * This implmentation is heavily influenced by the efanna
+ * This implementation is heavily influenced by the efanna
  * implementation by Cong Fu and the KGraph library by Wei Dong
  * (https://github.com/ZJULearning/efanna_graph)
  * (https://github.com/aaalgo/kgraph)
@@ -117,7 +117,7 @@ struct NNDescent {
     /// Perform local join on each node
     void join(DistanceComputer& qdis);
 
-    /// Sample new neighbors for each node to peform local join later
+    /// Sample new neighbors for each node to perform local join later
     void update();
 
     /// Sample a small number of points to evaluate the quality of KNNG built

data/vendor/faiss/faiss/impl/NSG.cpp

@@ -621,7 +621,7 @@ int NSG::attach_unlinked(
         }
     }
 
-    // randomly choice annother node
+    // randomly choice another node
     if (!found) {
         do {
             node = rng.rand_int(ntotal);

data/vendor/faiss/faiss/impl/PanoramaStats.cpp

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+// -*- c++ -*-
+
+#include <faiss/impl/PanoramaStats.h>
+
+namespace faiss {
+
+void PanoramaStats::reset() {
+    total_dims_scanned = 0;
+    total_dims = 0;
+    ratio_dims_scanned = 1.0f;
+}
+
+void PanoramaStats::add(const PanoramaStats& other) {
+    total_dims_scanned += other.total_dims_scanned;
+    total_dims += other.total_dims;
+    if (total_dims > 0) {
+        ratio_dims_scanned =
+                static_cast<float>(total_dims_scanned) / total_dims;
+    } else {
+        ratio_dims_scanned = 1.0f;
+    }
+}
+
+PanoramaStats indexPanorama_stats;
+
+} // namespace faiss

data/vendor/faiss/faiss/impl/PanoramaStats.h

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+// -*- c++ -*-
+
+#ifndef FAISS_PANORAMA_STATS_H
+#define FAISS_PANORAMA_STATS_H
+
+#include <faiss/impl/platform_macros.h>
+
+namespace faiss {
+
+/// Statistics are not robust to internal threading nor to
+/// concurrent Panorama searches. Use these values in a
+/// single-threaded context to accurately gauge Panorama's
+/// pruning effectiveness.
+struct PanoramaStats {
+    uint64_t total_dims_scanned = 0; // total dimensions scanned
+    uint64_t total_dims = 0;         // total dimensions
+    float ratio_dims_scanned = 1.0f; // fraction of dimensions actually scanned
+
+    PanoramaStats() {
+        reset();
+    }
+    void reset();
+    void add(const PanoramaStats& other);
+};
+
+// Single global var for all Panorama indexes
+FAISS_API extern PanoramaStats indexPanorama_stats;
+
+} // namespace faiss
+
+#endif

data/vendor/faiss/faiss/impl/PolysemousTraining.cpp

@@ -178,7 +178,7 @@ struct ReproduceWithHammingObjective : PermutationObjective {
         return x * x;
     }
 
-    // weihgting of distances: it is more important to reproduce small
+    // weighting of distances: it is more important to reproduce small
     // distances well
     double dis_weight(double x) const {
         return exp(-dis_weight_factor * x);
@@ -295,7 +295,7 @@ struct ReproduceWithHammingObjective : PermutationObjective {
 
 } // anonymous namespace
 
-// weihgting of distances: it is more important to reproduce small
+// weighting of distances: it is more important to reproduce small
 // distances well
 double ReproduceDistancesObjective::dis_weight(double x) const {
     return exp(-dis_weight_factor * x);
@@ -636,7 +636,7 @@ struct Score3Computer : PermutationObjective {
         return accu;
     }
 
-    /// PermutationObjective implementeation (just negates the scores
+    /// PermutationObjective implementation (just negates the scores
     /// for minimization)
 
     double compute_cost(const int* perm) const override {
@@ -689,7 +689,7 @@ struct RankingScore2 : Score3Computer<float, double> {
     /// count nb of i, j in a x b st. i < j
     /// a and b should be sorted on input
     /// they are the ranks of j and k respectively.
-    /// specific version for diff-of-rank weighting, cannot optimized
+    /// specific version for diff-of-rank weighting, cannot optimize
     /// with a cumulative table
     double accum_gt_weight_diff(
             const std::vector<int>& a,
@@ -985,7 +985,7 @@ size_t PolysemousTraining::memory_usage_per_thread(
             return n * n * n * sizeof(float);
     }
 
-    FAISS_THROW_MSG("Invalid optmization type");
+    FAISS_THROW_MSG("Invalid optimization type");
     return 0;
 }
 

data/vendor/faiss/faiss/impl/ProductAdditiveQuantizer.cpp

@@ -154,7 +154,7 @@ void ProductAdditiveQuantizer::compute_unpacked_codes(
         int32_t* unpacked_codes,
         size_t n,
         const float* centroids) const {
-    /// TODO: actuallly we do not need to unpack and pack
+    /// TODO: actually we do not need to unpack and pack
     size_t offset_d = 0, offset_m = 0;
     std::vector<float> xsub;
     std::vector<uint8_t> codes;

data/vendor/faiss/faiss/impl/ProductAdditiveQuantizer.h

@@ -46,7 +46,7 @@ struct ProductAdditiveQuantizer : AdditiveQuantizer {
 
     ProductAdditiveQuantizer();
 
-    virtual ~ProductAdditiveQuantizer();
+    virtual ~ProductAdditiveQuantizer() override;
 
     void init(
             size_t d,

data/vendor/faiss/faiss/impl/ProductQuantizer-inl.h

@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+#pragma once
+
 namespace faiss {
 
 inline PQEncoderGeneric::PQEncoderGeneric(

data/vendor/faiss/faiss/impl/ProductQuantizer.h

@@ -166,7 +166,7 @@ struct ProductQuantizer : Quantizer {
     /// Symmetric Distance Table
     std::vector<float> sdc_table;
 
-    // intitialize the SDC table from the centroids
+    // initialize the SDC table from the centroids
     void compute_sdc_table();
 
     void search_sdc(

data/vendor/faiss/faiss/impl/RaBitQUtils.cpp

@@ -0,0 +1,246 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#include <faiss/impl/RaBitQUtils.h>
+
+#include <faiss/impl/FaissAssert.h>
+#include <faiss/utils/distances.h>
+#include <algorithm>
+#include <cmath>
+#include <limits>
+
+namespace faiss {
+namespace rabitq_utils {
+
+// Ideal quantizer radii for quantizers of 1..8 bits, optimized to minimize
+// L2 reconstruction error.
+const float Z_MAX_BY_QB[8] = {
+        0.79688, // qb = 1.
+        1.49375,
+        2.05078,
+        2.50938,
+        2.91250,
+        3.26406,
+        3.59844,
+        3.91016, // qb = 8.
+};
+
+void compute_vector_intermediate_values(
+        const float* x,
+        size_t d,
+        const float* centroid,
+        float& norm_L2sqr,
+        float& or_L2sqr,
+        float& dp_oO) {
+    norm_L2sqr = 0.0f;
+    or_L2sqr = 0.0f;
+    dp_oO = 0.0f;
+
+    for (size_t j = 0; j < d; j++) {
+        const float x_val = x[j];
+        const float centroid_val = (centroid != nullptr) ? centroid[j] : 0.0f;
+        const float or_minus_c = x_val - centroid_val;
+
+        const float or_minus_c_sq = or_minus_c * or_minus_c;
+        norm_L2sqr += or_minus_c_sq;
+        or_L2sqr += x_val * x_val;
+
+        const bool xb = (or_minus_c > 0.0f);
+        dp_oO += xb ? or_minus_c : -or_minus_c;
+    }
+}
+
+FactorsData compute_factors_from_intermediates(
+        float norm_L2sqr,
+        float or_L2sqr,
+        float dp_oO,
+        size_t d,
+        MetricType metric_type) {
+    constexpr float epsilon = std::numeric_limits<float>::epsilon();
+    const float inv_d_sqrt =
+            (d == 0) ? 1.0f : (1.0f / std::sqrt(static_cast<float>(d)));
+
+    const float sqrt_norm_L2 = std::sqrt(norm_L2sqr);
+    const float inv_norm_L2 =
+            (norm_L2sqr < epsilon) ? 1.0f : (1.0f / sqrt_norm_L2);
+
+    const float normalized_dp = dp_oO * inv_norm_L2 * inv_d_sqrt;
+    const float inv_dp_oO =
+            (std::abs(normalized_dp) < epsilon) ? 1.0f : (1.0f / normalized_dp);
+
+    FactorsData factors;
+    factors.or_minus_c_l2sqr = (metric_type == MetricType::METRIC_INNER_PRODUCT)
+            ? (norm_L2sqr - or_L2sqr)
+            : norm_L2sqr;
+    factors.dp_multiplier = inv_dp_oO * sqrt_norm_L2;
+
+    return factors;
+}
+
+FactorsData compute_vector_factors(
+        const float* x,
+        size_t d,
+        const float* centroid,
+        MetricType metric_type) {
+    float norm_L2sqr, or_L2sqr, dp_oO;
+    compute_vector_intermediate_values(
+            x, d, centroid, norm_L2sqr, or_L2sqr, dp_oO);
+    return compute_factors_from_intermediates(
+            norm_L2sqr, or_L2sqr, dp_oO, d, metric_type);
+}
+
+QueryFactorsData compute_query_factors(
+        const float* query,
+        size_t d,
+        const float* centroid,
+        uint8_t qb,
+        bool centered,
+        MetricType metric_type,
+        std::vector<float>& rotated_q,
+        std::vector<uint8_t>& rotated_qq) {
+    FAISS_THROW_IF_NOT(qb <= 8);
+    FAISS_THROW_IF_NOT(qb > 0);
+
+    QueryFactorsData query_factors;
+
+    // Compute distance from query to centroid
+    if (centroid != nullptr) {
+        query_factors.qr_to_c_L2sqr = fvec_L2sqr(query, centroid, d);
+    } else {
+        query_factors.qr_to_c_L2sqr = fvec_norm_L2sqr(query, d);
+    }
+
+    // Rotate the query (subtract centroid)
+    rotated_q.resize(d);
+    for (size_t i = 0; i < d; i++) {
+        if (i < rotated_q.size()) {
+            rotated_q[i] =
+                    query[i] - ((centroid == nullptr) ? 0.0f : centroid[i]);
+        }
+    }
+
+    const float inv_d_sqrt =
+            (d == 0) ? 1.0f : (1.0f / std::sqrt(static_cast<float>(d)));
+
+    // Compute quantization range
+    float v_min = std::numeric_limits<float>::max();
+    float v_max = std::numeric_limits<float>::lowest();
+
+    if (centered) {
+        float z_max = Z_MAX_BY_QB[qb - 1];
+        float v_radius = z_max * std::sqrt(query_factors.qr_to_c_L2sqr / d);
+        v_min = -v_radius;
+        v_max = v_radius;
+    } else {
+        // Only compute min/max if we have dimensions to process
+        if (d > 0 && !rotated_q.empty()) {
+            for (size_t i = 0; i < d; i++) {
+                const float v_q = rotated_q[i];
+                v_min = std::min(v_min, v_q);
+                v_max = std::max(v_max, v_q);
+            }
+        } else {
+            // For empty dimensions, use default range
+            v_min = 0.0f;
+            v_max = 1.0f;
+        }
+    }
+
+    // Quantize the query
+    const uint8_t max_code = (1 << qb) - 1;
+    const float delta = (v_max - v_min) / max_code;
+    const float inv_delta = 1.0f / delta;
+
+    rotated_qq.resize(d);
+    size_t sum_qq = 0;
+    int64_t sum2_signed_odd_int = 0;
+
+    // Process arrays - throw error if they are unexpectedly empty
+    if (d > 0 && !rotated_q.empty() && !rotated_qq.empty()) {
+        for (size_t i = 0; i < d; i++) {
+            const float v_q = rotated_q[i];
+            // Non-randomized scalar quantization
+            const uint8_t v_qq = std::clamp<float>(
+                    std::round((v_q - v_min) * inv_delta), 0, max_code);
+            rotated_qq[i] = v_qq;
+            sum_qq += v_qq;
+
+            if (centered) {
+                int64_t signed_odd_int = int64_t(v_qq) * 2 - max_code;
+                sum2_signed_odd_int += signed_odd_int * signed_odd_int;
+            }
+        }
+    } else {
+        FAISS_THROW_MSG(
+                "Arrays unexpectedly empty when d=" + std::to_string(d) +
+                "or d is incorrectly set");
+    }
+
+    // Compute query factors
+    query_factors.c1 = 2 * delta * inv_d_sqrt;
+    query_factors.c2 = 2 * v_min * inv_d_sqrt;
+    query_factors.c34 = inv_d_sqrt * (delta * sum_qq + d * v_min);
+
+    if (centered) {
+        query_factors.int_dot_scale = std::sqrt(
+                query_factors.qr_to_c_L2sqr / (sum2_signed_odd_int * d));
+    } else {
+        query_factors.int_dot_scale = 1.0f;
+    }
+
+    // Compute query norm for inner product metric
+    query_factors.qr_norm_L2sqr = 0.0f;
+    if (metric_type == MetricType::METRIC_INNER_PRODUCT) {
+        query_factors.qr_norm_L2sqr = fvec_norm_L2sqr(query, d);
+    }
+
+    return query_factors;
+}
+
+bool extract_bit_standard(const uint8_t* code, size_t bit_index) {
+    const size_t byte_idx = bit_index / 8;
+    const size_t bit_offset = bit_index % 8;
+    return (code[byte_idx] >> bit_offset) & 1;
+}
+
+bool extract_bit_fastscan(const uint8_t* code, size_t bit_index) {
+    const size_t m = bit_index / 4; // Sub-quantizer index
+    const size_t dim_offset =
+            bit_index % 4;         // Bit position within sub-quantizer
+    const size_t byte_idx = m / 2; // Byte index (2 sub-quantizers per byte)
+    const uint8_t bit_mask = static_cast<uint8_t>(1 << dim_offset);
+
+    if (m % 2 == 0) {
+        // Lower 4 bits of byte
+        return (code[byte_idx] & bit_mask) != 0;
+    } else {
+        // Upper 4 bits of byte (shifted)
+        return (code[byte_idx] & (bit_mask << 4)) != 0;
+    }
+}
+
+void set_bit_standard(uint8_t* code, size_t bit_index) {
+    const size_t byte_idx = bit_index / 8;
+    const size_t bit_offset = bit_index % 8;
+    code[byte_idx] |= (1 << bit_offset);
+}
+
+void set_bit_fastscan(uint8_t* code, size_t bit_index) {
+    const size_t m = bit_index / 4;
+    const size_t dim_offset = bit_index % 4;
+    const uint8_t bit_mask = static_cast<uint8_t>(1 << dim_offset);
+    const size_t byte_idx = m / 2;
+
+    if (m % 2 == 0) {
+        code[byte_idx] |= bit_mask;
+    } else {
+        code[byte_idx] |= (bit_mask << 4);
+    }
+}
+
+} // namespace rabitq_utils
+} // namespace faiss

data/vendor/faiss/faiss/impl/RaBitQUtils.h

@@ -0,0 +1,153 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <faiss/MetricType.h>
+#include <faiss/impl/platform_macros.h>
+#include <cstddef>
+#include <cstdint>
+#include <vector>
+
+namespace faiss {
+namespace rabitq_utils {
+
+/** Factors computed per database vector for RaBitQ distance computation.
+ * These can be stored either embedded in codes (IndexRaBitQ) or separately
+ * (IndexRaBitQFastScan).
+ */
+struct FactorsData {
+    // ||or - c||^2 - ((metric==IP) ? ||or||^2 : 0)
+    float or_minus_c_l2sqr = 0;
+    float dp_multiplier = 0;
+};
+
+/** Query-specific factors computed during search for RaBitQ distance
+ * computation. Used by both IndexRaBitQ and IndexRaBitQFastScan
+ * implementations.
+ */
+struct QueryFactorsData {
+    float c1 = 0;
+    float c2 = 0;
+    float c34 = 0;
+
+    float qr_to_c_L2sqr = 0;
+    float qr_norm_L2sqr = 0;
+
+    float int_dot_scale = 1;
+};
+
+/** Ideal quantizer radii for quantizers of 1..8 bits, optimized to minimize
+ * L2 reconstruction error. Shared between all RaBitQ implementations.
+ */
+FAISS_API extern const float Z_MAX_BY_QB[8];
+
+/** Compute factors for a single database vector using RaBitQ algorithm.
+ * This function consolidates the mathematical logic that was duplicated
+ * between IndexRaBitQ and IndexRaBitQFastScan.
+ *
+ * @param x             input vector (d dimensions)
+ * @param d             dimensionality
+ * @param centroid      database centroid (nullptr if not used)
+ * @param metric_type   distance metric (L2 or Inner Product)
+ * @return              computed factors for distance computation
+ */
+FactorsData compute_vector_factors(
+        const float* x,
+        size_t d,
+        const float* centroid,
+        MetricType metric_type);
+
+/** Compute intermediate values needed for vector factor computation.
+ * Separated out to allow different bit packing strategies while sharing
+ * the core mathematical computation.
+ *
+ * @param x             input vector (d dimensions)
+ * @param d             dimensionality
+ * @param centroid      database centroid (nullptr if not used)
+ * @param norm_L2sqr    output: ||or - c||^2
+ * @param or_L2sqr      output: ||or||^2
+ * @param dp_oO         output: sum of |or_i - c_i| (absolute deviations)
+ */
+void compute_vector_intermediate_values(
+        const float* x,
+        size_t d,
+        const float* centroid,
+        float& norm_L2sqr,
+        float& or_L2sqr,
+        float& dp_oO);
+
+/** Compute final factors from intermediate values.
+ * @param norm_L2sqr    ||or - c||^2
+ * @param or_L2sqr      ||or||^2
+ * @param dp_oO         sum of |or_i - c_i|
+ * @param d             dimensionality
+ * @param metric_type   distance metric
+ * @return              computed factors
+ */
+FactorsData compute_factors_from_intermediates(
+        float norm_L2sqr,
+        float or_L2sqr,
+        float dp_oO,
+        size_t d,
+        MetricType metric_type);
+
+/** Compute query factors for RaBitQ distance computation.
+ * This consolidates the query processing logic shared between implementations.
+ *
+ * @param query         query vector (d dimensions)
+ * @param d             dimensionality
+ * @param centroid      database centroid (nullptr if not used)
+ * @param qb            number of quantization bits (1-8)
+ * @param centered      whether to use centered quantization
+ * @param metric_type   distance metric
+ * @param rotated_q     output: query - centroid
+ * @param rotated_qq    output: quantized query values
+ * @return              computed query factors
+ */
+QueryFactorsData compute_query_factors(
+        const float* query,
+        size_t d,
+        const float* centroid,
+        uint8_t qb,
+        bool centered,
+        MetricType metric_type,
+        std::vector<float>& rotated_q,
+        std::vector<uint8_t>& rotated_qq);
+
+/** Extract bit value from RaBitQ code in standard format.
+ * Used by IndexRaBitQ which stores bits sequentially.
+ *
+ * @param code          RaBitQ code data
+ * @param bit_index     which bit to extract (0 to d-1)
+ * @return              bit value (true/false)
+ */
+bool extract_bit_standard(const uint8_t* code, size_t bit_index);
+
+/** Extract bit value from FastScan code format.
+ * Used by IndexRaBitQFastScan which packs bits into 4-bit sub-quantizers.
+ *
+ * @param code          FastScan code data
+ * @param bit_index     which bit to extract (0 to d-1)
+ * @return              bit value (true/false)
+ */
+bool extract_bit_fastscan(const uint8_t* code, size_t bit_index);
+
+/** Set bit value in standard RaBitQ code format.
+ * @param code          RaBitQ code data to modify
+ * @param bit_index     which bit to set (0 to d-1)
+ */
+void set_bit_standard(uint8_t* code, size_t bit_index);
+
+/** Set bit value in FastScan code format.
+ * @param code          FastScan code data to modify
+ * @param bit_index     which bit to set (0 to d-1)
+ */
+void set_bit_fastscan(uint8_t* code, size_t bit_index);
+
+} // namespace rabitq_utils
+} // namespace faiss