usearch 2.25.0 → 2.25.3

package/README.md

@@ -42,7 +42,7 @@ Linux • macOS • Windows • iOS • Android • WebAssembly •
 <a href="https://crates.io/crates/usearch"> <img alt="Crate" src="https://img.shields.io/crates/d/usearch?label=Rust%20Crate%20installs"> </a>
 <a href="https://www.nuget.org/packages/Cloud.Unum.USearch"> <img alt="NuGet" src="https://img.shields.io/nuget/dt/Cloud.Unum.USearch?label=CSharp%20NuGet%20installs"> </a>
 <!-- Maven Central publishing is deprecated for now; fat-JAR download is the supported path. -->
-<img alt="GitHub code size in bytes" src="https://img.shields.io/github/languages/code-size/unum-cloud/usearch?label=Repo%20size">
+<img alt="GitHub code size in bytes" src="https://img.shields.io/github/languages/code-size/unum-cloud/USearch?label=Repo%20size">
 </div>
 
 ---
@@ -51,7 +51,7 @@ Linux • macOS • Windows • iOS • Android • WebAssembly •
 - ✅ Simple and extensible [single C++11 header][usearch-header] __library__.
 - ✅ [Trusted](#integrations) by giants like Google and DBs like [ClickHouse][clickhouse-docs] & [DuckDB][duckdb-docs].
 - ✅ [SIMD][simd]-optimized and [user-defined metrics](#user-defined-functions) with JIT compilation.
-- ✅ Hardware-agnostic `f16` & `i8` - [half-precision & quarter-precision support](#memory-efficiency-downcasting-and-quantization).
+- ✅ Hardware-agnostic `bf16`, `e5m2`, & `i8` - [half-precision & quarter-precision support](#memory-efficiency-downcasting-and-quantization).
 - ✅ [View large indexes from disk](#serialization--serving-index-from-disk) without loading into RAM.
 - ✅ Heterogeneous lookups, renaming/relabeling, and on-the-fly deletions.
 - ✅ Binary Tanimoto and Sorensen coefficients for [Genomics and Chemistry applications](#usearch--rdkit--molecular-search).
@@ -138,7 +138,7 @@ The default storage/quantization level is hardware-dependant for efficiency, but
 index = Index(
     ndim=3, # Define the number of dimensions in input vectors
     metric='cos', # Choose 'l2sq', 'ip', 'haversine' or other metric, default = 'cos'
-    dtype='bf16', # Store as 'f64', 'f32', 'f16', 'i8', 'b1'..., default = None
+    dtype='bf16', # Store as 'f64', 'f32', 'bf16', 'f16', 'e5m2', 'e4m3', 'e3m2', 'e2m3', 'u8', 'i8', 'b1'..., default = None
     connectivity=16, # Optional: Limit number of neighbors per graph node
     expansion_add=128, # Optional: Control the recall of indexing
     expansion_search=64, # Optional: Control the quality of the search
@@ -251,7 +251,7 @@ assert!(
 Training a quantization model and dimension-reduction is a common approach to accelerate vector search.
 Those, however, are only sometimes reliable, can significantly affect the statistical properties of your data, and require regular adjustments if your distribution shifts.
 Instead, we have focused on high-precision arithmetic over low-precision downcasted vectors.
-The same index, and `add` and `search` operations will automatically down-cast or up-cast between `f64_t`, `f32_t`, `f16_t`, `i8_t`, and single-bit `b1x8_t` representations.
+The same index, and `add` and `search` operations will automatically down-cast or up-cast between `f64_t`, `f32_t`, `bf16_t`, `f16_t`, `e5m2_t`, `e4m3_t`, `e3m2_t`, `e2m3_t`, `u8_t`, `i8_t`, and single-bit `b1x8_t` representations.
 You can use the following command to check, if hardware acceleration is enabled:
 
 ```sh
@@ -261,7 +261,9 @@ $ python -c 'from usearch.index import Index; print(Index(ndim=166, metric="tani
 > ice
 ```
 
-In most cases, it's recommended to use half-precision floating-point numbers on modern hardware.
+In most cases, `bf16` is recommended for modern CPUs.
+For even smaller footprints, USearch supports IEEE & MX-compatible Float8 (`e5m2` and `e4m3`) and Float6 (`e3m2` and `e2m3`) formats.
+You can pass pre-quantized buffers from [NumKong](https://github.com/ashvardanian/numkong) with the explicit `dtype=` parameter on `add` and `search`, or let USearch handle the quantization internally from higher-precision inputs.
 When quantization is enabled, the "get"-like functions won't be able to recover the original data, so you may want to replicate the original vectors elsewhere.
 When quantizing to `i8_t` integers, note that it's only valid for cosine-like metrics.
 As part of the quantization process, the vectors are normalized to unit length and later scaled to [-127, 127] range to occupy the full 8-bit range.
@@ -479,46 +481,41 @@ The Haversine distance is available out of the box, but you can also define more
 from numba import cfunc, types, carray
 import math
 
-# Define the dimension as 2 for latitude and longitude
 ndim = 2
+semi_major, flattening = 6378137.0, 1 / 298.257223563
+semi_minor = (1 - flattening) * semi_major
+
+def vincenty_distance(first_ptr, second_ptr):
+    first, second = carray(first_ptr, ndim), carray(second_ptr, ndim)
+    lat1, lon1, lat2, lon2 = first[0], first[1], second[0], second[1]
+    diff_lon = lon2 - lon1
+    rlat1, rlat2 = math.atan((1 - flattening) * math.tan(lat1)), math.atan((1 - flattening) * math.tan(lat2))
+    sin_rlat1, cos_rlat1 = math.sin(rlat1), math.cos(rlat1)
+    sin_rlat2, cos_rlat2 = math.sin(rlat2), math.cos(rlat2)
+    lon_on_sphere = diff_lon
+    for _ in range(100):
+        sin_lon, cos_lon = math.sin(lon_on_sphere), math.cos(lon_on_sphere)
+        sin_ang = math.sqrt((cos_rlat2 * sin_lon) ** 2 + (cos_rlat1 * sin_rlat2 - sin_rlat1 * cos_rlat2 * cos_lon) ** 2)
+        if sin_ang == 0: return 0.0
+        cos_ang = sin_rlat1 * sin_rlat2 + cos_rlat1 * cos_rlat2 * cos_lon
+        ang = math.atan2(sin_ang, cos_ang)
+        sin_az = cos_rlat1 * cos_rlat2 * sin_lon / sin_ang
+        cos2_az = 1 - sin_az ** 2
+        cos2_mid = cos_ang - 2 * sin_rlat1 * sin_rlat2 / cos2_az if cos2_az != 0 else 0.0
+        corr = flattening / 16 * cos2_az * (4 + flattening * (4 - 3 * cos2_az))
+        prev = lon_on_sphere
+        lon_on_sphere = diff_lon + (1 - corr) * flattening * (
+            sin_az * (ang + corr * sin_ang * (cos2_mid + corr * cos_ang * (-1 + 2 * cos2_mid ** 2))))
+        if abs(lon_on_sphere - prev) <= 1e-12: break
+    else:
+        return float('nan')
+    u_sq = cos2_az * (semi_major ** 2 - semi_minor ** 2) / (semi_minor ** 2)
+    ca = 1 + u_sq / 16384 * (4096 + u_sq * (-768 + u_sq * (320 - 175 * u_sq)))
+    cb = u_sq / 1024 * (256 + u_sq * (-128 + u_sq * (74 - 47 * u_sq)))
+    delta = cb * sin_ang * (cos2_mid + cb / 4 * (cos_ang * (-1 + 2 * cos2_mid ** 2)
+        - cb / 6 * cos2_mid * (-3 + 4 * sin_ang ** 2) * (-3 + 4 * cos2_mid ** 2)))
+    return semi_minor * ca * (ang - delta) / 1000.0
 
-# Signature for the custom metric
-signature = types.float32(
-    types.CPointer(types.float32),
-    types.CPointer(types.float32))
-
-# WGS-84 ellipsoid parameters
-a = 6378137.0  # major axis in meters
-f = 1 / 298.257223563  # flattening
-b = (1 - f) * a  # minor axis
-
-def vincenty_distance(a_ptr, b_ptr):
-    a_array = carray(a_ptr, ndim)
-    b_array = carray(b_ptr, ndim)
-    lat1, lon1, lat2, lon2 = a_array[0], a_array[1], b_array[0], b_array[1]
-    L, U1, U2 = lon2 - lon1, math.atan((1 - f) * math.tan(lat1)), math.atan((1 - f) * math.tan(lat2))
-    sinU1, cosU1, sinU2, cosU2 = math.sin(U1), math.cos(U1), math.sin(U2), math.cos(U2)
-    lambda_, iterLimit = L, 100
-    while iterLimit > 0:
-        iterLimit -= 1
-        sinLambda, cosLambda = math.sin(lambda_), math.cos(lambda_)
-        sinSigma = math.sqrt((cosU2 * sinLambda) ** 2 + (cosU1 * sinU2 - sinU1 * cosU2 * cosLambda) ** 2)
-        if sinSigma == 0: return 0.0  # Co-incident points
-        cosSigma, sigma = sinU1 * sinU2 + cosU1 * cosU2 * cosLambda, math.atan2(sinSigma, cosSigma)
-        sinAlpha, cos2Alpha = cosU1 * cosU2 * sinLambda / sinSigma, 1 - (cosU1 * cosU2 * sinLambda / sinSigma) ** 2
-        cos2SigmaM = cosSigma - 2 * sinU1 * sinU2 / cos2Alpha if not math.isnan(cosSigma - 2 * sinU1 * sinU2 / cos2Alpha) else 0  # Equatorial line
-        C = f / 16 * cos2Alpha * (4 + f * (4 - 3 * cos2Alpha))
-        lambda_, lambdaP = L + (1 - C) * f * (sinAlpha * (sigma + C * sinSigma * (cos2SigmaM + C * cosSigma * (-1 + 2 * cos2SigmaM ** 2)))), lambda_
-        if abs(lambda_ - lambdaP) <= 1e-12: break
-    if iterLimit == 0: return float('nan')  # formula failed to converge
-    u2 = cos2Alpha * (a ** 2 - b ** 2) / (b ** 2)
-    A = 1 + u2 / 16384 * (4096 + u2 * (-768 + u2 * (320 - 175 * u2)))
-    B = u2 / 1024 * (256 + u2 * (-128 + u2 * (74 - 47 * u2)))
-    deltaSigma = B * sinSigma * (cos2SigmaM + B / 4 * (cosSigma * (-1 + 2 * cos2SigmaM ** 2) - B / 6 * cos2SigmaM * (-3 + 4 * sinSigma ** 2) * (-3 + 4 * cos2SigmaM ** 2)))
-    s = b * A * (sigma - deltaSigma)
-    return s / 1000.0  # Distance in kilometers
-
-# Example usage:
 index = Index(ndim=ndim, metric=CompiledMetric(
     pointer=vincenty_distance.address,
     kind=MetricKind.Haversine,
@@ -547,13 +544,12 @@ index = Index(ndim=ndim, metric=CompiledMetric(
 ## Citations
 
 ```bibtex
-@software{Vardanian_USearch_2023,
+@software{Vardanian_USearch,
 doi = {10.5281/zenodo.7949416},
 author = {Vardanian, Ash},
 title = {{USearch by Unum Cloud}},
 url = {https://github.com/unum-cloud/USearch},
-version = {2.25.0},
-year = {2023},
-month = oct,
+version = {2.25.3},
+year = {2026},
 }
 ```

package/c/README.md

@@ -19,7 +19,7 @@ int main() {
     usearch_error_t error = NULL;
     usearch_init_options_t opts = {
         .metric_kind = usearch_metric_cos_k,
-        .scalar_kind = usearch_scalar_f16_k,
+        .scalar_kind = usearch_scalar_f16_k, // or f32_k, bf16_k, e5m2_k, e4m3_k, e3m2_k, e2m3_k, i8_k, u8_k
         .dimensions = dimensions,
         .expansion_add = 0, // for defaults
         .expansion_search = 0 // for defaults

package/c/lib.cpp

@@ -186,16 +186,14 @@ USEARCH_EXPORT usearch_index_t usearch_init(usearch_init_options_t* options, use
 
     using state_result_t = typename index_dense_t::state_result_t;
     state_result_t state = index_dense_t::make(metric, config);
-    if (!state)
+    if (!state) {
         *error = state.error.release();
-    index_dense_t* result_ptr = new index_dense_t(std::move(state.index));
+        return NULL;
+    }
+    index_dense_t* result_ptr = new (std::nothrow) index_dense_t(std::move(state.index));
     if (!result_ptr)
         *error = "Out of memory!";
 
-    // Let's immediately make it usable by reserving enough threads for this machine:
-    if (!result_ptr->try_reserve(index_limits_t()))
-        *error = "Out of memory when preparing contexts!";
-
     return result_ptr;
 }
 
@@ -236,8 +234,10 @@ USEARCH_EXPORT void usearch_metadata(char const* path, usearch_init_options_t* o
 
     USEARCH_ASSERT(path && options && error && "Missing arguments");
     index_dense_metadata_result_t result = index_dense_metadata_from_path(path);
-    if (!result)
+    if (!result) {
         *error = result.error.release();
+        return;
+    }
 
     options->metric_kind = metric_kind_to_c(result.head.kind_metric);
     options->quantization = scalar_kind_to_c(result.head.kind_scalar);
@@ -285,8 +285,10 @@ USEARCH_EXPORT void usearch_metadata_buffer(void const* buffer, size_t length, u
     USEARCH_ASSERT(buffer && length && options && error && "Missing arguments");
     index_dense_metadata_result_t result =
         index_dense_metadata_from_buffer(memory_mapped_file_t((byte_t*)(buffer), length));
-    if (!result)
+    if (!result) {
         *error = result.error.release();
+        return;
+    }
 
     options->metric_kind = metric_kind_to_c(result.head.kind_metric);
     options->quantization = scalar_kind_to_c(result.head.kind_scalar);
@@ -354,7 +356,8 @@ USEARCH_EXPORT void usearch_change_threads_add(usearch_index_t index, size_t thr
     auto& index_dense = *reinterpret_cast<index_dense_t*>(index);
     index_limits_t limits = index_dense.limits();
     limits.threads_add = threads;
-    index_dense.try_reserve(limits);
+    if (!index_dense.try_reserve(limits))
+        *error = "Out of memory!";
 }
 
 USEARCH_EXPORT void usearch_change_threads_search(usearch_index_t index, size_t threads, usearch_error_t* error) {
@@ -362,15 +365,22 @@ USEARCH_EXPORT void usearch_change_threads_search(usearch_index_t index, size_t
     auto& index_dense = *reinterpret_cast<index_dense_t*>(index);
     index_limits_t limits = index_dense.limits();
     limits.threads_search = threads;
-    index_dense.try_reserve(limits);
+    if (!index_dense.try_reserve(limits))
+        *error = "Out of memory!";
 }
 
 USEARCH_EXPORT void usearch_change_metric_kind(usearch_index_t index, usearch_metric_kind_t kind,
                                                usearch_error_t* error) {
     USEARCH_ASSERT(index && error && "Missing arguments");
     auto& index_dense = *reinterpret_cast<index_dense_t*>(index);
-    index_dense.change_metric(
-        metric_punned_t::builtin(index_dense.dimensions(), metric_kind_to_cpp(kind), index_dense.scalar_kind()));
+    auto metric_punned =
+        metric_punned_t::builtin(index_dense.dimensions(), metric_kind_to_cpp(kind), index_dense.scalar_kind());
+    if (metric_punned.missing()) {
+        *error = "Unsupported metric for this index's dimensions and scalar kind!";
+        return;
+    }
+    if (!index_dense.try_change_metric(std::move(metric_punned)))
+        *error = "Failed to grow cast buffer for the new metric!";
 }
 
 USEARCH_EXPORT void usearch_change_metric(usearch_index_t index, usearch_metric_t metric, void* state,
@@ -384,7 +394,12 @@ USEARCH_EXPORT void usearch_change_metric(usearch_index_t index, usearch_metric_
               : metric_punned_t::stateless(index_dense.dimensions(), reinterpret_cast<std::uintptr_t>(metric),
                                            metric_punned_signature_t::array_array_k, metric_kind_to_cpp(kind),
                                            index_dense.scalar_kind());
-    index_dense.change_metric(std::move(metric_punned));
+    if (metric_punned.missing()) {
+        *error = "Unsupported metric for this index's dimensions and scalar kind!";
+        return;
+    }
+    if (!index_dense.try_change_metric(std::move(metric_punned)))
+        *error = "Failed to grow cast buffer for the new metric!";
 }
 
 USEARCH_EXPORT void usearch_reserve(usearch_index_t index, size_t capacity, usearch_error_t* error) {

package/c/test.c

@@ -448,6 +448,46 @@ void test_view(size_t const collection_size, size_t const dimensions) {
     printf("Test: View - PASSED\n");
 }
 
+void test_mini_float_quantizations(size_t const collection_size, size_t const dimensions) {
+    printf("Test: Mini-float quantizations... %zu vectors, %zu dimensions\n", collection_size, dimensions);
+    usearch_scalar_kind_t kinds[] = {
+        usearch_scalar_e5m2_k,
+        usearch_scalar_e4m3_k,
+        usearch_scalar_e3m2_k,
+        usearch_scalar_e2m3_k,
+    };
+    float* data = create_vectors(collection_size, dimensions);
+    usearch_key_t* keys = (usearch_key_t*)malloc(collection_size * sizeof(usearch_key_t));
+    float* distances = (float*)malloc(collection_size * sizeof(float));
+    expect(keys && distances, "Failed to allocate memory");
+
+    for (size_t k = 0; k < sizeof(kinds) / sizeof(kinds[0]); ++k) {
+        usearch_error_t error = NULL;
+        usearch_init_options_t opts = create_options(dimensions);
+        opts.quantization = kinds[k];
+        usearch_index_t index = usearch_init(&opts, &error);
+        expect(!error, error);
+        usearch_reserve(index, collection_size, &error);
+        expect(!error, error);
+        for (size_t i = 0; i < collection_size; ++i) {
+            usearch_add(index, (usearch_key_t)i, data + i * dimensions, usearch_scalar_f32_k, &error);
+            expect(!error, error);
+        }
+        expect_eq(usearch_size(index, &error), collection_size, error);
+        for (size_t i = 0; i < collection_size; ++i) {
+            size_t found =
+                usearch_search(index, data + i * dimensions, usearch_scalar_f32_k, 1, keys, distances, &error);
+            expect(!error, error);
+            expect(found >= 1, "Vector not found");
+        }
+        usearch_free(index, &error);
+    }
+    free(data);
+    free(keys);
+    free(distances);
+    printf("Test: Mini-float quantizations - PASSED\n");
+}
+
 int main(int argc, char const* argv[]) {
     install_crash_handlers();
     printf("Running tests...\n");
@@ -464,6 +504,7 @@ int main(int argc, char const* argv[]) {
             test_remove_vector(collection_sizes[index], dimensions[jdx]);
             test_save_load(collection_sizes[index], dimensions[jdx]);
             test_view(collection_sizes[index], dimensions[jdx]);
+            test_mini_float_quantizations(collection_sizes[index], dimensions[jdx]);
         }
     }
 

package/cpp/test.cpp

@@ -17,6 +17,7 @@
 #include <csignal> // `std::signal`, `SIGSEGV`, ...
 #include <cstdio>  // `std::fprintf`
 #include <cstdlib> // `std::_Exit`
+#include <limits>  // `std::numeric_limits`
 
 #include <algorithm>     // `std::shuffle`
 #include <random>        // `std::default_random_engine`
@@ -216,6 +217,47 @@ void test_uint40() {
     expect_eq(u40_default, uint40_t(0u));
 }
 
+void test_checked_size_arithmetic() {
+
+    std::printf("Testing checked size arithmetic\n");
+    std::size_t max = (std::numeric_limits<std::size_t>::max)();
+
+    checked_size_result_t cast = checked_size_from_u64(42);
+    expect(cast);
+    expect_eq(cast.value, static_cast<std::size_t>(42));
+    if (sizeof(std::size_t) < sizeof(std::uint64_t))
+        expect(!checked_size_from_u64((std::numeric_limits<std::uint64_t>::max)()));
+
+    checked_size_result_t sum = checked_add(max - 1, 1);
+    expect(sum);
+    expect_eq(sum.value, max);
+    expect(!checked_add(max, 1));
+
+    checked_size_result_t product = checked_mul(max / 2, 2);
+    expect(product);
+    expect_eq(product.value, max - 1);
+    expect(!checked_mul(max / 2 + 1, 2));
+
+    checked_size_result_t fused = checked_mul_add(10, 20, 30);
+    expect(fused);
+    expect_eq(fused.value, static_cast<std::size_t>(230));
+    expect(!checked_mul_add(max / 2 + 1, 2, 0));
+    expect(!checked_mul_add(max / 2, 2, 2));
+
+    checked_size_result_t rounded = checked_round_up(17, 8);
+    expect(rounded);
+    expect_eq(rounded.value, static_cast<std::size_t>(24));
+    expect(!checked_round_up(max, 8));
+
+    checked_size_result_t power = checked_ceil2(17);
+    expect(power);
+    expect_eq(power.value, static_cast<std::size_t>(32));
+    checked_size_result_t zero_power = checked_ceil2(0);
+    expect(zero_power);
+    expect_eq(zero_power.value, static_cast<std::size_t>(0));
+    expect(!checked_ceil2(max));
+}
+
 /**
  *  @brief  Tests the functionality of the custom float16_t type ensuring consistent.
  */
@@ -1264,6 +1306,61 @@ static void install_crash_handlers() {
         std::signal(signal_number, &usearch_crash_handler);
 }
 
+/**
+ *  @brief  Regression test: `make(metric, config)` must return an index that is
+ *          immediately usable - no explicit `reserve` required before `load` /
+ *          `view` / `search`. Previously the typed graph's `{0, 0}` thread
+ *          limits leaked into `load_from_stream`, leaving `available_threads_`
+ *          empty and making the first `search` throw "No available threads to
+ *          lock".
+ */
+void test_load_after_metric_make() {
+    std::printf("Testing load and view into a metric-made index\n");
+
+    using index_t = index_dense_gt<std::int64_t, std::uint32_t>;
+    std::size_t const dimensions = 32;
+    std::size_t const collection = 64;
+
+    std::default_random_engine rng(7);
+    std::uniform_real_distribution<float> distribution(-1.f, 1.f);
+    std::vector<std::vector<float>> data(collection);
+    for (auto& vector : data) {
+        vector.resize(dimensions);
+        for (auto& value : vector)
+            value = distribution(rng);
+    }
+
+    metric_punned_t metric(dimensions, metric_kind_t::cos_k, scalar_kind<f32_t>());
+    index_dense_config_t config(16);
+
+    // Build an index and persist it to disk.
+    index_t::state_result_t built = index_t::make(metric, config);
+    expect(built);
+    expect(built.index.try_reserve(collection));
+    for (std::size_t i = 0; i != collection; ++i)
+        expect(built.index.add(static_cast<std::int64_t>(i), data[i].data()));
+    char const* path = "tmp_metric_make.usearch";
+    expect(built.index.save(path));
+
+    // Load into a fresh, metric-made index that was never explicitly reserved.
+    // The first `search` must not throw "No available threads to lock".
+    index_t::state_result_t loaded = index_t::make(metric, config);
+    expect(loaded);
+    expect(loaded.index.load(path));
+    expect_eq(loaded.index.size(), collection);
+    std::int64_t found[8];
+    expect(loaded.index.search(data[0].data(), 5).dump_to(found) != 0);
+
+    // Same check for the memory-mapped `view` path.
+    index_t::state_result_t viewed = index_t::make(metric, config);
+    expect(viewed);
+    expect(viewed.index.view(path));
+    expect_eq(viewed.index.size(), collection);
+    expect(viewed.index.search(data[0].data(), 5).dump_to(found) != 0);
+
+    std::remove(path);
+}
+
 int main(int, char**) {
     install_crash_handlers();
 
@@ -1272,6 +1369,7 @@ int main(int, char**) {
 
     // Non-default floating-point types may result in many compilation & rounding issues.
     test_uint40();
+    test_checked_size_arithmetic();
     test_cosine<f32_t, std::int64_t, uint40_t>(10, 10);
     test_cosine<bf16_t, std::int64_t, uint40_t>(10, 10);
     test_cosine<f16_t, std::int64_t, uint40_t>(10, 10);
@@ -1354,5 +1452,6 @@ int main(int, char**) {
 
     test_filtered_search();
     test_isolate();
+    test_load_after_metric_make();
     return 0;
 }