usearch 2.15.3 → 2.16.1

package/README.md

@@ -544,7 +544,7 @@ doi = {10.5281/zenodo.7949416},
 author = {Vardanian, Ash},
 title = {{USearch by Unum Cloud}},
 url = {https://github.com/unum-cloud/usearch},
-version = {2.15.3},
+version = {2.16.1},
 year = {2023},
 month = oct,
 }

package/cpp/test.cpp

@@ -1100,6 +1100,22 @@ int main(int, char**) {
     test_uint40();
     test_cosine<float, std::int64_t, uint40_t>(10, 10);
 
+    // Test plugins, like K-Means clustering.
+    {
+        std::size_t vectors_count = 1000, centroids_count = 10, dimensions = 256;
+        kmeans_clustering_t clustering;
+        clustering.max_iterations = 2;
+        std::vector<float> vectors(vectors_count * dimensions), centroids(centroids_count * dimensions);
+        matrix_slice_gt<float const> vectors_slice(vectors.data(), dimensions, vectors_count);
+        matrix_slice_gt<float> centroids_slice(centroids.data(), dimensions, centroids_count);
+        std::generate(vectors.begin(), vectors.end(), [] { return float(std::rand()) / float(INT_MAX); });
+        std::vector<std::size_t> assignments(vectors_count);
+        std::vector<distance_punned_t> distances(vectors_count);
+        auto clustering_result = clustering(vectors_slice, centroids_slice, {assignments.data(), assignments.size()},
+                                            {distances.data(), distances.size()});
+        expect(clustering_result);
+    }
+
     // Exact search without constructing indexes.
     // Great for validating the distance functions.
     std::printf("Testing exact search\n");

package/include/usearch/index.hpp

@@ -8,8 +8,8 @@
 #define UNUM_USEARCH_HPP
 
 #define USEARCH_VERSION_MAJOR 2
-#define USEARCH_VERSION_MINOR 15
-#define USEARCH_VERSION_PATCH 3
+#define USEARCH_VERSION_MINOR 16
+#define USEARCH_VERSION_PATCH 1
 
 // Inferring C++ version
 // https://stackoverflow.com/a/61552074
@@ -370,7 +370,7 @@ template <typename scalar_at, typename allocator_at = std::allocator<scalar_at>>
     void reset() noexcept {
         if (!std::is_trivially_destructible<scalar_at>::value)
             for (std::size_t i = 0; i != size_; ++i)
-                destroy_at(data_ + i);
+                unum::usearch::destroy_at(data_ + i); //< Facing some symbol visibility/ambiguity issues
         allocator_at{}.deallocate(data_, size_);
         data_ = nullptr;
         size_ = 0;
@@ -960,6 +960,10 @@ class sorted_buffer_gt {
 
 /**
  *  @brief  Five-byte integer type to address node clouds with over 4B entries.
+ *
+ *  40 bits is enough to address a @b Trillion entries potentially colocated on 1 machine.
+ *  At roughly 5 bytes * 20 neighbors + 100 bytes per entry, this translates to 200 TB of data,
+ *  which is similar to a single-server capacity of modern NVME arrays.
  */
 class usearch_pack_m uint40_t {
     unsigned char octets[5];
@@ -1214,8 +1218,8 @@ class ring_gt {
     using element_t = element_at;
     using allocator_t = allocator_at;
 
-    static_assert(std::is_trivially_destructible<element_t>(), "This heap is designed for trivial structs");
-    static_assert(std::is_trivially_copy_constructible<element_t>(), "This heap is designed for trivial structs");
+    static_assert(std::is_trivially_destructible<element_t>(), "This ring is designed for trivial structs");
+    static_assert(std::is_trivially_copy_constructible<element_t>(), "This ring is designed for trivial structs");
 
     using value_type = element_t;
 
@@ -3175,6 +3179,18 @@ class index_gt {
 
     std::size_t memory_usage_per_node(level_t level) const noexcept { return node_bytes_(level); }
 
+    double inverse_log_connectivity() const {
+        return pre_.inverse_log_connectivity;
+    }
+
+    std::size_t neighbors_base_bytes() const {
+        return pre_.neighbors_base_bytes;
+    }
+
+    std::size_t neighbors_bytes() const {
+        return pre_.neighbors_bytes;
+    }
+
 #if defined(USEARCH_USE_PRAGMA_REGION)
 #pragma endregion
 

package/include/usearch/index_dense.hpp

@@ -693,6 +693,9 @@ class index_dense_gt {
     std::size_t max_level() const { return typed_->max_level(); }
     index_dense_config_t const& config() const { return config_; }
     index_limits_t const& limits() const { return typed_->limits(); }
+    double inverse_log_connectivity() const { return typed_->inverse_log_connectivity(); }
+    std::size_t neighbors_base_bytes() const { return typed_->neighbors_base_bytes(); }
+    std::size_t neighbors_bytes() const { return typed_->neighbors_bytes(); }
     bool multi() const { return config_.multi; }
     std::size_t currently_available_threads() const {
         std::unique_lock<std::mutex> available_threads_lock(available_threads_mutex_);
@@ -1460,6 +1463,8 @@ class index_dense_gt {
     labeling_result_t remove(vector_key_t key) {
         usearch_assert_m(config().enable_key_lookups, "Key lookups are disabled");
         labeling_result_t result;
+        if (typed_->is_immutable())
+            return result.failed("Can't remove from an immutable index");
 
         unique_lock_t lookup_lock(slot_lookup_mutex_);
         auto matching_slots = slot_lookup_.equal_range(key_and_slot_t::any_slot(key));
@@ -2249,4 +2254,4 @@ static join_result_t join(                                    //
 }
 
 } // namespace usearch
-} // namespace unum
+} // namespace unum

package/include/usearch/index_plugins.hpp

@@ -4,6 +4,7 @@
 #include <stdlib.h> // `aligned_alloc`
 
 #include <atomic>  // `std::atomic`
+#include <chrono>  // `std::chrono`
 #include <cstring> // `std::strncmp`
 #include <thread>  // `std::thread`
 
@@ -65,11 +66,11 @@
 #pragma GCC diagnostic ignored "-Wunused-parameter"
 #pragma GCC diagnostic ignored "-Wunused-variable"
 #pragma GCC diagnostic ignored "-Wunused-but-set-variable"
-#ifdef _MSC_VER
+#if defined(_MSC_VER)
 #pragma warning(push)
 #pragma warning(disable : 4101) // "Unused variables"
 #pragma warning(disable : 4068) // "Unknown pragmas", when MSVC tries to read GCC pragmas
-#endif // _MSC_VER
+#endif                          // _MSC_VER
 #include <simsimd/simsimd.h>
 #ifdef _MSC_VER
 #pragma warning(pop)
@@ -2020,7 +2021,7 @@ class matrix_slice_gt {
     explicit operator bool() const noexcept { return begin_; }
     std::size_t size() const noexcept { return count_; }
     std::size_t dimensions() const noexcept { return dimensions_; }
-    std::size_t stride() const noexcept { return stride_bytes_; }
+    std::size_t stride_bytes() const noexcept { return stride_bytes_; }
     scalar_t* data() const noexcept { return begin_; }
     scalar_t* at(std::size_t i) const noexcept {
         return reinterpret_cast<scalar_t*>(reinterpret_cast<byte_addressable_t*>(begin_) + i * stride_bytes_);
@@ -2032,7 +2033,7 @@ struct exact_offset_and_distance_t {
     f32_t distance;
 };
 
-using exact_search_results_t = matrix_slice_gt<exact_offset_and_distance_t>;
+using exact_search_results_t = matrix_slice_gt<exact_offset_and_distance_t const>;
 
 /**
  *  @brief  Helper-structure for exact search operations.
@@ -2057,10 +2058,10 @@ class exact_search_t {
         matrix_slice_gt<scalar_at const> dataset, matrix_slice_gt<scalar_at const> queries, //
         std::size_t wanted, metric_punned_t const& metric,                                  //
         executor_at&& executor = executor_at{}, progress_at&& progress = progress_at{}) {
-        return operator()(                                                                     //
-            metric,                                                                            //
-            reinterpret_cast<byte_t const*>(dataset.data()), dataset.size(), dataset.stride(), //
-            reinterpret_cast<byte_t const*>(queries.data()), queries.size(), queries.stride(), //
+        return operator()(                                                                           //
+            metric,                                                                                  //
+            reinterpret_cast<byte_t const*>(dataset.data()), dataset.size(), dataset.stride_bytes(), //
+            reinterpret_cast<byte_t const*>(queries.data()), queries.size(), queries.stride_bytes(), //
             wanted, executor, progress);
     }
 
@@ -2137,6 +2138,342 @@ class exact_search_t {
     }
 };
 
+struct kmeans_clustering_result_t {
+    error_t error{};
+    std::size_t computed_distances{};
+    /// @brief The number of iterations the algorithm took to converge.
+    std::size_t iterations{};
+    /// @brief The number of points that changed clusters in the last iteration.
+    std::size_t last_iteration_points_shifted{};
+    /// @brief The inertia of the last iteration (sum of squared distances to centroids).
+    f64_t last_iteration_inertia{};
+    /// @brief The total elapsed runtime of the algorithm in seconds.
+    f64_t runtime_seconds{};
+    /// @brief The total distance between the points and their assigned centroids.
+    f64_t aggregate_distance{};
+
+    explicit operator bool() const noexcept { return !error; }
+    kmeans_clustering_result_t failed(error_t message) noexcept {
+        error = std::move(message);
+        return std::move(*this);
+    }
+};
+
+/**
+ *  @brief  Helper-class for K-Means clustering of dense vectors.
+ *          Doesn't require constructing the index, but benefits from mixed-precision logic.
+ *          ! Doesn't guarantee that the clusters are balanced in size.
+ *
+ *  The algorithm is as follows:
+ *  - Initialization: Select K initial centroids (randomly or with a heuristic).
+ *  - Assignment: Assign each data point to the nearest centroid based on the Euclidean distance.
+ *  - Update: Recalculate the centroids as the mean of all points assigned to each centroid.
+ *  - Repeat: Repeat the assignment and update steps until the centroids no longer change significantly
+ *            or an early-exit condition is met.
+ */
+template <typename allocator_at = std::allocator<char>> class kmeans_clustering_gt {
+  public:
+    using distance_t = distance_punned_t;
+
+    metric_kind_t metric_kind{metric_kind_t::l2sq_k};
+    scalar_kind_t quantization_kind{scalar_kind_t::bf16_k};
+
+    static constexpr std::size_t max_iterations_default_k = 300;
+    static constexpr f64_t inertia_threshold_default_k = 1e-4;
+    static constexpr f64_t max_seconds_default_k = 60.0;
+    static constexpr f64_t min_shifts_default_k = 0.01;
+
+    /// @brief Early-exit parameter - the maximum number of iterations to perform.
+    std::size_t max_iterations{max_iterations_default_k};
+    /// @brief Early-exit parameter - the threshold for the final inertia to terminate early.
+    f64_t inertia_threshold{inertia_threshold_default_k};
+    /// @brief Early-exit parameter - the maximum runtime allowed in seconds.
+    f64_t max_seconds{max_seconds_default_k};
+    /// @brief Early-exit parameter - the minimum share of points that must change clusters per iteration.
+    f64_t min_shifts{min_shifts_default_k};
+    /// @brief The random seed to use for centroid initialization.
+    std::uint64_t seed{0};
+
+    kmeans_clustering_gt(std::uint64_t seed) noexcept : seed(seed) {}
+    kmeans_clustering_gt() noexcept(false) {
+        std::random_device random_device;
+        seed = random_device();
+    }
+
+    kmeans_clustering_gt(kmeans_clustering_gt const&) = default;
+    kmeans_clustering_gt& operator=(kmeans_clustering_gt const&) = default;
+
+    template <typename scalar_at, typename executor_at = dummy_executor_t, typename progress_at = dummy_progress_t>
+    kmeans_clustering_result_t operator()( //
+        matrix_slice_gt<scalar_at const> points, matrix_slice_gt<scalar_at> centroids,
+        span_gt<std::size_t> point_to_centroid_index, span_gt<distance_t> point_to_centroid_distance, //
+        executor_at&& executor = executor_at{}, progress_at&& progress = progress_at{}) {
+        return operator()(                                                                        //
+            reinterpret_cast<byte_t const*>(points.data()), points.size(), points.stride_bytes(), //
+            reinterpret_cast<byte_t*>(centroids.data()), centroids.size(), centroids.stride_bytes(),
+            point_to_centroid_index.data(), point_to_centroid_distance.data(), //
+            scalar_kind<scalar_at>(), points.dimensions(), executor, progress);
+    }
+
+    template <typename executor_at = dummy_executor_t, typename progress_at = dummy_progress_t>
+    kmeans_clustering_result_t operator()(                                                       //
+        byte_t const* points_data, std::size_t points_count, std::size_t points_stride_bytes,    //
+        byte_t* centroids_data, std::size_t wanted_clusters, std::size_t centroids_stride_bytes, //
+        std::size_t* point_to_centroid_index, distance_t* point_to_centroid_distance,            //
+        scalar_kind_t original_scalar_kind, std::size_t dimensions, executor_at&& executor = executor_at{},
+        progress_at&& progress = progress_at{}) {
+
+        // Perform sanity checks for algorithm settings.
+        kmeans_clustering_result_t result;
+        if (max_iterations < 1)
+            return result.failed("The number of iterations must be at least 1");
+
+        // Perform sanity checks for input arguments.
+        if (wanted_clusters < 2)
+            return result.failed("The number of clusters must be at least 2");
+        if (wanted_clusters >= points_count)
+            return result.failed("The number of clusters must be less than the number of vectors");
+
+        metric_punned_t metric = metric_punned_t::builtin(dimensions, metric_kind, quantization_kind);
+        if (!metric)
+            return result.failed("Unsupported metric or scalar kind");
+
+        // Let's allocate memory for the centroids coordinates and make sure it's
+        // rows are aligned to cache lines to avoid false sharing.
+        buffer_gt<distance_t, aligned_allocator_gt<distance_t, 64>> point_to_centroid_distance_buffer(points_count);
+        buffer_gt<std::size_t, aligned_allocator_gt<std::size_t, 64>> point_to_centroid_index_buffer(points_count);
+        buffer_gt<std::atomic<std::size_t>, aligned_allocator_gt<std::atomic<std::size_t>, 64>> cluster_sizes_buffer(
+            wanted_clusters);
+
+        // For a mixed precision computation, we keep the centroids represented in two forms -
+        // double precision and quantized the same way as in the index, to avoid paying conversion penalties.
+        // Double precision is needed to avoid accumulating errors when aggregating too many entries.
+        std::size_t const bytes_per_vector_original =
+            divide_round_up<CHAR_BIT>(dimensions * bits_per_scalar(original_scalar_kind));
+        std::size_t const bytes_per_vector_quantized = metric.bytes_per_vector();
+        std::size_t const stride_per_vector_quantized = divide_round_up<64>(bytes_per_vector_quantized) * 64;
+        buffer_gt<byte_t, aligned_allocator_gt<byte_t, 64>> points_quantized_buffer( //
+            points_count * stride_per_vector_quantized);
+        buffer_gt<byte_t, aligned_allocator_gt<byte_t, 64>> centroids_quantized_buffer( //
+            wanted_clusters * stride_per_vector_quantized);
+
+        // When aggregating centroids, we want to parallelize the operation and need more memory.
+        // For every thread we keep two double-precision vectors. One is the up-casting output buffer for quantized
+        // coordinates, and the other is the temporary buffer for the partial sums of the double-precision coordinates.
+        // The ordering:
+        //
+        //      - thread 0: [centroid 0, centroid 1, centroid 2, centroid 3, ...]
+        //      - thread 1: [centroid 0, centroid 1, centroid 2, centroid 3, ...]
+        //      - thread 2: [centroid 0, centroid 1, centroid 2, centroid 3, ...]
+        //
+        std::size_t const thread_count = executor.size();
+        buffer_gt<f64_t, aligned_allocator_gt<f64_t, 64>> centroids_precise_buffer( //
+            wanted_clusters * dimensions * thread_count);
+        buffer_gt<f64_t, aligned_allocator_gt<f64_t, 64>> points_precise_buffer( //
+            wanted_clusters * dimensions * thread_count);
+
+        // Check if all memory allocations were successful.
+        if (!centroids_precise_buffer || !points_precise_buffer || !centroids_quantized_buffer ||
+            !point_to_centroid_index_buffer || !cluster_sizes_buffer || !point_to_centroid_distance_buffer ||
+            !points_quantized_buffer)
+            return result.failed("No memory for result outputs!");
+
+        std::fill_n(point_to_centroid_index_buffer.data(), points_count, wanted_clusters);
+        std::fill_n(point_to_centroid_distance_buffer.data(), points_count, std::numeric_limits<distance_t>::max());
+
+        // Initialize the casting kernel for quantization and export.
+        casts_punned_t casts = casts_punned_t::make(quantization_kind);
+        cast_punned_t const& compress_points = casts.from[original_scalar_kind];
+        cast_punned_t const& decompress_points = casts.to[original_scalar_kind];
+        cast_punned_t const& compress_precise = casts.from.f64;
+        cast_punned_t const& decompress_precise = casts.to.f64;
+        for (std::size_t i = 0; i < points_count; i++) {
+            byte_t const* vector = points_data + i * points_stride_bytes;
+            byte_t* quantized = points_quantized_buffer.data() + i * stride_per_vector_quantized;
+            if (!compress_points(vector, dimensions, quantized))
+                std::memcpy(quantized, vector, bytes_per_vector_original);
+        }
+
+        // Initialize centroids with random points vectors.
+        std::mt19937_64 random_engine;
+        random_engine.seed(seed);
+        for (std::size_t i = 0; i < wanted_clusters; i++) {
+            // Generate the random index of the points vector,
+            // that is unique and not already used as a centroid.
+            std::size_t random_index;
+            do {
+                random_index = random_engine() % points_count;
+                bool is_unique = true;
+                for (std::size_t j = 0; j < i; j++) {
+                    if (point_to_centroid_index_buffer[j] == random_index) {
+                        is_unique = false;
+                        break;
+                    }
+                }
+                if (is_unique)
+                    break;
+            } while (true);
+
+            // Copy the vector to the centroid and quantize it.
+            byte_t const* quantized_point = points_quantized_buffer.data() + random_index * stride_per_vector_quantized;
+            byte_t* quantized_centroid = centroids_quantized_buffer.data() + i * stride_per_vector_quantized;
+            std::memcpy(quantized_centroid, quantized_point, bytes_per_vector_quantized);
+            point_to_centroid_index_buffer[random_index] = i;
+            point_to_centroid_distance_buffer[random_index] = 0;
+        }
+
+        auto start_time = std::chrono::high_resolution_clock::now();
+        std::size_t iterations = 0;
+        std::size_t const min_points_shifted_per_iteration = static_cast<std::size_t>(min_shifts * points_count);
+        f64_t last_aggregate_distance = std::numeric_limits<f64_t>::max();
+
+        while (iterations < max_iterations) {
+            iterations++;
+
+            // For every point, find the closest centroid.
+            std::atomic<std::size_t> points_shifted{0};
+            executor.dynamic(points_count, [&](std::size_t thread_idx, std::size_t points_idx) {
+                byte_t const* quantized_point =
+                    points_quantized_buffer.data() + points_idx * stride_per_vector_quantized;
+                byte_t const* quantized_centroids = centroids_quantized_buffer.data();
+                distance_t closest_distance_local = std::numeric_limits<distance_t>::max();
+                std::size_t closest_idx_local = 0;
+                for (std::size_t centroid_idx = 0; centroid_idx < wanted_clusters; centroid_idx++) {
+                    byte_t const* quantized_centroid = quantized_centroids + centroid_idx * stride_per_vector_quantized;
+                    distance_t distance = metric(quantized_point, quantized_centroid);
+                    if (distance < closest_distance_local) {
+                        closest_distance_local = distance;
+                        closest_idx_local = centroid_idx;
+                    }
+                }
+
+                distance_t& closest_distance_ref = point_to_centroid_distance_buffer[points_idx];
+                std::size_t& closest_idx_ref = point_to_centroid_index_buffer[points_idx];
+                if (closest_idx_local != closest_idx_ref) {
+                    closest_idx_ref = closest_idx_local;
+                    points_shifted.fetch_add(1, std::memory_order_relaxed);
+                }
+
+                closest_distance_ref = closest_distance_local;
+                return true;
+            });
+
+            f64_t aggregate_distance = 0.0;
+            for (std::size_t i = 0; i < points_count; i++)
+                aggregate_distance += point_to_centroid_distance_buffer[i];
+            f64_t aggregate_distance_change =
+                std::abs(aggregate_distance - last_aggregate_distance) / last_aggregate_distance;
+
+            auto current_time = std::chrono::high_resolution_clock::now();
+            std::chrono::duration<f64_t> elapsed_time = current_time - start_time;
+            result.runtime_seconds = elapsed_time.count();
+            result.last_iteration_inertia = aggregate_distance_change;
+            result.last_iteration_points_shifted = points_shifted.load(std::memory_order_relaxed);
+
+            // Check for early-exit conditions
+            if (last_aggregate_distance != 0.0 && inertia_threshold != 0.0)
+                if (aggregate_distance_change <= inertia_threshold)
+                    break;
+            if (min_points_shifted_per_iteration != 0 || result.last_iteration_points_shifted == 0)
+                if (result.last_iteration_points_shifted <= min_points_shifted_per_iteration)
+                    break;
+            if (max_seconds != 0)
+                if (result.runtime_seconds >= max_seconds)
+                    break;
+
+            // For every centroid, recalculate the mean of all points assigned to it.
+            // That part is problematic to parallelize on many-core-systems, because of the contention.
+            // Alternatively, a tree-like approach can be used, where every core accumulates it's own partial sums.
+            // And those are later aggregated by a single thread.
+            std::memset(centroids_precise_buffer.data(), 0,
+                        wanted_clusters * dimensions * thread_count * sizeof(f64_t));
+            std::memset(reinterpret_cast<byte_t*>(cluster_sizes_buffer.data()), 0,
+                        wanted_clusters * sizeof(std::atomic<std::size_t>));
+            executor.dynamic(points_count, [&](std::size_t thread_idx, std::size_t points_idx) {
+                std::size_t centroid_idx = point_to_centroid_index_buffer[points_idx];
+                byte_t const* quantized_point =
+                    points_quantized_buffer.data() + points_idx * stride_per_vector_quantized;
+                f64_t* centroid_precise = centroids_precise_buffer.data() + wanted_clusters * dimensions * thread_idx +
+                                          centroid_idx * dimensions;
+
+                // Upcast the points point into a buffer of double-precision floats.
+                f64_t* point_precise = points_precise_buffer.data() + wanted_clusters * dimensions * thread_idx +
+                                       centroid_idx * dimensions;
+                if (!decompress_precise(quantized_point, dimensions, reinterpret_cast<byte_t*>(point_precise)))
+                    std::memcpy(reinterpret_cast<byte_t*>(point_precise), quantized_point, bytes_per_vector_quantized);
+
+                // Now add the vector from the points into the centroid partial sum.
+                for (std::size_t i = 0; i < dimensions; i++)
+                    centroid_precise[i] += point_precise[i];
+
+                cluster_sizes_buffer[centroid_idx].fetch_add(1, std::memory_order_relaxed);
+                return true;
+            });
+
+            // Aggregate the partial sums into the final centroids - storing them in the high-precision
+            // buffer of the first thread. Normalization procedure is different for different metrics.
+            for (std::size_t centroid_idx = 0; centroid_idx < wanted_clusters; centroid_idx++) {
+                f64_t* centroid_precise_aggregated = centroids_precise_buffer.data() + centroid_idx * dimensions;
+                for (std::size_t thread_idx = 1; thread_idx < thread_count; thread_idx++) {
+                    f64_t* centroid_precise = centroids_precise_buffer.data() +
+                                              wanted_clusters * dimensions * thread_idx + centroid_idx * dimensions;
+                    for (std::size_t i = 0; i < dimensions; i++)
+                        centroid_precise_aggregated[i] += centroid_precise[i];
+                }
+
+                // Normalize based on the metric kind
+                if (metric_kind == metric_kind_t::l2sq_k) {
+                    // Normalize for Euclidean distance (L2)
+                    std::size_t cluster_size = cluster_sizes_buffer[centroid_idx].load(std::memory_order_relaxed);
+                    if (cluster_size > 0)
+                        for (std::size_t i = 0; i < dimensions; i++)
+                            centroid_precise_aggregated[i] /= static_cast<f64_t>(cluster_size);
+
+                } else if (metric_kind == metric_kind_t::cos_k) {
+                    // Normalize for Cosine distance
+                    f64_t norm = 0.0;
+                    for (std::size_t i = 0; i < dimensions; i++)
+                        norm += centroid_precise_aggregated[i] * centroid_precise_aggregated[i];
+                    norm = std::sqrt(norm);
+                    if (norm > 0.0)
+                        for (std::size_t i = 0; i < dimensions; i++)
+                            centroid_precise_aggregated[i] /= norm;
+                }
+
+                // Quantize the centroid after normalization for further iterations
+                byte_t* centroid_quantized =
+                    centroids_quantized_buffer.data() + centroid_idx * stride_per_vector_quantized;
+                if (!compress_precise(reinterpret_cast<byte_t*>(centroid_precise_aggregated), dimensions,
+                                      centroid_quantized))
+                    std::memcpy(centroid_quantized, reinterpret_cast<byte_t*>(centroid_precise_aggregated),
+                                bytes_per_vector_quantized);
+            }
+        }
+
+        // Export stats.
+        result.iterations = iterations;
+        result.computed_distances = points_count * wanted_clusters * iterations;
+        result.aggregate_distance = 0;
+        for (distance_t distance : point_to_centroid_distance_buffer)
+            result.aggregate_distance += distance;
+
+        // We've finished all the iterations, now we can export the centroids back to the original precision.
+        std::memcpy(point_to_centroid_index, point_to_centroid_index_buffer.data(), points_count * sizeof(std::size_t));
+        std::memcpy(point_to_centroid_distance, point_to_centroid_distance_buffer.data(),
+                    points_count * sizeof(distance_t));
+        for (std::size_t i = 0; i < wanted_clusters; i++) {
+            byte_t const* quantized_centroid = centroids_quantized_buffer.data() + i * stride_per_vector_quantized;
+            byte_t* centroid = centroids_data + i * centroids_stride_bytes;
+            if (!decompress_points(quantized_centroid, dimensions, centroid))
+                std::memcpy(centroid, quantized_centroid, bytes_per_vector_quantized);
+        }
+
+        return result;
+    }
+};
+
+using kmeans_clustering_t = kmeans_clustering_gt<>;
+
 /**
  *  @brief  C++11 Multi-Hash-Set with Linear Probing.
  *

package/javascript/lib.cpp

@@ -20,6 +20,8 @@
 using namespace unum::usearch;
 using namespace unum;
 
+using add_result_t = typename index_dense_t::add_result_t;
+
 class CompiledIndex : public Napi::ObjectWrap<CompiledIndex> {
   public:
     static Napi::Object Init(Napi::Env env, Napi::Object exports);
@@ -129,6 +131,8 @@ void CompiledIndex::Load(Napi::CallbackInfo const& ctx) {
         auto result = native_->load(path.c_str());
         if (!result)
             Napi::TypeError::New(ctx.Env(), result.error.release()).ThrowAsJavaScriptException();
+        if (!native_->try_reserve(ceil2(native_->size())))
+            Napi::Error::New(ctx.Env(), "Failed to reserve memory").ThrowAsJavaScriptException();
 
     } catch (...) {
         Napi::TypeError::New(ctx.Env(), "Loading failed").ThrowAsJavaScriptException();
@@ -142,6 +146,8 @@ void CompiledIndex::View(Napi::CallbackInfo const& ctx) {
         auto result = native_->view(path.c_str());
         if (!result)
             Napi::TypeError::New(ctx.Env(), result.error.release()).ThrowAsJavaScriptException();
+        if (!native_->try_reserve(ceil2(native_->size())))
+            Napi::Error::New(ctx.Env(), "Failed to reserve memory").ThrowAsJavaScriptException();
 
     } catch (...) {
         Napi::TypeError::New(ctx.Env(), "Memory-mapping failed").ThrowAsJavaScriptException();
@@ -161,7 +167,10 @@ void CompiledIndex::Add(Napi::CallbackInfo const& ctx) {
     auto run_parallel = [&](auto vectors) {
         executor_stl_t executor;
         executor.fixed(tasks, [&](std::size_t /*thread_idx*/, std::size_t task_idx) {
-            native_->add(static_cast<default_key_t>(keys[task_idx]), vectors + task_idx * native_->dimensions());
+            add_result_t result = native_->add(static_cast<default_key_t>(keys[task_idx]),
+                                               vectors + task_idx * native_->dimensions());
+            if (!result)
+                Napi::Error::New(ctx.Env(), result.error.release()).ThrowAsJavaScriptException();
         });
     };
 
@@ -245,11 +254,14 @@ Napi::Value CompiledIndex::Remove(Napi::CallbackInfo const& ctx) {
     Napi::Env env = ctx.Env();
     Napi::BigUint64Array keys = ctx[0].As<Napi::BigUint64Array>();
     std::size_t length = keys.ElementLength();
-    Napi::Array result = Napi::Array::New(env, length);
+    Napi::Array results = Napi::Array::New(env, length);
     for (std::size_t i = 0; i < length; ++i) {
-        result[i] = Napi::Number::New(env, native_->remove(static_cast<default_key_t>(keys[i])).completed);
+        auto result = native_->remove(static_cast<default_key_t>(keys[i]));
+        if (!result)
+            Napi::Error::New(ctx.Env(), result.error.release()).ThrowAsJavaScriptException();
+        results[i] = Napi::Number::New(env, result.completed);
     }
-    return result;
+    return results;
 }
 
 Napi::Value CompiledIndex::Contains(Napi::CallbackInfo const& ctx) {
@@ -268,7 +280,7 @@ Napi::Value CompiledIndex::Count(Napi::CallbackInfo const& ctx) {
     std::size_t length = keys.ElementLength();
     Napi::Array result = Napi::Array::New(env, length);
     for (std::size_t i = 0; i < length; ++i)
-        result[i] = Napi::Boolean::New(env, native_->count(static_cast<default_key_t>(keys[i])));
+        result[i] = Napi::Number::New(env, native_->count(static_cast<default_key_t>(keys[i])));
     return result;
 }