faiss 0.4.3 → 0.5.1

data/vendor/faiss/faiss/svs/IndexSVSVamana.cpp

@@ -0,0 +1,245 @@
+/*
+ * 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/svs/IndexSVSFaissUtils.h>
+#include <faiss/svs/IndexSVSVamana.h>
+
+#include <faiss/Index.h>
+
+#include <svs/runtime/api_defs.h>
+#include <svs/runtime/dynamic_vamana_index.h>
+#include <svs/runtime/vamana_index.h>
+
+#include <cstddef>
+#include <numeric>
+#include <span>
+#include <type_traits>
+#include <vector>
+
+namespace faiss {
+namespace {
+svs_runtime::VamanaIndex::SearchParams make_search_parameters(
+        const IndexSVSVamana& index,
+        const SearchParameters* params) {
+    FAISS_THROW_IF_NOT(index.impl);
+
+    auto search_window_size = index.search_window_size;
+    auto search_buffer_capacity = index.search_buffer_capacity;
+
+    if (auto svs_params =
+                dynamic_cast<const SearchParametersSVSVamana*>(params)) {
+        if (svs_params->search_window_size > 0)
+            search_window_size = svs_params->search_window_size;
+        if (svs_params->search_buffer_capacity > 0)
+            search_buffer_capacity = svs_params->search_buffer_capacity;
+    }
+
+    return {search_window_size, search_buffer_capacity};
+}
+} // namespace
+
+IndexSVSVamana::IndexSVSVamana() = default;
+
+IndexSVSVamana::IndexSVSVamana(
+        idx_t d,
+        size_t degree,
+        MetricType metric,
+        SVSStorageKind storage)
+        : Index(d, metric), graph_max_degree{degree}, storage_kind{storage} {
+    prune_to = graph_max_degree < 4 ? graph_max_degree : graph_max_degree - 4;
+    alpha = metric == METRIC_L2 ? 1.2f : 0.95f;
+
+    // Validate the requested storage kind is available in current runtime.
+    // NB: LVQ/LeanVec are only available on Intel(R) hardware AND when using
+    //     a build based on LVQ/LeanVec-enabled SVS.
+    auto svs_storage = to_svs_storage_kind(storage_kind);
+    auto status =
+            svs_runtime::DynamicVamanaIndex::check_storage_kind(svs_storage);
+    if (!status.ok()) {
+        FAISS_THROW_MSG(status.message());
+    }
+}
+
+bool IndexSVSVamana::is_lvq_leanvec_enabled() {
+    auto lvq = to_svs_storage_kind(SVS_LVQ4x0);
+    auto status = svs_runtime::DynamicVamanaIndex::check_storage_kind(lvq);
+    if (!status.ok()) {
+        return false;
+    }
+    auto leanvec = to_svs_storage_kind(SVS_LeanVec4x4);
+    status = svs_runtime::DynamicVamanaIndex::check_storage_kind(leanvec);
+    if (!status.ok()) {
+        return false;
+    }
+    return true;
+}
+
+IndexSVSVamana::~IndexSVSVamana() {
+    if (impl) {
+        auto status = svs_runtime::DynamicVamanaIndex::destroy(impl);
+        FAISS_ASSERT(status.ok());
+        impl = nullptr;
+    }
+}
+
+void IndexSVSVamana::add(idx_t n, const float* x) {
+    if (!impl) {
+        create_impl();
+    }
+
+    std::vector<size_t> labels(n);
+    std::iota(labels.begin(), labels.end(), ntotal);
+
+    auto status = impl->add(n, labels.data(), x);
+    if (!status.ok()) {
+        FAISS_THROW_MSG(status.message());
+    }
+    ntotal += n;
+}
+
+void IndexSVSVamana::reset() {
+    if (impl) {
+        impl->reset();
+    }
+    is_trained = false;
+    ntotal = 0;
+}
+
+void IndexSVSVamana::search(
+        idx_t n,
+        const float* x,
+        idx_t k,
+        float* distances,
+        idx_t* labels,
+        const SearchParameters* params) const {
+    if (!impl) {
+        for (idx_t i = 0; i < n; ++i) {
+            distances[i] = std::numeric_limits<float>::infinity();
+            labels[i] = -1;
+        }
+        return;
+    }
+    FAISS_THROW_IF_NOT(k > 0);
+    FAISS_THROW_IF_NOT(is_trained);
+
+    auto sp = make_search_parameters(*this, params);
+    auto id_filter = make_faiss_id_filter(params);
+    auto status = impl->search(
+            static_cast<size_t>(n),
+            x,
+            static_cast<size_t>(k),
+            distances,
+            convert_output_buffer<size_t>(labels, static_cast<size_t>(n * k)),
+            &sp,
+            id_filter.get());
+
+    if (!status.ok()) {
+        FAISS_THROW_MSG(status.message());
+    }
+}
+
+void IndexSVSVamana::range_search(
+        idx_t n,
+        const float* x,
+        float radius,
+        RangeSearchResult* result,
+        const SearchParameters* params) const {
+    FAISS_THROW_IF_NOT(impl);
+    FAISS_THROW_IF_NOT(radius > 0);
+    FAISS_THROW_IF_NOT(is_trained);
+    FAISS_THROW_IF_NOT(result->nq == static_cast<size_t>(n));
+
+    auto sp = make_search_parameters(*this, params);
+    auto id_filter = make_faiss_id_filter(params);
+    auto status = impl->range_search(
+            static_cast<size_t>(n),
+            x,
+            radius,
+            FaissResultsAllocator{result},
+            &sp,
+            id_filter.get());
+    if (!status.ok()) {
+        FAISS_THROW_MSG(status.message());
+    }
+}
+
+size_t IndexSVSVamana::remove_ids(const IDSelector& sel) {
+    FAISS_THROW_IF_NOT(impl);
+    auto id_filter = FaissIDFilter{sel};
+    size_t removed = 0;
+    auto Status = impl->remove_selected(&removed, id_filter);
+    ntotal -= removed;
+    return removed;
+}
+
+void IndexSVSVamana::create_impl() {
+    FAISS_THROW_IF_NOT(!impl);
+    ntotal = 0;
+    auto svs_metric = to_svs_metric(metric_type);
+    auto svs_storage_kind = to_svs_storage_kind(storage_kind);
+    auto build_params = svs_runtime::VamanaIndex::BuildParams{
+            .graph_max_degree = graph_max_degree,
+            .prune_to = prune_to,
+            .alpha = alpha,
+            .construction_window_size = construction_window_size,
+            .max_candidate_pool_size = max_candidate_pool_size,
+            .use_full_search_history = use_full_search_history,
+    };
+    auto search_params = svs_runtime::VamanaIndex::SearchParams{
+            .search_window_size = search_window_size,
+            .search_buffer_capacity = search_buffer_capacity,
+    };
+    auto Status = svs_runtime::DynamicVamanaIndex::build(
+            &impl,
+            d,
+            svs_metric,
+            svs_storage_kind,
+            build_params,
+            search_params);
+    if (!Status.ok()) {
+        FAISS_THROW_MSG(Status.message());
+    }
+    FAISS_THROW_IF_NOT(impl);
+}
+
+void IndexSVSVamana::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 IndexSVSVamana::deserialize_impl(std::istream& in) {
+    FAISS_THROW_IF_MSG(impl, "Cannot deserialize: SVS index already loaded.");
+    auto svs_metric = to_svs_metric(metric_type);
+    auto svs_storage_kind = to_svs_storage_kind(storage_kind);
+    auto status = impl->load(&impl, in, svs_metric, svs_storage_kind);
+    if (!status.ok()) {
+        FAISS_THROW_MSG(status.message());
+    }
+}
+
+} // namespace faiss

data/vendor/faiss/faiss/svs/IndexSVSVamana.h

@@ -0,0 +1,137 @@
+/*
+ * 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 <svs/runtime/api_defs.h>
+
+#include <iostream>
+
+namespace faiss {
+
+struct SearchParametersSVSVamana : public SearchParameters {
+    size_t search_window_size = 0;
+    size_t search_buffer_capacity = 0;
+};
+
+// redefinition for swig export
+enum SVSStorageKind {
+    SVS_FP32,
+    SVS_FP16,
+    SVS_SQI8,
+    SVS_LVQ4x0,
+    SVS_LVQ4x4,
+    SVS_LVQ4x8,
+    SVS_LeanVec4x4,
+    SVS_LeanVec4x8,
+    SVS_LeanVec8x8,
+};
+
+inline svs_runtime::StorageKind to_svs_storage_kind(SVSStorageKind kind) {
+    switch (kind) {
+        case SVS_FP32:
+            return svs_runtime::StorageKind::FP32;
+        case SVS_FP16:
+            return svs_runtime::StorageKind::FP16;
+        case SVS_SQI8:
+            return svs_runtime::StorageKind::SQI8;
+        case SVS_LVQ4x0:
+            return svs_runtime::StorageKind::LVQ4x0;
+        case SVS_LVQ4x4:
+            return svs_runtime::StorageKind::LVQ4x4;
+        case SVS_LVQ4x8:
+            return svs_runtime::StorageKind::LVQ4x8;
+        case SVS_LeanVec4x4:
+            return svs_runtime::StorageKind::LeanVec4x4;
+        case SVS_LeanVec4x8:
+            return svs_runtime::StorageKind::LeanVec4x8;
+        case SVS_LeanVec8x8:
+            return svs_runtime::StorageKind::LeanVec8x8;
+        default:
+            FAISS_ASSERT(!"not supported SVS storage kind");
+    }
+}
+
+struct IndexSVSVamana : Index {
+    size_t graph_max_degree;
+    size_t prune_to;
+    float alpha = 1.2;
+    size_t search_window_size = 10;
+    size_t search_buffer_capacity = 10;
+    size_t construction_window_size = 40;
+    size_t max_candidate_pool_size = 200;
+    bool use_full_search_history = true;
+
+    SVSStorageKind storage_kind;
+
+    IndexSVSVamana();
+
+    IndexSVSVamana(
+            idx_t d,
+            size_t degree,
+            MetricType metric = METRIC_L2,
+            SVSStorageKind storage = SVSStorageKind::SVS_FP32);
+
+    ~IndexSVSVamana() override;
+
+    // static member that exposes whether or not LVQ/LeanVec are enabled for
+    // this build and runtime.
+    static bool is_lvq_leanvec_enabled();
+
+    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 range_search(
+            idx_t n,
+            const float* x,
+            float radius,
+            RangeSearchResult* result,
+            const SearchParameters* params = nullptr) const override;
+
+    size_t remove_ids(const IDSelector& sel) override;
+
+    void reset() override;
+
+    /* Serialization and deserialization helpers */
+    void serialize_impl(std::ostream& out) const;
+    virtual void deserialize_impl(std::istream& in);
+
+    /* The actual SVS implementation */
+    svs_runtime::DynamicVamanaIndex* impl{nullptr};
+
+   protected:
+    /* Initializes the implementation*/
+    virtual void create_impl();
+};
+
+} // namespace faiss

data/vendor/faiss/faiss/svs/IndexSVSVamanaLVQ.cpp

@@ -0,0 +1,39 @@
+/*
+ * 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/svs/IndexSVSVamanaLVQ.h>
+
+namespace faiss {
+
+IndexSVSVamanaLVQ::IndexSVSVamanaLVQ() : IndexSVSVamana() {
+    storage_kind = SVSStorageKind::SVS_LVQ4x0;
+}
+
+IndexSVSVamanaLVQ::IndexSVSVamanaLVQ(
+        idx_t d,
+        size_t degree,
+        MetricType metric,
+        SVSStorageKind storage)
+        : IndexSVSVamana(d, degree, metric, storage) {}
+
+} // namespace faiss

data/vendor/faiss/faiss/svs/IndexSVSVamanaLVQ.h

@@ -0,0 +1,42 @@
+/*
+ * 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/svs/IndexSVSVamana.h>
+
+namespace faiss {
+
+struct IndexSVSVamanaLVQ : IndexSVSVamana {
+    IndexSVSVamanaLVQ();
+
+    IndexSVSVamanaLVQ(
+            idx_t d,
+            size_t degree,
+            MetricType metric = METRIC_L2,
+            SVSStorageKind storage = SVSStorageKind::SVS_LVQ4x4);
+
+    ~IndexSVSVamanaLVQ() override = default;
+};
+
+} // namespace faiss

data/vendor/faiss/faiss/svs/IndexSVSVamanaLeanVec.cpp

@@ -0,0 +1,149 @@
+/*
+ * 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/svs/IndexSVSFaissUtils.h>
+#include <faiss/svs/IndexSVSVamanaLeanVec.h>
+
+#include <svs/runtime/dynamic_vamana_index.h>
+#include <svs/runtime/training.h>
+#include <svs/runtime/vamana_index.h>
+
+#include <memory>
+#include <span>
+#include "faiss/svs/IndexSVSVamana.h"
+
+namespace faiss {
+
+IndexSVSVamanaLeanVec::IndexSVSVamanaLeanVec() : IndexSVSVamana() {
+    is_trained = false;
+    storage_kind = SVSStorageKind::SVS_LeanVec4x4;
+}
+
+IndexSVSVamanaLeanVec::IndexSVSVamanaLeanVec(
+        idx_t d,
+        size_t degree,
+        MetricType metric,
+        size_t leanvec_dims,
+        SVSStorageKind storage_kind)
+        : IndexSVSVamana(d, degree, metric, storage_kind) {
+    is_trained = false;
+    leanvec_d = leanvec_dims == 0 ? d / 2 : leanvec_dims;
+}
+
+IndexSVSVamanaLeanVec::~IndexSVSVamanaLeanVec() {
+    if (training_data) {
+        auto status = svs_runtime::LeanVecTrainingData::destroy(training_data);
+        FAISS_ASSERT(status.ok());
+        training_data = nullptr;
+    }
+    IndexSVSVamana::~IndexSVSVamana();
+}
+
+void IndexSVSVamanaLeanVec::add(idx_t n, const float* x) {
+    FAISS_THROW_IF_MSG(
+            !is_trained, "Index not trained: call train() before add().");
+    IndexSVSVamana::add(n, x);
+}
+
+void IndexSVSVamanaLeanVec::train(idx_t n, const float* x) {
+    FAISS_THROW_IF_MSG(
+            training_data || impl, "Index already trained or contains data.");
+
+    FAISS_THROW_IF_NOT_MSG(
+            IndexSVSVamana::is_lvq_leanvec_enabled(),
+            "LVQ/LeanVec support not available on this platform or build");
+
+    auto status = svs_runtime::LeanVecTrainingData::build(
+            &training_data, d, n, x, leanvec_d);
+    if (!status.ok()) {
+        FAISS_THROW_MSG(status.message());
+    }
+    FAISS_THROW_IF_NOT_MSG(
+            training_data, "Failed to build leanvec training info.");
+    is_trained = true;
+}
+
+void IndexSVSVamanaLeanVec::serialize_training_data(std::ostream& out) const {
+    FAISS_THROW_IF_NOT_MSG(
+            training_data, "Cannot serialize: Training data not initialized.");
+
+    auto status = training_data->save(out);
+    if (!status.ok()) {
+        FAISS_THROW_MSG(status.message());
+    }
+}
+
+void IndexSVSVamanaLeanVec::deserialize_training_data(std::istream& in) {
+    svs_runtime::LeanVecTrainingData* tdata = nullptr;
+    auto status = svs_runtime::LeanVecTrainingData::load(&tdata, in);
+    if (!status.ok()) {
+        FAISS_THROW_MSG(status.message());
+    }
+    FAISS_THROW_IF_NOT_MSG(tdata, "Failed to load leanvec training data.");
+    training_data = tdata;
+}
+
+void IndexSVSVamanaLeanVec::create_impl() {
+    ntotal = 0;
+    auto svs_metric = to_svs_metric(metric_type);
+    auto svs_storage_kind = to_svs_storage_kind(storage_kind);
+    auto build_params = svs_runtime::VamanaIndex::BuildParams{
+            .graph_max_degree = graph_max_degree,
+            .prune_to = prune_to,
+            .alpha = alpha,
+            .construction_window_size = construction_window_size,
+            .max_candidate_pool_size = max_candidate_pool_size,
+            .use_full_search_history = use_full_search_history,
+    };
+    auto search_params = svs_runtime::VamanaIndex::SearchParams{
+            .search_window_size = search_window_size,
+            .search_buffer_capacity = search_buffer_capacity,
+    };
+    auto status = svs_runtime::Status_Ok;
+    if (training_data) {
+        status = svs_runtime::DynamicVamanaIndexLeanVec::build(
+                &impl,
+                d,
+                svs_metric,
+                svs_storage_kind,
+                training_data,
+                build_params,
+                search_params);
+    } else {
+        status = svs_runtime::DynamicVamanaIndexLeanVec::build(
+                &impl,
+                d,
+                svs_metric,
+                svs_storage_kind,
+                leanvec_d,
+                build_params,
+                search_params);
+    }
+
+    if (!status.ok()) {
+        FAISS_THROW_MSG(status.message());
+    }
+    FAISS_THROW_IF_NOT(impl);
+}
+
+} // namespace faiss

data/vendor/faiss/faiss/svs/IndexSVSVamanaLeanVec.h

@@ -0,0 +1,58 @@
+/*
+ * 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/svs/IndexSVSVamana.h>
+
+namespace faiss {
+
+struct IndexSVSVamanaLeanVec : IndexSVSVamana {
+    IndexSVSVamanaLeanVec();
+
+    IndexSVSVamanaLeanVec(
+            idx_t d,
+            size_t degree,
+            MetricType metric = METRIC_L2,
+            size_t leanvec_dims = 0,
+            SVSStorageKind storage = SVSStorageKind::SVS_LeanVec4x4);
+
+    ~IndexSVSVamanaLeanVec() override;
+
+    void add(idx_t n, const float* x) override;
+
+    void train(idx_t n, const float* x) override;
+
+    void serialize_training_data(std::ostream& out) const;
+    void deserialize_training_data(std::istream& in);
+
+    size_t leanvec_d;
+
+    /* Training information */
+    svs_runtime::LeanVecTrainingData* training_data{nullptr};
+
+   protected:
+    void create_impl() override;
+};
+
+} // namespace faiss

data/vendor/faiss/faiss/utils/AlignedTable.h

@@ -25,7 +25,7 @@ inline bool is_aligned_pointer(const void* x) {
 }
 
 // class that manages suitably aligned arrays for SIMD
-// T should be a POV type. The default alignment is 32 for AVX
+// T should be a POD type. The default alignment is 32 for AVX
 template <class T, int A = 32>
 struct AlignedTableTightAlloc {
     T* ptr;

data/vendor/faiss/faiss/utils/Heap.cpp

@@ -139,7 +139,7 @@ void HeapArray<C>::per_line_extrema(T* out_val, TI* out_ids) const {
     }
 }
 
-// explicit instanciations
+// explicit instantiations
 
 template struct HeapArray<CMin<float, int64_t>>;
 template struct HeapArray<CMax<float, int64_t>>;
@@ -238,7 +238,7 @@ void merge_knn_results(
     }
 }
 
-// explicit instanciations
+// explicit instantiations
 #define INSTANTIATE(C, distance_t)                                \
     template void merge_knn_results<int64_t, C<distance_t, int>>( \
             size_t,                                               \