usearch 2.26.4 → 2.26.5

package/README.md

@@ -568,7 +568,7 @@ doi = {10.5281/zenodo.7949415},
 author = {Vardanian, Ash},
 title = {{USearch by Unum Cloud}},
 url = {https://github.com/unum-cloud/USearch},
-version = {2.26.4},
+version = {2.26.5},
 year = {2026},
 }
 ```

package/c/CMakeLists.txt

@@ -30,4 +30,13 @@ if (USEARCH_BUILD_LIB_C)
     setup_target(usearch_c)
     setup_target(usearch_static_c)
 
+    if (USEARCH_INSTALL)
+        install(TARGETS usearch_c usearch_static_c
+                LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+                ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+                RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+        install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/usearch.h
+                DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+    endif ()
+
 endif ()

package/cmake/pkg-config.pc.in

@@ -1,4 +1,7 @@
-Name: ${PROJECT_NAME}
+prefix=@CMAKE_INSTALL_PREFIX@
+includedir=@CMAKE_INSTALL_FULL_INCLUDEDIR@
+
+Name: @PROJECT_NAME@
 Description: Smaller & Faster Single-File Vector Search Engine from Unum
-Version: ${PROJECT_VERSION}
-Cflags: -I${CMAKE_INSTALL_FULL_INCLUDEDIR}
+Version: @PROJECT_VERSION@
+Cflags: -I${includedir}

package/cpp/test.cpp

@@ -1534,6 +1534,36 @@ void test_view_of_truncated_file() {
     std::remove(path);
 }
 
+/**
+ *  @brief  Regression test: every thread context must draw node levels of its own. Default-seeded, all
+ *          contexts drew the same levels and started over after every `reserve`, so every per-level node
+ *          count was a multiple of `contexts * steps`, the upper levels too full and the top ones missing.
+ */
+void test_level_generators() {
+    constexpr std::size_t contexts = 16, steps = 16, per_context_step = 64, dimensions = 2;
+    metric_punned_t metric(dimensions, metric_kind_t::l2sq_k, scalar_kind_t::f32_k);
+    index_dense_t index = index_dense_t::make(metric);
+
+    std::mt19937 generator(42);
+    std::uniform_real_distribution<float> distribution(0.0, 1.0);
+
+    std::size_t key = 0;
+    for (std::size_t step = 0; step != steps; ++step) {
+        expect(index.try_reserve(index_limits_t((step + 1) * contexts * per_context_step, contexts)));
+        for (std::size_t idx = 0; idx != contexts * per_context_step; ++idx, ++key) {
+            float vector[dimensions] = {distribution(generator), distribution(generator)};
+            expect(index.add(key, vector, idx % contexts));
+        }
+    }
+    expect_eq(index.size(), contexts * steps * per_context_step);
+
+    // Independent draws put about 1024 nodes on level 1 and 64 on level 2: almost never multiples of 256.
+    bool all_multiples = true;
+    for (std::size_t level = 1; level <= index.max_level(); ++level)
+        all_multiples = all_multiples && index.stats(level).nodes % (contexts * steps) == 0;
+    expect(!all_multiples);
+}
+
 int main(int, char**) {
     install_crash_handlers();
 
@@ -1632,5 +1662,6 @@ int main(int, char**) {
     test_compact();
     test_load_after_metric_make();
     test_view_of_truncated_file();
+    test_level_generators();
     return 0;
 }

package/include/usearch/index.hpp

@@ -9,7 +9,7 @@
 
 #define USEARCH_VERSION_MAJOR 2
 #define USEARCH_VERSION_MINOR 26
-#define USEARCH_VERSION_PATCH 4
+#define USEARCH_VERSION_PATCH 5
 
 // Inferring C++ version
 // https://stackoverflow.com/a/61552074
@@ -96,7 +96,7 @@
 #include <cstring>   // `std::memset`
 #include <iterator>  // `std::reverse_iterator`
 #include <mutex>     // `std::unique_lock` - replacement candidate
-#include <random>    // `std::default_random_engine` - replacement candidate
+#include <random>    // `std::uniform_real_distribution`
 #include <stdexcept> // `std::runtime_exception`
 #include <thread>    // `std::thread`
 #include <utility>   // `std::pair`
@@ -1277,6 +1277,29 @@ template <typename element_at> struct hash_gt {
     std::size_t operator()(element_at const& element) const noexcept { return std::hash<element_at>{}(element); }
 };
 
+/**
+ *  @brief Eight-byte, non-cryptographic uniform random bit generator for STL distributions.
+ *  @see https://prng.di.unimi.it/splitmix64.c (public-domain reference implementation).
+ *  @details Every seed is valid, including zero. Generation and skipping use unsigned wraparound.
+ */
+class splitmix64_t {
+    std::uint64_t state_;
+
+  public:
+    using result_type = std::uint64_t;
+    static result_type mix_uint64(result_type x) noexcept {
+        x = (x ^ (x >> 30u)) * 0xBF58476D1CE4E5B9ULL;
+        x = (x ^ (x >> 27u)) * 0x94D049BB133111EBULL;
+        return x ^ (x >> 31u);
+    }
+    constexpr explicit splitmix64_t(result_type value = 0) noexcept : state_(value) {}
+    static constexpr result_type(min)() noexcept { return 0; }
+    static constexpr result_type(max)() noexcept { return (std::numeric_limits<result_type>::max)(); }
+    void seed(result_type value = 0) noexcept { state_ = value; }
+    result_type operator()() noexcept { return mix_uint64(state_ += 0x9E3779B97F4A7C15ULL); }
+    void discard(unsigned long long count) noexcept { state_ += result_type(count) * 0x9E3779B97F4A7C15ULL; }
+};
+
 /**
  *  @brief  SplitMix64 finalizer, used to scatter integer keys before masking.
  *
@@ -1289,10 +1312,7 @@ template <typename element_at> struct hash_gt {
  */
 template <> struct hash_gt<std::uint64_t> {
     std::size_t operator()(std::uint64_t const& element) const noexcept {
-        std::uint64_t x = element;
-        x = (x ^ (x >> 30u)) * 0xBF58476D1CE4E5B9ULL;
-        x = (x ^ (x >> 27u)) * 0x94D049BB133111EBULL;
-        return static_cast<std::size_t>(x ^ (x >> 31u));
+        return static_cast<std::size_t>(splitmix64_t::mix_uint64(element));
     }
 };
 
@@ -2489,7 +2509,7 @@ class index_gt {
         top_candidates_t top_for_refine{};
         next_candidates_t next_candidates{};
         visits_hash_set_t visits{};
-        std::default_random_engine level_generator{};
+        splitmix64_t level_generator{};
         std::size_t iteration_cycles{};
         std::size_t computed_distances{};
         std::size_t computed_distances_in_refines{};
@@ -2687,6 +2707,10 @@ class index_gt {
         if (!other.reserve(limits_))
             return result.failed("Failed to reserve the contexts");
 
+        // A copy must continue the same node-level streams as the original.
+        for (std::size_t i = 0; i != contexts_.size(); ++i)
+            other.contexts_[i].level_generator = contexts_[i].level_generator;
+
         // Now all is left - is to allocate new `node_t` instances and populate
         // the `other.nodes_` array into it.
         for (std::size_t i = 0; i != nodes_count_; ++i)
@@ -2892,10 +2916,15 @@ class index_gt {
 
     /**
      *  @brief  Increases the `capacity()` of the index to allow adding more vectors.
+     *  @note Thread reservations never shrink; `reset()` releases all contexts.
      *  @return `true` on success, `false` on memory allocation errors.
      */
     bool try_reserve(index_limits_t limits) usearch_noexcept_m {
 
+        // Keep previously allocated contexts, including streams for temporarily unused threads.
+        limits.threads_add = (std::max)(limits.threads_add, limits_.threads_add);
+        limits.threads_search = (std::max)(limits.threads_search, limits_.threads_search);
+
         if (limits.threads_add <= limits_.threads_add          //
             && limits.threads_search <= limits_.threads_search //
             && limits.members <= limits_.members)
@@ -2918,10 +2947,19 @@ class index_gt {
         // Move the nodes info, and deallocate previous buffers.
         if (nodes_)
             std::memcpy(new_nodes.data(), nodes_.data(), sizeof(node_t) * size());
-        for (std::size_t i = 0; i != new_contexts.size(); ++i)
+        for (std::size_t i = 0; i != new_contexts.size(); ++i) {
             if (!new_contexts[i].top_for_refine.reserve(connectivity_max + 1))
                 return false;
 
+            // Copy rather than advance the old stream, so a failed reserve leaves it unchanged.
+            if (i < contexts_.size())
+                new_contexts[i].level_generator = contexts_[i].level_generator;
+            else {
+                // Mix logical thread slots instead of using adjacent seeds (or an OS thread ID).
+                new_contexts[i].level_generator.seed(splitmix64_t::mix_uint64(static_cast<std::uint64_t>(i) + 1));
+            }
+        }
+
         limits_ = limits;
         nodes_capacity_ = limits.members;
         nodes_ = std::move(new_nodes);
@@ -3211,11 +3249,13 @@ class index_gt {
         if (!next.reserve(config.expansion))
             return result.failed("Out of memory!");
 
+        // Each caller exclusively owns its context; sampling needs no shared graph lock.
+        level_t new_target_level = choose_random_level_(context.level_generator);
+
         // Determining how much memory to allocate for the node depends on the target level
         std::unique_lock<std::mutex> new_level_lock(global_mutex_);
         level_t max_level_copy = max_level_;                                             // Copy under lock
         compressed_slot_t entry_slot_copy = static_cast<compressed_slot_t>(entry_slot_); // Copy under lock
-        level_t new_target_level = choose_random_level_(context.level_generator);
 
         // Make sure we are not overflowing
         std::size_t capacity = nodes_capacity_.load();
@@ -4366,10 +4406,11 @@ class index_gt {
         }
     }
 
-    level_t choose_random_level_(std::default_random_engine& level_generator) const noexcept {
+    level_t choose_random_level_(splitmix64_t& level_generator) const noexcept {
         std::uniform_real_distribution<double> distribution(0.0, 1.0);
-        double r = -std::log(distribution(level_generator)) * pre_.inverse_log_connectivity;
-        return (level_t)r;
+        // Reflect into (0, 1] and guard against a rounded upper endpoint from the STL.
+        double uniform = (std::max)(1.0 - distribution(level_generator), (std::numeric_limits<double>::min)());
+        return static_cast<level_t>(-std::log(uniform) * pre_.inverse_log_connectivity);
     }
 
     struct candidates_range_t;

package/include/usearch/index_dense.hpp

@@ -1053,6 +1053,9 @@ class index_dense_gt {
         // Reserving is monotonic: reducing thread limits must not shrink member-addressed storage.
         limits.members = (std::max)(limits.members, typed_->capacity());
         limits.members = (std::max)(limits.members, vectors_lookup_.size());
+        // Match the core's retained contexts so cast buffers and available thread IDs stay consistent.
+        limits.threads_add = (std::max)(limits.threads_add, typed_->limits().threads_add);
+        limits.threads_search = (std::max)(limits.threads_search, typed_->limits().threads_search);
 
         // The slot lookup system will generally prefer power-of-two sizes.
         if (config_.enable_key_lookups) {

package/include/usearch/index_plugins.hpp

@@ -526,8 +526,10 @@ inline std::uint16_t f32_to_f16(float f32) noexcept {
  */
 inline float bf16_to_f32(std::uint16_t u16) noexcept {
 #if USEARCH_USE_NUMKONG
+    nk_bf16_t bits;
+    std::memcpy(&bits, &u16, sizeof(bits));
     nk_f32_t result;
-    nk_bf16_to_f32_serial((nk_bf16_t const*)&u16, &result);
+    nk_bf16_to_f32_serial(&bits, &result);
     return result;
 #else
     union float_or_unsigned_int_t {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "usearch",
-    "version": "2.26.4",
+    "version": "2.26.5",
     "description": "Smaller & Faster Single-File Vector Search Engine from Unum",
     "author": "Ash Vardanian (https://ashvardanian.com/)",
     "license": "Apache 2.0",