faiss 0.4.3 → 0.5.1

data/vendor/faiss/faiss/impl/CodePacker.h

@@ -38,14 +38,14 @@ struct CodePacker {
                                   // code_size
     ) const = 0;
 
-    // pack all code in a block
+    // pack all codes in a block
     virtual void pack_all(
             const uint8_t* flat_codes, // codes to write to the block, size
                                        // (nvec * code_size)
             uint8_t* block             // block to write to (size block_size)
     ) const;
 
-    // unpack all code in a block
+    // unpack all codes in a block
     virtual void unpack_all(
             const uint8_t* block, // block to read from (size block_size)
             uint8_t* flat_codes // where to write the resulting codes size (nvec

data/vendor/faiss/faiss/impl/DistanceComputer.h

@@ -60,7 +60,7 @@ struct DistanceComputer {
 };
 
 /* Wrap the distance computer into one that negates the
-   distances. This makes supporting INNER_PRODUCE search easier */
+   distances. This makes supporting INNER_PRODUCT search easier */
 
 struct NegativeDistanceComputer : DistanceComputer {
     /// owned by this
@@ -100,7 +100,7 @@ struct NegativeDistanceComputer : DistanceComputer {
         return -basedis->symmetric_dis(i, j);
     }
 
-    virtual ~NegativeDistanceComputer() {
+    virtual ~NegativeDistanceComputer() override {
         delete basedis;
     }
 };
@@ -113,19 +113,90 @@ struct FlatCodesDistanceComputer : DistanceComputer {
     const uint8_t* codes;
     size_t code_size;
 
-    FlatCodesDistanceComputer(const uint8_t* codes, size_t code_size)
-            : codes(codes), code_size(code_size) {}
+    const float* q = nullptr; // not used in all distance computers
 
-    FlatCodesDistanceComputer() : codes(nullptr), code_size(0) {}
+    FlatCodesDistanceComputer(
+            const uint8_t* codes,
+            size_t code_size,
+            const float* q = nullptr)
+            : codes(codes), code_size(code_size), q(q) {}
+
+    explicit FlatCodesDistanceComputer(const float* q)
+            : codes(nullptr), code_size(0), q(q) {}
+
+    FlatCodesDistanceComputer() : codes(nullptr), code_size(0), q(nullptr) {}
 
     float operator()(idx_t i) override {
         return distance_to_code(codes + i * code_size);
     }
 
+    /// Computes a partial dot product over a slice of the query vector.
+    /// The slice is defined by the following parameters:
+    ///   — `offset`: the starting index of the first component to include
+    ///   — `num_components`: the number of consecutive components to include
+    ///
+    /// Components refer to raw dimensions of the flat (uncompressed) query
+    /// vector.
+    ///
+    /// By default, this method throws an error, as it is only implemented
+    /// in specific subclasses such as `FlatL2Dis`. Other flat distance
+    /// computers may override this when partial dot product support is needed.
+    ///
+    /// Over time, this method might be changed to a pure virtual function (`=
+    /// 0`) to enforce implementation in subclasses that require this
+    /// functionality.
+    ///
+    /// This method is not part of the generic `DistanceComputer` interface
+    /// because for compressed representations (e.g., product quantization),
+    /// calling `partial_dot_product` repeatedly is often less efficient than
+    /// computing the full distance at once.
+    ///
+    /// Supporting efficient partial scans generally requires a different memory
+    /// layout, such as interleaved blocks that keep SIMD lanes full. This is a
+    /// non-trivial change and not supported in the current flat layout.
+    ///
+    /// For more details on partial (or chunked) dot product computations and
+    /// the performance trade-offs involved, refer to the Panorama paper:
+    /// https://arxiv.org/pdf/2510.00566
+    virtual float partial_dot_product(
+            const idx_t /* i */,
+            const uint32_t /* offset */,
+            const uint32_t /* num_components */) {
+        FAISS_THROW_MSG("partial_dot_product not implemented");
+    }
+
     /// compute distance of current query to an encoded vector
     virtual float distance_to_code(const uint8_t* code) = 0;
 
-    virtual ~FlatCodesDistanceComputer() {}
+    /// Compute partial dot products of current query to 4 stored vectors.
+    /// See `partial_dot_product` for more details.
+    virtual void partial_dot_product_batch_4(
+            const idx_t idx0,
+            const idx_t idx1,
+            const idx_t idx2,
+            const idx_t idx3,
+            float& dp0,
+            float& dp1,
+            float& dp2,
+            float& dp3,
+            const uint32_t offset,
+            const uint32_t num_components) {
+        // default implementation for correctness
+        const float d0 =
+                this->partial_dot_product(idx0, offset, num_components);
+        const float d1 =
+                this->partial_dot_product(idx1, offset, num_components);
+        const float d2 =
+                this->partial_dot_product(idx2, offset, num_components);
+        const float d3 =
+                this->partial_dot_product(idx3, offset, num_components);
+        dp0 = d0;
+        dp1 = d1;
+        dp2 = d2;
+        dp3 = d3;
+    }
+
+    virtual ~FlatCodesDistanceComputer() override {}
 };
 
 } // namespace faiss

data/vendor/faiss/faiss/impl/FastScanDistancePostProcessing.h

@@ -0,0 +1,53 @@
+/*
+ * 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 <cstddef>
+
+namespace faiss {
+
+// Forward declarations
+struct NormTableScaler;
+
+namespace rabitq_utils {
+struct QueryFactorsData;
+}
+
+/**
+ * Simple context object that holds processors for FastScan operations.
+ * */
+struct FastScanDistancePostProcessing {
+    /// Norm scaling processor for Additive Quantizers (nullptr if not needed)
+    const NormTableScaler* norm_scaler = nullptr;
+
+    /// Query factors data pointer for RaBitQ (nullptr if not needed)
+    /// This pointer should point to the beginning of the relevant
+    /// QueryFactorsData subset for this context.
+    rabitq_utils::QueryFactorsData* query_factors = nullptr;
+
+    /// The nprobe value used when allocating query_factors storage.
+    /// This is needed because the allocation size (n * nprobe) may use a
+    /// different nprobe than index->nprobe if search params override it.
+    /// Set to 0 to use index->nprobe as fallback.
+    size_t nprobe = 0;
+
+    /// Default constructor - no processing
+    FastScanDistancePostProcessing() = default;
+
+    /// Check if norm scaling is enabled
+    bool has_norm_scaling() const {
+        return norm_scaler != nullptr;
+    }
+
+    /// Check if query factors processing is enabled
+    bool has_query_processing() const {
+        return query_factors != nullptr;
+    }
+};
+
+} // namespace faiss

data/vendor/faiss/faiss/impl/HNSW.cpp

@@ -9,6 +9,8 @@
 
 #include <cstddef>
 
+#include <faiss/IndexHNSW.h>
+
 #include <faiss/impl/AuxIndexStructures.h>
 #include <faiss/impl/DistanceComputer.h>
 #include <faiss/impl/IDSelector.h>
@@ -60,7 +62,7 @@ HNSW::HNSW(int M) : rng(12345) {
 
 int HNSW::random_level() {
     double f = rng.rand_float();
-    // could be a bit faster with bissection
+    // could be a bit faster with bisection
     for (int level = 0; level < assign_probas.size(); level++) {
         if (f < assign_probas[level]) {
             return level;
@@ -588,6 +590,28 @@ void HNSW::add_with_locks(
 using MinimaxHeap = HNSW::MinimaxHeap;
 using Node = HNSW::Node;
 using C = HNSW::C;
+
+/** Helper to extract search parameters from HNSW and SearchParameters */
+static inline void extract_search_params(
+        const HNSW& hnsw,
+        const SearchParameters* params,
+        bool& do_dis_check,
+        int& efSearch,
+        const IDSelector*& sel) {
+    // can be overridden by search params
+    do_dis_check = hnsw.check_relative_distance;
+    efSearch = hnsw.efSearch;
+    sel = nullptr;
+    if (params) {
+        if (const SearchParametersHNSW* hnsw_params =
+                    dynamic_cast<const SearchParametersHNSW*>(params)) {
+            do_dis_check = hnsw_params->check_relative_distance;
+            efSearch = hnsw_params->efSearch;
+        }
+        sel = params->sel;
+    }
+}
+
 /** Do a BFS on the candidates list */
 int search_from_candidates(
         const HNSW& hnsw,
@@ -602,18 +626,10 @@ int search_from_candidates(
     int nres = nres_in;
     int ndis = 0;
 
-    // can be overridden by search params
-    bool do_dis_check = hnsw.check_relative_distance;
-    int efSearch = hnsw.efSearch;
-    const IDSelector* sel = nullptr;
-    if (params) {
-        if (const SearchParametersHNSW* hnsw_params =
-                    dynamic_cast<const SearchParametersHNSW*>(params)) {
-            do_dis_check = hnsw_params->check_relative_distance;
-            efSearch = hnsw_params->efSearch;
-        }
-        sel = params->sel;
-    }
+    bool do_dis_check;
+    int efSearch;
+    const IDSelector* sel;
+    extract_search_params(hnsw, params, do_dis_check, efSearch, sel);
 
     C::T threshold = res.threshold;
     for (int i = 0; i < candidates.size(); i++) {
@@ -735,6 +751,253 @@ int search_from_candidates(
     return nres;
 }
 
+int search_from_candidates_panorama(
+        const HNSW& hnsw,
+        const IndexHNSW* index,
+        DistanceComputer& qdis,
+        ResultHandler<C>& res,
+        MinimaxHeap& candidates,
+        VisitedTable& vt,
+        HNSWStats& stats,
+        int level,
+        int nres_in,
+        const SearchParameters* params) {
+    int nres = nres_in;
+    int ndis = 0;
+
+    bool do_dis_check;
+    int efSearch;
+    const IDSelector* sel;
+    extract_search_params(hnsw, params, do_dis_check, efSearch, sel);
+
+    C::T threshold = res.threshold;
+    for (int i = 0; i < candidates.size(); i++) {
+        idx_t v1 = candidates.ids[i];
+        float d = candidates.dis[i];
+        FAISS_ASSERT(v1 >= 0);
+        if (!sel || sel->is_member(v1)) {
+            if (d < threshold) {
+                if (res.add_result(d, v1)) {
+                    threshold = res.threshold;
+                }
+            }
+        }
+        vt.set(v1);
+    }
+
+    // Validate the index type so we can access cumulative sums, n_levels, and
+    // get the ability to compute partial dot products.
+    const auto* panorama_index =
+            dynamic_cast<const IndexHNSWFlatPanorama*>(index);
+    FAISS_THROW_IF_NOT_MSG(
+            panorama_index, "Index must be a IndexHNSWFlatPanorama");
+    auto* flat_codes_qdis = dynamic_cast<FlatCodesDistanceComputer*>(&qdis);
+    FAISS_THROW_IF_NOT_MSG(
+            flat_codes_qdis,
+            "DistanceComputer must be a FlatCodesDistanceComputer");
+
+    // Allocate space for the index array and exact distances.
+    size_t M = hnsw.nb_neighbors(0);
+    std::vector<idx_t> index_array(M);
+    std::vector<float> exact_distances(M);
+
+    const float* query = flat_codes_qdis->q;
+    std::vector<float> query_cum_sums(panorama_index->num_panorama_levels + 1);
+    IndexHNSWFlatPanorama::compute_cum_sums(
+            query,
+            query_cum_sums.data(),
+            panorama_index->d,
+            panorama_index->num_panorama_levels,
+            panorama_index->panorama_level_width);
+    float query_norm_sq = query_cum_sums[0] * query_cum_sums[0];
+
+    int nstep = 0;
+
+    while (candidates.size() > 0) {
+        float d0 = 0;
+        int v0 = candidates.pop_min(&d0);
+
+        if (do_dis_check) {
+            // tricky stopping condition: there are more than ef
+            // distances that are processed already that are smaller
+            // than d0
+
+            int n_dis_below = candidates.count_below(d0);
+            if (n_dis_below >= efSearch) {
+                break;
+            }
+        }
+
+        size_t begin, end;
+        hnsw.neighbor_range(v0, level, &begin, &end);
+
+        // Unlike the vanilla HNSW, we already remove (and compact) the visited
+        // nodes from the candidates list at this stage. We also remove nodes
+        // that are not selected.
+        size_t initial_size = 0;
+        for (size_t j = begin; j < end; j++) {
+            int v1 = hnsw.neighbors[j];
+            if (v1 < 0) {
+                break;
+            }
+
+            const float* cum_sums_v1 = panorama_index->get_cum_sum(v1);
+            index_array[initial_size] = v1;
+            exact_distances[initial_size] =
+                    query_norm_sq + cum_sums_v1[0] * cum_sums_v1[0];
+
+            bool is_selected = !sel || sel->is_member(v1);
+            initial_size += is_selected && !vt.get(v1) ? 1 : 0;
+
+            vt.set(v1);
+        }
+
+        size_t batch_size = initial_size;
+        size_t curr_panorama_level = 0;
+        const size_t num_panorama_levels = panorama_index->num_panorama_levels;
+        while (curr_panorama_level < num_panorama_levels && batch_size > 0) {
+            float query_cum_norm = query_cum_sums[curr_panorama_level + 1];
+
+            const size_t panorama_level_width =
+                    panorama_index->panorama_level_width;
+            size_t start_dim = curr_panorama_level * panorama_level_width;
+            size_t end_dim = (curr_panorama_level + 1) * panorama_level_width;
+            end_dim = std::min(end_dim, static_cast<size_t>(panorama_index->d));
+
+            size_t i = 0;
+            size_t next_batch_size = 0;
+            for (; i + 3 < batch_size; i += 4) {
+                idx_t idx_0 = index_array[i];
+                idx_t idx_1 = index_array[i + 1];
+                idx_t idx_2 = index_array[i + 2];
+                idx_t idx_3 = index_array[i + 3];
+
+                float dp[4];
+                flat_codes_qdis->partial_dot_product_batch_4(
+                        idx_0,
+                        idx_1,
+                        idx_2,
+                        idx_3,
+                        dp[0],
+                        dp[1],
+                        dp[2],
+                        dp[3],
+                        start_dim,
+                        end_dim - start_dim);
+                ndis += 4;
+
+                float new_exact_0 = exact_distances[i + 0] - 2 * dp[0];
+                float new_exact_1 = exact_distances[i + 1] - 2 * dp[1];
+                float new_exact_2 = exact_distances[i + 2] - 2 * dp[2];
+                float new_exact_3 = exact_distances[i + 3] - 2 * dp[3];
+
+                float cum_sum_0 = panorama_index->get_cum_sum(
+                        idx_0)[curr_panorama_level + 1];
+                float cum_sum_1 = panorama_index->get_cum_sum(
+                        idx_1)[curr_panorama_level + 1];
+                float cum_sum_2 = panorama_index->get_cum_sum(
+                        idx_2)[curr_panorama_level + 1];
+                float cum_sum_3 = panorama_index->get_cum_sum(
+                        idx_3)[curr_panorama_level + 1];
+
+                float cs_bound_0 = 2.0f * cum_sum_0 * query_cum_norm;
+                float cs_bound_1 = 2.0f * cum_sum_1 * query_cum_norm;
+                float cs_bound_2 = 2.0f * cum_sum_2 * query_cum_norm;
+                float cs_bound_3 = 2.0f * cum_sum_3 * query_cum_norm;
+
+                float lower_bound_0 = new_exact_0 - cs_bound_0;
+                float lower_bound_1 = new_exact_1 - cs_bound_1;
+                float lower_bound_2 = new_exact_2 - cs_bound_2;
+                float lower_bound_3 = new_exact_3 - cs_bound_3;
+
+                // The following code is not the most branch friendly (due to
+                // the maintenance of the candidate heap), but micro-benchmarks
+                // have shown that it is not worth it to write horrible code to
+                // squeeze out those cycles.
+                if (lower_bound_0 <= threshold) {
+                    exact_distances[next_batch_size] = new_exact_0;
+                    index_array[next_batch_size] = idx_0;
+                    next_batch_size += 1;
+                } else {
+                    candidates.push(idx_0, new_exact_0);
+                }
+                if (lower_bound_1 <= threshold) {
+                    exact_distances[next_batch_size] = new_exact_1;
+                    index_array[next_batch_size] = idx_1;
+                    next_batch_size += 1;
+                } else {
+                    candidates.push(idx_1, new_exact_1);
+                }
+                if (lower_bound_2 <= threshold) {
+                    exact_distances[next_batch_size] = new_exact_2;
+                    index_array[next_batch_size] = idx_2;
+                    next_batch_size += 1;
+                } else {
+                    candidates.push(idx_2, new_exact_2);
+                }
+                if (lower_bound_3 <= threshold) {
+                    exact_distances[next_batch_size] = new_exact_3;
+                    index_array[next_batch_size] = idx_3;
+                    next_batch_size += 1;
+                } else {
+                    candidates.push(idx_3, new_exact_3);
+                }
+            }
+
+            // Process the remaining candidates.
+            for (; i < batch_size; i++) {
+                idx_t idx = index_array[i];
+
+                float dp = flat_codes_qdis->partial_dot_product(
+                        idx, start_dim, end_dim - start_dim);
+                ndis += 1;
+                float new_exact = exact_distances[i] - 2.0f * dp;
+
+                float cum_sum = panorama_index->get_cum_sum(
+                        idx)[curr_panorama_level + 1];
+                float cs_bound = 2.0f * cum_sum * query_cum_norm;
+                float lower_bound = new_exact - cs_bound;
+
+                if (lower_bound <= threshold) {
+                    exact_distances[next_batch_size] = new_exact;
+                    index_array[next_batch_size] = idx;
+                    next_batch_size += 1;
+                } else {
+                    candidates.push(idx, new_exact);
+                }
+            }
+
+            batch_size = next_batch_size;
+            curr_panorama_level++;
+        }
+
+        // Add surviving candidates to the result handler.
+        for (size_t i = 0; i < batch_size; i++) {
+            idx_t idx = index_array[i];
+            if (res.add_result(exact_distances[i], idx)) {
+                nres += 1;
+            }
+            candidates.push(idx, exact_distances[i]);
+        }
+
+        nstep++;
+        if (!do_dis_check && nstep > efSearch) {
+            break;
+        }
+    }
+
+    if (level == 0) {
+        stats.n1++;
+        if (candidates.size() == 0) {
+            stats.n2++;
+        }
+        stats.ndis += ndis;
+        stats.nhops += nstep;
+    }
+
+    return nres;
+}
+
 std::priority_queue<HNSW::Node> search_from_candidate_unbounded(
         const HNSW& hnsw,
         const Node& node,
@@ -936,6 +1199,7 @@ int extract_k_from_ResultHandler(ResultHandler<C>& res) {
 
 HNSWStats HNSW::search(
         DistanceComputer& qdis,
+        const IndexHNSW* index,
         ResultHandler<C>& res,
         VisitedTable& vt,
         const SearchParameters* params) const {
@@ -966,13 +1230,28 @@ HNSWStats HNSW::search(
     }
 
     int ef = std::max(efSearch, k);
-    if (bounded_queue) { // this is the most common branch
+    if (bounded_queue) { // this is the most common branch, for now we only
+                         // support Panorama search in this branch
         MinimaxHeap candidates(ef);
 
         candidates.push(nearest, d_nearest);
 
-        search_from_candidates(
-                *this, qdis, res, candidates, vt, stats, 0, 0, params);
+        if (!is_panorama) {
+            search_from_candidates(
+                    *this, qdis, res, candidates, vt, stats, 0, 0, params);
+        } else {
+            search_from_candidates_panorama(
+                    *this,
+                    index,
+                    qdis,
+                    res,
+                    candidates,
+                    vt,
+                    stats,
+                    0,
+                    0,
+                    params);
+        }
     } else {
         std::priority_queue<Node> top_candidates =
                 search_from_candidate_unbounded(

data/vendor/faiss/faiss/impl/HNSW.h

@@ -8,12 +8,12 @@
 #pragma once
 
 #include <queue>
-#include <unordered_set>
 #include <vector>
 
 #include <omp.h>
 
 #include <faiss/Index.h>
+#include <faiss/impl/DistanceComputer.h>
 #include <faiss/impl/FaissAssert.h>
 #include <faiss/impl/maybe_owned_vector.h>
 #include <faiss/impl/platform_macros.h>
@@ -22,6 +22,10 @@
 
 namespace faiss {
 
+// Forward declarations to avoid circular dependency.
+struct IndexHNSW;
+struct IndexHNSWFlatPanorama;
+
 /** Implementation of the Hierarchical Navigable Small World
  * datastructure.
  *
@@ -31,7 +35,7 @@ namespace faiss {
  *  Yu. A. Malkov, D. A. Yashunin, arXiv 2017
  *
  * This implementation is heavily influenced by the NMSlib
- * implementation by Yury Malkov and Leonid Boystov
+ * implementation by Yury Malkov and Leonid Boytsov
  * (https://github.com/searchivarius/nmslib)
  *
  * The HNSW object stores only the neighbor link structure, see
@@ -61,7 +65,7 @@ struct HNSW {
 
     typedef std::pair<float, storage_idx_t> Node;
 
-    /** Heap structure that allows fast
+    /** Heap structure that allows fast access and updates.
      */
     struct MinimaxHeap {
         int n;
@@ -87,7 +91,7 @@ struct HNSW {
         int count_below(float thresh);
     };
 
-    /// to sort pairs of (id, distance) from nearest to fathest or the reverse
+    /// to sort pairs of (id, distance) from nearest to farthest or the reverse
     struct NodeDistCloser {
         float d;
         int id;
@@ -146,6 +150,9 @@ struct HNSW {
     /// use bounded queue during exploration
     bool search_bounded_queue = true;
 
+    /// use Panorama progressive pruning in search
+    bool is_panorama = false;
+
     // methods that initialize the tree sizes
 
     /// initialize the assign_probas and cum_nneighbor_per_level to
@@ -160,7 +167,7 @@ struct HNSW {
     /// nb of neighbors for this level
     int nb_neighbors(int layer_no) const;
 
-    /// cumumlative nb up to (and excluding) this level
+    /// cumulative nb up to (and excluding) this level
     int cum_nb_neighbors(int layer_no) const;
 
     /// range of entries in the neighbors table of vertex no at layer_no
@@ -196,9 +203,15 @@ struct HNSW {
             VisitedTable& vt,
             bool keep_max_size_level0 = false);
 
-    /// search interface for 1 point, single thread
+    /// Search interface for 1 point, single thread
+    ///
+    /// NOTE: We pass a reference to the index itself to allow for additional
+    /// state information to be passed (used for Panorama progressive pruning).
+    /// The alternative would be to override both HNSW::search and
+    /// HNSWIndex::search, which would be a nuisance of code duplication.
     HNSWStats search(
             DistanceComputer& qdis,
+            const IndexHNSW* index,
             ResultHandler<C>& res,
             VisitedTable& vt,
             const SearchParameters* params = nullptr) const;
@@ -267,6 +280,22 @@ int search_from_candidates(
         int nres_in = 0,
         const SearchParameters* params = nullptr);
 
+/// Equivalent to `search_from_candidates`, but applies pruning with progressive
+/// refinement bounds.
+/// This is used in `IndexHNSWFlatPanorama` to improve the search performance
+/// for higher dimensional vectors.
+int search_from_candidates_panorama(
+        const HNSW& hnsw,
+        const IndexHNSW* index,
+        DistanceComputer& qdis,
+        ResultHandler<HNSW::C>& res,
+        HNSW::MinimaxHeap& candidates,
+        VisitedTable& vt,
+        HNSWStats& stats,
+        int level,
+        int nres_in = 0,
+        const SearchParameters* params = nullptr);
+
 HNSWStats greedy_update_nearest(
         const HNSW& hnsw,
         DistanceComputer& qdis,

data/vendor/faiss/faiss/impl/IDSelector.cpp

@@ -31,7 +31,7 @@ void IDSelectorRange::find_sorted_ids_bounds(
         *jmin_out = *jmax_out = 0;
         return;
     }
-    // bissection to find imin
+    // bisection to find imin
     if (ids[0] >= imin) {
         *jmin_out = 0;
     } else {
@@ -46,7 +46,7 @@ void IDSelectorRange::find_sorted_ids_bounds(
         }
         *jmin_out = j1;
     }
-    // bissection to find imax
+    // bisection to find imax
     if (*jmin_out == list_size || ids[*jmin_out] >= imax) {
         *jmax_out = *jmin_out;
     } else {