faiss 0.4.3 → 0.5.1

data/vendor/faiss/faiss/invlists/DirectMap.cpp

@@ -53,7 +53,7 @@ void DirectMap::set_type(
             for (long ofs = 0; ofs < list_size; ofs++) {
                 FAISS_THROW_IF_NOT_MSG(
                         0 <= idlist[ofs] && idlist[ofs] < ntotal,
-                        "direct map supported only for seuquential ids");
+                        "direct map supported only for sequential ids");
                 array[idlist[ofs]] = lo_build(key, ofs);
             }
         } else if (new_type == Hashtable) {

data/vendor/faiss/faiss/invlists/InvertedLists.cpp

@@ -229,7 +229,7 @@ bool InvertedLists::is_empty(size_t list_no, void* inverted_list_context)
     }
 }
 
-// implemnent iterator on top of get_codes / get_ids
+// implement iterator on top of get_codes / get_ids
 namespace {
 
 struct CodeArrayIterator : InvertedListsIterator {
@@ -346,6 +346,120 @@ void ArrayInvertedLists::permute_invlists(const idx_t* map) {
 
 ArrayInvertedLists::~ArrayInvertedLists() {}
 
+/***********************************************
+ * ArrayInvertedListsPanorama implementation
+ **********************************************/
+
+ArrayInvertedListsPanorama::ArrayInvertedListsPanorama(
+        size_t nlist,
+        size_t code_size,
+        size_t n_levels)
+        : ArrayInvertedLists(nlist, code_size),
+          n_levels(n_levels),
+          level_width(
+                  (((code_size / sizeof(float)) + n_levels - 1) / n_levels) *
+                  sizeof(float)),
+          pano(code_size, n_levels, kBatchSize) {
+    FAISS_THROW_IF_NOT(n_levels > 0);
+    FAISS_THROW_IF_NOT(code_size % sizeof(float) == 0);
+    FAISS_THROW_IF_NOT_MSG(
+            !use_iterator,
+            "IndexIVFFlatPanorama does not support iterators, use vanilla IndexIVFFlat instead");
+    FAISS_ASSERT(level_width % sizeof(float) == 0);
+
+    cum_sums.resize(nlist);
+}
+
+const float* ArrayInvertedListsPanorama::get_cum_sums(size_t list_no) const {
+    assert(list_no < nlist);
+    return cum_sums[list_no].data();
+}
+
+size_t ArrayInvertedListsPanorama::add_entries(
+        size_t list_no,
+        size_t n_entry,
+        const idx_t* ids_in,
+        const uint8_t* code) {
+    assert(list_no < nlist);
+    size_t o = ids[list_no].size();
+
+    ids[list_no].resize(o + n_entry);
+    memcpy(&ids[list_no][o], ids_in, sizeof(ids_in[0]) * n_entry);
+
+    size_t new_size = o + n_entry;
+    size_t num_batches = (new_size + kBatchSize - 1) / kBatchSize;
+    codes[list_no].resize(num_batches * kBatchSize * code_size);
+    cum_sums[list_no].resize(num_batches * kBatchSize * (n_levels + 1));
+
+    // Cast to float* is safe here as we guarantee codes are always float
+    // vectors for `IndexIVFFlatPanorama` (verified by the constructor).
+    const float* vectors = reinterpret_cast<const float*>(code);
+    pano.copy_codes_to_level_layout(codes[list_no].data(), o, n_entry, code);
+    pano.compute_cumulative_sums(cum_sums[list_no].data(), o, n_entry, vectors);
+
+    return o;
+}
+
+void ArrayInvertedListsPanorama::update_entries(
+        size_t list_no,
+        size_t offset,
+        size_t n_entry,
+        const idx_t* ids_in,
+        const uint8_t* code) {
+    assert(list_no < nlist);
+    assert(n_entry + offset <= ids[list_no].size());
+
+    memcpy(&ids[list_no][offset], ids_in, sizeof(ids_in[0]) * n_entry);
+
+    // Cast to float* is safe here as we guarantee codes are always float
+    // vectors for `IndexIVFFlatPanorama` (verified by the constructor).
+    const float* vectors = reinterpret_cast<const float*>(code);
+    pano.copy_codes_to_level_layout(
+            codes[list_no].data(), offset, n_entry, code);
+    pano.compute_cumulative_sums(
+            cum_sums[list_no].data(), offset, n_entry, vectors);
+}
+
+void ArrayInvertedListsPanorama::resize(size_t list_no, size_t new_size) {
+    ids[list_no].resize(new_size);
+
+    size_t num_batches = (new_size + kBatchSize - 1) / kBatchSize;
+    codes[list_no].resize(num_batches * kBatchSize * code_size);
+    cum_sums[list_no].resize(num_batches * kBatchSize * (n_levels + 1));
+}
+
+const uint8_t* ArrayInvertedListsPanorama::get_single_code(
+        size_t list_no,
+        size_t offset) const {
+    assert(list_no < nlist);
+    assert(offset < ids[list_no].size());
+
+    uint8_t* recons_buffer = new uint8_t[code_size];
+
+    float* recons = reinterpret_cast<float*>(recons_buffer);
+    pano.reconstruct(offset, recons, codes[list_no].data());
+
+    return recons_buffer;
+}
+
+void ArrayInvertedListsPanorama::release_codes(
+        size_t list_no,
+        const uint8_t* codes) const {
+    // Only delete if it's heap-allocated (from get_single_code).
+    // If it's from get_codes (raw storage), it will be codes[list_no].data()
+    if (codes != this->codes[list_no].data()) {
+        delete[] codes;
+    }
+}
+
+InvertedListsIterator* ArrayInvertedListsPanorama::get_iterator(
+        size_t /* list_no */,
+        void* /* inverted_list_context */) const {
+    FAISS_THROW_MSG(
+            "IndexIVFFlatPanorama does not support iterators, use vanilla IndexIVFFlat instead");
+    return nullptr;
+}
+
 /*****************************************************************
  * Meta-inverted list implementations
  *****************************************************************/

data/vendor/faiss/faiss/invlists/InvertedLists.h

@@ -18,6 +18,7 @@
 #include <vector>
 
 #include <faiss/MetricType.h>
+#include <faiss/impl/Panorama.h>
 #include <faiss/impl/maybe_owned_vector.h>
 
 namespace faiss {
@@ -276,6 +277,51 @@ struct ArrayInvertedLists : InvertedLists {
     ~ArrayInvertedLists() override;
 };
 
+/// Level-oriented storage as defined in the IVFFlat section of Panorama
+/// (https://www.arxiv.org/pdf/2510.00566).
+struct ArrayInvertedListsPanorama : ArrayInvertedLists {
+    static constexpr size_t kBatchSize = 128;
+    std::vector<MaybeOwnedVector<float>> cum_sums;
+    const size_t n_levels;
+    const size_t level_width; // in code units
+    Panorama pano;
+
+    ArrayInvertedListsPanorama(size_t nlist, size_t code_size, size_t n_levels);
+
+    const float* get_cum_sums(size_t list_no) const;
+
+    size_t add_entries(
+            size_t list_no,
+            size_t n_entry,
+            const idx_t* ids,
+            const uint8_t* code) override;
+
+    void update_entries(
+            size_t list_no,
+            size_t offset,
+            size_t n_entry,
+            const idx_t* ids,
+            const uint8_t* code) override;
+
+    void resize(size_t list_no, size_t new_size) override;
+
+    /// Panorama's layout make it impractical to support iterators as defined
+    /// by Faiss (i.e. `InvertedListsIterator` API). The iterator would require
+    /// to allocate and reassemble the vector at each call.
+    /// Hence, we override this method to throw an error, this effectively
+    /// disables the `iterate_codes` and `iterate_codes_range` methods.
+    InvertedListsIterator* get_iterator(
+            size_t list_no,
+            void* inverted_list_context = nullptr) const override;
+
+    /// Reconstructs a single code from level-oriented storage to flat format.
+    const uint8_t* get_single_code(size_t list_no, size_t offset)
+            const override;
+
+    /// Frees codes returned by `get_single_code`.
+    void release_codes(size_t list_no, const uint8_t* codes) const override;
+};
+
 /*****************************************************************
  * Meta-inverted lists
  *

data/vendor/faiss/faiss/invlists/OnDiskInvertedLists.cpp

@@ -372,7 +372,7 @@ OnDiskInvertedLists::~OnDiskInvertedLists() {
     if (ptr != nullptr) {
         int err = munmap(ptr, totsize);
         if (err != 0) {
-            fprintf(stderr, "mumap error: %s", strerror(errno));
+            fprintf(stderr, "munmap error: %s", strerror(errno));
         }
     }
     delete locks;

data/vendor/faiss/faiss/invlists/OnDiskInvertedLists.h

@@ -121,7 +121,7 @@ struct OnDiskInvertedLists : InvertedLists {
 
     LockLevels* locks;
 
-    // encapsulates the threads that are busy prefeteching
+    // encapsulates the threads that are busy prefetching
     struct OngoingPrefetch;
     OngoingPrefetch* pf;
     int prefetch_nthread;

data/vendor/faiss/faiss/svs/IndexSVSFaissUtils.h

@@ -0,0 +1,261 @@
+/*
+ * Portions 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.
+ */
+
+/*
+ * Portions Copyright 2025 Intel Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <svs/runtime/api_defs.h>
+
+#include <faiss/Index.h>
+#include <faiss/MetricType.h>
+#include <faiss/impl/AuxIndexStructures.h>
+#include <faiss/impl/FaissAssert.h>
+#include <faiss/impl/IDSelector.h>
+
+#include <algorithm>
+#include <concepts>
+#include <memory>
+#include <span>
+#include <type_traits>
+#include <vector>
+
+// validate FAISS_SVS_RUNTIME_VERSION is set
+#ifndef FAISS_SVS_RUNTIME_VERSION
+#error "FAISS_SVS_RUNTIME_VERSION is not defined"
+#endif
+// create svs_runtime as alias for svs::runtime::FAISS_SVS_RUNTIME_VERSION
+SVS_RUNTIME_CREATE_API_ALIAS(svs_runtime, FAISS_SVS_RUNTIME_VERSION);
+
+// SVS forward declarations
+namespace svs {
+namespace runtime {
+inline namespace v0 {
+struct FlatIndex;
+struct VamanaIndex;
+struct DynamicVamanaIndex;
+struct LeanVecTrainingData;
+} // namespace v0
+} // namespace runtime
+} // namespace svs
+
+namespace faiss {
+
+inline svs_runtime::MetricType to_svs_metric(faiss::MetricType metric) {
+    switch (metric) {
+        case METRIC_INNER_PRODUCT:
+            return svs_runtime::MetricType::INNER_PRODUCT;
+        case METRIC_L2:
+            return svs_runtime::MetricType::L2;
+        default:
+            FAISS_ASSERT(!"not supported SVS distance");
+    }
+}
+
+struct FaissIDFilter : public svs_runtime::IDFilter {
+    FaissIDFilter(const faiss::IDSelector& sel) : selector(sel) {}
+
+    bool is_member(size_t id) const override {
+        return selector.is_member(static_cast<faiss::idx_t>(id));
+    }
+
+   private:
+    const faiss::IDSelector& selector;
+};
+
+inline std::unique_ptr<FaissIDFilter> make_faiss_id_filter(
+        const SearchParameters* params = nullptr) {
+    if (params && params->sel) {
+        return std::make_unique<FaissIDFilter>(*params->sel);
+    }
+    return nullptr;
+}
+
+template <typename T, typename U, typename = void>
+struct InputBufferConverter {
+    InputBufferConverter(std::span<const U> data = {}) : buffer(data.size()) {
+        FAISS_ASSERT(
+                !"InputBufferConverter: there is no suitable user code for this type conversion");
+        std::transform(
+                data.begin(), data.end(), buffer.begin(), [](const U& val) {
+                    return static_cast<T>(val);
+                });
+    }
+
+    operator T*() {
+        return buffer.data();
+    }
+    operator const T*() const {
+        return buffer.data();
+    }
+
+    operator std::span<T>() {
+        return buffer;
+    }
+    operator std::span<const T>() const {
+        return buffer;
+    }
+
+   private:
+    std::vector<T> buffer;
+};
+
+// Specialization for reinterpret cast when types are integral and have the same
+// size
+template <typename T, typename U>
+struct InputBufferConverter<
+        T,
+        U,
+        std::enable_if_t<
+                std::is_same_v<T, U> ||
+                (std::is_integral_v<T> && std::is_integral_v<U> &&
+                 sizeof(T) == sizeof(U))>> {
+    InputBufferConverter(std::span<const U> data = {}) : data_span(data) {}
+    operator T*() {
+        return reinterpret_cast<T*>(data_span.data());
+    }
+    operator const T*() const {
+        return reinterpret_cast<const T*>(data_span.data());
+    }
+    operator std::span<T>() {
+        return std::span<T>(
+                reinterpret_cast<T*>(data_span.data()), data_span.size());
+    }
+    operator std::span<const T>() const {
+        return std::span<const T>(
+                reinterpret_cast<const T*>(data_span.data()), data_span.size());
+    }
+
+   private:
+    std::span<const U> data_span;
+};
+
+template <typename T, typename U, typename = void>
+struct OutputBufferConverter {
+    OutputBufferConverter(std::span<U> data = {})
+            : data_span(data), buffer(data.size()) {
+        FAISS_ASSERT(
+                !"OutputBufferConverter: there is no suitable user code for this type conversion");
+    }
+
+    ~OutputBufferConverter() {
+        std::transform(
+                buffer.begin(),
+                buffer.end(),
+                data_span.begin(),
+                [](const T& val) { return static_cast<U>(val); });
+    }
+
+    operator T*() {
+        return buffer.data();
+    }
+    operator std::span<T>() {
+        return buffer;
+    }
+
+   private:
+    std::span<U> data_span;
+    std::vector<T> buffer;
+};
+
+// Specialization for reinterpret cast when types are integral and have the same
+// size
+template <typename T, typename U>
+struct OutputBufferConverter<
+        T,
+        U,
+        std::enable_if_t<
+                std::is_same_v<T, U> ||
+                (std::is_integral_v<T> && std::is_integral_v<U> &&
+                 sizeof(T) == sizeof(U))>> {
+    OutputBufferConverter(std::span<U> data = {}) : data_span(data) {}
+    operator T*() {
+        return reinterpret_cast<T*>(data_span.data());
+    }
+    operator std::span<T>() {
+        return std::span<T>(
+                reinterpret_cast<T*>(data_span.data()), data_span.size());
+    }
+
+   private:
+    std::span<U> data_span;
+};
+
+template <typename T, typename U>
+auto convert_input_buffer(std::span<const U> data) {
+    // Create temporary buffer and convert input data
+    // to target type T in the temporary buffer
+    // The temporary buffer will be destroyed
+    // when going out of scope
+    return InputBufferConverter<T, U>(data);
+}
+
+template <typename T, typename U>
+auto convert_input_buffer(const U* data, size_t size) {
+    return convert_input_buffer<T, U>(std::span<const U>(data, size));
+}
+
+// Output buffer conversion
+template <typename T, typename U>
+auto convert_output_buffer(std::span<U> data) {
+    // Create temporary buffer for output data
+    // The temporary buffer will be destroyed
+    // when going out of scope, copying back
+    // the converted data to original buffer
+    return OutputBufferConverter<T, U>(data);
+}
+
+template <typename T, typename U>
+auto convert_output_buffer(U* data, size_t size) {
+    return convert_output_buffer<T, U>(std::span<U>(data, size));
+}
+
+struct FaissResultsAllocator : public svs_runtime::ResultsAllocator {
+    FaissResultsAllocator(faiss::RangeSearchResult* result) : result(result) {
+        FAISS_ASSERT(result != nullptr);
+    }
+
+    svs_runtime::SearchResultsStorage allocate(
+            std::span<size_t> result_counts) const override {
+        FAISS_ASSERT(result != nullptr);
+        FAISS_ASSERT(result_counts.size() == result->nq);
+
+        // RangeSearchResult .ctor() allows unallocated lims
+        if (result->lims == nullptr) {
+            result->lims = new size_t[result->nq + 1];
+        }
+
+        std::copy(result_counts.begin(), result_counts.end(), result->lims);
+        result->do_allocation();
+        this->labels_converter = LabelsConverter{
+                std::span(result->labels, result->lims[result_counts.size()])};
+        return svs_runtime::SearchResultsStorage{
+                labels_converter,
+                std::span<float>(
+                        result->distances, result->lims[result_counts.size()])};
+    }
+
+   private:
+    faiss::RangeSearchResult* result;
+    using LabelsConverter = OutputBufferConverter<size_t, faiss::idx_t>;
+    mutable LabelsConverter labels_converter;
+};
+} // namespace faiss

data/vendor/faiss/faiss/svs/IndexSVSFlat.cpp

@@ -0,0 +1,117 @@
+/*
+ * Portions 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.
+ */
+
+/*
+ * Portions Copyright 2025 Intel Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <faiss/Index.h>
+#include <faiss/svs/IndexSVSFaissUtils.h>
+#include <faiss/svs/IndexSVSFlat.h>
+
+#include <svs/runtime/flat_index.h>
+
+#include <iostream>
+
+namespace faiss {
+
+IndexSVSFlat::IndexSVSFlat(idx_t d, MetricType metric) : Index(d, metric) {}
+
+IndexSVSFlat::~IndexSVSFlat() {
+    if (impl) {
+        auto status = svs_runtime::FlatIndex::destroy(impl);
+        FAISS_ASSERT(status.ok());
+        impl = nullptr;
+    }
+}
+
+void IndexSVSFlat::add(idx_t n, const float* x) {
+    if (!impl) {
+        create_impl();
+    }
+
+    auto status = impl->add(n, x);
+    if (!status.ok()) {
+        FAISS_THROW_MSG(status.message());
+    }
+    ntotal += n;
+}
+
+void IndexSVSFlat::reset() {
+    if (impl) {
+        auto status = impl->reset();
+        if (!status.ok()) {
+            FAISS_THROW_MSG(status.message());
+        }
+    }
+    ntotal = 0;
+}
+
+void IndexSVSFlat::search(
+        idx_t n,
+        const float* x,
+        idx_t k,
+        float* distances,
+        idx_t* labels,
+        const SearchParameters* params) const {
+    FAISS_THROW_IF_NOT(impl);
+    auto status = impl->search(
+            n,
+            x,
+            static_cast<size_t>(k),
+            distances,
+            reinterpret_cast<size_t*>(labels));
+    if (!status.ok()) {
+        FAISS_THROW_MSG(status.message());
+    }
+}
+
+/* Initializes the implementation*/
+void IndexSVSFlat::create_impl() {
+    FAISS_ASSERT(impl == nullptr);
+    auto svs_metric = to_svs_metric(metric_type);
+    auto status = svs_runtime::FlatIndex::build(&impl, d, svs_metric);
+    if (!status.ok()) {
+        FAISS_THROW_MSG(status.message());
+    }
+    FAISS_THROW_IF_NOT(impl);
+}
+
+/* Serialization */
+void IndexSVSFlat::serialize_impl(std::ostream& out) const {
+    FAISS_THROW_IF_NOT_MSG(
+            impl, "Cannot serialize: SVS index not initialized.");
+
+    auto status = impl->save(out);
+    if (!status.ok()) {
+        FAISS_THROW_MSG(status.message());
+    }
+}
+
+void IndexSVSFlat::deserialize_impl(std::istream& in) {
+    FAISS_THROW_IF_MSG(impl, "Cannot deserialize: SVS index already loaded.");
+    auto metric = to_svs_metric(metric_type);
+    auto status = impl->load(&impl, in, metric);
+    if (!status.ok()) {
+        FAISS_THROW_MSG(status.message());
+    }
+    FAISS_THROW_IF_NOT(impl);
+}
+
+} // namespace faiss

data/vendor/faiss/faiss/svs/IndexSVSFlat.h

@@ -0,0 +1,66 @@
+/*
+ * Portions 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.
+ */
+
+/*
+ * Portions Copyright 2025 Intel Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <faiss/Index.h>
+#include <faiss/svs/IndexSVSFaissUtils.h>
+
+#include <iostream>
+
+namespace faiss {
+
+struct IndexSVSFlat : Index {
+    // sequential labels
+    size_t nlabels{0};
+
+    IndexSVSFlat() = default;
+    IndexSVSFlat(idx_t d, MetricType metric = METRIC_L2);
+
+    ~IndexSVSFlat() override;
+
+    void add(idx_t n, const float* x) override;
+
+    void search(
+            idx_t n,
+            const float* x,
+            idx_t k,
+            float* distances,
+            idx_t* labels,
+            const SearchParameters* params = nullptr) const override;
+
+    void reset() override;
+
+    /* The actual SVS implementation */
+    svs_runtime::FlatIndex* impl{nullptr};
+
+    /* Serialization */
+    void serialize_impl(std::ostream& out) const;
+    void deserialize_impl(std::istream& in);
+
+   protected:
+    /* Initializes the implementation*/
+    virtual void create_impl();
+};
+
+} // namespace faiss