usearch 2.17.1 → 2.19.4

package/README.md

@@ -161,7 +161,7 @@ This can result in __20x cost reduction__ on AWS and other public clouds.
 index.save("index.usearch")
 
 loaded_copy = index.load("index.usearch")
-view = Index.restore("index.usearch", view=True)
+view = Index.restore("index.usearch", view=True, ...)
 
 other_view = Index(ndim=..., metric=...)
 other_view.view("index.usearch")
@@ -528,7 +528,11 @@ index = Index(ndim=ndim, metric=CompiledMetric(
 
 - [x] ClickHouse: [C++](https://github.com/ClickHouse/ClickHouse/pull/53447), [docs](https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/annindexes#usearch).
 - [x] DuckDB: [post](https://duckdb.org/2024/05/03/vector-similarity-search-vss.html).
+- [x] ScyllaDB: [Rust](https://github.com/scylladb/vector-store), [presentation](https://www.slideshare.net/slideshow/vector-search-with-scylladb-by-szymon-wasik/276571548).
+- [x] TiDB & TiFlash: [C++](https://github.com/pingcap/tiflash), [announcement](https://www.pingcap.com/article/introduce-vector-search-indexes-in-tidb/).
+- [x] YugaByte: [C++](https://github.com/yugabyte/yugabyte-db/blob/366b9f5e3c4df3a1a17d553db41d6dc50146f488/src/yb/vector_index/usearch_wrapper.cc).
 - [x] Google: [UniSim](https://github.com/google/unisim), [RetSim](https://arxiv.org/abs/2311.17264) paper.
+- [x] MemGraph: [C++](https://github.com/memgraph/memgraph/blob/784dd8520f65050d033aea8b29446e84e487d091/src/storage/v2/indices/vector_index.cpp), [announcement](https://memgraph.com/blog/simplify-data-retrieval-memgraph-vector-search).
 - [x] LanternDB: [C++](https://github.com/lanterndata/lantern), [Rust](https://github.com/lanterndata/lantern_extras), [docs](https://lantern.dev/blog/hnsw-index-creation).
 - [x] LangChain: [Python](https://github.com/langchain-ai/langchain/releases/tag/v0.0.257) and [JavaScript](https://github.com/hwchase17/langchainjs/releases/tag/0.0.125).
 - [x] Microsoft Semantic Kernel: [Python](https://github.com/microsoft/semantic-kernel/releases/tag/python-0.3.9.dev) and C#.
@@ -546,7 +550,7 @@ doi = {10.5281/zenodo.7949416},
 author = {Vardanian, Ash},
 title = {{USearch by Unum Cloud}},
 url = {https://github.com/unum-cloud/usearch},
-version = {2.17.1},
+version = {2.19.4},
 year = {2023},
 month = oct,
 }

package/c/lib.cpp

@@ -493,4 +493,9 @@ USEARCH_EXPORT void usearch_exact_search(                             //
             query_distances[i] = static_cast<usearch_distance_t>(query_result[i].distance);
     }
 }
+
+USEARCH_EXPORT void usearch_clear(usearch_index_t index, usearch_error_t* error) {
+    USEARCH_ASSERT(index && error && "Missing arguments");
+    reinterpret_cast<index_dense_t*>(index)->clear();
+}
 }

package/c/module.modulemap

@@ -0,0 +1,4 @@
+module USearchC {
+    header "usearch.h"
+    export *
+}

package/c/usearch.h

@@ -1,6 +1,10 @@
 #ifndef UNUM_USEARCH_H
 #define UNUM_USEARCH_H
 
+#include <stdbool.h> // `bool`
+#include <stddef.h>  // `size_t`
+#include <stdint.h>  // `uint64_t`
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -13,10 +17,6 @@ extern "C" {
 #endif
 #endif
 
-#include <stdbool.h> // `bool`
-#include <stddef.h>  // `size_t`
-#include <stdint.h>  // `uint64_t`
-
 USEARCH_EXPORT typedef void* usearch_index_t;
 USEARCH_EXPORT typedef uint64_t usearch_key_t;
 USEARCH_EXPORT typedef float usearch_distance_t;
@@ -472,6 +472,14 @@ USEARCH_EXPORT void usearch_exact_search(                            //
     usearch_distance_t* distances, size_t distances_stride,          //
     usearch_error_t* error);
 
+/**
+ * @brief Erases all the vectors from the index.
+ *  @param[inout] index The handle to the USearch index to be modified.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT void usearch_clear(usearch_index_t index,
+                                  usearch_error_t* error);
+
 #ifdef __cplusplus
 }
 #endif

package/cpp/README.md

@@ -164,7 +164,7 @@ As in many other bulk-processing APIs, the `executor` and `progress` are optiona
 In its high-level interface, USearch supports a variety of metrics, including the most popular ones:
 
 - `metric_cos_gt<scalar_t>` for "Cosine" or "Angular" distance.
-- `metric_ip_gt<scalar_t>` for "Inner Product" or "Dot Product" distance.
+- `metric_ip_gt<scalar_t>` for "Inner Product" or "Dot Product" distance with normalized vectors.
 - `metric_l2sq_gt<scalar_t>` for the squared "L2" or "Euclidean" distance.
 - `metric_jaccard_gt<scalar_t>` for "Jaccard" distance between two ordered sets of unique elements.
 - `metric_hamming_gt<scalar_t>` for "Hamming" distance, as the number of shared bits in hashes.

package/cpp/bench.cpp

@@ -514,7 +514,7 @@ struct args_t {
 };
 
 template <typename index_at, typename dataset_at> //
-void run_punned(dataset_at& dataset, args_t const& args, index_config_t config, index_limits_t limits) {
+void run_punned(dataset_at& dataset, args_t const& args, index_dense_config_t config, index_limits_t limits) {
 
     scalar_kind_t quantization = args.quantization();
     std::printf("-- Quantization: %s\n", scalar_kind_name(quantization));

package/cpp/test.cpp

@@ -14,6 +14,7 @@
  */
 #include <algorithm>     // `std::shuffle`
 #include <cassert>       // `assert`
+#include <cmath>         // `std::abs`
 #include <random>        // `std::default_random_engine`
 #include <stdexcept>     // `std::terminate`
 #include <unordered_map> // `std::unordered_map`
@@ -35,7 +36,7 @@ void __expect(bool must_be_true, char const* file, int line, char const* message
     message = message ? message : "C++ unit test failed";
     char buffer[512];
     std::snprintf(buffer, sizeof(buffer), "%s at %s:%d", message, file, line);
-    __usearch_raise_runtime_error(buffer);
+    usearch_raise_runtime_error(buffer);
 }
 
 template <typename value_at>
@@ -673,16 +674,16 @@ void test_cosine(std::size_t collection_size, std::size_t dimensions) {
         scalar_t const* row(std::size_t i) const noexcept { return (*vector_of_vectors_ptr)[i].data(); }
 
         float operator()(member_cref_t const& a, member_cref_t const& b) const {
-            return metric_cos_gt<scalar_t>{}(row(get_slot(b)), row(get_slot(a)), dimensions);
+            return metric_cos_gt<scalar_t, float>{}(row(get_slot(b)), row(get_slot(a)), dimensions);
         }
         float operator()(scalar_t const* some_vector, member_cref_t const& member) const {
-            return metric_cos_gt<scalar_t>{}(some_vector, row(get_slot(member)), dimensions);
+            return metric_cos_gt<scalar_t, float>{}(some_vector, row(get_slot(member)), dimensions);
         }
         float operator()(member_citerator_t const& a, member_citerator_t const& b) const {
-            return metric_cos_gt<scalar_t>{}(row(get_slot(b)), row(get_slot(a)), dimensions);
+            return metric_cos_gt<scalar_t, float>{}(row(get_slot(b)), row(get_slot(a)), dimensions);
         }
         float operator()(scalar_t const* some_vector, member_citerator_t const& member) const {
-            return metric_cos_gt<scalar_t>{}(some_vector, row(get_slot(member)), dimensions);
+            return metric_cos_gt<scalar_t, float>{}(some_vector, row(get_slot(member)), dimensions);
         }
     };
 
@@ -872,21 +873,23 @@ void test_absurd(std::size_t dimensions, std::size_t connectivity, std::size_t e
  * @param dataset_count Number of vectors in the dataset.
  * @param queries_count Number of query vectors.
  * @param wanted_count Number of top matches required from each query.
+ * @tparam scalar_at Data type of the elements in the vectors.
  */
+template <typename scalar_at>
 void test_exact_search(std::size_t dataset_count, std::size_t queries_count, std::size_t wanted_count) {
     std::size_t dimensions = 32;
-    metric_punned_t metric(dimensions, metric_kind_t::cos_k);
+    metric_punned_t metric(dimensions, metric_kind_t::cos_k, scalar_kind<scalar_at>());
 
-    std::random_device rd;
-    std::mt19937 gen(rd());
-    std::uniform_real_distribution<> dis(0.0, 1.0);
-    std::vector<float> dataset(dataset_count * dimensions);
-    std::generate(dataset.begin(), dataset.end(), [&] { return dis(gen); });
+    std::random_device seed_source;
+    std::mt19937 generator(seed_source());
+    std::uniform_real_distribution<> distribution(0.0, 1.0); // ! We can't pass `scalar_at` to the distribution
+    std::vector<scalar_at> dataset(dataset_count * dimensions);
+    std::generate(dataset.begin(), dataset.end(), [&] { return static_cast<scalar_at>(distribution(generator)); });
 
     exact_search_t search;
-    auto results = search(                                                        //
-        (byte_t const*)dataset.data(), dataset_count, dimensions * sizeof(float), //
-        (byte_t const*)dataset.data(), queries_count, dimensions * sizeof(float), //
+    auto results = search(                                                            //
+        (byte_t const*)dataset.data(), dataset_count, dimensions * sizeof(scalar_at), //
+        (byte_t const*)dataset.data(), queries_count, dimensions * sizeof(scalar_at), //
         wanted_count, metric);
 
     for (std::size_t i = 0; i < results.size(); ++i)
@@ -1096,10 +1099,94 @@ template <typename key_at, typename slot_at> void test_replacing_update() {
     expect_eq(final_search[2].member.key, 44);
 }
 
+/**
+ * Tests the filtered search functionality of the index.
+ */
+void test_filtered_search() {
+    constexpr std::size_t dataset_count = 2048;
+    constexpr std::size_t dimensions = 32;
+    metric_punned_t metric(dimensions, metric_kind_t::cos_k);
+
+    std::random_device seed_source;
+    std::mt19937 generator(seed_source());
+    std::uniform_real_distribution<float> distribution(0.0, 1.0);
+    using vector_of_vectors_t = std::vector<std::vector<float>>;
+
+    vector_of_vectors_t vector_of_vectors(dataset_count);
+    for (auto& vector : vector_of_vectors) {
+        vector.resize(dimensions);
+        std::generate(vector.begin(), vector.end(), [&] { return distribution(generator); });
+    }
+
+    index_dense_t index = index_dense_t::make(metric);
+    index.reserve(dataset_count);
+    for (std::size_t idx = 0; idx < dataset_count; ++idx)
+        index.add(idx, vector_of_vectors[idx].data());
+    expect_eq(index.size(), dataset_count);
+
+    {
+        auto predicate = [](index_dense_t::key_t key) { return key != 0; };
+        auto results = index.filtered_search(vector_of_vectors[0].data(), 10, predicate);
+        expect_eq(10, results.size()); // ! Should not contain 0
+        for (std::size_t i = 0; i != results.size(); ++i)
+            expect(0 != results[i].member.key);
+    }
+    {
+        auto predicate = [](index_dense_t::key_t) { return false; };
+        auto results = index.filtered_search(vector_of_vectors[0].data(), 10, predicate);
+        expect_eq(0, results.size()); // ! Should not contain 0
+    }
+    {
+        auto predicate = [](index_dense_t::key_t key) { return key == 10; };
+        auto results = index.filtered_search(vector_of_vectors[0].data(), 10, predicate);
+        expect_eq(1, results.size()); // ! Should not contain 0
+        expect_eq(10, results[0].member.key);
+    }
+}
+
+void test_isolate() {
+    constexpr std::size_t dataset_count = 16;
+    constexpr std::size_t dimensions = 32;
+    metric_punned_t metric(dimensions, metric_kind_t::cos_k);
+
+    std::random_device seed_source;
+    std::mt19937 generator(seed_source());
+    std::uniform_real_distribution<float> distribution(0.0, 1.0);
+    using vector_of_vectors_t = std::vector<std::vector<float>>;
+
+    vector_of_vectors_t vector_of_vectors(dataset_count);
+    for (auto& vector : vector_of_vectors) {
+        vector.resize(dimensions);
+        std::generate(vector.begin(), vector.end(), [&] { return distribution(generator); });
+    }
+
+    index_dense_t index = index_dense_t::make(metric);
+    index.reserve(dataset_count);
+    for (std::size_t idx = 0; idx < dataset_count; ++idx) {
+        index.add(idx, vector_of_vectors[idx].data());
+    }
+    expect_eq(index.size(), dataset_count);
+
+    for (std::size_t idx = 0; idx < dataset_count; ++idx) {
+        if (idx % 2 == 0)
+            index.remove(idx);
+    }
+
+    auto result = index.isolate();
+    for (std::size_t idx = 0; idx < dataset_count; ++idx) {
+        auto result = index.search(vector_of_vectors[idx].data(), 16);
+        expect_eq(result.size(), dataset_count / 2);
+    }
+}
+
 int main(int, char**) {
     test_uint40();
     test_cosine<float, std::int64_t, uint40_t>(10, 10);
 
+    // Non-default floating-point types may result in many compilation & rounding issues.
+    test_cosine<f16_t, std::int64_t, uint40_t>(10, 10);
+    test_cosine<bf16_t, std::int64_t, uint40_t>(10, 10);
+
     // Test plugins, like K-Means clustering.
     {
         std::size_t vectors_count = 1000, centroids_count = 10, dimensions = 256;
@@ -1121,8 +1208,11 @@ int main(int, char**) {
     std::printf("Testing exact search\n");
     for (std::size_t dataset_count : {10, 100})
         for (std::size_t queries_count : {1, 10})
-            for (std::size_t wanted_count : {1, 5})
-                test_exact_search(dataset_count, queries_count, wanted_count);
+            for (std::size_t wanted_count : {1, 5}) {
+                test_exact_search<float>(dataset_count, queries_count, wanted_count);
+                test_exact_search<f16_t>(dataset_count, queries_count, wanted_count);
+                test_exact_search<bf16_t>(dataset_count, queries_count, wanted_count);
+            }
 
     // Make sure the initializers and the algorithms can work with inadequately small values.
     // Be warned - this combinatorial explosion of tests produces close to __500'000__ tests!
@@ -1149,6 +1239,8 @@ int main(int, char**) {
             test_cosine<float, std::int64_t, slot32_t>(collection_size, dimensions);
             std::printf("- Indexing %zu vectors with cos: <float, std::int64_t, uint40_t> \n", collection_size);
             test_cosine<float, std::int64_t, uint40_t>(collection_size, dimensions);
+            std::printf("- Indexing %zu vectors with cos: <bf16, std::int64_t, uint40_t> \n", collection_size);
+            test_cosine<bf16_t, std::int64_t, uint40_t>(collection_size, dimensions);
         }
 
     // Test with binary vectors
@@ -1163,5 +1255,7 @@ int main(int, char**) {
         test_sets<std::int64_t, slot32_t>(set_size, 20, 30);
     test_strings<std::int64_t, slot32_t>();
 
+    test_filtered_search();
+    test_isolate();
     return 0;
 }

package/include/usearch/index.hpp

@@ -8,8 +8,8 @@
 #define UNUM_USEARCH_HPP
 
 #define USEARCH_VERSION_MAJOR 2
-#define USEARCH_VERSION_MINOR 17
-#define USEARCH_VERSION_PATCH 1
+#define USEARCH_VERSION_MINOR 19
+#define USEARCH_VERSION_PATCH 4
 
 // Inferring C++ version
 // https://stackoverflow.com/a/61552074
@@ -149,15 +149,15 @@
 #else
 #define usearch_assert_m(must_be_true, message)                                                                        \
     if (!(must_be_true)) {                                                                                             \
-        __usearch_raise_runtime_error(message);                                                                        \
+        usearch_raise_runtime_error(message);                                                                          \
     }
 #define usearch_noexcept_m
 #endif
 
 extern "C" {
-/// @brief  Helper function to simplify debugging - trace just one symbol - `__usearch_raise_runtime_error`.
+/// @brief  Helper function to simplify debugging - trace just one symbol - `usearch_raise_runtime_error`.
 ///         Assuming the `extern C` block, the name won't be mangled.
-inline static void __usearch_raise_runtime_error(char const* message) {
+inline static void usearch_raise_runtime_error(char const* message) {
     // On Windows we compile with `/EHc` flag, which specifies that functions
     // with C linkage do not throw C++ exceptions.
 #if !defined(__cpp_exceptions) || defined(USEARCH_DEFINED_WINDOWS)
@@ -202,7 +202,7 @@ template <typename at> void misaligned_store(void* ptr, at v) noexcept {
 }
 
 /// @brief  Simply dereferencing misaligned pointers can be dangerous.
-template <typename at> at misaligned_load(void* ptr) noexcept {
+template <typename at> at misaligned_load(void const* ptr) noexcept {
     static_assert(!std::is_reference<at>::value, "Can't load a reference");
     at v;
     std::memcpy(&v, ptr, sizeof(at));
@@ -1751,6 +1751,9 @@ class memory_mapped_file_t {
     {
     }
 
+    memory_mapped_file_t(memory_mapped_file_t const&) = delete;
+    memory_mapped_file_t& operator=(memory_mapped_file_t const&) = delete;
+
     memory_mapped_file_t(byte_t* data, std::size_t length) noexcept : ptr_(data), length_(length) {}
 
     memory_mapped_file_t& operator=(memory_mapped_file_t&& other) noexcept {
@@ -1900,7 +1903,7 @@ template <typename key_at> inline key_at get_key(member_ref_gt<key_at> const& m)
  *          If classical containers store @b Key->Value mappings, this one can
  *          be seen as a network of keys, accelerating approximate @b Value~>Key visited_members.
  *
- *  Unlike most implementations, this one is generic anc can be used for any search,
+ *  Unlike most implementations, this one is generic and can be used for any search,
  *  not just within equi-dimensional vectors. Examples range from Texts to similar Chess
  *  positions, Geo-Spatial Search, and even Graphs.
  *
@@ -2174,6 +2177,20 @@ class index_gt {
             misaligned_store<compressed_slot_t>(tape_ + shift(n), slot);
             misaligned_store<neighbors_count_t>(tape_, n + 1);
         }
+        template <typename allow_slot_at> std::size_t erase_if(allow_slot_at&& allow_slot) noexcept {
+            std::size_t old_count = misaligned_load<neighbors_count_t>(tape_);
+            std::size_t removed_count = 0;
+            for (std::size_t i = 0; i < old_count; ++i) {
+                compressed_slot_t slot = misaligned_load<compressed_slot_t>(tape_ + shift(i));
+                if (allow_slot(slot)) {
+                    removed_count++;
+                } else {
+                    misaligned_store<compressed_slot_t>(tape_ + shift(i - removed_count), slot);
+                }
+            }
+            misaligned_store<neighbors_count_t>(tape_, old_count - removed_count);
+            return removed_count;
+        }
     };
 
     /**
@@ -2183,6 +2200,7 @@ class index_gt {
      */
     struct usearch_align_m context_t {
         top_candidates_t top_candidates{};
+        top_candidates_t top_for_refine{};
         next_candidates_t next_candidates{};
         visits_hash_set_t visits{};
         std::default_random_engine level_generator{};
@@ -2326,7 +2344,7 @@ class index_gt {
         state_result_t failed(error_t message) noexcept { return {std::move(index), std::move(message)}; }
         operator index_gt&&() && {
             if (error)
-                __usearch_raise_runtime_error(error.what());
+                usearch_raise_runtime_error(error.what());
             return std::move(index);
         }
     };
@@ -2498,6 +2516,13 @@ class index_gt {
         if (nodes_)
             std::memcpy(new_nodes.data(), nodes_.data(), sizeof(node_t) * size());
 
+        // Pre-reserve the capacity for `top_for_refine`, which always contains at most one more
+        // element than the connectivity factors.
+        std::size_t connectivity_max = (std::max)(config_.connectivity_base, config_.connectivity);
+        for (std::size_t i = 0; i != new_contexts.size(); ++i)
+            if (!new_contexts[i].top_for_refine.reserve(connectivity_max + 1))
+                return false;
+
         limits_ = limits;
         nodes_capacity_ = limits.members;
         nodes_ = std::move(new_nodes);
@@ -3179,17 +3204,11 @@ class index_gt {
 
     std::size_t memory_usage_per_node(level_t level) const noexcept { return node_bytes_(level); }
 
-    double inverse_log_connectivity() const {
-        return pre_.inverse_log_connectivity;
-    }
+    double inverse_log_connectivity() const { return pre_.inverse_log_connectivity; }
 
-    std::size_t neighbors_base_bytes() const {
-        return pre_.neighbors_base_bytes;
-    }
+    std::size_t neighbors_base_bytes() const { return pre_.neighbors_base_bytes; }
 
-    std::size_t neighbors_bytes() const {
-        return pre_.neighbors_bytes;
-    }
+    std::size_t neighbors_bytes() const { return pre_.neighbors_bytes; }
 
 #if defined(USEARCH_USE_PRAGMA_REGION)
 #pragma endregion
@@ -3649,14 +3668,10 @@ class index_gt {
             node_t node = node_at_(node_idx);
             for (level_t level = 0; level <= node.level(); ++level) {
                 neighbors_ref_t neighbors = neighbors_(node, level);
-                std::size_t old_size = neighbors.size();
-                neighbors.clear();
-                for (std::size_t i = 0; i != old_size; ++i) {
-                    compressed_slot_t neighbor_slot = neighbors[i];
+                neighbors.erase_if([&](compressed_slot_t neighbor_slot) {
                     node_t neighbor = node_at_(neighbor_slot);
-                    if (allow_member(member_cref_t{neighbor.ckey(), neighbor_slot}))
-                        neighbors.push_back(neighbor_slot);
-                }
+                    return !allow_member(member_cref_t{neighbor.ckey(), neighbor_slot});
+                });
             }
             ++processed;
             if (thread_idx == 0)
@@ -3790,7 +3805,7 @@ class index_gt {
         metric_at&& metric, compressed_slot_t new_slot, candidates_view_t new_neighbors, value_at&& value,
         level_t level, context_t& context) usearch_noexcept_m {
 
-        top_candidates_t& top = context.top_candidates;
+        top_candidates_t& top_for_refine = context.top_for_refine;
         std::size_t const connectivity_max = level ? config_.connectivity : config_.connectivity_base;
 
         // Reverse links from the neighbors:
@@ -3817,19 +3832,16 @@ class index_gt {
                 continue;
             }
 
-            // To fit a new connection we need to drop an existing one.
-            top.clear();
-            usearch_assert_m((top.capacity() >= (close_header.size() + 1)),
-                             "The memory must have been reserved in `add`");
-            top.insert_reserved({context.measure(value, citerator_at(close_slot), metric), new_slot});
+            top_for_refine.clear();
+            top_for_refine.insert_reserved({context.measure(value, citerator_at(close_slot), metric), new_slot});
             for (compressed_slot_t successor_slot : close_header)
-                top.insert_reserved(
+                top_for_refine.insert_reserved(
                     {context.measure(citerator_at(close_slot), citerator_at(successor_slot), metric), successor_slot});
 
             // Export the results:
             close_header.clear();
-            candidates_view_t top_view =
-                refine_(metric, connectivity_max, top, context, context.computed_distances_in_reverse_refines);
+            candidates_view_t top_view = refine_(metric, connectivity_max, top_for_refine, context,
+                                                 context.computed_distances_in_reverse_refines);
             usearch_assert_m(top_view.size(), "This would lead to isolated nodes");
             for (std::size_t idx = 0; idx != top_view.size(); idx++)
                 close_header.push_back(top_view[idx].slot);
@@ -4178,9 +4190,10 @@ class index_gt {
                     // This can substantially grow our priority queue:
                     next.insert({-successor_dist, successor_slot});
                     if (is_dummy<predicate_at>() ||
-                        predicate(member_cref_t{node_at_(successor_slot).ckey(), successor_slot}))
+                        predicate(member_cref_t{node_at_(successor_slot).ckey(), successor_slot})) {
                         top.insert({successor_dist, successor_slot}, top_limit);
-                    radius = top.top().distance;
+                        radius = top.top().distance;
+                    }
                 }
             }
         }