faiss 0.5.0 → 0.5.1

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

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