Improve: Harden mini-float testing across SDKs

Author: ashvardanian

README.md

@@ -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,

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

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]);
         }
     }
 

csharp/README.md

@@ -14,7 +14,7 @@ using Cloud.Unum.USearch;
 
 using var index = new USearchIndex(
     metricKind: MetricKind.Cos, // Choose cosine metric
-    quantization: ScalarKind.Float32, // Only quantization to Float32, Float64, Int8 is currently supported
+    quantization: ScalarKind.Float32, // or Float64, BFloat16, Float16, E5M2, E4M3, E3M2, E2M3, Int8, UInt8
     dimensions: 3,  // Define the number of dimensions in input vectors
     connectivity: 16, // How frequent should the connections in the graph be, optional
     expansionAdd: 128, // Control the recall of indexing, optional

csharp/src/Cloud.Unum.USearch.Tests/USearchIndexTests.cs

@@ -165,6 +165,31 @@ public void Add_FloatVector_UpdatesIndexOptions()
         }
     }
 
+    [Fact]
+    public void Add_FloatVector_MiniFloatQuantizations()
+    {
+        ScalarKind[] kinds = { ScalarKind.E5M2, ScalarKind.E4M3, ScalarKind.E3M2, ScalarKind.E2M3 };
+        foreach (var kind in kinds)
+        {
+            var indexOptions = new IndexOptions(
+                metricKind: MetricKind.Cos,
+                quantization: kind,
+                dimensions: 64
+            );
+            var vector = GenerateFloatVector(64);
+            using (var index = new USearchIndex(indexOptions))
+            {
+                index.Add(1, vector);
+                Assert.True(index.Contains(1));
+                Assert.Equal(1u, index.Size());
+
+                int found = index.Search(vector, 1, out ulong[] keys, out float[] distances);
+                Assert.Equal(1, found);
+                Assert.Equal(1UL, keys[0]);
+            }
+        }
+    }
+
     [Fact]
     public void Add_ByteVector_UpdatesIndexOptions()
     {

golang/README.md

@@ -58,6 +58,7 @@ func main() {
    	vectorSize := 3
    	vectorsCount := 100
    	conf := usearch.DefaultConfig(uint(vectorSize))
+   	conf.Quantization = usearch.F32 // or BF16, F16, E5M2, E4M3, E3M2, E2M3, I8, U8
    	index, err := usearch.NewIndex(conf)
    	if err != nil {
    		panic("Failed to create Index")

golang/lib.go

@@ -769,7 +769,7 @@ func (index *Index) FilteredSearch(query []float32, limit uint, handler *Filtere
 	distances = make([]float32, limit)
 	var errorMessage *C.char
 	resultCount := uint(C.usearch_filtered_search(index.handle, unsafe.Pointer(&query[0]), C.usearch_scalar_f32_k, (C.size_t)(limit),
-		(C.usearch_filtered_search_callback_t)(C.goFilteredSearchCallback), unsafe.Pointer(handler),
+		(C.usearch_filtered_search_callback_t)(C.goFilteredSearchCallback), unsafe.Pointer(handler), //nolint:govet // handler is kept alive by the caller
 		(*C.usearch_key_t)(&keys[0]), (*C.usearch_distance_t)(&distances[0]), (*C.usearch_error_t)(&errorMessage)))
 	runtime.KeepAlive(query)
 	runtime.KeepAlive(keys)
@@ -856,7 +856,7 @@ func (index *Index) FilteredSearchUnsafe(query unsafe.Pointer, limit uint, handl
 	distances = make([]float32, limit)
 	var errorMessage *C.char
 	resultCount := uint(C.usearch_filtered_search(index.handle, query, index.config.Quantization.CValue(), (C.size_t)(limit),
-		(C.usearch_filtered_search_callback_t)(C.goFilteredSearchCallback), unsafe.Pointer(handler),
+		(C.usearch_filtered_search_callback_t)(C.goFilteredSearchCallback), unsafe.Pointer(handler), //nolint:govet // handler is kept alive by the caller
 		(*C.usearch_key_t)(&keys[0]), (*C.usearch_distance_t)(&distances[0]), (*C.usearch_error_t)(&errorMessage)))
 	runtime.KeepAlive(query)
 	runtime.KeepAlive(keys)
@@ -1041,7 +1041,7 @@ func (index *Index) FilteredSearchI8(query []int8, limit uint, handler *Filtered
 	distances = make([]float32, limit)
 	var errorMessage *C.char
 	resultCount := uint(C.usearch_filtered_search(index.handle, unsafe.Pointer(&query[0]), C.usearch_scalar_i8_k, (C.size_t)(limit),
-		(C.usearch_filtered_search_callback_t)(C.goFilteredSearchCallback), unsafe.Pointer(handler),
+		(C.usearch_filtered_search_callback_t)(C.goFilteredSearchCallback), unsafe.Pointer(handler), //nolint:govet // handler is kept alive by the caller
 		(*C.usearch_key_t)(&keys[0]), (*C.usearch_distance_t)(&distances[0]), (*C.usearch_error_t)(&errorMessage)))
 	runtime.KeepAlive(query)
 	runtime.KeepAlive(keys)
@@ -1134,7 +1134,7 @@ func (index *Index) FilteredSearchU8(query []uint8, limit uint, handler *Filtere
 	distances = make([]float32, limit)
 	var errorMessage *C.char
 	resultCount := uint(C.usearch_filtered_search(index.handle, unsafe.Pointer(&query[0]), C.usearch_scalar_u8_k, (C.size_t)(limit),
-		(C.usearch_filtered_search_callback_t)(C.goFilteredSearchCallback), unsafe.Pointer(handler),
+		(C.usearch_filtered_search_callback_t)(C.goFilteredSearchCallback), unsafe.Pointer(handler), //nolint:govet // handler is kept alive by the caller
 		(*C.usearch_key_t)(&keys[0]), (*C.usearch_distance_t)(&distances[0]), (*C.usearch_error_t)(&errorMessage)))
 	runtime.KeepAlive(query)
 	runtime.KeepAlive(keys)

golang/lib_test.go

@@ -2,6 +2,7 @@ package usearch
 
 import (
 	"errors"
+	"fmt"
 	"io"
 	"math"
 	"runtime"
@@ -724,6 +725,32 @@ func TestQuantizationTypes(t *testing.T) {
 			t.Fatalf("U8 Get returned wrong dimensions: got %d, expected 32", len(retrieved))
 		}
 	})
+
+	for _, qt := range []Quantization{E5M2, E4M3, E3M2, E2M3} {
+		qt := qt
+		t.Run(fmt.Sprintf("%v mini-float operations", qt), func(t *testing.T) {
+			index := createTestIndex(t, 32, qt)
+			defer func() {
+				if err := index.Destroy(); err != nil {
+					t.Errorf("Failed to destroy index: %v", err)
+				}
+			}()
+			if err := index.Reserve(1); err != nil {
+				t.Fatalf("Failed to reserve: %v", err)
+			}
+			vector := generateTestVector(32)
+			if err := index.Add(1, vector); err != nil {
+				t.Fatalf("Add failed: %v", err)
+			}
+			keys, _, err := index.Search(vector, 1)
+			if err != nil {
+				t.Fatalf("Search failed: %v", err)
+			}
+			if len(keys) == 0 || keys[0] != 1 {
+				t.Fatalf("search results incorrect")
+			}
+		})
+	}
 }
 
 func TestUnsafeOperations(t *testing.T) {
@@ -1114,7 +1141,7 @@ func TestVersion(t *testing.T) {
 
 func TestClear(t *testing.T) {
 	index := createTestIndex(t, 32, F32)
-	defer index.Destroy()
+	defer func() { _ = index.Destroy() }()
 
 	if err := index.Reserve(10); err != nil {
 		t.Fatalf("Failed to reserve capacity: %v", err)
@@ -1155,7 +1182,7 @@ func TestClear(t *testing.T) {
 
 func TestCount(t *testing.T) {
 	index := createTestIndex(t, 32, F32)
-	defer index.Destroy()
+	defer func() { _ = index.Destroy() }()
 
 	if err := index.Reserve(10); err != nil {
 		t.Fatalf("Failed to reserve capacity: %v", err)
@@ -1188,7 +1215,7 @@ func TestCount(t *testing.T) {
 
 func TestRename(t *testing.T) {
 	index := createTestIndex(t, 32, F32)
-	defer index.Destroy()
+	defer func() { _ = index.Destroy() }()
 
 	if err := index.Reserve(10); err != nil {
 		t.Fatalf("Failed to reserve capacity: %v", err)

java/README.md

@@ -104,7 +104,7 @@ long connectivity = index.connectivity();
 
 ## Multiple Data Types and Quantization
 
-USearch supports hardware-agnostic `f64`, `f32`, and `i8` quantization for memory efficiency and performance optimization.
+USearch supports hardware-agnostic `f64`, `f32`, `bf16`, `f16`, `e5m2`, `e4m3`, `e3m2`, `e2m3`, `i8`, and `b1` quantization for memory efficiency and performance optimization.
 
 ```java
 // Double precision (f64) for highest accuracy

java/test/IndexTest.java

@@ -229,6 +229,22 @@ public void testByteVectorWithInt8() {
         }
     }
 
+    @Test
+    public void testMiniFloatQuantizations() {
+        for (String quantization : new String[]{"e5m2", "e4m3", "e3m2", "e2m3"}) {
+            try (Index index = new Index.Config()
+                    .metric("cos").dimensions(64).quantization(quantization).build()) {
+                float[] vec = new float[64];
+                for (int i = 0; i < 64; i++) vec[i] = (float) i * 0.1f;
+                index.reserve(10);
+                index.add(42, vec);
+
+                long[] keys = index.search(vec, 1);
+                assertEquals("Self-match failed for " + quantization, 42L, keys[0]);
+            }
+        }
+    }
+
     @Test
     public void testGetIntoBufferMethods() {
         try (Index index = new Index.Config().metric("cos").dimensions(3).build()) {