usearch 0.9.7 → 0.11.0

package/.github/workflows/release.yml

@@ -231,7 +231,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
           file: docs.tar.gz
-          asset_name: docs.tar.gz
+          update_latest_release: true
 
   deploy_docs_pages:
     name: Deploy GitHub Pages

package/.gitmodules

@@ -4,3 +4,6 @@
 [submodule "fp16"]
 	path = fp16
 	url = https://github.com/maratyszcza/fp16
+[submodule "robin-map"]
+	path = robin-map
+	url = https://github.com/tessil/robin-map

package/.vscode/settings.json

@@ -125,10 +125,12 @@
         "OPENMP",
         "preprocess",
         "Quickstart",
+        "rtype",
         "simsimd",
         "SLOC",
         "usearch",
         "usecases"
     ],
+    "autoDocstring.docstringFormat": "sphinx",
     "java.configuration.updateBuildConfiguration": "interactive"
 }

package/Cargo.toml

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

package/Package.swift

@@ -20,6 +20,7 @@ let package = Package(
                 .headerSearchPath("../include/"),
                 .headerSearchPath("../src/"),
                 .headerSearchPath("../fp16/include/"),
+                .headerSearchPath("../robin-map/include/"),
                 .headerSearchPath("../simismd/include/")
             ]
         ),

package/README.md

@@ -308,7 +308,7 @@ def python_dot(a, b, n, m):
         c += a_array[i] * b_array[i]
     return c
 
-index = Index(ndim=ndim, metric_pointer=python_dot.address)
+index = Index(ndim=ndim, metric=python_dot.address)
 ```
 
 [numba]: https://numba.readthedocs.io/en/stable/reference/jit-compilation.html#c-callbacks

package/VERSION

@@ -1 +1 @@
-0.9.7
+0.11.0

package/binding.gyp

@@ -10,6 +10,7 @@
                 "include",
                 "src",
                 "fp16/include",
+                "robin-map/include",
                 "simsimd/include"
             ],
             "dependencies": [
@@ -23,9 +24,9 @@
                 "MACOSX_DEPLOYMENT_TARGET": "10.15"
             },
             "msvs_settings": {
-                "VCCLCompilerTool": { 
-                    "ExceptionHandling": 1, 
-                    "AdditionalOptions": [ "-std:c++11" ]
+                "VCCLCompilerTool": {
+                    "ExceptionHandling": 1,
+                    "AdditionalOptions": ["-std:c++11"]
                 }
             }
         }

package/build.gradle

@@ -45,7 +45,7 @@ model {
                         include "**/*.cpp"
                     }
                     exportedHeaders {
-                        srcDirs "include", "src", "fp16/include", "simsimd/include", "${Jvm.current().javaHome}/include"
+                        srcDirs "include", "src", "fp16/include", "robin-map/include", "simsimd/include", "${Jvm.current().javaHome}/include"
                     }
                 }
             }

package/build.rs

@@ -7,6 +7,7 @@ fn main() {
         .include("rust")
         .include("src")
         .include("fp16/include")
+        .include("robin-map/include")
         .include("simsimd/include")
         .compile("usearch");
 

package/conanfile.py

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

package/docs/compilation.md

@@ -63,8 +63,7 @@ Benchmarking:
 ## Python
 
 ```sh
-pip install -e .
-pytest python/scripts/test.py
+pip install -e . && pytest python/scripts/test.py
 ```
 
 Linting:
@@ -131,7 +130,11 @@ g++ -shared -o USearchJNI.dll cloud_unum_usearch_Index.o -Wl,--add-stdcall-alias
 
 # MacOS
 g++ -std=c++11 -c -fPIC \
-    -I../../../../include -I../../../../src -I../../../../fp16/include -I../../../../simsimd/include \
+    -I../../../../include \
+    -I../../../../src \
+    -I../../../../fp16/include \
+    -I../../../../robin-map/include \
+    -I../../../../simsimd/include \
     -I${JAVA_HOME}/include -I${JAVA_HOME}/include/darwin cloud_unum_usearch_Index.cpp -o cloud_unum_usearch_Index.o
 g++ -dynamiclib -o libusearch.dylib cloud_unum_usearch_Index.o -lc
 # Run linking to that directory

package/include/usearch/usearch.hpp

@@ -9,6 +9,18 @@
 #ifndef UNUM_USEARCH_H
 #define UNUM_USEARCH_H
 
+#if !defined(USEARCH_VERSION_MAJOR)
+#define USEARCH_VERSION_MAJOR 0
+#endif
+
+#if !defined(USEARCH_VERSION_MINOR)
+#define USEARCH_VERSION_MINOR 0
+#endif
+
+#if !defined(USEARCH_VERSION_PATCH)
+#define USEARCH_VERSION_PATCH 0
+#endif
+
 // Inferring C++ version
 #if ((defined(_MSVC_LANG) && _MSVC_LANG >= 201703L) || __cplusplus >= 201703L)
 #define USEARCH_IS_CPP17
@@ -61,7 +73,7 @@
 #include <mutex>     // `std::unique_lock` - replacement candidate
 #include <random>    // `std::default_random_engine` - replacement candidate
 #include <stdexcept> // `std::runtime_exception`
-#include <utility>   // `std::exchange`, `std::pair`
+#include <utility>   // `std::pair`
 #include <vector>    // `std::vector`
 
 // Prefetching
@@ -125,12 +137,20 @@ inline std::size_t ceil2(std::size_t v) noexcept {
 
 template <typename at> void misaligned_store(void* ptr, at v) noexcept { std::memcpy(ptr, &v, sizeof(v)); }
 
+/// @brief  Simply dereferencing misaligned pointers can be dangerous.
 template <typename at> at misaligned_load(void* ptr) noexcept {
     at v;
     std::memcpy(&v, ptr, sizeof(v));
     return v;
 }
 
+/// @brief  The `std::exchange` alternative for C++11.
+template <typename at, typename other_at = at> at exchange(at& obj, other_at&& new_value) {
+    at old_value = std::move(obj);
+    obj = std::forward<other_at>(new_value);
+    return old_value;
+}
+
 template <typename at> class misaligned_ref_gt {
     byte_t* ptr_;
 
@@ -141,10 +161,8 @@ template <typename at> class misaligned_ref_gt {
         misaligned_store<at>(ptr_, v);
         return *this;
     }
-    misaligned_ref_gt& operator=(at v) noexcept {
-        misaligned_store<at>(ptr_, v);
-        return *this;
-    }
+
+    void reset(byte_t* ptr) noexcept { ptr_ = ptr; }
 };
 
 template <typename at> class misaligned_ptr_gt {
@@ -781,6 +799,13 @@ template <typename scalar_at> class span_gt {
 constexpr std::size_t default_connectivity() { return 16; }
 constexpr std::size_t default_expansion_add() { return 128; }
 constexpr std::size_t default_expansion_search() { return 64; }
+constexpr std::size_t default_allocator_entry_bytes() { return 64; }
+
+/**
+ *  @brief  The "magic" sequence helps infer the type of the file.
+ *          USearch indexes start with the "unumusearch" string.
+ */
+static constexpr char const* default_magic() { return "unumusearch"; }
 
 /**
  *  @brief  Configuration settings for the index construction.
@@ -808,6 +833,7 @@ struct config_t {
     std::size_t max_elements = 0;
     std::size_t max_threads_add = 1;
     std::size_t max_threads_search = 1;
+    std::size_t vector_alignment = 1;
 
     std::size_t max_threads() const noexcept { return (std::max)(max_threads_add, max_threads_search); }
     std::size_t concurrency() const noexcept { return (std::min)(max_threads_add, max_threads_search); }
@@ -825,6 +851,67 @@ struct search_config_t {
     bool exact{};
 };
 
+using file_header_t = byte_t[64];
+
+/**
+ *  @brief  Serialized binary representations of the USearch index start with metadata.
+ *          Metadata is parsed into a `file_head_t`, containing the USearch package version,
+ *          and the properties of the index.
+ */
+struct file_head_t {
+
+    using magic_t = char[11];
+    using version_major_t = std::uint16_t;
+    using version_minor_t = std::uint16_t;
+    using version_patch_t = std::uint16_t;
+
+    enum metric_t : std::uint8_t {
+        unknown_k = 0,
+        ip_k = 'i',
+        cos_k = 'c',
+        l2sq_k = 'e',
+        jaccard_k = 'j',
+        hamming_k = 'h',
+        pearson_k = 'p',
+        haversine_k = 'h',
+    };
+
+    using connectivity_t = std::uint8_t;
+    using max_level_t = std::uint8_t;
+    using vector_alignment_t = std::uint8_t;
+    using bytes_per_label_t = std::uint16_t;
+    using bytes_per_id_t = std::uint16_t;
+    using size_t = std::uint64_t;
+    using entry_idx_t = std::uint64_t;
+
+    char const* magic;
+    misaligned_ref_gt<version_major_t> version_major;
+    misaligned_ref_gt<version_minor_t> version_minor;
+    misaligned_ref_gt<version_patch_t> version_patch;
+    misaligned_ref_gt<metric_t> metric;
+    misaligned_ref_gt<connectivity_t> connectivity;
+    misaligned_ref_gt<max_level_t> max_level;
+    misaligned_ref_gt<vector_alignment_t> vector_alignment;
+    misaligned_ref_gt<bytes_per_label_t> bytes_per_label;
+    misaligned_ref_gt<bytes_per_id_t> bytes_per_id;
+    misaligned_ref_gt<size_t> size;
+    misaligned_ref_gt<entry_idx_t> entry_idx;
+
+    file_head_t(byte_t* ptr) noexcept
+        : magic((char const*)exchange(ptr, ptr + sizeof(magic_t))),
+          version_major(exchange(ptr, ptr + sizeof(version_major_t))),
+          version_minor(exchange(ptr, ptr + sizeof(version_minor_t))),
+          version_patch(exchange(ptr, ptr + sizeof(version_patch_t))), metric(exchange(ptr, ptr + sizeof(metric_t))),
+          connectivity(exchange(ptr, ptr + sizeof(connectivity_t))),
+          max_level(exchange(ptr, ptr + sizeof(max_level_t))),
+          vector_alignment(exchange(ptr, ptr + sizeof(vector_alignment_t))),
+          bytes_per_label(exchange(ptr, ptr + sizeof(bytes_per_label_t))),
+          bytes_per_id(exchange(ptr, ptr + sizeof(bytes_per_id_t))), size(exchange(ptr, ptr + sizeof(size_t))),
+          entry_idx(exchange(ptr, ptr + sizeof(entry_idx_t))) {}
+};
+
+static_assert(sizeof(file_header_t) == 64, "File header should be exactly 64 bytes");
+
 /**
  *  @brief  Approximate Nearest Neighbors Search index using the
  *          Hierarchical Navigable Small World graph algorithm.
@@ -916,14 +1003,15 @@ class index_gt {
         vector_view_t vector;
     };
 
-    template <typename ref_at> class member_iterator_gt {
+    template <typename ref_at, typename index_at> class member_iterator_gt {
         using ref_t = ref_at;
-        index_gt* index_{};
+        using index_t = index_at;
+        index_t* index_{};
         std::size_t offset_{};
 
         friend class index_gt;
         member_iterator_gt() noexcept {}
-        member_iterator_gt(index_gt* index, std::size_t offset) noexcept : index_(index), offset_(offset) {}
+        member_iterator_gt(index_t* index, std::size_t offset) noexcept : index_(index), offset_(offset) {}
 
       public:
         using iterator_category = std::random_access_iterator_tag;
@@ -932,7 +1020,7 @@ class index_gt {
         using pointer = void;
         using reference = ref_t;
 
-        reference operator*() const noexcept { return index_->node_with_id_(offset_).ref(); }
+        reference operator*() const noexcept { return ref_t(index_->node_with_id_(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); }
@@ -962,8 +1050,8 @@ class index_gt {
         }
     };
 
-    using member_iterator_t = member_iterator_gt<member_ref_t>;
-    using member_citerator_t = member_iterator_gt<member_cref_t>;
+    using member_iterator_t = member_iterator_gt<member_ref_t, index_gt>;
+    using member_citerator_t = member_iterator_gt<member_cref_t, index_gt const>;
 
     // STL compatibility:
     using value_type = std::pair<label_t, distance_t>;
@@ -1050,8 +1138,8 @@ class index_gt {
 
         operator vector_view_t() const noexcept { return {vector(), dim()}; }
         vector_view_t vector_view() const noexcept { return {vector(), dim()}; }
-        member_ref_t ref() noexcept { return {{tape_}, vector_view()}; }
-        member_cref_t cref() const noexcept { return {label(), vector_view()}; }
+        explicit operator member_ref_t() noexcept { return {{tape_}, vector_view()}; }
+        explicit operator member_cref_t() const noexcept { return {label(), vector_view()}; }
     };
 
     /**
@@ -1273,7 +1361,7 @@ class index_gt {
         inline std::size_t size() const noexcept { return count; }
         inline search_result_t operator[](std::size_t i) const noexcept {
             candidate_t const* top_ordered = top_.data();
-            return {index_.node_with_id_(top_ordered[i].id).cref(), top_ordered[i].distance};
+            return {member_cref_t(index_.node_with_id_(top_ordered[i].id)), top_ordered[i].distance};
         }
         inline std::size_t dump_to(label_t* labels, distance_t* distances) const noexcept {
             for (std::size_t i = 0; i != count; ++i) {
@@ -1416,6 +1504,7 @@ class index_gt {
         std::size_t nodes;
         std::size_t edges;
         std::size_t max_edges;
+        std::size_t allocated_bytes;
     };
 
     stats_t stats() const noexcept {
@@ -1428,6 +1517,7 @@ class index_gt {
             for (level_t level = 0; level != node.level(); ++level)
                 edges += neighbors_(node, level).size();
 
+            result.allocated_bytes += node_bytes_(node);
             result.edges += edges;
             result.max_edges += max_edges;
         }
@@ -1437,34 +1527,55 @@ class index_gt {
     stats_t stats(std::size_t level) const noexcept {
         stats_t result{};
         result.nodes = size();
+
+        std::size_t neighbors_bytes = !level ? pre_.neighbors_base_bytes : pre_.neighbors_bytes;
         for (std::size_t i = 0; i != result.nodes; ++i) {
             node_t node = node_with_id_(i);
-            if (node.level() >= level)
-                result.edges += neighbors_(node, level).size();
+            if (node.level() < level)
+                continue;
+
+            result.edges += neighbors_(node, level).size();
+            result.allocated_bytes += node_head_bytes_() + node_vector_bytes_(node) + neighbors_bytes;
         }
+
         std::size_t max_edges_per_node = level ? config_.connectivity : base_level_multiple_() * config_.connectivity;
         result.max_edges = result.nodes * max_edges_per_node;
         return result;
     }
 
-#pragma endregion
+    /**
+     *  @brief  A relatively accurate lower bound on the amount of memory consumed by the system.
+     *          In practice it's error will be below 10%.
+     */
+    std::size_t memory_usage(std::size_t allocator_entry_bytes = default_allocator_entry_bytes()) const noexcept {
+        std::size_t total = 0;
+        if (viewed_file_descriptor_ == 0) {
+            stats_t s = stats();
+            total += s.allocated_bytes;
+            total += s.nodes * allocator_entry_bytes;
+        }
 
-#pragma region Serialization
+        // Temporary data-structures, proportional to the number of nodes:
+        total += nodes_.capacity() * sizeof(node_t) + allocator_entry_bytes;
 
-  private:
-    struct serialized_state_t {
-        // Check compatibility
-        std::uint64_t bytes_per_label{};
-        std::uint64_t bytes_per_id{};
+        // Temporary data-structures, proportional to the number of threads:
+        std::size_t per_thread = (std::max)(config_.expansion_search, config_.expansion_add) * sizeof(candidate_t);
+        total += thread_contexts_.capacity() * (sizeof(thread_context_t) + per_thread) + allocator_entry_bytes * 3;
+        return total;
+    }
 
-        // Describe state
-        std::uint64_t connectivity{};
-        std::uint64_t size{};
-        std::uint64_t entry_id{};
-        std::uint64_t max_level{};
-    };
+    void change_expansion_add(std::size_t n) noexcept { config_.expansion_add = n; }
+    void change_expansion_search(std::size_t n) noexcept { config_.expansion_search = n; }
+    void change_metric(metric_t const& m) noexcept(false) {
+        metric_ = m;
+        for (thread_context_t& context : thread_contexts_)
+            context.metric = metric_;
+    }
+
+#pragma endregion
+
+#pragma region Serialization
 
-  public:
     /**
      *  @brief  Saves serialized binary index representation to disk,
      *          co-locating vectors and neighbors lists.
@@ -1472,15 +1583,25 @@ class index_gt {
      */
     void save(char const* file_path) const noexcept(false) {
 
-        serialized_state_t state;
+        file_header_t state_buffer{};
+        std::memset(state_buffer, 0, sizeof(file_header_t));
+        file_head_t state{state_buffer};
+        std::memcpy(state_buffer, default_magic(), std::strlen(default_magic()));
+
         // Check compatibility
-        state.bytes_per_label = sizeof(label_t);
-        state.bytes_per_id = sizeof(id_t);
+        state.version_major = USEARCH_VERSION_MAJOR;
+        state.version_minor = USEARCH_VERSION_MINOR;
+        state.version_patch = USEARCH_VERSION_PATCH;
+        state.metric = file_head_t::unknown_k;
+
         // Describe state
         state.connectivity = config_.connectivity;
-        state.size = size_;
-        state.entry_id = entry_id_;
         state.max_level = max_level_;
+        state.vector_alignment = config_.vector_alignment;
+        state.bytes_per_label = sizeof(label_t);
+        state.bytes_per_id = sizeof(id_t);
+        state.size = size_;
+        state.entry_idx = entry_id_;
 
         std::FILE* file = std::fopen(file_path, "w");
         if (!file)
@@ -1495,7 +1616,7 @@ class index_gt {
         };
 
         // Write the header
-        write_chunk(&state, sizeof(state));
+        write_chunk(&state_buffer[0], sizeof(file_header_t));
 
         // Serialize nodes one by one
         for (std::size_t i = 0; i != state.size; ++i) {
@@ -1516,7 +1637,7 @@ class index_gt {
      *          Available on Linux, MacOS, Windows.
      */
     void load(char const* file_path) noexcept(false) {
-        serialized_state_t state;
+        file_header_t state_buffer{};
         std::FILE* file = std::fopen(file_path, "r");
         if (!file)
             throw std::runtime_error(std::strerror(errno));
@@ -1531,7 +1652,8 @@ class index_gt {
 
         // Read the header
         {
-            read_chunk(&state, sizeof(state));
+            read_chunk(&state_buffer[0], sizeof(file_header_t));
+            file_head_t state{state_buffer};
             if (state.bytes_per_label != sizeof(label_t)) {
                 std::fclose(file);
                 throw std::runtime_error("Incompatible label type!");
@@ -1543,15 +1665,16 @@ class index_gt {
 
             config_.connectivity = state.connectivity;
             config_.max_elements = state.size;
+            config_.vector_alignment = state.vector_alignment;
             pre_ = precompute_(config_);
             reserve(state.size);
             size_ = state.size;
             max_level_ = static_cast<level_t>(state.max_level);
-            entry_id_ = static_cast<id_t>(state.entry_id);
+            entry_id_ = static_cast<id_t>(state.entry_idx);
         }
 
         // Load nodes one by one
-        for (std::size_t i = 0; i != state.size; ++i) {
+        for (std::size_t i = 0; i != size_; ++i) {
             label_t label;
             dim_t dim;
             level_t level;
@@ -1578,7 +1701,6 @@ class index_gt {
 #if defined(USEARCH_IS_WINDOWS)
         throw std::logic_error("Memory-mapping is not yet available for Windows");
 #else
-        serialized_state_t state;
         int open_flags = O_RDONLY;
 #if __linux__
         open_flags |= O_NOATIME;
@@ -1602,7 +1724,7 @@ class index_gt {
 
         // Read the header
         {
-            std::memcpy(&state, file, sizeof(state));
+            file_head_t state{file};
             if (state.bytes_per_label != sizeof(label_t)) {
                 close(descriptor);
                 throw std::runtime_error("Incompatible label type!");
@@ -1614,17 +1736,18 @@ class index_gt {
 
             config_.connectivity = state.connectivity;
             config_.max_elements = state.size;
+            config_.vector_alignment = state.vector_alignment;
             config_.max_threads_add = 0;
             pre_ = precompute_(config_);
             reserve(state.size);
             size_ = state.size;
             max_level_ = static_cast<level_t>(state.max_level);
-            entry_id_ = static_cast<id_t>(state.entry_id);
+            entry_id_ = static_cast<id_t>(state.entry_idx);
         }
 
         // Locate every node packed into file
-        std::size_t progress = sizeof(state);
-        for (std::size_t i = 0; i != state.size; ++i) {
+        std::size_t progress = sizeof(file_header_t);
+        for (std::size_t i = 0; i != size_; ++i) {
             byte_t* tape = (byte_t*)(file + progress);
             dim_t dim = misaligned_load<dim_t>(tape + sizeof(label_t));
             level_t level = misaligned_load<level_t>(tape + sizeof(label_t) + sizeof(dim_t));

package/package.json

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