usearch 0.9.7 → 0.10.0

package/Cargo.toml

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

package/VERSION

@@ -1 +1 @@
-0.9.7
+0.10.0

package/conanfile.py

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

package/include/usearch/usearch.hpp

@@ -781,6 +781,7 @@ 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  Configuration settings for the index construction.
@@ -1416,6 +1417,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 +1430,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,16 +1440,46 @@ 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;
     }
 
+    /**
+     *  @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;
+        }
+
+        // Temporary data-structures, proportional to the number of nodes:
+        total += nodes_.capacity() * sizeof(node_t) + allocator_entry_bytes;
+
+        // 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;
+    }
+
+    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; }
+
 #pragma endregion
 
 #pragma region Serialization

package/package.json

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

package/python/lib.cpp

@@ -405,6 +405,9 @@ template <typename index_at> void save_index(index_at const& index, std::string
 template <typename index_at> void load_index(index_at& index, std::string const& path) { index.load(path.c_str()); }
 template <typename index_at> void view_index(index_at& index, std::string const& path) { index.view(path.c_str()); }
 template <typename index_at> void clear_index(index_at& index) { index.clear(); }
+template <typename index_at> std::size_t get_expansion_add(index_at const &index) { return index.config().expansion_add; }
+template <typename index_at> std::size_t get_expansion_search(index_at const &index) { return index.config().expansion_search; }
+
 // clang-format on
 
 template <typename element_at> bool has_duplicates(element_at const* begin, element_at const* end) {
@@ -522,6 +525,10 @@ PYBIND11_MODULE(index, m) {
     i.def_property_readonly("capacity", &punned_py_t::capacity);
     i.def_property_readonly( //
         "dtype", [](punned_py_t const& index) -> std::string { return accuracy_name(index.accuracy()); });
+    i.def_property_readonly("memory_usage", &punned_py_t::memory_usage);
+
+    i.def_property("expansion_add", &get_expansion_add<punned_py_t>, &punned_py_t::change_expansion_add);
+    i.def_property("expansion_search", &get_expansion_search<punned_py_t>, &punned_py_t::change_expansion_search);
 
     i.def("save", &save_index<punned_py_t>, py::arg("path"));
     i.def("load", &load_index<punned_py_t>, py::arg("path"));

package/src/punned.hpp

@@ -455,6 +455,8 @@ class punned_gt {
     std::size_t capacity() const { return typed_->capacity(); }
     config_t const& config() const { return typed_->config(); }
     void clear() { return typed_->clear(); }
+    void change_expansion_add(std::size_t n) noexcept { typed_->change_expansion_add(n); }
+    void change_expansion_search(std::size_t n) noexcept { typed_->change_expansion_search(n); }
 
     member_citerator_t cbegin() const noexcept { return typed_->cbegin(); }
     member_citerator_t cend() const noexcept { return typed_->cend(); }
@@ -474,6 +476,10 @@ class punned_gt {
     void view(char const* path) { typed_->view(path); }
     void reserve(std::size_t capacity) { typed_->reserve(capacity); }
 
+    std::size_t memory_usage(std::size_t allocator_entry_bytes = default_allocator_entry_bytes()) const noexcept {
+        return typed_->memory_usage(allocator_entry_bytes);
+    }
+
     // clang-format off
     add_result_t add(label_t label, f8_bits_t const* vector) { return add_(label, vector, casts_.from_f8); }
     add_result_t add(label_t label, f16_bits_t const* vector) { return add_(label, vector, casts_.from_f16); }

package/src/test.cpp

@@ -65,6 +65,9 @@ template <typename scalar_at, typename index_at> void test3d(index_at&& index) {
     assert(matched_count == 3);
     assert(matched_labels[0] == 42);
     assert(std::abs(matched_distances[0]) < 0.01);
+
+    assert(index.memory_usage() > 0);
+    assert(index.stats().max_edges > 0);
 }
 
 int main(int, char**) {