faiss 0.6.1 → 0.6.3

data/vendor/faiss/faiss/impl/ScalarQuantizer.h

@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <cstring>
+
 #include <faiss/impl/AuxIndexStructures.h>
 #include <faiss/impl/DistanceComputer.h>
 #include <faiss/impl/Quantizer.h>
@@ -39,6 +41,18 @@ struct ScalarQuantizer : Quantizer {
         QT_3bit_tqmse, ///< TurboQuant MSE-optimized, 3 bits per component
         QT_4bit_tqmse, ///< TurboQuant MSE-optimized, 4 bits per component
         QT_8bit_tqmse, ///< TurboQuant MSE-optimized, 8 bits per component
+        QT_2bit_tq,    ///< Full TurboQuant (1-bit MSE + 1-bit QJL + factors)
+        QT_3bit_tq,    ///< Full TurboQuant (2-bit MSE + 1-bit QJL + factors)
+        QT_4bit_tq,    ///< Full TurboQuant (3-bit MSE + 1-bit QJL + factors)
+        QT_5bit_tq,    ///< Full TurboQuant (4-bit MSE + 1-bit QJL + factors)
+        QT_1bit_eden,  ///< EDEN Lloyd-Max scalar code, 1 bit per component
+        QT_2bit_eden,  ///< EDEN Lloyd-Max scalar code, 2 bits per component
+        QT_3bit_eden,  ///< EDEN Lloyd-Max scalar code, 3 bits per component
+        QT_4bit_eden,  ///< EDEN Lloyd-Max scalar code, 4 bits per component
+        QT_5bit_eden,  ///< EDEN Lloyd-Max scalar code, 5 bits per component
+        QT_6bit_eden,  ///< EDEN Lloyd-Max scalar code, 6 bits per component
+        QT_7bit_eden,  ///< EDEN Lloyd-Max scalar code, 7 bits per component
+        QT_8bit_eden,  ///< EDEN Lloyd-Max scalar code, 8 bits per component
         QT_count
     };
 
@@ -129,8 +143,64 @@ struct ScalarQuantizer : Quantizer {
         float distance_to_code(const uint8_t* code) final {
             return query_to_code(code);
         }
+
+        void distance_to_code_batch_4(
+                const uint8_t* c1,
+                const uint8_t* c2,
+                const uint8_t* c3,
+                const uint8_t* c4,
+                float& d1,
+                float& d2,
+                float& d3,
+                float& d4) override {
+            query_to_codes_batch_4(c1, c2, c3, c4, d1, d2, d3, d4);
+        }
+    };
+
+    /// TurboQuant full (QT_*_tq) refinement state, isolated from the
+    /// main ScalarQuantizer to avoid polluting it with TQ-specific data.
+    struct TurboQuantRefine {
+        static bool is_turboq_full(QuantizerType qt) {
+            return qt >= QT_2bit_tq && qt <= QT_5bit_tq;
+        }
+
+        static void pack_seed(uint64_t seed, float out[2]) {
+            static_assert(sizeof(uint64_t) == 2 * sizeof(float));
+            std::memcpy(out, &seed, sizeof(uint64_t));
+        }
+
+        static uint64_t unpack_seed(float lo, float hi) {
+            float tmp[2] = {lo, hi};
+            uint64_t s;
+            static_assert(sizeof(uint64_t) == 2 * sizeof(float));
+            std::memcpy(&s, tmp, sizeof(uint64_t));
+            return s;
+        }
+
+        uint8_t qjl_type = 0;
+        uint64_t seed = 42;
+        size_t padded_d = 0;
+        std::vector<float> fwht_signs;
+        std::vector<float> rr_matrix;
+        size_t nb_bits_lo = 0;
+        size_t n_hi_dims = 0;
+
+        void init_projection(size_t d);
+        bool use_fwht() const {
+            return qjl_type == 0;
+        }
+
+        struct DistanceComputer : SQDistanceComputer {
+            virtual void configure(uint8_t qb, bool int_qjl) = 0;
+            virtual void set_prescreen_threshold(
+                    const float* t,
+                    bool minimize) = 0;
+            virtual void clear_prescreen_threshold() = 0;
+        };
     };
 
+    TurboQuantRefine turboq_refine;
+
     SQDistanceComputer* get_distance_computer(
             MetricType metric = METRIC_L2) const;
 

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

@@ -70,8 +70,8 @@ void ThreadedIndex<IndexT>::addIndex(IndexT* index) {
 
         // Make sure this index is not duplicated
         for (auto& p : indices_) {
-            FAISS_THROW_IF_NOT_MSG(
-                    p.first != index,
+            FAISS_THROW_IF_MSG(
+                    p.first == index,
                     "addIndex: attempting to add index "
                     "that is already in the collection");
         }

data/vendor/faiss/faiss/impl/VisitedTable.cpp

@@ -15,22 +15,42 @@ namespace faiss {
 // advance() is O(1) except every 250 calls, which are O(size).
 // The hash set strategy is a constant factor slower for get()/set(),
 // but O(1) to construct and O(visits) to advance.
-// A size of ~1M seems to be the threshold where the hash set wins.
-size_t visited_table_hashset_threshold = 500000;
-
-VisitedTable::VisitedTable(size_t size, std::optional<bool> use_hashset)
-        : visno(use_hashset.value_or(size >= visited_table_hashset_threshold)
-                        ? 0
-                        : 1) {
-    if (visno != 0) {
-        visited.resize(size, 0);
+// 10M is only a current estimated threshold, not a proven crossover: we are not
+// sure the array still wins at 10M. The point where the array stops paying off
+// varies by dataset (it shifts with dimension, working-set / cache pressure,
+// etc.), so this is a coarse default that should eventually be replaced by
+// smarter per-index tuning.
+size_t visited_table_hashset_threshold = 10000000;
+
+std::unique_ptr<VisitedTable> VisitedTable::create(
+        size_t size,
+        std::optional<bool> use_hashset) {
+    bool use_set =
+            use_hashset.value_or(size >= visited_table_hashset_threshold);
+    if (use_set) {
+        return std::make_unique<VisitedTableSet>();
+    }
+    return std::make_unique<VisitedTableVector>(size);
+}
+
+VisitedTable& VisitedTable::get_reusable(
+        size_t size,
+        std::optional<bool> use_hashset) {
+    bool use_set =
+            use_hashset.value_or(size >= visited_table_hashset_threshold);
+    if (use_set) {
+        thread_local VisitedTableSet tls_set;
+        tls_set.advance();
+        return tls_set;
     }
+    thread_local VisitedTableVector tls_vec(0);
+    tls_vec.ensure_size(size);
+    tls_vec.advance();
+    return tls_vec;
 }
 
-void VisitedTable::advance() {
-    if (visno == 0) {
-        visited_set.clear();
-    } else if (visno < 254) {
+void VisitedTableVector::advance() {
+    if (visno < 254) {
         // 254 rather than 255 because sometimes we use visno and visno+1
         ++visno;
     } else {

data/vendor/faiss/faiss/impl/VisitedTable.h

@@ -10,6 +10,7 @@
 
 #include <stdint.h>
 
+#include <memory>
 #include <optional>
 #include <unordered_set>
 #include <vector>
@@ -21,54 +22,108 @@ namespace faiss {
 
 FAISS_API extern size_t visited_table_hashset_threshold;
 
-/// A fast, reusable Visited Set for graph search algorithms.
+/// Abstract base class for a fast, reusable Visited Set for graph search
+/// algorithms.
 struct VisitedTable {
-    std::vector<uint8_t> visited;
-    std::unordered_set<size_t> visited_set;
-    uint8_t visno; // 0 if using visited_set, 1..250 if using vector.
+    virtual ~VisitedTable() = default;
+
+    /// set flag #no to true, return whether this changed it.
+    virtual bool set(size_t no) = 0;
+
+    /// get flag #no
+    virtual bool get(size_t no) const = 0;
+
+    /// prefetch flag #no
+    virtual void prefetch(size_t no) const = 0;
+
+    /// pre-allocate bucket space to avoid rehashing during repeated set() calls
+    virtual void reserve(size_t /*n*/) {}
+
+    /// reset all flags to false
+    virtual void advance() = 0;
 
-    // If use_hashset is nullopt, the use of a hashset will be determined by
-    // size >= visited_table_hashset_threshold.
-    explicit VisitedTable(
+    /// Factory method to create appropriate implementation.
+    /// If use_hashset is nullopt, the use of a hashset will be determined by
+    /// size >= visited_table_hashset_threshold.
+    static std::unique_ptr<VisitedTable> create(
             size_t size,
             std::optional<bool> use_hashset = std::nullopt);
 
-    /// set flag #no to true, return whether this changed it.
-    bool set(size_t no) {
-        if (visno == 0) {
-            return visited_set.insert(no).second;
-        } else if (visited[no] == visno) {
-            return false;
-        } else {
-            visited[no] = visno;
-            return true;
-        }
+    /// Returns a thread-local, reusable table sized for at least `size` and
+    /// reset to a clean state. Unlike create(), it does not allocate on each
+    /// call: the O(size) versioned array is allocated once per thread and
+    /// reused across searches, avoiding a per-search alloc+zero of the whole
+    /// array when a static index is searched repeatedly.
+    ///
+    /// The returned reference is owned by thread-local storage: do not delete
+    /// it and do not use it beyond the current search on the calling thread.
+    static VisitedTable& get_reusable(
+            size_t size,
+            std::optional<bool> use_hashset = std::nullopt);
+};
+
+/// Set-based implementation using unordered_set.
+/// O(1) to construct and O(visits) to advance.
+struct VisitedTableSet FAISS_FINAL : VisitedTable {
+    std::unordered_set<size_t> visited_set;
+
+    VisitedTableSet() = default;
+
+    bool set(size_t no) final {
+        return visited_set.insert(no).second;
     }
 
-    /// pre-allocate bucket space to avoid rehashing during repeated set() calls
-    void reserve(size_t n) {
-        if (visno == 0) {
-            visited_set.reserve(n);
-        }
+    bool get(size_t no) const final {
+        return visited_set.count(no) != 0;
     }
 
-    /// get flag #no
-    bool get(size_t no) const {
-        if (visno == 0) {
-            return visited_set.count(no) != 0;
-        } else {
-            return visited[no] == visno;
+    void prefetch(size_t /*no*/) const final {
+        // No-op for set-based implementation
+    }
+
+    void reserve(size_t n) final {
+        visited_set.reserve(n);
+    }
+
+    void advance() final {
+        visited_set.clear();
+    }
+};
+
+/// Vector-based implementation using a versioned byte array.
+/// Faster for get()/set(), but O(size) to initialize.
+/// advance() is O(1) except every 250 calls, which are O(size).
+struct VisitedTableVector FAISS_FINAL : VisitedTable {
+    std::vector<uint8_t> visited;
+    uint8_t visno{1}; // Version number, 1..254
+
+    explicit VisitedTableVector(size_t size) : visited(size, 0) {}
+
+    /// Grow so indices in [0, size) are valid; new slots read as unvisited.
+    /// Never shrinks, so capacity is retained when the table is reused.
+    void ensure_size(size_t size) {
+        if (visited.size() < size) {
+            visited.resize(size, 0);
         }
     }
 
-    void prefetch(size_t no) const {
-        if (visno != 0) {
-            prefetch_L2(&visited[no]);
+    bool set(size_t no) final {
+        if (visited[no] == visno) {
+            return false;
         }
+        visited[no] = visno;
+        return true;
     }
 
-    /// reset all flags to false
-    void advance();
+    bool get(size_t no) const final {
+        return visited[no] == visno;
+    }
+
+    void prefetch(size_t no) const final {
+        prefetch_L2(&visited[no]);
+    }
+
+    void advance() final;
 };
 
 } // namespace faiss

data/vendor/faiss/faiss/impl/binary_hamming/IndexBinaryIVF_impl.h

@@ -292,7 +292,7 @@ void search_knn_hamming_per_invlist(
     nprobe = std::min((idx_t)ivf->nlist, nprobe);
     idx_t max_codes = params ? params->max_codes : ivf->max_codes;
     FAISS_THROW_IF_NOT(max_codes == 0);
-    FAISS_THROW_IF_NOT(!store_pairs);
+    FAISS_THROW_IF_MSG(store_pairs, "store_pairs is not supported here");
 
     // reorder buckets
     std::vector<int64_t> lims(n + 1);

data/vendor/faiss/faiss/impl/binary_hamming/avx2.cpp

@@ -9,17 +9,17 @@
 
 #define THE_SIMD_LEVEL SIMDLevel::AVX2
 
-// NOLINTNEXTLINE(facebook-hte-InlineHeader)
+// NOLINTNEXTLINE(facebook-hte-InlineHeader,facebook-unused-include-check)
 #include <faiss/utils/hamming_distance/hamming_computer-avx2.h>
 
 // NOLINTNEXTLINE(facebook-hte-InlineHeader)
-#include <faiss/impl/binary_hamming/IndexBinaryHNSW_impl.h>
+#include <faiss/impl/binary_hamming/IndexBinaryHNSW_impl.h> // IWYU pragma: keep
 // NOLINTNEXTLINE(facebook-hte-InlineHeader)
-#include <faiss/impl/binary_hamming/IndexBinaryHash_impl.h>
+#include <faiss/impl/binary_hamming/IndexBinaryHash_impl.h> // IWYU pragma: keep
 // NOLINTNEXTLINE(facebook-hte-InlineHeader)
 #include <faiss/impl/binary_hamming/IndexBinaryIVF_impl.h>
 // NOLINTNEXTLINE(facebook-hte-InlineHeader)
-#include <faiss/impl/binary_hamming/IndexIVFSpectralHash_impl.h>
+#include <faiss/impl/binary_hamming/IndexIVFSpectralHash_impl.h> // IWYU pragma: keep
 // NOLINTNEXTLINE(facebook-hte-InlineHeader)
 #include <faiss/impl/binary_hamming/IndexPQ_impl.h>
 

data/vendor/faiss/faiss/impl/fast_scan/dispatching.h

@@ -33,6 +33,7 @@
 
 #include <faiss/impl/fast_scan/accumulate_loops.h>
 #include <faiss/impl/fast_scan/fast_scan.h>
+#include <faiss/utils/simd_levels.h>
 
 #if defined(COMPILE_SIMD_AVX512) && defined(__AVX512F__)
 #include <faiss/impl/fast_scan/accumulate_loops_512.h>
@@ -48,7 +49,9 @@ using namespace simd_result_handlers;
  * so callers don't need to know the handler type.
  ***************************************************************/
 
-template <class Handler>
+// SIMDLevel SL = THE_LEVEL_TO_DISPATCH added to make the mangled
+// symbol name unique per translation unit.
+template <class Handler, SIMDLevel SL = THE_LEVEL_TO_DISPATCH>
 struct ScannerMixIn : FastScanCodeScanner {
     Handler handler_;
 
@@ -112,8 +115,40 @@ struct ScannerMixIn : FastScanCodeScanner {
         constexpr bool use_avx512_qbs = false;
 #endif
         if constexpr (use_avx512_qbs) {
-            // Use 512-bit QBS kernels with properly-leveled scalers.
-            if (pq2x4_scale) {
+            // AMD Zen 4 / Zen 4c ("Bergamo", family 0x19) split 512-bit
+            // ops over a 256-bit datapath, so the 512-bit QBS kernel yields no
+            // throughput gain but pays extra per-block LUT-assembly and
+            // cross-lane reduction overhead (measured ~14% search regression
+            // for PQ8x4fs / PQ16x4fs). Route those CPUs to the 256-bit (AVX2)
+            // QBS kernel instead -- same output, no downside on Zen 4. This is
+            // a process-constant runtime branch, hoisted out of the inner
+            // accumulate loop. Intel AVX-512 keeps the 512-bit kernel.
+            if (SIMDConfig::avx512_split) {
+                if (pq2x4_scale) {
+                    NormTableScaler<SIMDLevel::AVX2> scaler(pq2x4_scale);
+                    pq4_accumulate_loop_qbs_fixed_scaler_256<SIMDLevel::AVX2>(
+                            qbs,
+                            nb,
+                            nsq,
+                            codes,
+                            LUT,
+                            handler_,
+                            scaler,
+                            block_stride);
+                } else {
+                    DummyScaler<SIMDLevel::AVX2> dummy;
+                    pq4_accumulate_loop_qbs_fixed_scaler_256<SIMDLevel::AVX2>(
+                            qbs,
+                            nb,
+                            nsq,
+                            codes,
+                            LUT,
+                            handler_,
+                            dummy,
+                            block_stride);
+                }
+            } else if (pq2x4_scale) {
+                // Use 512-bit QBS kernels with properly-leveled scalers.
                 NormTableScaler<THE_LEVEL_TO_DISPATCH> scaler(pq2x4_scale);
                 pq4_accumulate_loop_qbs_fixed_scaler_512(
                         qbs,

data/vendor/faiss/faiss/impl/hnsw/LockVector.cpp

@@ -30,7 +30,7 @@ void LockVector::prepare(size_t new_size) {
         // Just destroy old and init fresh; omp_lock_t is not copyable.
         clear();
         data_ = static_cast<omp_lock_t*>(malloc(new_cap * sizeof(omp_lock_t)));
-        FAISS_THROW_IF_NOT(data_ != nullptr);
+        FAISS_THROW_IF_NOT(data_);
         capacity_ = new_cap;
     }
     for (size_t i = size_; i < new_size; i++) {

data/vendor/faiss/faiss/impl/hnsw/MinimaxHeap.cpp

@@ -5,39 +5,32 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-#include <cmath>
-
 #include <faiss/impl/hnsw/MinimaxHeap.h>
 
-#include <cassert>
-
 #include <faiss/impl/simd_dispatch.h>
 
 namespace faiss {
 
-void MinimaxHeap::push(storage_idx_t i, float v) {
-    // Treat NaN distances as infinitely far away so heap ordering is preserved.
-    if (std::isnan(v)) {
-        v = HC::neutral();
-    }
-    if (k == n) {
-        if (v >= dis[0]) {
-            return;
-        }
-        if (ids[0] != -1) {
-            --nvalid;
-        }
-        faiss::heap_pop<HC>(k--, dis.data(), ids.data());
-    }
-    faiss::heap_push<HC>(++k, dis.data(), ids.data(), v, i);
-    ++nvalid;
+// Runtime-dispatched pop_min (NONE + AVX2 + AVX512 only).
+constexpr int MINIMAX_HEAP_SIMD_LEVELS = (1 << int(SIMDLevel::NONE)) |
+        (1 << int(SIMDLevel::AVX2)) | (1 << int(SIMDLevel::AVX512));
+
+template <class HC_>
+int MinimaxHeapT<HC_>::pop_min(float* vmin_out) {
+    return with_selected_simd_levels<MINIMAX_HEAP_SIMD_LEVELS>(
+            [&]<SIMDLevel SL>() {
+                return pop_min_tpl<HC_, SL>(this, vmin_out);
+            });
 }
 
-// Scalar (NONE) specialization of pop_min_tpl
-template <>
-int MinimaxHeap::pop_min_tpl<SIMDLevel::NONE>(float* vmin_out) {
+// Primary-template scalar implementation. Used directly when SL==NONE
+template <class HC>
+int pop_min_simd_none(MinimaxHeapT<HC>* heap, float* vmin_out) {
+    int k = heap->k;
+    int* ids = heap->ids.data();
+    float* dis = heap->dis.data();
     assert(k > 0);
-    // returns min. This is an O(n) operation
+    // Returns the "best" entry. This is an O(n) operation.
     int i = k - 1;
     while (i >= 0) {
         if (ids[i] != -1) {
@@ -52,7 +45,8 @@ int MinimaxHeap::pop_min_tpl<SIMDLevel::NONE>(float* vmin_out) {
     float vmin = dis[i];
     i--;
     while (i >= 0) {
-        if (ids[i] != -1 && dis[i] < vmin) {
+        // HC::cmp(vmin, dis[i]) → "dis[i] is better than vmin".
+        if (ids[i] != -1 && HC::cmp(vmin, dis[i])) {
             vmin = dis[i];
             imin = i;
         }
@@ -63,29 +57,27 @@ int MinimaxHeap::pop_min_tpl<SIMDLevel::NONE>(float* vmin_out) {
     }
     int ret = ids[imin];
     ids[imin] = -1;
-    --nvalid;
-
+    --heap->nvalid;
     return ret;
 }
 
-// Runtime-dispatched pop_min (NONE + AVX2 + AVX512 only)
-constexpr int MINIMAX_HEAP_SIMD_LEVELS = (1 << int(SIMDLevel::NONE)) |
-        (1 << int(SIMDLevel::AVX2)) | (1 << int(SIMDLevel::AVX512));
-
-int MinimaxHeap::pop_min(float* vmin_out) {
-    return with_selected_simd_levels<MINIMAX_HEAP_SIMD_LEVELS>(
-            [&]<SIMDLevel SL>() { return pop_min_tpl<SL>(vmin_out); });
+// declare for min and max heap at simd level NONE
+template <>
+int pop_min_tpl<CMin<float, int32_t>, SIMDLevel::NONE>(
+        MinimaxHeapT<CMin<float, int32_t>>* heap,
+        float* vmin_out) {
+    return pop_min_simd_none(heap, vmin_out);
 }
 
-int MinimaxHeap::count_below(float thresh) {
-    int n_below = 0;
-    for (int i = 0; i < k; i++) {
-        if (dis[i] < thresh) {
-            n_below++;
-        }
-    }
-
-    return n_below;
+template <>
+int pop_min_tpl<CMax<float, int32_t>, SIMDLevel::NONE>(
+        MinimaxHeapT<CMax<float, int32_t>>* heap,
+        float* vmin_out) {
+    return pop_min_simd_none(heap, vmin_out);
 }
 
+// Explicit instantiations of pop_min for the two HC variants
+template int MinimaxHeapT<CMax<float, int32_t>>::pop_min(float*);
+template int MinimaxHeapT<CMin<float, int32_t>>::pop_min(float*);
+
 } // namespace faiss

data/vendor/faiss/faiss/impl/hnsw/MinimaxHeap.h

@@ -7,21 +7,30 @@
 
 #pragma once
 
+#include <cassert>
+#include <cmath>
 #include <cstdint>
 #include <vector>
 
 #include <faiss/utils/Heap.h>
+#include <faiss/utils/ordered_key_value.h>
 #include <faiss/utils/simd_levels.h>
 
 namespace faiss {
 
 /** Heap structure that allows fast access and updates.
  *
- * Supports both max-heap operations (via the underlying CMax heap)
- * and efficient min extraction via linear scan (with optional SIMD
- * acceleration).
+ * Templated on the comparator HC_ so that the same data structure can
+ * service both distance-style searches (HC_ = CMax<float, int32_t>, smaller
+ * is better) and similarity-style searches (HC_ = CMin<float, int32_t>,
+ * larger is better). For the distance variant the underlying heap is a
+ * max-heap and "pop_min" returns the closest element; for similarity the
+ * underlying heap is a min-heap and "pop_min" returns the most similar
+ * element.
  */
-struct MinimaxHeap {
+template <class HC_ = CMax<float, int32_t>>
+struct MinimaxHeapT {
+    using HC = HC_;
     using storage_idx_t = int32_t;
 
     int n;
@@ -30,12 +39,34 @@ struct MinimaxHeap {
 
     std::vector<storage_idx_t> ids;
     std::vector<float> dis;
-    using HC = faiss::CMax<float, storage_idx_t>;
 
-    explicit MinimaxHeap(int n_in)
+    explicit MinimaxHeapT(int n_in)
             : n(n_in), k(0), nvalid(0), ids(n_in), dis(n_in) {}
 
-    void push(storage_idx_t i, float v);
+    void push(storage_idx_t i, float v) {
+        // Treat NaN distances as the "worst" value so heap ordering is
+        // preserved (insertion is then guaranteed to fall through the
+        // not-better-than-top early-reject branch when the heap is full).
+        if (std::isnan(v)) {
+            v = HC::neutral();
+        }
+        if (k == n) {
+            // top of the heap is the "worst" entry under HC. If the new
+            // value is not strictly better than the worst, drop it.
+            // HC::cmp(top, v) means "v is better than top" for both CMax
+            // (cmp = a > b → top > v → v < top) and CMin (cmp = a < b →
+            // top < v → v > top).
+            if (!HC::cmp(dis[0], v)) {
+                return;
+            }
+            if (ids[0] != -1) {
+                --nvalid;
+            }
+            faiss::heap_pop<HC>(k--, dis.data(), ids.data());
+        }
+        faiss::heap_push<HC>(++k, dis.data(), ids.data(), v, i);
+        ++nvalid;
+    }
 
     float max() const {
         return dis[0];
@@ -49,16 +80,34 @@ struct MinimaxHeap {
         nvalid = k = 0;
     }
 
-    /// SIMD-templated pop_min implementation.
-    /// Specializations exist for NONE, AVX2, and AVX512.
-    template <SIMDLevel SL>
-    int pop_min_tpl(float* vmin_out = nullptr);
-
-    /// Runtime-dispatched pop_min (calls pop_min_tpl with best available
-    /// SIMD level).
+    /// Runtime-dispatched best-element extraction (NONE + AVX2 + AVX512).
     int pop_min(float* vmin_out = nullptr);
 
-    int count_below(float thresh);
+    int count_below(float thresh) {
+        int n_below = 0;
+        for (int i = 0; i < k; i++) {
+            // Count entries that are strictly "better than" thresh.
+            // HC::cmp(thresh, dis[i]) → for CMax: thresh > dis[i]
+            // (i.e., dis[i] < thresh, the historical L2 semantics);
+            // for CMin: thresh < dis[i] (similarity above threshold).
+            if (HC::cmp(thresh, dis[i])) {
+                n_below++;
+            }
+        }
+        return n_below;
+    }
 };
 
+// Default `MinimaxHeap` keeps the historical max-heap semantics (smaller
+// distance is better). The CMin instantiation is used when the owning
+// HNSW has `is_similarity = true`. The alias itself is declared once,
+// alongside the forward declaration in HNSW.h, to avoid duplicate
+// `using` declarations that SWIG treats as redundant.
+
+// Forward declarations of the SIMD specializations. The actual bodies live
+// in the SIMD-specific translation units (avx2.cpp, avx512.cpp) and are
+// resolved at link time.
+template <class HC_, SIMDLevel SL>
+int pop_min_tpl(MinimaxHeapT<HC_>* heap, float* vmin_out);
+
 } // namespace faiss