usearch 0.13.0 → 0.15.0

package/rust/lib.hpp

@@ -3,19 +3,16 @@
 
 #include <memory> // `std::shared_ptr`
 
-#include "punned.hpp"
+#include <usearch/index_punned_dense.hpp>
 
 struct Matches;
-
-enum class Metric;
-
-enum class Accuracy;
+struct IndexOptions;
 
 class Index {
   public:
     using label_t = std::uint32_t;
     using distance_t = unum::usearch::punned_distance_t;
-    using punned_t = unum::usearch::punned_gt<label_t>;
+    using punned_t = unum::usearch::index_punned_dense_gt<label_t>;
 
     Index(std::unique_ptr<punned_t> index);
 
@@ -40,7 +37,4 @@ class Index {
     std::unique_ptr<punned_t> index_;
 };
 
-std::unique_ptr<Index> new_ip(size_t dims, rust::Str quant, size_t connectivity, size_t exp_add, size_t exp_search);
-std::unique_ptr<Index> new_l2sq(size_t dims, rust::Str quant, size_t connectivity, size_t exp_add, size_t exp_search);
-std::unique_ptr<Index> new_cos(size_t dims, rust::Str quant, size_t connectivity, size_t exp_add, size_t exp_search);
-std::unique_ptr<Index> new_haversine(rust::Str quant, size_t connectivity, size_t exp_add, size_t exp_search);
+std::unique_ptr<Index> new_index(IndexOptions const& options);

package/rust/lib.rs

@@ -8,16 +8,41 @@ pub mod ffi {
         distances: Vec<f32>,
     }
 
+    enum MetricKind {
+        IP,
+        L2Sq,
+        Cos,
+        Pearson,
+        Haversine,
+        Hamming,
+        Tanimoto,
+        Sorensen,
+    }
+
+    enum ScalarKind {
+        F64,
+        F32,
+        F16,
+        F8,
+        B1,
+    }
+
+    struct IndexOptions {
+        dimensions: usize,
+        metric: MetricKind,
+        quantization: ScalarKind,
+        connectivity: usize,
+        expansion_add: usize,
+        expansion_search: usize,
+    }
+
     // C++ types and signatures exposed to Rust.
     unsafe extern "C++" {
         include!("lib.hpp");
 
         type Index;
 
-        pub fn new_ip(dimensions: usize, quantization: &str, connectivity: usize, expansion_add: usize, expansion_search: usize) -> Result<UniquePtr<Index>>;
-        pub fn new_l2sq(dimensions: usize, quantization: &str, connectivity: usize, expansion_add: usize, expansion_search: usize) -> Result<UniquePtr<Index>>;
-        pub fn new_cos(dimensions: usize, quantization: &str, connectivity: usize, expansion_add: usize, expansion_search: usize) -> Result<UniquePtr<Index>>;
-        pub fn new_haversine(quantization: &str, connectivity: usize, expansion_add: usize, expansion_search: usize) -> Result<UniquePtr<Index>>;
+        pub fn new_index(options: &IndexOptions) -> Result<UniquePtr<Index>>;
 
         pub fn reserve(self: &Index, capacity: usize) -> Result<()>;
 
@@ -29,9 +54,6 @@ pub mod ffi {
         pub fn add(self: &Index, label: u32, vector: &[f32]) -> Result<()>;
         pub fn search(self: &Index, query: &[f32], count: usize) -> Result<Matches>;
 
-        pub fn add_in_thread(self: &Index, label: u32, vector: &[f32], thread: usize) -> Result<()>;
-        pub fn search_in_thread(self: &Index, query: &[f32], count: usize, thread: usize) -> Result<Matches>;
-
         pub fn save(self: &Index, path: &str) -> Result<()>;
         pub fn load(self: &Index, path: &str) -> Result<()>;
         pub fn view(self: &Index, path: &str) -> Result<()>;
@@ -41,16 +63,24 @@ pub mod ffi {
 
 #[cfg(test)]
 mod tests {
-    use crate::ffi::new_ip;
-    use crate::ffi::new_l2sq;
-    use crate::ffi::new_cos;
-    use crate::ffi::new_haversine;
+    use crate::ffi::MetricKind;
+    use crate::ffi::ScalarKind;
+    use crate::ffi::IndexOptions;
+    use crate::ffi::new_index;
 
     #[test]
     fn integration() {
 
-        let quant = "f16";
-        let index = new_ip(5,  &quant, 0, 0, 0).unwrap();
+        let mut options = IndexOptions {
+            dimensions: 5,
+            metric: MetricKind::IP,
+            quantization: ScalarKind::F16,
+            connectivity: 0,
+            expansion_add: 0,
+            expansion_search: 0
+        };
+
+        let index = new_index(&options).unwrap();
     
         assert!(index.reserve(10).is_ok());
         assert!(index.capacity() >= 10);
@@ -75,9 +105,12 @@ mod tests {
         assert!(index.view("index.rust.usearch").is_ok());
     
         // Make sure every function is called at least once
-        assert!(new_ip(5,  &quant, 0, 0, 0).is_ok());
-        assert!(new_l2sq(5,  &quant, 0, 0, 0).is_ok());
-        assert!(new_cos(5,  &quant, 0, 0, 0).is_ok());
-        assert!(new_haversine(&quant, 0, 0, 0).is_ok());
+        assert!(new_index(&options).is_ok());
+        options.metric = MetricKind::L2Sq;
+        assert!(new_index(&options).is_ok());
+        options.metric = MetricKind::Cos;
+        assert!(new_index(&options).is_ok());
+        options.metric = MetricKind::Haversine;
+        assert!(new_index(&options).is_ok());
     }
 }

package/setup.py

@@ -7,10 +7,12 @@ from pybind11.setup_helpers import Pybind11Extension
 
 compile_args = ['-std=c++11', '-O3']
 link_args = []
+macros_args = []
 
 if sys.platform == 'linux':
     compile_args.append('-fopenmp')
     link_args.append('-lgomp')
+    macros_args.append(('USEARCH_USE_OPENMP', '1'))
     compile_args.append('-Wno-unknown-pragmas')
 
 if sys.platform == 'darwin':
@@ -22,12 +24,14 @@ if sys.platform == 'darwin':
 if sys.platform == 'win32':
     compile_args = ['/std:c++14', '/O2']
 
+
 ext_modules = [
     Pybind11Extension(
         'usearch.compiled',
         ['python/lib.cpp'],
         extra_compile_args=compile_args,
         extra_link_args=link_args,
+        define_macros=macros_args,
     ),
 ]
 
@@ -79,10 +83,16 @@ setup(
     ],
 
     include_dirs=[
-        'include', 'src',
+        'include',
         'fp16/include', 'robin-map/include', 'simsimd/include'],
+
     ext_modules=ext_modules,
+    install_requires=[
+        'numpy',
+        'ucall',
+        'pandas',
+    ],
     extras_require={
-        'jit': ['numba'],
+        'jit': ['numba', 'cppyy'],
     },
 )

package/simsimd/include/simsimd/simsimd.h

@@ -128,7 +128,7 @@ inline static simsimd_f16_t simsimd_l2sq_f16sve(simsimd_f16_t const* a_enum, sim
 #endif
 }
 
-inline static size_t simsimd_hamming_u1x8sve(uint8_t const* a, uint8_t const* b, size_t d) {
+inline static size_t simsimd_hamming_b1x8sve(uint8_t const* a, uint8_t const* b, size_t d) {
 #if defined(__ARM_FEATURE_SVE)
     size_t i = 0;
     svuint8_t d_vec = svdupq_n_u8(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0);
@@ -183,6 +183,35 @@ inline static simsimd_f32_t simsimd_cos_f16x4neon(simsimd_f16_t const* a, simsim
 #endif
 }
 
+inline static simsimd_f32_t simsimd_cos_i8x16neon(int8_t const* a, int8_t const* b, size_t d) {
+#if defined(__ARM_NEON)
+    int8x16_t const* a8x16 = reinterpret_cast<int8x16_t const*>(a);
+    int8x16_t const* b8x16 = reinterpret_cast<int8x16_t const*>(b);
+
+    int32x4_t ab_vec = vdupq_n_s32(0);
+    int32x4_t a2_vec = vdupq_n_s32(0);
+    int32x4_t b2_vec = vdupq_n_s32(0);
+    for (size_t i = 0; i != d / 16; ++i) {
+        int8x16_t a_vec = a8x16[i];
+        int8x16_t b_vec = b8x16[i];
+        ab_vec = vdotq_s32(ab_vec, a_vec, b_vec);
+        a2_vec = vdotq_s32(a2_vec, a_vec, a_vec);
+        b2_vec = vdotq_s32(b2_vec, b_vec, b_vec);
+    }
+
+    int32x2_t ab_part = vadd_s32(vget_high_s32(ab_vec), vget_low_s32(ab_vec));
+    int32_t ab = vget_lane_s32(vpadd_s32(ab_part, ab_part), 0);
+    int32x2_t a2_part = vadd_s32(vget_high_s32(a2_vec), vget_low_s32(a2_vec));
+    int32_t a2 = vget_lane_s32(vpadd_s32(a2_part, a2_part), 0);
+    int32x2_t b2_part = vadd_s32(vget_high_s32(b2_vec), vget_low_s32(b2_vec));
+    int32_t b2 = vget_lane_s32(vpadd_s32(b2_part, b2_part), 0);
+    return ab / (sqrt(a2) * sqrt(b2));
+#else
+    (void)a, (void)b, (void)d;
+    return 0;
+#endif
+}
+
 inline static simsimd_f32_t simsimd_cos_f32x4neon(simsimd_f32_t const* a, simsimd_f32_t const* b, size_t d) {
 #if defined(__ARM_NEON)
     float32x4_t ab_vec = vdupq_n_f32(0);
@@ -205,7 +234,7 @@ inline static simsimd_f32_t simsimd_cos_f32x4neon(simsimd_f32_t const* a, simsim
 #endif
 }
 
-inline static size_t simsimd_hamming_u1x128sve(uint8_t const* a, uint8_t const* b, size_t d) {
+inline static size_t simsimd_hamming_b1x128sve(uint8_t const* a, uint8_t const* b, size_t d) {
 #if defined(__ARM_NEON)
     /// Contains 16x 8-bit integers with running population count sums.
     uint8x16_t d_vec = vdupq_n_u8(0);
@@ -309,7 +338,7 @@ inline static simsimd_f32_t simsimd_cos_f32x4avx2(simsimd_f32_t const* a, simsim
 #endif
 }
 
-inline static size_t simsimd_hamming_u1x128avx512(uint8_t const* a, uint8_t const* b, size_t d) {
+inline static size_t simsimd_hamming_b1x128avx512(uint8_t const* a, uint8_t const* b, size_t d) {
 #if defined(__AVX512VPOPCNTDQ__)
     size_t words = d / 128;
     uint64_t const* a64 = (uint64_t const*)(a);

package/swift/Index+Sugar.swift

@@ -1,20 +1,28 @@
 //
 //  Index+Sugar.swift
-//  
+//
 //
 //  Created by Ashot Vardanian on 5/11/23.
 //
 
 @available(iOS 13, macOS 10.15, tvOS 13.0, watchOS 6.0, *)
-extension Index {
-
-    public func add(label: UInt32, vector: ArraySlice<Float32>) -> () {
+extension USearchIndex {
+    /// Adds a labeled vector to the index.
+    /// - Parameter label: Unique identifer for that object.
+    /// - Parameter vector: Single-precision vector.
+    /// - Throws: If runs out of memory.
+    public func add(label: UInt32, vector: ArraySlice<Float32>) {
         vector.withContiguousStorageIfAvailable {
             addSingle(label: label, vector: $0.baseAddress!)
         }
     }
+
     
-    
+    /// Approximate nearest neighbors search.
+    /// - Parameter vector: Single-precision query vector.
+    /// - Parameter count: Upper limit on the number of matches to retrieve.
+    /// - Returns: Labels and distances to closest approximate matches in decreasing similarity order.
+    /// - Throws: If runs out of memory.
     public func search(vector: ArraySlice<Float32>, count: Int) -> ([UInt32], [Float]) {
         var matches: [UInt32] = Array(repeating: 0, count: count)
         var distances: [Float] = Array(repeating: 0, count: count)
@@ -26,46 +34,64 @@ extension Index {
         return (matches, distances)
     }
 
-    public func add(label: UInt32, vector: ArraySlice<Float64>) -> () {
+    /// Adds a labeled vector to the index.
+    /// - Parameter label: Unique identifer for that object.
+    /// - Parameter vector: Double-precision vector.
+    /// - Throws: If runs out of memory.
+    public func add(label: UInt32, vector: ArraySlice<Float64>) {
         vector.withContiguousStorageIfAvailable {
-            addPrecise(label: label, vector: $0.baseAddress!)
+            addDouble(label: label, vector: $0.baseAddress!)
         }
     }
-
+    
+    /// Approximate nearest neighbors search.
+    /// - Parameter vector: Double-precision query vector.
+    /// - Parameter count: Upper limit on the number of matches to retrieve.
+    /// - Returns: Labels and distances to closest approximate matches in decreasing similarity order.
+    /// - Throws: If runs out of memory.
     public func search(vector: ArraySlice<Float64>, count: Int) -> ([UInt32], [Float]) {
         var matches: [UInt32] = Array(repeating: 0, count: count)
         var distances: [Float] = Array(repeating: 0, count: count)
         let results = vector.withContiguousStorageIfAvailable {
-            searchPrecise(vector: $0.baseAddress!, count: CUnsignedInt(count), labels: &matches, distances: &distances)
+            searchDouble(vector: $0.baseAddress!, count: CUnsignedInt(count), labels: &matches, distances: &distances)
         }
         matches.removeLast(count - Int(results!))
         distances.removeLast(count - Int(results!))
         return (matches, distances)
     }
 
-#if arch(arm64)
+    #if arch(arm64)
 
-    @available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)
-    public func add(label: UInt32, vector: ArraySlice<Float16>) -> () {
-        vector.withContiguousStorageIfAvailable { buffer in
-            addImprecise(label: label, vector: buffer.baseAddress!)
+        /// Adds a labeled vector to the index.
+        /// - Parameter label: Unique identifer for that object.
+        /// - Parameter vector: Half-precision vector.
+        /// - Throws: If runs out of memory.
+        @available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)
+        public func add(label: UInt32, vector: ArraySlice<Float16>) {
+            vector.withContiguousStorageIfAvailable { buffer in
+                addHalf(label: label, vector: buffer.baseAddress!)
+            }
         }
-    }
 
-    @available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)
-    public func search(vector: ArraySlice<Float16>, count: Int) -> ([UInt32], [Float]) {
-        var matches: [UInt32] = Array(repeating: 0, count: count)
-        var distances: [Float] = Array(repeating: 0, count: count)
-        let results = vector.withContiguousStorageIfAvailable {
-            searchImprecise(vector: $0.baseAddress!, count: CUnsignedInt(count), labels: &matches, distances: &distances)
+        /// Approximate nearest neighbors search.
+        /// - Parameter vector: Half-precision query vector.
+        /// - Parameter count: Upper limit on the number of matches to retrieve.
+        /// - Returns: Labels and distances to closest approximate matches in decreasing similarity order.
+        /// - Throws: If runs out of memory.
+        @available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)
+        public func search(vector: ArraySlice<Float16>, count: Int) -> ([UInt32], [Float]) {
+            var matches: [UInt32] = Array(repeating: 0, count: count)
+            var distances: [Float] = Array(repeating: 0, count: count)
+            let results = vector.withContiguousStorageIfAvailable {
+                searchHalf(vector: $0.baseAddress!, count: CUnsignedInt(count), labels: &matches, distances: &distances)
+            }
+            matches.removeLast(count - Int(results!))
+            distances.removeLast(count - Int(results!))
+            return (matches, distances)
         }
-        matches.removeLast(count - Int(results!))
-        distances.removeLast(count - Int(results!))
-        return (matches, distances)
-    }
-    
-#endif
 
-    public var count: Int { get { return Int(length) } }
-    
+    #endif
+
+    /// Number of vectors in the index.
+    public var count: Int { return Int(length) }
 }

package/swift/Test.swift

@@ -10,7 +10,7 @@ import USearch
 
 @available(iOS 13, macOS 10.15, tvOS 13.0, watchOS 6.0, *)
 func testUnit() throws {
-    let index = Index.l2sq(dimensions: 4, connectivity: 8)
+    let index = USearchIndex.make(metric:USearchMetric.l2sq, dimensions: 4, connectivity: 8, quantization:USearchScalar.F32)
     let vectorA: [Float32] = [0.3, 0.5, 1.2, 1.4]
     let vectorB: [Float32] = [0.4, 0.2, 1.2, 1.1]
     index.add(label: 42, vector: vectorA[...])

package/wolfram/lib.cpp

@@ -1,9 +1,9 @@
 #include "WolframLibrary.h"
-#include "punned.hpp"
+#include <usearch/index_punned_dense.hpp>
 
 using namespace unum::usearch;
 using distance_t = punned_distance_t;
-using punned_t = punned_gt<int>;
+using punned_t = index_punned_dense_gt<int>;
 using span_t = span_gt<float>;
 
 EXTERN_C DLLEXPORT int WolframLibrary_initialize(WolframLibraryData libData) { return LIBRARY_NO_ERROR; }
@@ -22,8 +22,8 @@ EXTERN_C DLLEXPORT int IndexCreate(WolframLibraryData libData, mint Argc, MArgum
         config.expansion_add = static_cast<std::size_t>(MArgument_getInteger(Args[5]));
         config.expansion_search = static_cast<std::size_t>(MArgument_getInteger(Args[6]));
 
-        accuracy_t accuracy = accuracy_from_name(accuracy_cstr, std::strlen(accuracy_cstr));
-        common_metric_kind_t metric_kind = common_metric_from_name(metric_cstr, std::strlen(metric_cstr));
+        scalar_kind_t accuracy = scalar_kind_from_name(accuracy_cstr, std::strlen(accuracy_cstr));
+        metric_kind_t metric_kind = metric_from_name(metric_cstr, std::strlen(metric_cstr));
         punned_t index = make_punned<punned_t>(metric_kind, dimensions, accuracy, config);
         index.reserve(capacity);
 

package/python/scripts/bench_params.py

@@ -1,161 +0,0 @@
-import os
-import time
-
-import fire
-import plotly.express as px
-import numpy as np
-import pandas as pd
-
-
-from usearch.index import Index
-
-
-def measure(f) -> float:
-    a = time.time_ns()
-    result = f()
-    b = time.time_ns()
-    c = b - a
-    secs = c / (10 ** 9)
-    print(f'- Took: {secs:.2f} seconds')
-    return secs, result
-
-
-def bench_usearch(index, vectors: np.ndarray) -> float:
-    labels = np.arange(vectors.shape[0], dtype=np.longlong)
-    assert len(index) == 0
-    dt, _ = measure(lambda: index.add(labels, vectors))
-    assert len(index) == vectors.shape[0]
-    insertions_per_second = vectors.shape[0]/dt
-    print(f'- Performance: {insertions_per_second:.2f} insertions/s')
-    return insertions_per_second
-
-
-class Main:
-
-    def dimensions(
-        self,
-        count: int = 1_000_000,
-        connectivity: int = 16,
-        expansion_add: int = 128,
-        expansion_search: int = 64,
-    ):
-        """Measures indexing speed for different dimensionality vectors.
-
-        :param count: Number of vectors, defaults to 1_000_000
-        :type count: int, optional
-        """
-
-        dimensions = [
-            2, 3, 4, 8, 16, 32, 96, 100,
-            256, 384, 512, 768, 1024, 1536]
-        results = []
-
-        try:
-            for ndim in dimensions:
-                vectors_mat = np.random.rand(count, ndim).astype(np.float32)
-
-                print(f'USearch for {ndim}-dimensional f32 vectors')
-                index = Index(
-                    ndim=ndim,
-                    expansion_add=expansion_add,
-                    expansion_search=expansion_search,
-                    connectivity=connectivity,
-                )
-                speed = bench_usearch(index, vectors_mat)
-                results.append({'ndim': ndim, 'speed': speed})
-                del index
-        except KeyboardInterrupt:
-            pass
-
-        df = pd.DataFrame(results)
-        fig = px.line(
-            df, x='ndim', y='speed', log_x=True,
-            title='HNSW Indexing Speed vs Vector Dimensions')
-        fig.write_image(os.path.join(os.path.dirname(
-            __file__), 'bench_dimensions.png'))
-        fig.show()
-
-    def connectivity(
-        self,
-        count: int = 1_000_000,
-        ndim: int = 256,
-        expansion_add: int = 128,
-        expansion_search: int = 64,
-    ):
-        """Measures indexing speed and accuracy for different level of
-        connectivity in the levels of the hierarchical proximity graph.
-
-        :param count: Number of vectors, defaults to 1_000_000
-        :type count: int, optional
-        :param ndim: Number of dimensions per vector, defaults to 256
-        :type ndim: int, optional
-        """
-
-        connectivity_options = range(10, 20)
-        results = []
-
-        try:
-            for connectivity in connectivity_options:
-                vectors_mat = np.random.rand(count, ndim).astype(np.float32)
-
-                print(f'USearch for {connectivity} connectivity')
-                index = Index(
-                    ndim=ndim,
-                    expansion_add=expansion_add,
-                    expansion_search=expansion_search,
-                    connectivity=connectivity,
-                )
-                speed = bench_usearch(index, vectors_mat)
-                results.append({'connectivity': connectivity, 'speed': speed})
-                del index
-        except KeyboardInterrupt:
-            pass
-
-        df = pd.DataFrame(results)
-        fig = px.line(
-            df, x='connectivity', y='speed', log_x=True,
-            title='HNSW Indexing Speed vs Connectivity')
-        fig.write_image(os.path.join(os.path.dirname(
-            __file__), 'bench_connectivity.png'))
-        fig.show()
-
-    def robustness(
-        self,
-        experiments: int = 10,
-        count: int = 1_000_000,
-        ndim: int = 256,
-        connectivity: int = 16,
-        expansion_add: int = 128,
-        expansion_search: int = 64,
-    ):
-        """How much does accuracy fluctuate depending on the indexing order.
-
-        :param experiments: How many times to repeat, defaults to 10
-        :type experiments: int, optional
-        :param count: Number of vectors, defaults to 1_000_000
-        :type count: int, optional
-        :param ndim: Number of dimensions per vector, defaults to 256
-        :type ndim: int, optional
-        """
-
-        recall_levels = []
-        vectors_mat = np.random.rand(count, ndim).astype(np.float32)
-
-        for _ in range(experiments):
-
-            index = Index(
-                ndim=ndim,
-                expansion_add=expansion_add,
-                expansion_search=expansion_search,
-                connectivity=connectivity,
-            )
-            bench_usearch(index, vectors_mat)
-            del index
-
-        min_ = min(recall_levels)
-        max_ = max(recall_levels)
-        print(f'Recall@1 varies between {min_:.3f} and {max_:.3f}')
-
-
-if __name__ == '__main__':
-    fire.Fire(Main)

package/python/usearch/synthetic.py

@@ -1,32 +0,0 @@
-import numpy as np
-
-from usearch.index import Index, Matches, MetricKind, BitwiseMetricKind
-
-
-def vectors(index: Index, count: int) -> np.ndarray:
-
-    if not isinstance(index, Index):
-        raise ValueError('Unsupported `index` type')
-
-    dimensions = index.ndim
-
-    if index.metric in BitwiseMetricKind:
-        bit_vectors = np.random.randint(2, size=(count, dimensions))
-        bit_vectors = np.packbits(bit_vectors, axis=1)
-        return bit_vectors
-
-    else:
-        x = np.random.rand(count, dimensions).astype(index.numpy_dtype)
-        if index.metric == MetricKind.IP:
-            return x / np.linalg.norm(x, axis=1, keepdims=True)
-        return x
-
-
-def recall_at_one(index: Index, vectors: np.ndarray) -> float:
-    empty_replica: Index = index.fork()
-
-    labels = np.arange(vectors.shape[0])
-    empty_replica.add(labels=labels, vectors=vectors)
-    matches: Matches = empty_replica.search(empty_replica, 1)
-
-    return np.sum(matches.labels.flatten() == labels) / len(labels)