usearch 0.19.3 → 0.20.0

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "usearch"
-version = "0.19.3"
+version = "0.20.0"
 authors = ["Ashot Vardanian <1983160+ashvardanian@users.noreply.github.com>"]
 description = "Smaller & Faster Single-File Vector Search Engine from Unum"
 edition = "2021"

package/README.md

@@ -167,7 +167,7 @@ index.add(/* label: */ 42, /* vector: */ {&vec[0], 3});
 auto results = index.search(/* query: */ {&vec[0], 3}, 5 /* neighbors */);
 
 for (std::size_t i = 0; i != results.size(); ++i)
-    results[i].element.label, results[i].element.vector, results[i].distance;
+    results[i].member.label, results[i].member.vector, results[i].member.id, results[i].distance;
 ```
 
 The `add` is thread-safe for concurrent index construction.

package/c/test.c

@@ -1,182 +1,294 @@
-#include <assert.h>
+#include <stdio.h>
 #include <errno.h>
 #include <stdio.h>
 #include <stdlib.h>
-#include <string.h>
 #include <sys/stat.h>
-#include <time.h>
 
 #include "usearch.h"
 
-float* read_fvecs_file(const char* filename, size_t* num_vectors, size_t* vector_dim) {
-    struct stat st;
-    FILE* file;
-    size_t cnt;
-    float skip;
-
-    ;
-    if (stat(filename, &st) == -1) {
-        printf("Failed to read file: %s err: %d: %s\n", filename, errno, strerror(errno));
-        return NULL;
+#define ASSERT(must_be_true, message)           \
+    if (!(must_be_true)) {                      \
+        printf("Assert: %s\n", message);        \
+        exit(-1);                               \
     }
 
-    file = fopen(filename, "rb");
-    if (file == NULL) {
-        printf("Failed to open file: %s\n", filename);
-        return NULL;
-    }
 
-    // Read the number of vectors and vector dimension from the file
-    cnt = fread(vector_dim, sizeof(int), 1, file);
-    assert(cnt == 1);
-    if (st.st_size % ((*vector_dim + 1) * sizeof(float)) != 0) {
-        printf("File does not contain a whole number of vectors.\n Vector dim: %ld, file size: %ld\n", *vector_dim,
-               st.st_size);
-        fclose(file);
-        return NULL;
-    }
+void parse_vectors_from_file(char const* file_path, size_t* count, size_t* dimension, float** data) {
 
-    *num_vectors = st.st_size / ((*vector_dim + 1) * sizeof(float));
+    // Open the file
+    struct stat st = {};
+    ASSERT(stat(file_path, &st) == 0, "Failed to get metadata of the file");
+    FILE* file = fopen(file_path, "rb");
+    ASSERT(file, "Failed to open the file");
 
-    // Allocate memory for the array
-    float* data = (float*)malloc(*num_vectors * *vector_dim * sizeof(float));
-    if (data == NULL) {
-        printf("Memory allocation failed.\n");
-        fclose(file);
-        return NULL;
-    }
+    // Read vectors dimension and calculate count
+    int dim = 0;
+    size_t read = fread(&dim, sizeof(int), 1, file);
+    ASSERT(read == 1, "Failed to read from the file");
+    ASSERT(st.st_size % ((dim + 1) * sizeof(float)) == 0, "File does not contain a whole number of vectors");
+    *dimension = (size_t)dim;
+    *count = st.st_size / ((dim + 1) * sizeof(float));
 
-    // Read the data from the file into the array
-    for (size_t i = 0; i < *num_vectors; i++) {
-        cnt = fread(data + i * *vector_dim, sizeof(float), *vector_dim, file);
-        assert(cnt == *vector_dim);
-        if (i == *num_vectors - 1) {
+    // Allocate memory for the vectors' data
+    *data = (float*)malloc(*count * *dimension * sizeof(float));
+    ASSERT(*data, "Failed to allocate memory");
+
+    // Read the data
+    for (size_t i = 0; i < *count; ++i) {
+        read = fread(*data + i * *dimension, sizeof(float), *dimension, file);
+        ASSERT(read == *dimension, "Failed to read from the file");
+         if (i == *count - 1)
             break;
-        }
-        cnt = fread(&skip, sizeof(float), 1, file);
-        assert(cnt == 1);
+
+        // Skip
+        float skip;
+        read = fread(&skip, sizeof(float), 1, file);
+        ASSERT(read == 1, "Failed to read from the file");
     }
 
     fclose(file);
-    return data;
 }
 
-// log every this many iterations in test loops
-const int LOG_GRANULARITY = 10000;
-
-void test_index(float* data, size_t num_vectors, size_t vector_dim) {
+usearch_init_options_t create_options(size_t vector_dimension) {
     usearch_init_options_t opts;
-    usearch_index_t idx;
-    usearch_error_t error = NULL;
-    clock_t start;
     opts.connectivity = 2; // 32 in faiss
-    opts.dimensions = vector_dim;
+    opts.dimensions = vector_dimension;
     opts.expansion_add = 40;    // 40 in faiss
     opts.expansion_search = 16; // 10 in faiss
     opts.metric_kind = usearch_metric_ip_k;
     opts.metric = NULL;
     opts.quantization = usearch_scalar_f32_k;
+    return opts;
+}
+
+void test_init(size_t vectors_count, size_t vector_dimension) {
+    printf("Test: Index Initialization...\n");
+
+    // Init index
+    usearch_index_t idx = NULL;
+    usearch_error_t error = NULL;
+    usearch_init_options_t opts = create_options(vector_dimension);
+    idx = usearch_init(&opts, &error);
+    ASSERT(!error, error);
+    usearch_free(idx, &error);
+    ASSERT(!error, error);
+
+    // Init second time
+    idx = usearch_init(&opts, &error);
+    ASSERT(!error, error);
+
+    ASSERT(usearch_size(idx, &error) == 0, error);
+    ASSERT(usearch_capacity(idx, &error) == 0, error);
+    ASSERT(usearch_dimensions(idx, &error) == vector_dimension, error);
+    ASSERT(usearch_connectivity(idx, &error) == opts.connectivity, error);
+
+    // Reserve
+    usearch_reserve(idx, vectors_count, &error);
+    ASSERT(!error, error);
+    ASSERT(usearch_size(idx, &error) == 0, error);
+    ASSERT(usearch_capacity(idx, &error) == vectors_count, error);
+    ASSERT(usearch_dimensions(idx, &error) == vector_dimension, error);
+    ASSERT(usearch_connectivity(idx, &error) == opts.connectivity, error);
+
+    usearch_free(idx, &error);
+    ASSERT(!error, error);
+
+    printf("Test: Index Initialization - PASSED\n");
+}
 
-    // results arrays
-    int k = 10;
-    num_vectors /= 10;
-    usearch_label_t* labels = (usearch_label_t*)calloc(k, sizeof(usearch_label_t));
-    float* distances = (float*)calloc(k, sizeof(float));
+void test_add_vector(size_t vectors_count, size_t vector_dimension, float const* data) {
+    printf("Test: Add Vector...\n");
 
-    fprintf(stderr, "read %ld vectors of dimension %ld\n", num_vectors, vector_dim);
-    fprintf(stderr, "initializing usearch...\n");
+    usearch_index_t idx = NULL;
+    usearch_error_t error = NULL;
+    usearch_init_options_t opts = create_options(vector_dimension);
     idx = usearch_init(&opts, &error);
-    if (error != NULL) {
-        fprintf(stderr, "usearch error: %s\n", error);
-        assert(false);
+    usearch_reserve(idx, vectors_count, &error);
+
+    // Add vectors
+    for (size_t i = 0; i < vectors_count; ++i) {
+        usearch_label_t label = i;
+        usearch_add(idx, label, data + i * vector_dimension, usearch_scalar_f32_k, &error);
+        ASSERT(!error, error);
     }
 
-    fprintf(stderr, "reserving capacity...\n");
-    usearch_reserve(idx, num_vectors, &error);
-    assert(!error);
+    ASSERT(usearch_size(idx, &error) == vectors_count, error);
+    ASSERT(usearch_capacity(idx, &error) == vectors_count, error);
 
-    fprintf(stderr, "adding vectors...\n");
-    for (size_t i = 0; i < num_vectors; i++) {
-        if (i % LOG_GRANULARITY == 0) {
-            fprintf(stderr, "added %ld vectors...\n", i);
-        }
+    // Check vectors in the index
+    for (size_t i = 0; i < vectors_count; ++i) {
         usearch_label_t label = i;
-        usearch_add(idx, label, data + i * vector_dim, usearch_scalar_f32_k, &error);
-        assert(!error);
+        ASSERT(usearch_contains(idx, label, &error), error);
     }
+    ASSERT(!usearch_contains(idx, -1, &error), error); // Non existing label
+
+    usearch_free(idx, &error);
+    printf("Test: Add Vector - PASSED\n");
+}
+
+void test_find_vector(size_t vectors_count, size_t vector_dimension, float const* data) {
+    printf("Test: Find Vector...\n");
 
-    fprintf(stderr, "checking containment of vectors...\n");
-    for (size_t i = 0; i < num_vectors; i++) {
-        if (i % LOG_GRANULARITY == 0) {
-            fprintf(stderr, "checked %ld vectors...\n", i);
-        }
+    usearch_index_t idx = NULL;
+    usearch_error_t error = NULL;
+    usearch_init_options_t opts = create_options(vector_dimension);
+    idx = usearch_init(&opts, &error);
+    usearch_reserve(idx, vectors_count, &error);
+
+    // Create result buffers
+    int results_count = 10;
+    usearch_label_t* labels = (usearch_label_t*)malloc(results_count * sizeof(usearch_label_t));
+    float* distances = (float*)malloc(results_count * sizeof(float));
+    ASSERT(labels && distances, "Failed to allocate memory");
+
+    // Add vectors
+    for (size_t i = 0; i < vectors_count; ++i) {
         usearch_label_t label = i;
-        assert(usearch_contains(idx, label, &error));
-        assert(!error);
+        usearch_add(idx, label, data + i * vector_dimension, usearch_scalar_f32_k, &error);
+        ASSERT(!error, error);
     }
 
-    assert(!usearch_contains(idx, -1, &error));
-    assert(!error);
-
-    fprintf(stderr, "searching vectors...\n");
-    for (size_t i = 0; i < num_vectors; i++) {
-        if (i % LOG_GRANULARITY == 0) {
-            fprintf(stderr, "searched %ld vectors...\n", i);
-        }
-        const void *query_vector = data + i * vector_dim;
-        usearch_search(idx, query_vector, usearch_scalar_f32_k, k, labels, distances, &error);
-        assert(!error);
+    // Find the vectors
+    for (size_t i = 0; i < vectors_count; i++) {
+        const void *query_vector = data + i * vector_dimension;
+        size_t found_count = usearch_search(idx, query_vector, usearch_scalar_f32_k, results_count, labels, distances, &error);
+        ASSERT(!error, error);
+        ASSERT(found_count = results_count, "Vector is missing");
     }
 
-    fprintf(stderr, "saving the index...\n");
-    start = clock();
-    usearch_save(idx, "usearch_index.bin", &error);
-    assert(!error);
-    fprintf(stderr, "saving took %.2f ms\n", ((double)(clock() - start)) / CLOCKS_PER_SEC * 1000);
+    usearch_free(idx, &error);
+    printf("Test: Find Vector - PASSED\n");
+}
+
+void test_remove_vector(size_t vectors_count, size_t vector_dimension, float const* data) {
+    printf("Test: Remove Vector...\n");
+
+    usearch_index_t idx = NULL;
+    usearch_error_t error = NULL;
+    usearch_init_options_t opts = create_options(vector_dimension);
+    idx = usearch_init(&opts, &error);
+    usearch_reserve(idx, vectors_count, &error);
+
+    // Add vectors
+    for (size_t i = 0; i < vectors_count; ++i) {
+        usearch_label_t label = i;
+        usearch_add(idx, label, data + i * vector_dimension, usearch_scalar_f32_k, &error);
+        ASSERT(!error, error);
+    }
+
+    // Remove the vectors
+    for (size_t i = 0; i < vectors_count; i++) {
+        usearch_label_t label = i;
+        usearch_remove(idx, label, &error);
+        ASSERT(error, "Currently, Remove is not supported");
+    }
+
+    usearch_free(idx, &error);
+    printf("Test: Remove Vector - PASSED\n");
+}
 
-    fprintf(stderr, "destroying the index...\n");
-    start = clock();
+void test_save_load(size_t vectors_count, size_t vector_dimension, float const* data) {
+    printf("Test: Save/Load...\n");
+
+    usearch_index_t idx = NULL;
+    usearch_error_t error = NULL;
+    usearch_init_options_t opts = create_options(vector_dimension);
+    idx = usearch_init(&opts, &error);
+    usearch_reserve(idx, vectors_count, &error);
+
+    // Add vectors
+    for (size_t i = 0; i < vectors_count; ++i) {
+        usearch_label_t label = i;
+        usearch_add(idx, label, data + i * vector_dimension, usearch_scalar_f32_k, &error);
+        ASSERT(!error, error);
+    }
+
+    // Save and free the index
+    usearch_save(idx, "usearch_index.bin", &error);
+    ASSERT(!error, error);
     usearch_free(idx, &error);
-    assert(!error);
-    fprintf(stderr, "destroying the index took %.2f ms\n", ((double)(clock() - start)) / CLOCKS_PER_SEC * 1000);
+    ASSERT(!error, error);
 
-    fprintf(stderr, "loading the index...\n");
-    start = clock();
+    // Reinit
     idx = usearch_init(&opts, &error);
-    assert(!error);
-    assert(usearch_size(idx, &error) == 0);
-    assert(!error);
+    ASSERT(!error, error);
+    ASSERT(usearch_size(idx, &error) == 0, error);
+
+    // Load
     usearch_load(idx, "usearch_index.bin", &error);
-    assert(!error);
-    fprintf(stderr, "loading the index took %.2f ms\n", ((double)(clock() - start)) / CLOCKS_PER_SEC * 1000);
-    assert(usearch_size(idx, &error) == num_vectors);
-    assert(!error);
+    ASSERT(!error, error);
+    ASSERT(usearch_size(idx, &error) == vectors_count, error);
+    ASSERT(usearch_capacity(idx, &error) == vectors_count, error);
+    ASSERT(usearch_dimensions(idx, &error) == vector_dimension, error);
+    ASSERT(usearch_connectivity(idx, &error) == opts.connectivity, error);
+
+    // Check vectors in the index
+    for (size_t i = 0; i < vectors_count; ++i) {
+        usearch_label_t label = i;
+        ASSERT(usearch_contains(idx, label, &error), error);
+    }
+
     usearch_free(idx, &error);
+    printf("Test: Save/Load - PASSED\n");
+}
+
+void test_view(size_t vectors_count, size_t vector_dimension, float const* data) {
+    printf("Test: View...\n");
 
-    fprintf(stderr, "viewing the index...\n");
-    start = clock();
+    usearch_index_t idx = NULL;
+    usearch_error_t error = NULL;
+    usearch_init_options_t opts = create_options(vector_dimension);
     idx = usearch_init(&opts, &error);
-    assert(!error);
-    assert(usearch_size(idx, &error) == 0);
-    assert(!error);
-    usearch_view(idx, "usearch_index.bin", &error);
-    assert(!error);
-    fprintf(stderr, "viewing the index took %.2f ms\n", ((double)(clock() - start)) / CLOCKS_PER_SEC * 1000);
-    assert(usearch_size(idx, &error) == num_vectors);
-    assert(!error);
+    usearch_reserve(idx, vectors_count, &error);
+
+    // Add vectors
+    for (size_t i = 0; i < vectors_count; ++i) {
+        usearch_label_t label = i;
+        usearch_add(idx, label, data + i * vector_dimension, usearch_scalar_f32_k, &error);
+        ASSERT(!error, error);
+    }
+
+    // Save and free the index
+    usearch_save(idx, "usearch_index.bin", &error);
+    ASSERT(!error, error);
     usearch_free(idx, &error);
+    ASSERT(!error, error);
+
+    // Reinit
+    idx = usearch_init(&opts, &error);
+    ASSERT(!error, error);
+
+    // View
+    usearch_view(idx, "usearch_index.bin", &error);
+    ASSERT(!error, error);
 
+    usearch_free(idx, &error);
+    printf("Test: View - PASSED\n");
 }
 
-int main() {
-    const char* filename = "sift/sift_base.fvecs";
-    size_t num_vectors = 0, vector_dim = 0;
-    float* data = read_fvecs_file(filename, &num_vectors, &vector_dim);
-    if (data != NULL) {
+int main(int argc, char* argv[]) {
+    // Resolve file path
+    char const* filename = "sample.fvecs";
+    if (argc == 2)
+        filename = argv[1];
 
-        test_index(data, num_vectors, vector_dim);
+    // Read data from the file
+    float* data = NULL;
+    size_t vectors_count = 0;
+    size_t vector_dimension = 0;
+    parse_vectors_from_file(filename, &vectors_count, &vector_dimension, &data);
+    vectors_count = vectors_count > 100000 ? 100000 : vectors_count; // Just limit vectors
+
+    // Test
+    test_init(vectors_count, vector_dimension);
+    test_add_vector(vectors_count, vector_dimension, data);
+    test_find_vector(vectors_count, vector_dimension, data);
+    test_remove_vector(vectors_count, vector_dimension, data);
+    test_save_load(vectors_count, vector_dimension, data);
+    test_view(vectors_count, vector_dimension, data);
+
+    // Free vectors' buffer
+    free(data);
 
-        free(data); // Remember to free the dynamically allocated memory
-    }
     return 0;
 }

package/conanfile.py

@@ -4,7 +4,7 @@ from conans import ConanFile
 class USearchConan(ConanFile):
 
     name = 'USearch'
-    version = '0.19.3'
+    version = '0.20.0'
     license = 'Apache 2.0'
     url = 'https://github.com/unum-cloud/usearch'
     description = 'Smaller & Faster Single-File Vector Search Engine from Unum'

package/cpp/test.cpp

@@ -9,8 +9,6 @@
 using namespace unum::usearch;
 using namespace unum;
 
-using point_id_t = std::int64_t;
-
 void expect(bool must_be_true) {
     if (!must_be_true)
         throw std::runtime_error("Failed!");
@@ -22,6 +20,7 @@ template <typename scalar_at, typename index_at> void test3d(index_at&& index) {
     using view_t = span_gt<scalar_t const>;
     using index_t = typename std::remove_reference<index_at>::type;
     using distance_t = typename index_t::distance_t;
+    using label_t = typename index_t::label_t;
 
     scalar_t vec[3] = {10, 20, 15};
     scalar_t vec_a[3] = {15, 16, 17};
@@ -31,7 +30,7 @@ template <typename scalar_at, typename index_at> void test3d(index_at&& index) {
     index.add(42, view_t{&vec[0], 3ul});
 
     // Default approximate search
-    point_id_t matched_labels[10] = {0};
+    label_t matched_labels[10] = {0};
     distance_t matched_distances[10] = {0};
     std::size_t matched_count = index.search(view_t{&vec[0], 3ul}, 5).dump_to(matched_labels, matched_distances);
 
@@ -52,7 +51,7 @@ template <typename scalar_at, typename index_at> void test3d(index_at&& index) {
     // Validate scans
     std::size_t count = 0;
     for (auto member : index) {
-        point_id_t id = member.label;
+        label_t id = member.label;
         expect(id >= 42 && id <= 44);
         count++;
     }
@@ -146,11 +145,12 @@ int main(int, char**) {
     // static_assert(!std::is_same<index_gt<pearson_correlation_gt<>>::value_type, std::true_type>());
     // static_assert(!std::is_same<index_gt<haversine_gt<>>::value_type, std::true_type>());
 
-    test3d<float>(index_gt<cos_gt<float>, point_id_t, std::uint32_t>{});
-    test3d<float>(index_gt<l2sq_gt<float>, point_id_t, std::uint32_t>{});
+    using big_point_id_t = std::int64_t;
+    test3d<float>(index_gt<cos_gt<float>, big_point_id_t, std::uint32_t>{});
+    test3d<float>(index_gt<l2sq_gt<float>, big_point_id_t, std::uint32_t>{});
 
-    test3d<double>(index_gt<cos_gt<double>, point_id_t, std::uint32_t>{});
-    test3d<double>(index_gt<l2sq_gt<double>, point_id_t, std::uint32_t>{});
+    test3d<double>(index_gt<cos_gt<double>, big_point_id_t, std::uint32_t>{});
+    test3d<double>(index_gt<l2sq_gt<double>, big_point_id_t, std::uint32_t>{});
 
     test3d<float>(punned_small_t::make(3, metric_kind_t::cos_k));
     test3d<float>(punned_small_t::make(3, metric_kind_t::l2sq_k));
@@ -161,11 +161,11 @@ int main(int, char**) {
     test3d_punned<float>(punned_small_t::make(3, metric_kind_t::cos_k));
     test3d_punned<float>(punned_small_t::make(3, metric_kind_t::l2sq_k));
 
-    test_sets(index_gt<jaccard_gt<std::int32_t, float>, point_id_t, std::uint32_t>{});
-    test_sets(index_gt<jaccard_gt<std::int64_t, float>, point_id_t, std::uint32_t>{});
+    test_sets(index_gt<jaccard_gt<std::int32_t, float>, big_point_id_t, std::uint32_t>{});
+    test_sets(index_gt<jaccard_gt<std::int64_t, float>, big_point_id_t, std::uint32_t>{});
 
-    test_sets_moved<index_gt<jaccard_gt<std::int32_t, float>, point_id_t, std::uint32_t>>();
-    test_sets_moved<index_gt<jaccard_gt<std::int64_t, float>, point_id_t, std::uint32_t>>();
+    test_sets_moved<index_gt<jaccard_gt<std::int32_t, float>, big_point_id_t, std::uint32_t>>();
+    test_sets_moved<index_gt<jaccard_gt<std::int64_t, float>, big_point_id_t, std::uint32_t>>();
 
     return 0;
 }

package/include/usearch/index.hpp

@@ -162,6 +162,10 @@ template <std::size_t multiple_ak> std::size_t divide_round_up(std::size_t num)
     return (num + multiple_ak - 1) / multiple_ak;
 }
 
+inline std::size_t divide_round_up(std::size_t num, std::size_t denominator) noexcept {
+    return (num + denominator - 1) / denominator;
+}
+
 inline std::size_t ceil2(std::size_t v) noexcept {
     v--;
     v |= v >> 1;
@@ -174,12 +178,16 @@ inline std::size_t ceil2(std::size_t v) noexcept {
     return v;
 }
 
-template <typename at> void misaligned_store(void* ptr, at v) noexcept { std::memcpy(ptr, &v, sizeof(v)); }
+template <typename at> void misaligned_store(void* ptr, at v) noexcept {
+    static_assert(!std::is_reference<at>::value);
+    std::memcpy(ptr, &v, sizeof(at));
+}
 
 /// @brief  Simply dereferencing misaligned pointers can be dangerous.
 template <typename at> at misaligned_load(void* ptr) noexcept {
+    static_assert(!std::is_reference<at>::value);
     at v;
-    std::memcpy(&v, ptr, sizeof(v));
+    std::memcpy(&v, ptr, sizeof(at));
     return v;
 }
 
@@ -640,7 +648,9 @@ template <typename allocator_at = std::allocator<char>> class visits_bitset_gt {
 
     void reset() noexcept {
         if (slots_)
-            allocator_t{}.deallocate((byte_t*)slots_, count_ * sizeof(slot_t)), slots_ = nullptr, count_ = 0;
+            allocator_t{}.deallocate((byte_t*)slots_, count_ * sizeof(slot_t));
+        slots_ = nullptr;
+        count_ = 0;
     }
 
     bool resize(std::size_t capacity) noexcept {
@@ -661,10 +671,8 @@ template <typename allocator_at = std::allocator<char>> class visits_bitset_gt {
     }
 
     visits_bitset_gt(visits_bitset_gt&& other) noexcept {
-        slots_ = other.slots_;
-        count_ = other.count_;
-        other.slots_ = nullptr;
-        other.count_ = 0;
+        slots_ = exchange(other.slots_, nullptr);
+        count_ = exchange(other.count_, 0);
     }
 
     visits_bitset_gt& operator=(visits_bitset_gt&& other) noexcept {
@@ -673,6 +681,9 @@ template <typename allocator_at = std::allocator<char>> class visits_bitset_gt {
         return *this;
     }
 
+    visits_bitset_gt(visits_bitset_gt const&) = delete;
+    visits_bitset_gt& operator=(visits_bitset_gt const&) = delete;
+
     inline bool test(std::size_t i) const noexcept { return slots_[i / bits_per_slot()] & (1ul << (i & bits_mask())); }
     inline void set(std::size_t i) noexcept { slots_[i / bits_per_slot()] |= (1ul << (i & bits_mask())); }
 
@@ -911,17 +922,18 @@ class sorted_buffer_gt {
         if (!new_elements)
             return false;
 
-        if (size_) {
+        if (size_)
             std::memcpy(new_elements, elements_, size_ * sizeof(element_t));
+        if (elements_)
             allocator.deallocate(elements_, capacity_);
-        }
+
         elements_ = new_elements;
         capacity_ = new_capacity;
         return true;
     }
 
     inline void insert_reserved(element_t&& element) noexcept {
-        std::size_t slot = std::lower_bound(elements_, elements_ + size_, element, &less) - elements_;
+        std::size_t slot = size_ ? std::lower_bound(elements_, elements_ + size_, element, &less) - elements_ : 0;
         std::size_t to_move = size_ - slot;
         element_t* source = elements_ + size_ - 1;
         for (; to_move; --to_move, --source)
@@ -934,7 +946,7 @@ class sorted_buffer_gt {
      *  @return `true` if the entry was added, `false` if it wasn't relevant enough.
      */
     inline bool insert(element_t&& element, std::size_t limit) noexcept {
-        std::size_t slot = std::lower_bound(elements_, elements_ + size_, element, &less) - elements_;
+        std::size_t slot = size_ ? std::lower_bound(elements_, elements_ + size_, element, &less) - elements_ : 0;
         if (slot == limit)
             return false;
         std::size_t to_move = size_ - slot - (size_ == limit);
@@ -975,10 +987,10 @@ class usearch_pack_m uint40_t {
 
   public:
     inline uint40_t() noexcept { std::memset(octets, 0, 5); }
-    inline uint40_t(std::uint32_t n) noexcept { std::memcpy(octets + 1, (char*)&n, 4), octets[0] = 0; }
-    inline uint40_t(std::uint64_t n) noexcept { std::memcpy(octets, (char*)&n + 3, 5); }
+    inline uint40_t(std::uint32_t n) noexcept { std::memcpy(octets, (char*)&n, 4); }
+    inline uint40_t(std::uint64_t n) noexcept { std::memcpy(octets, (char*)&n, 5); }
 #if defined(USEARCH_DEFINED_CLANG) && defined(USEARCH_DEFINED_APPLE)
-    inline uint40_t(std::size_t n) noexcept { std::memcpy(octets, (char*)&n + 3, 5); }
+    inline uint40_t(std::size_t n) noexcept { std::memcpy(octets, (char*)&n, 5); }
 #endif
 
     uint40_t(uint40_t&&) = default;
@@ -986,24 +998,40 @@ class usearch_pack_m uint40_t {
     uint40_t& operator=(uint40_t&&) = default;
     uint40_t& operator=(uint40_t const&) = default;
 
-    inline uint40_t& operator+=(std::uint32_t i) noexcept {
-        std::uint32_t& tail = *reinterpret_cast<std::uint32_t*>(octets + 1);
-        octets[0] += static_cast<unsigned char>((tail + i) < tail);
-        tail += i;
+    inline uint40_t& operator+=(std::uint32_t n) noexcept {
+        std::uint32_t& tail = *reinterpret_cast<std::uint32_t*>(octets);
+        octets[4] += static_cast<unsigned char>((tail + n) < tail);
+        tail += n;
+        return *this;
+    }
+
+    inline uint40_t& operator+=(std::size_t n) noexcept {
+        unsigned char* n_octets = reinterpret_cast<unsigned char*>(&n);
+        std::uint32_t& n_tail = *reinterpret_cast<std::uint32_t*>(&n);
+        std::uint32_t& tail = *reinterpret_cast<std::uint32_t*>(octets);
+        octets[4] += static_cast<unsigned char>((tail + n_tail) < tail);
+        tail += n_tail;
+        octets[4] += n_octets[4];
         return *this;
     }
 
+    inline uint40_t operator+(std::size_t n) noexcept {
+        uint40_t other(*this);
+        other += n;
+        return other;
+    }
+
     inline operator std::size_t() const noexcept {
         std::size_t result = 0;
-        std::memcpy((char*)&result + 3, octets, 5);
+        std::memcpy((char*)&result, octets, 5);
         return result;
     }
 
-    inline uint40_t& operator++() noexcept { return *this += 1; }
+    inline uint40_t& operator++() noexcept { return *this += 1u; }
 
     inline uint40_t operator++(int) noexcept {
         uint40_t old = *this;
-        *this += 1;
+        *this += 1u;
         return old;
     }
 };
@@ -1317,11 +1345,13 @@ class index_gt {
     struct member_ref_t {
         misaligned_ref_gt<label_t> label;
         vector_view_t vector;
+        id_t id;
     };
 
     struct member_cref_t {
         label_t label;
         vector_view_t vector;
+        id_t id;
     };
 
     template <typename ref_at, typename index_at> class member_iterator_gt {
@@ -1341,7 +1371,11 @@ class index_gt {
         using pointer = void;
         using reference = ref_t;
 
-        reference operator*() const noexcept { return ref_t(index_->node_with_id_(offset_)); }
+        reference operator*() const noexcept {
+            node_t node = index_->node_with_id_(offset_);
+            return {node.label(), node.vector_view(), static_cast<id_t>(offset_)};
+        }
+
         member_iterator_gt operator++(int) noexcept { return member_iterator_gt(index_, offset_ + 1); }
         member_iterator_gt operator--(int) noexcept { return member_iterator_gt(index_, offset_ - 1); }
         member_iterator_gt operator+(difference_type d) noexcept { return member_iterator_gt(index_, offset_ + d); }
@@ -1453,9 +1487,9 @@ class index_gt {
         node_t(node_t const&) = default;
         node_t& operator=(node_t const&) = default;
 
-        label_t label() const noexcept { return misaligned_load<label_t>(tape_); }
-        dim_t dim() const noexcept { return misaligned_load<dim_t>(tape_ + sizeof(label_t)); }
-        level_t level() const noexcept { return misaligned_load<level_t>(tape_ + sizeof(label_t) + sizeof(dim_t)); }
+        misaligned_ref_gt<label_t> label() const noexcept { return {tape_}; }
+        misaligned_ref_gt<dim_t> dim() const noexcept { return {tape_ + sizeof(label_t)}; }
+        misaligned_ref_gt<level_t> level() const noexcept { return {tape_ + sizeof(label_t) + sizeof(dim_t)}; }
 
         void label(label_t v) noexcept { return misaligned_store<label_t>(tape_, v); }
         void dim(dim_t v) noexcept { return misaligned_store<dim_t>(tape_ + sizeof(label_t), v); }
@@ -1605,8 +1639,11 @@ class index_gt {
 
         if (nodes_)
             node_allocator_t{}.deallocate(exchange(nodes_, nullptr), limits_.elements);
-        if (contexts_)
+        if (contexts_) {
+            for (std::size_t i = 0; i != limits_.threads(); ++i)
+                contexts_[i].~context_t();
             context_allocator_t{}.deallocate(exchange(contexts_, nullptr), limits_.threads());
+        }
         limits_ = index_limits_t{0, 0};
         capacity_ = 0;
         reset_view_();
@@ -1730,7 +1767,7 @@ class index_gt {
     };
 
     struct match_t {
-        member_cref_t element;
+        member_cref_t member;
         distance_t distance;
     };
 
@@ -1763,14 +1800,23 @@ class index_gt {
 
         inline operator std::size_t() const noexcept { return count; }
         inline std::size_t size() const noexcept { return count; }
-        inline match_t operator[](std::size_t i) const noexcept {
+        inline match_t operator[](std::size_t i) const noexcept { return at(i); }
+        inline bool contains(label_t label) const noexcept {
+            for (std::size_t i = 0; i != count; ++i)
+                if (at(i).member.label == label)
+                    return true;
+            return false;
+        }
+        inline match_t at(std::size_t i) const noexcept {
             candidate_t const* top_ordered = top_.data();
-            return {member_cref_t(index_.node_with_id_(top_ordered[i].id)), top_ordered[i].distance};
+            candidate_t candidate = top_ordered[i];
+            node_t node = index_.node_with_id_(candidate.id);
+            return {member_cref_t{node.label(), node.vector_view(), candidate.id}, candidate.distance};
         }
         inline std::size_t dump_to(label_t* labels, distance_t* distances) const noexcept {
             for (std::size_t i = 0; i != count; ++i) {
                 match_t result = operator[](i);
-                labels[i] = result.element.label;
+                labels[i] = result.member.label;
                 distances[i] = result.distance;
             }
             return count;
@@ -1778,7 +1824,7 @@ class index_gt {
         inline std::size_t dump_to(label_t* labels) const noexcept {
             for (std::size_t i = 0; i != count; ++i) {
                 match_t result = operator[](i);
-                labels[i] = result.element.label;
+                labels[i] = result.member.label;
             }
             return count;
         }
@@ -1849,6 +1895,7 @@ class index_gt {
             // TODO: Handle out of memory conditions
             search_to_insert_(closest_id, vector, level, config.expansion, context);
             closest_id = connect_new_node_(new_id, level, context);
+            reconnect_neighbor_nodes_(new_id, level, context);
         }
 
         // Normalize stats
@@ -1863,15 +1910,23 @@ class index_gt {
         return result;
     }
 
+    struct dummy_predicate_t {
+        constexpr bool operator()(match_t const&) const noexcept { return true; }
+    };
+
     /**
      *  @brief Searches for the closest elements to the given ::query. Thread-safe.
      *
      *  @param[in] query Contiguous range of scalars forming a vector view.
      *  @param[in] wanted The upper bound for the number of results to return.
      *  @param[in] config Configuration options for this specific operation.
+     *  @param[in] predicate Optional filtering predicate for `member_cref_t`.
      *  @return Smart object referencing temporary memory. Valid until next `search()` or `add()`.
      */
-    search_result_t search(vector_view_t query, std::size_t wanted, search_config_t config = {}) const noexcept {
+    template <typename predicate_at = dummy_predicate_t>
+    search_result_t search( //
+        vector_view_t query, std::size_t wanted, search_config_t config = {},
+        predicate_at&& predicate = dummy_predicate_t{}) const noexcept {
 
         context_t& context = contexts_[config.thread];
         top_candidates_t& top = context.top_candidates;
@@ -1886,7 +1941,7 @@ class index_gt {
         if (config.exact) {
             if (!top.reserve(wanted))
                 return result.failed("Out of memory!");
-            search_exact_(query, wanted, context);
+            search_exact_(query, wanted, context, std::forward<predicate_at>(predicate));
         } else {
             next_candidates_t& next = context.next_candidates;
             std::size_t expansion = (std::max)(config.expansion, wanted);
@@ -1897,7 +1952,7 @@ class index_gt {
 
             id_t closest_id = search_for_one_(entry_id_, query, max_level_, 0, context);
             // For bottom layer we need a more optimized procedure
-            if (!search_to_find_in_base_(closest_id, query, expansion, context))
+            if (!search_to_find_in_base_(closest_id, query, expansion, context, std::forward<predicate_at>(predicate)))
                 return result.failed("Out of memory!");
         }
 
@@ -1911,9 +1966,10 @@ class index_gt {
         return result;
     }
 
+    template <typename predicate_at = dummy_predicate_t>
     search_result_t search_around(                          //
         id_t hint, vector_view_t query, std::size_t wanted, //
-        search_config_t config = {}) const noexcept {
+        search_config_t config = {}, predicate_at&& predicate = dummy_predicate_t{}) const noexcept {
 
         context_t& context = contexts_[config.thread];
         top_candidates_t& top = context.top_candidates;
@@ -1933,7 +1989,7 @@ class index_gt {
         result.measurements = context.measurements_count;
         result.cycles = context.iteration_cycles;
 
-        search_to_find_in_base_(hint, query, expansion, context);
+        search_to_find_in_base_(hint, query, expansion, context, std::forward<predicate_at>(predicate));
         top.sort_ascending();
         top.shrink(wanted);
 
@@ -1944,6 +2000,10 @@ class index_gt {
         return result;
     }
 
+#pragma endregion
+
+#pragma region Metadata
+
     struct stats_t {
         std::size_t nodes;
         std::size_t edges;
@@ -1958,7 +2018,7 @@ class index_gt {
             node_t node = node_with_id_(i);
             std::size_t max_edges = node.level() * config_.connectivity + base_level_multiple_() * config_.connectivity;
             std::size_t edges = 0;
-            for (level_t level = 0; level != node.level(); ++level)
+            for (level_t level = 0; level <= node.level(); ++level)
                 edges += neighbors_(node, level).size();
 
             result.allocated_bytes += node_bytes_(node);
@@ -2007,6 +2067,8 @@ class index_gt {
         return total;
     }
 
+    std::size_t memory_usage_per_node(dim_t dim, level_t level) const noexcept { return node_bytes_(dim, level); }
+
     void change_metric(metric_t const& m) noexcept {
         metric_ = m;
         for (std::size_t i = 0; i != limits_.threads(); ++i)
@@ -2285,7 +2347,6 @@ class index_gt {
             std::size_t node_vector_bytes = dim * sizeof(scalar_t);
             nodes_[i] = node_t{tape, (scalar_t*)(tape + node_bytes - node_vector_bytes)};
             progress += node_bytes;
-            max_level_ = (std::max)(max_level_, level);
         }
 
         return {};
@@ -2396,7 +2457,6 @@ class index_gt {
 
         node_t new_node = node_with_id_(new_id);
         top_candidates_t& top = context.top_candidates;
-        std::size_t const connectivity_max = level ? config_.connectivity : pre_.connectivity_max_base;
 
         // Outgoing links from `new_id`:
         neighbors_ref_t new_neighbors = neighbors_(new_node, level);
@@ -2411,7 +2471,17 @@ class index_gt {
             }
         }
 
+        return new_neighbors[0];
+    }
+
+    void reconnect_neighbor_nodes_(id_t new_id, level_t level, context_t& context) usearch_noexcept_m {
+
+        node_t new_node = node_with_id_(new_id);
+        top_candidates_t& top = context.top_candidates;
+        neighbors_ref_t new_neighbors = neighbors_(new_node, level);
+
         // Reverse links from the neighbors:
+        std::size_t const connectivity_max = level ? config_.connectivity : pre_.connectivity_max_base;
         for (id_t close_id : new_neighbors) {
             node_t close_node = node_with_id_(close_id);
             node_lock_t close_lock = node_lock_(close_id);
@@ -2441,8 +2511,6 @@ class index_gt {
             for (std::size_t idx = 0; idx != top_view.size(); idx++)
                 close_header.push_back(top_view[idx].id);
         }
-
-        return new_neighbors[0];
     }
 
     level_t choose_random_level_(std::default_random_engine& level_generator) const noexcept {
@@ -2538,8 +2606,10 @@ class index_gt {
      *          Doesn't lock any nodes, assuming read-only simultaneous access.
      *  @return `true` if procedure succeeded, `false` if run out of memory.
      */
+    template <typename predicate_at>
     bool search_to_find_in_base_( //
-        id_t start_id, vector_view_t query, std::size_t expansion, context_t& context) const noexcept {
+        id_t start_id, vector_view_t query, std::size_t expansion, context_t& context,
+        predicate_at&& predicate) const noexcept {
 
         visits_bitset_t& visits = context.visits;
         next_candidates_t& next = context.next_candidates; // pop min, push
@@ -2573,14 +2643,19 @@ class index_gt {
                     continue;
 
                 visits.set(successor_id);
-                distance_t successor_dist = context.measure(query, node_with_id_(successor_id));
+                node_t successor = node_with_id_(successor_id);
+                distance_t successor_dist = context.measure(query, successor);
 
                 if (top.size() < top_limit || successor_dist < radius) {
                     // This can substantially grow our priority queue:
                     next.insert({-successor_dist, successor_id});
-                    // This will automatically evict poor matches:
-                    top.insert({successor_dist, successor_id}, top_limit);
-                    radius = top.top().distance;
+                    if (predicate( //
+                            match_t{member_cref_t{successor.label(), successor.vector_view(), successor_id},
+                                    successor_dist})) {
+                        // This will automatically evict poor matches:
+                        top.insert({successor_dist, successor_id}, top_limit);
+                        radius = top.top().distance;
+                    }
                 }
             }
         }
@@ -2591,12 +2666,21 @@ class index_gt {
     /**
      *  @brief  Iterates through all managed vectors, without actually touching the index.
      */
-    void search_exact_(vector_view_t query, std::size_t count, context_t& context) const noexcept {
+    template <typename predicate_at>
+    void search_exact_(                                             //
+        vector_view_t query, std::size_t count, context_t& context, //
+        predicate_at&& predicate) const noexcept {
+
         top_candidates_t& top = context.top_candidates;
         top.clear();
         top.reserve(count);
-        for (std::size_t i = 0; i != size(); ++i)
-            top.insert({context.measure(query, node_with_id_(i)), static_cast<id_t>(i)}, count);
+        for (std::size_t i = 0; i != size(); ++i) {
+            id_t id = static_cast<id_t>(i);
+            node_t node = node_with_id_(i);
+            distance_t distance = context.measure(query, node);
+            if (predicate(match_t{member_cref_t{node.label(), node.vector_view(), id}, distance}))
+                top.insert(candidate_t{distance, id}, count);
+        }
     }
 
     void prefetch_neighbors_(neighbors_ref_t, visits_bitset_t const&) const noexcept {}

package/include/usearch/index_punned_helpers.hpp

@@ -295,6 +295,8 @@ class f8_bits_t {
     inline explicit operator std::int32_t() const noexcept { return int8_; }
     inline explicit operator std::int64_t() const noexcept { return int8_; }
 
+    inline f8_bits_t(f16_t v)
+        : int8_(usearch::clamp<std::int8_t>(static_cast<std::int8_t>(v * divisor_k), min_k, max_k)) {}
     inline f8_bits_t(float v)
         : int8_(usearch::clamp<std::int8_t>(static_cast<std::int8_t>(v * divisor_k), min_k, max_k)) {}
     inline f8_bits_t(double v)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "usearch",
-    "version": "0.19.3",
+    "version": "0.20.0",
     "description": "Smaller & Faster Single-File Vector Search Engine from Unum",
     "author": "Ashot Vardanian",
     "license": "Apache 2.0",