usearch 0.22.3 → 1.0.0

package/cpp/README.md

@@ -1,4 +1,4 @@
-# USearch C++ Inteface
+# USearch for C++
 
 ## Installation
 
@@ -18,15 +18,15 @@ This covers 90% of use-cases.
 ```c++
 using namespace unum::usearch;
 
-index_gt<cos_gt<float>> index;
+index_gt<metric_cos_gt<float>> index;
 float vec[3] = {0.1, 0.3, 0.2};
 
 index.reserve(10);
-index.add(/* label: */ 42, /* vector: */ {&vec[0], 3});
+index.add(/* key: */ 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].element.key, results[i].element.vector, results[i].distance;
 ```
 
 The `add` is thread-safe for concurrent index construction.
@@ -44,8 +44,8 @@ index.view("index.usearch"); // Memory-mapping from disk
 For advanced users, more compile-time abstractions are available.
 
 ```cpp
-template <typename metric_at = ip_gt<float>,            //
-          typename label_at = std::size_t,              // `uint32_t`, `uuid_t`...
+template <typename metric_at = metric_ip_gt<float>,            //
+          typename key_at = std::size_t,              // `uint32_t`, `uuid_t`...
           typename id_at = std::uint32_t,               // `uint40_t`, `uint64_t`...
           typename scalar_at = float,                   // `double`, `half`, `char`...
           typename allocator_at = std::allocator<char>> //
@@ -63,15 +63,15 @@ struct custom_metric_t {
 
 The following distances are pre-packaged:
 
-- `cos_gt<scalar_t>` for "Cosine" or "Angular" distance.
-- `ip_gt<scalar_t>` for "Inner Product" or "Dot Product" distance.
-- `l2sq_gt<scalar_t>` for the squared "L2" or "Euclidean" distance.
-- `jaccard_gt<scalar_t>` for "Jaccard" distance between two ordered sets of unique elements.
-- `hamming_gt<scalar_t>` for "Hamming" distance, as the number of shared bits in hashes.
-- `tanimoto_gt<scalar_t>` for "Tanimoto" coefficient for bit-strings.
-- `sorensen_gt<scalar_t>` for "Dice-Sorensen" coefficient for bit-strings.
-- `pearson_correlation_gt<scalar_t>` for "Pearson" correlation between probability distributions.
-- `haversine_gt<scalar_t>` for "Haversine" or "Great Circle" distance between coordinates used in GIS applications.
+- `metric_cos_gt<scalar_t>` for "Cosine" or "Angular" distance.
+- `metric_ip_gt<scalar_t>` for "Inner Product" or "Dot Product" distance.
+- `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.
+- `metric_tanimoto_gt<scalar_t>` for "Tanimoto" coefficient for bit-strings.
+- `metric_sorensen_gt<scalar_t>` for "Dice-Sorensen" coefficient for bit-strings.
+- `metric_pearson_gt<scalar_t>` for "Pearson" correlation between probability distributions.
+- `metric_haversine_gt<scalar_t>` for "Haversine" or "Great Circle" distance between coordinates used in GIS applications.
 
 ## Multi-Threading
 
@@ -81,7 +81,7 @@ Instead of spawning additional threads within USearch, we focus on the thread sa
 ```cpp
 #pragma omp parallel for
     for (std::size_t i = 0; i < n; ++i)
-        native.add(label, span_t{vector, dims}, add_config_t { .thread = omp_get_thread_num() });
+        native.add(key, span_t{vector, dims}, index_update_config_t { .thread = omp_get_thread_num() });
 ```
 
 During initialization, we allocate enough temporary memory for all the cores on the machine.

package/cpp/bench.cpp

@@ -1,6 +1,6 @@
 /**
  *  @brief A benchmark for the construction speed of the USearch index
- *  and the resulting accuracy (recall) of the Approximate Nearest Neighbors
+ *  and the resulting quantization (recall) of the Approximate Nearest Neighbors
  *  Search queries.
  */
 
@@ -44,14 +44,13 @@
 
 #include <simsimd/simsimd.h>
 
-#include <usearch/index_punned_dense.hpp>
+#include <usearch/index_dense.hpp>
 
 using namespace unum::usearch;
 using namespace unum;
 
-using label_t = std::int64_t;
-using vector_id_t = std::uint32_t;
-using vector_view_t = span_gt<float const>;
+using compressed_slot_t = std::uint32_t;
+using float_span_t = span_gt<float const>;
 
 template <typename element_at>
 std::size_t offset_of(element_at const* begin, element_at const* end, element_at v) noexcept {
@@ -151,10 +150,10 @@ struct vectors_view_gt {
 template <typename scalar_at, typename vector_id_at> //
 struct persisted_dataset_gt {
     using scalar_t = scalar_at;
-    using vector_id_t = vector_id_at;
+    using compressed_slot_t = vector_id_at;
     persisted_matrix_gt<scalar_t> vectors_;
     persisted_matrix_gt<scalar_t> queries_;
-    persisted_matrix_gt<vector_id_t> neighborhoods_;
+    persisted_matrix_gt<compressed_slot_t> neighborhoods_;
     std::size_t vectors_to_skip_{};
     std::size_t vectors_to_take_{};
 
@@ -174,7 +173,7 @@ struct persisted_dataset_gt {
     std::size_t neighborhood_size() const noexcept { return neighborhoods_.cols; }
     scalar_t const* vector(std::size_t i) const noexcept { return vectors_.row(i + vectors_to_skip_); }
     scalar_t const* query(std::size_t i) const noexcept { return queries_.row(i); }
-    vector_id_t const* neighborhood(std::size_t i) const noexcept { return neighborhoods_.row(i); }
+    compressed_slot_t const* neighborhood(std::size_t i) const noexcept { return neighborhoods_.row(i); }
 
     std::size_t vectors_count() const noexcept {
         return vectors_to_take_ ? vectors_to_take_ : (vectors_.rows - vectors_to_skip_);
@@ -187,11 +186,11 @@ struct persisted_dataset_gt {
 template <typename scalar_at, typename vector_id_at> //
 struct in_memory_dataset_gt {
     using scalar_t = scalar_at;
-    using vector_id_t = vector_id_at;
+    using compressed_slot_t = vector_id_at;
 
     std::vector<scalar_t> vectors_{};
     std::vector<scalar_t> queries_{};
-    std::vector<vector_id_t> neighborhoods_{};
+    std::vector<compressed_slot_t> neighborhoods_{};
     std::size_t dimensions_{};
     std::size_t vectors_count_{};
     std::size_t neighborhood_size_{};
@@ -210,13 +209,13 @@ struct in_memory_dataset_gt {
     std::size_t neighborhood_size() const noexcept { return 1; }
     scalar_t const* vector(std::size_t i) const noexcept { return vectors_.data() + i * dimensions_; }
     scalar_t const* query(std::size_t i) const noexcept { return queries_.data() + i * dimensions_; }
-    vector_id_t const* neighborhood(std::size_t i) const noexcept {
+    compressed_slot_t const* neighborhood(std::size_t i) const noexcept {
         return neighborhoods_.data() + i * neighborhood_size_;
     }
 
     scalar_t* vector(std::size_t i) noexcept { return vectors_.data() + i * dimensions_; }
     scalar_t* query(std::size_t i) noexcept { return queries_.data() + i * dimensions_; }
-    vector_id_t* neighborhood(std::size_t i) noexcept { return neighborhoods_.data() + i * neighborhood_size_; }
+    compressed_slot_t* neighborhood(std::size_t i) noexcept { return neighborhoods_.data() + i * neighborhood_size_; }
 
     vectors_view_gt<scalar_t> vectors_view() const noexcept { return {vector(0), vectors_count(), dimensions()}; }
 };
@@ -279,7 +278,7 @@ struct running_stats_printer_t {
 };
 
 template <typename index_at, typename vector_id_at, typename real_at>
-void index_many(index_at& native, std::size_t n, vector_id_at const* ids, real_at const* vectors, std::size_t dims) {
+void index_many(index_at& index, std::size_t n, vector_id_at const* ids, real_at const* vectors, std::size_t dims) {
 
     running_stats_printer_t printer{n, "Indexing"};
 
@@ -287,13 +286,12 @@ void index_many(index_at& native, std::size_t n, vector_id_at const* ids, real_a
 #pragma omp parallel for schedule(static, 32)
 #endif
     for (std::size_t i = 0; i < n; ++i) {
-        add_config_t config;
+        index_update_config_t config;
 #if USEARCH_USE_OPENMP
         config.thread = omp_get_thread_num();
 #endif
-        config.store_vector = true;
-        vector_view_t vector{vectors + dims * i, dims};
-        native.add(ids[i], vector, config);
+        float_span_t vector{vectors + dims * i, dims};
+        index.add(ids[i], vector, config);
         printer.progress++;
         if (config.thread == 0)
             printer.refresh();
@@ -302,7 +300,7 @@ void index_many(index_at& native, std::size_t n, vector_id_at const* ids, real_a
 
 template <typename index_at, typename vector_id_at, typename real_at>
 void search_many( //
-    index_at& native, std::size_t n, real_at const* vectors, std::size_t dims, std::size_t wanted, vector_id_at* ids,
+    index_at& index, std::size_t n, real_at const* vectors, std::size_t dims, std::size_t wanted, vector_id_at* ids,
     real_at* distances) {
 
     std::string name = "Search " + std::to_string(wanted);
@@ -312,12 +310,12 @@ void search_many( //
 #pragma omp parallel for schedule(static, 32)
 #endif
     for (std::size_t i = 0; i < n; ++i) {
-        search_config_t config;
+        index_search_config_t config;
 #if USEARCH_USE_OPENMP
         config.thread = omp_get_thread_num();
 #endif
-        vector_view_t vector{vectors + dims * i, dims};
-        native.search(vector, wanted, config).dump_to(ids + wanted * i, distances + wanted * i);
+        float_span_t vector{vectors + dims * i, dims};
+        index.search(vector, wanted, config).dump_to(ids + wanted * i, distances + wanted * i);
         printer.progress++;
         if (config.thread == 0)
             printer.refresh();
@@ -326,22 +324,20 @@ void search_many( //
 
 template <typename dataset_at, typename index_at> //
 static void single_shot(dataset_at& dataset, index_at& index, bool construct = true) {
-    using label_t = typename index_at::label_t;
     using distance_t = typename index_at::distance_t;
-    using join_result_t = typename index_at::join_result_t;
-    constexpr label_t missing_label = std::numeric_limits<label_t>::max();
+    constexpr default_key_t missing_key = std::numeric_limits<default_key_t>::max();
 
     std::printf("\n");
     std::printf("------------\n");
     if (construct) {
         // Perform insertions, evaluate speed
-        std::vector<label_t> ids(dataset.vectors_count());
+        std::vector<default_key_t> ids(dataset.vectors_count());
         std::iota(ids.begin(), ids.end(), 0);
         index_many(index, dataset.vectors_count(), ids.data(), dataset.vector(0), dataset.dimensions());
     }
 
     // Perform search, evaluate speed
-    std::vector<label_t> found_neighbors(dataset.queries_count() * dataset.neighborhood_size());
+    std::vector<default_key_t> found_neighbors(dataset.queries_count() * dataset.neighborhood_size());
     std::vector<distance_t> found_distances(dataset.queries_count() * dataset.neighborhood_size());
     search_many(index, dataset.queries_count(), dataset.query(0), dataset.dimensions(), dataset.neighborhood_size(),
                 found_neighbors.data(), found_distances.data());
@@ -352,39 +348,39 @@ static void single_shot(dataset_at& dataset, index_at& index, bool construct = t
         auto expected = dataset.neighborhood(i);
         auto received = found_neighbors.data() + i * dataset.neighborhood_size();
         recall_at_1 += expected[0] == received[0];
-        recall_full += contains(received, received + dataset.neighborhood_size(), label_t{expected[0]});
+        recall_full += contains(received, received + dataset.neighborhood_size(), default_key_t{expected[0]});
     }
 
     std::printf("Recall@1 %.2f %%\n", recall_at_1 * 100.f / dataset.queries_count());
     std::printf("Recall %.2f %%\n", recall_full * 100.f / dataset.queries_count());
 
     // Perform joins
-    std::vector<label_t> man_to_woman(dataset.vectors_count());
-    std::vector<label_t> woman_to_man(dataset.vectors_count());
+    std::vector<default_key_t> man_to_woman(dataset.vectors_count());
+    std::vector<default_key_t> woman_to_man(dataset.vectors_count());
     std::size_t join_attempts = 0;
     {
         index_at& men = index;
         index_at women = index.copy().index;
-        std::fill(man_to_woman.begin(), man_to_woman.end(), missing_label);
-        std::fill(woman_to_man.begin(), woman_to_man.end(), missing_label);
+        std::fill(man_to_woman.begin(), man_to_woman.end(), missing_key);
+        std::fill(woman_to_man.begin(), woman_to_man.end(), missing_key);
         {
             executor_default_t executor(index.limits().threads());
             running_stats_printer_t printer{1, "Join"};
-            join_result_t result = index_at::join(          //
-                men, women, join_config_t{executor.size()}, //
-                man_to_woman.data(), woman_to_man.data(),   //
+            join_result_t result = join(                          //
+                men, women, index_join_config_t{executor.size()}, //
+                man_to_woman.data(), woman_to_man.data(),         //
                 executor, [&](std::size_t progress, std::size_t total) {
                     if (progress % 1000 == 0)
                         printer.print(progress, total);
                 });
-            join_attempts = result.cycles;
+            join_attempts = result.visited_members;
         }
     }
     // Evaluate join quality
     std::size_t recall_join = 0, unmatched_count = 0;
     for (std::size_t i = 0; i != index.size(); ++i) {
-        recall_join += man_to_woman[i] == static_cast<label_t>(i);
-        unmatched_count += man_to_woman[i] == missing_label;
+        recall_join += man_to_woman[i] == static_cast<default_key_t>(i);
+        unmatched_count += man_to_woman[i] == missing_key;
     }
     std::printf("Recall Joins %.2f %%\n", recall_join * 100.f / index.size());
     std::printf("Unmatched %.2f %% (%zu items)\n", unmatched_count * 100.f / index.size(), unmatched_count);
@@ -453,10 +449,9 @@ struct args_t {
     bool help = false;
 
     bool big = false;
-    bool native = false;
 
     bool quantize_f16 = false;
-    bool quantize_f8 = false;
+    bool quantize_i8 = false;
     bool quantize_b1 = false;
 
     bool metric_ip = false;
@@ -483,11 +478,11 @@ struct args_t {
         return metric_kind_t::ip_k;
     }
 
-    scalar_kind_t accuracy() const noexcept {
+    scalar_kind_t quantization() const noexcept {
         if (quantize_f16)
             return scalar_kind_t::f16_k;
-        if (quantize_f8)
-            return scalar_kind_t::f8_k;
+        if (quantize_i8)
+            return scalar_kind_t::i8_k;
         if (quantize_b1)
             return scalar_kind_t::b1x8_k;
         return scalar_kind_t::f32_k;
@@ -497,15 +492,16 @@ 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) {
 
-    scalar_kind_t accuracy = args.accuracy();
-    std::printf("-- Accuracy: %s\n", scalar_kind_name(accuracy));
+    scalar_kind_t quantization = args.quantization();
+    std::printf("-- Quantization: %s\n", scalar_kind_name(quantization));
 
     metric_kind_t kind = args.metric();
     std::printf("-- Metric: %s\n", metric_kind_name(kind));
 
-    index_at index = index_at::make(dataset.dimensions(), kind, config, accuracy);
+    metric_punned_t metric(dataset.dimensions(), kind, quantization);
+    index_at index = index_at::make(metric, config);
     index.reserve(limits);
-    std::printf("-- Hardware acceleration: %s\n", isa_name(index.metric().isa_));
+    std::printf("-- Hardware acceleration: %s\n", isa_name(index.metric().isa_kind()));
     std::printf("Will benchmark in-memory\n");
 
     single_shot(dataset, index, true);
@@ -535,74 +531,6 @@ void run_typed(dataset_at& dataset, args_t const& args, index_config_t config, i
     single_shot(dataset, index_view, false);
 }
 
-template <typename neighbor_id_at, typename dataset_at> //
-void run_big_or_small(dataset_at& dataset, args_t const& args, index_config_t config, index_limits_t limits) {
-    if (args.native) {
-        if (args.metric_cos) {
-            std::printf("-- Metric: Angular\n");
-            run_typed<index_gt<cos_gt<float>, label_t, neighbor_id_at>>(dataset, args, config, limits);
-        } else if (args.metric_l2) {
-            std::printf("-- Metric: Euclidean\n");
-            run_typed<index_gt<l2sq_gt<float>, label_t, neighbor_id_at>>(dataset, args, config, limits);
-        } else if (args.metric_haversine) {
-            std::printf("-- Metric: Haversine\n");
-            run_typed<index_gt<haversine_gt<float>, label_t, neighbor_id_at>>(dataset, args, config, limits);
-        } else {
-            std::printf("-- Metric: Inner Product\n");
-            run_typed<index_gt<ip_gt<float>, label_t, neighbor_id_at>>(dataset, args, config, limits);
-        }
-    } else
-        run_punned<index_punned_dense_gt<label_t, neighbor_id_at>>(dataset, args, config, limits);
-}
-
-void report_alternative_setups() {
-    using set_member_t = std::uint32_t;
-    using sets_index_t = index_gt<jaccard_gt<set_member_t>, label_t, std::uint32_t>;
-    set_member_t set_a[] = {10, 12, 15};
-    set_member_t set_b[] = {11, 12, 15, 16};
-    sets_index_t index;
-    index.reserve(100);
-    index.add(10, span_gt<set_member_t const>{&set_a[0], 3});
-    index.add(11, span_gt<set_member_t const>{&set_b[0], 4});
-    exit(0);
-}
-
-void report_expected_losses(persisted_dataset_gt<float, vector_id_t> const& dataset) {
-
-    auto vec1 = dataset.vector(0);
-    auto vec2 = dataset.query(0);
-    std::vector<f16_t> vec1f16(dataset.dimensions());
-    std::vector<f16_t> vec2f16(dataset.dimensions());
-    std::transform(vec1, vec1 + dataset.dimensions(), vec1f16.data(), [](float v) { return v; });
-    std::transform(vec2, vec2 + dataset.dimensions(), vec2f16.data(), [](float v) { return v; });
-    std::vector<f8_bits_t> vec1f8(dataset.dimensions());
-    std::vector<f8_bits_t> vec2f8(dataset.dimensions());
-    std::transform(vec1, vec1 + dataset.dimensions(), vec1f8.data(), [](float v) { return v; });
-    std::transform(vec2, vec2 + dataset.dimensions(), vec2f8.data(), [](float v) { return v; });
-
-#if 0
-    auto ip_default = ip_gt<float>{}(vec1, vec2, dataset.dimensions());
-    auto ip_f16 = ip_gt<f16_t, float>{}(vec1f16.data(), vec2f16.data(), dataset.dimensions());
-    auto ip_f8 = ip_gt<f8_bits_t, float>{}(vec1f8.data(), vec2f8.data(), dataset.dimensions());
-
-#if defined(__AVX512F__)
-    auto ip_f16avx512 = 1.f - simsimd_dot_f16x16avx512((simsimd_f16_t const*)vec1f16.data(),
-                                                       (simsimd_f16_t const*)vec2f16.data(), dataset.dimensions());
-#endif
-#if defined(__ARM_FEATURE_SVE)
-    auto ip_sve = 1.f - simsimd_dot_f32sve(vec1, vec2, dataset.dimensions());
-    auto ip_f16sve = 1.f - simsimd_dot_f16sve((simsimd_f16_t const*)vec1f16.data(),
-                                              (simsimd_f16_t const*)vec2f16.data(), dataset.dimensions());
-#endif
-#if defined(__ARM_NEON)
-    auto ip_neon = 1.f - simsimd_dot_f32x4neon(vec1, vec2, dataset.dimensions());
-    auto ip_f16neon = 1.f - simsimd_dot_f16x8neon((simsimd_f16_t const*)vec1f16.data(),
-                                                  (simsimd_f16_t const*)vec2f16.data(), dataset.dimensions());
-#endif
-    exit(0);
-#endif
-}
-
 int main(int argc, char** argv) {
 
     // Print backtrace if something goes wrong.
@@ -624,9 +552,8 @@ int main(int argc, char** argv) {
         (option("--rows-skip") & value("integer", args.vectors_to_skip)).doc("Number of vectors to skip"),
         (option("--rows-take") & value("integer", args.vectors_to_take)).doc("Number of vectors to take"),
         ( //
-            option("--native").set(args.native).doc("Use raw templates instead of type-punned classes") |
             option("-f16", "--f16quant").set(args.quantize_f16).doc("Enable `f16_t` quantization") |
-            option("-f8", "--f8quant").set(args.quantize_f8).doc("Enable `f8_t` quantization") |
+            option("-i8", "--i8quant").set(args.quantize_i8).doc("Enable `i8_t` quantization") |
             option("-b1", "--b1quant").set(args.quantize_b1).doc("Enable `b1x8_t` quantization")),
         ( //
             option("--ip").set(args.metric_ip).doc("Choose Inner Product metric") |
@@ -648,7 +575,7 @@ int main(int argc, char** argv) {
     }
 
 #if USEARCH_USE_OPENMP
-    // Instead of relying on `multithreaded` from "index_punned_dense.hpp" we will use OpenMP
+    // Instead of relying on `multithreaded` from "index_dense.hpp" we will use OpenMP
     // to better estimate statistics between tasks batches, without having to recreate
     // the threads.
     omp_set_dynamic(true);
@@ -661,7 +588,7 @@ int main(int argc, char** argv) {
     std::printf("-- Query vectors path: %s\n", args.path_queries.c_str());
     std::printf("-- Ground truth neighbors path: %s\n", args.path_neighbors.c_str());
 
-    persisted_dataset_gt<float, vector_id_t> dataset{
+    persisted_dataset_gt<float, compressed_slot_t> dataset{
         args.path_vectors.c_str(),   //
         args.path_queries.c_str(),   //
         args.path_neighbors.c_str(), //
@@ -676,27 +603,24 @@ int main(int argc, char** argv) {
     // report_alternative_setups();
     // report_expected_losses(dataset);
 
-    index_config_t config;
-    config.connectivity = args.connectivity;
-    // config.expansion_add = args.expansion_add;
-    // config.expansion_search = args.expansion_search;
+    index_dense_config_t config(args.connectivity, args.expansion_add, args.expansion_search);
     index_limits_t limits;
     limits.threads_add = limits.threads_search = args.threads;
     limits.members = dataset.vectors_count();
 
     std::printf("- Index: \n");
     std::printf("-- Connectivity: %zu\n", config.connectivity);
-    // std::printf("-- Expansion @ Add: %zu\n", config.expansion_add);
-    // std::printf("-- Expansion @ Search: %zu\n", config.expansion_search);
+    std::printf("-- Expansion @ Add: %zu\n", config.expansion_add);
+    std::printf("-- Expansion @ Search: %zu\n", config.expansion_search);
 
     if (args.big)
 #ifdef USEARCH_64BIT_ENV
-        run_big_or_small<uint40_t>(dataset, args, config, limits);
+        run_punned<index_dense_gt<default_key_t, uint40_t>>(dataset, args, config, limits);
 #else
         std::printf("Error: Don't use 40 bit identifiers in 32bit environment\n");
 #endif
     else
-        run_big_or_small<std::uint32_t>(dataset, args, config, limits);
+        run_punned<index_dense_gt<default_key_t, std::uint32_t>>(dataset, args, config, limits);
 
     return 0;
 }