usearch 0.2.2 → 0.2.3

package/.github/workflows/release.yml

@@ -32,7 +32,7 @@ jobs:
 #     needs: versioning
     strategy:
       matrix:
-        os: [ubuntu-20.04, macOS-11, windows-2022]
+        os: [ubuntu-20.04, macOS-11]
 
     steps:
       - uses: actions/checkout@v3

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "usearch"
-version = "0.2.2"
+version = "0.2.3"
 authors = ["Ashot Vardanian <1983160+ashvardanian@users.noreply.github.com>"]
 description = "Smaller & Faster Single-File Vector Search Engine from Unum"
 edition = "2021"

package/README.md

@@ -17,30 +17,33 @@ Vector Search Engine<br/>
 <a href="https://github.com/unum-cloud/usearch"><img height="25" src="https://github.com/unum-cloud/.github/raw/main/assets/github.svg" alt="GitHub"></a>
 </p>
 
+<p align="center">
+Euclidean • Angular • Jaccard • Hamming • Haversine • User-Defined Metrics
+<br/>
+<a href="#c++">C++11</a> •
+<a href="#python">Python</a> •
+<a href="#javascript">JavaScript</a> •
+<a href="#java">Java</a> •
+<a href="#rust">Rust</a> •
+<a href="#objective-c">Objective-C</a> •
+<a href="#swift">Swift</a> •
+<a href="#golang">GoLang</a> •
+<a href="#wolfram">Wolfram</a>
+<br/>
+Linux • MacOS • Windows
+</p>
+
 - [x] [Single C++11 header][usearch-header] implementation, easily extendible.
 - [x] [4B+](#go-beyond-4b-entries) sized space efficient point-clouds with `uint40_t`.
-- [x] [Half-precision](#quantize-on-the-fly) support with [`maratyszcza/fp16`](https://github.com/maratyszcza/fp16).
+- [x] [Half-precision](#quantize-on-the-fly) support with [`fp16`](https://github.com/maratyszcza/fp16).
 - [x] [View from disk](#view-larger-indexes-from-disk), without loading into RAM.
-- [x] [Any metric](#define-custom-metrics), includes: 
-  - [x] Euclidean, Dot-product, Cosine,
-  - [x] Jaccard, Hamming, Haversine.
-  - [x] Hardware-accelerated [`ashvardanian/simsimd`](https://github.com/ashvardanian/simsimd). 
+- [x] [User-defined](#define-custom-metrics) and hardware-accelerated metrics with [`simsimd`](https://github.com/ashvardanian/simsimd). 
 - [x] Variable dimensionality vectors.
 - [x] Don't copy vectors if not needed.
 - [x] [Bring your threads](#bring-your-threads), like OpenMP.
 - [x] Multiple vectors per label.
-- [x] [Python](#python) bindings: `pip install usearch`.
-- [x] [JavaScript](#javascript) bindings: `npm install usearch`.
-- [x] [Rust](#rust) bindings: `cargo add usearch`.
-- [x] [Java](#java) bindings: `cloud.unum:usearch` on GitHub.
-- [ ] GoLang bindings.
-- [x] Wolfram language bindings.
-- [x] For Linux: GCC, Clang.
-- [x] For MacOS: Apple Clang.
-- [ ] For Windows.
-- [ ] Multi-index lookups in Python.
 - [ ] Thread-safe `reserve`.
-- [ ] Distributed construction with MPI.
+- [x] Compatible with Linux, MacOS, and Windows.
 - [x] AI + Vector Search = Semantic Search.
 
 [usearch-header]: https://github.com/unum-cloud/usearch/blob/main/include/usearch/usearch.hpp
@@ -209,12 +212,14 @@ struct custom_metric_t {
 
 ### Python
 
+```sh
+pip install usearch
+```
+
 Python bindings are implemented with [`pybind/pybind11`](https://github.com/pybind/pybind11).
 Assuming the presence of Global Interpreter Lock in Python, on large insertions we spawn threads in the C++ layer.
 
 ```python
-$ pip install usearch
-
 import numpy as np
 from usearch.index import Index
 
@@ -232,6 +237,8 @@ index.add(42, vector)
 matches, distances, count = index.search(vector, 10)
 ```
 
+#### Batch Operations
+
 Same can be done with batches, rather than single entries.
 Under the hood, worker threads will be spawned, to parallelize the procedure.
 
@@ -240,17 +247,31 @@ n = 100
 labels = np.array(range(n), dtype=np.longlong)
 vectors = np.random.uniform(0, 0.3, (n, index.ndim)).astype(np.float32)
 
-# You can avoid copying the data
-# Handy when build 1B+ indexes of memory-mapped files
-index.add(labels, vectors, copy=True)
+index.add(labels, vectors)
 matches, distances, counts = index.search(vectors, 10)
 ```
 
+#### Performance
+
+To maximize performance, you can:
+
+- adjust the number of threads passed to `index.add(threads=)`.
+- downcast to half-precision with `Index(accuracy=)`.
+- JIT-compile your metrics for hardware and pass to `Index(matric_pointer=)`.
+
+For a dataset with 1 Million 256-dimensional embeddings at single precision, the performance would be:
+
+- FAISS: 77'563 vectors/s.
+- USearch precompiled for old hardware: 53'198 vectors/s (-32%).
+- USearch with Numba JIT for target hardware: 88'658 vectors/s (+14%).
+
 ### JavaScript
 
-```js
-// npm install usearch
+```sh
+npm install usearch
+```
 
+```js
 var index = new usearch.Index({ metric: 'cos', connectivity: 16, dimensions: 2 })
 assert.equal(index.connectivity(), 16)
 assert.equal(index.dimensions(), 2)
@@ -266,12 +287,14 @@ assert.deepEqual(results.distances, new Float32Array([45, 130]))
 
 ### Rust
 
+```sh
+cargo add usearch
+```
+
 Being a systems-programming language, Rust has better control over memory management and concurrency, but lacks function overloading.
 Aside from the `add` and `search`, it also provides `add_in_thread` and `search_in_thread` which let users identify the calling thread to use underlying temporary memory more efficiently.
 
 ```rust
-// cargo add usearch
-
 let quant: &str = "f16";
 let index = new_ip(5, &quant, 0, 0, 0).unwrap();
 
@@ -305,6 +328,16 @@ assert!(new_haversine(&quant, 0, 0, 0).is_ok());
 
 ### Java
 
+```xml
+<dependency>
+  <groupId>cloud.unum.usearch</groupId>
+  <artifactId>usearch</artifactId>
+  <version>0.2.3</version>
+</dependency>
+```
+
+Add that snippet to your `pom.xml` and hit `mvn install`.
+
 ```java
 Index index = new Index.Config().metric("cos").dimensions(2).build();
 float vec[] = {10, 20};
@@ -312,7 +345,7 @@ index.add(42, vec);
 int[] labels = index.search(vec, 5);
 ```
 
-### Objective-C and Swift
+### Swift
 
 ```swift
 let index = Index.l2(dimensions: 4, connectivity: 8)

package/VERSION

@@ -1 +1 @@
-0.2.2
+0.2.3

package/conanfile.py

@@ -1,9 +1,10 @@
 from conans import ConanFile
 
+
 class USearchConan(ConanFile):
-    
+
     name = 'USearch'
-    version = '0.2.2'
+    version = '0.2.3'
     license = 'Apache 2.0'
     url = 'https://github.com/unum-cloud/usearch'
     description = 'Smaller & Faster Single-File Vector Search Engine from Unum'

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "usearch",
-    "version": "0.2.2",
+    "version": "0.2.3",
     "description": "Smaller & Faster Single-File Vector Search Engine from Unum",
     "author": "Ashot Vardanian",
     "license": "Apache 2.0",

package/python/bench.py

@@ -1,25 +1,28 @@
-import datetime
+import time
 import numpy as np
 import fire
 
-import faiss
-import usearch
-
-import struct
 import numpy as np
+from numba import cfunc, types, carray
+
+from faiss import IndexHNSWFlat, IndexIVFPQ
+from usearch.index import Index
+from usearch.io import load_matrix
+
 
 def measure(f) -> float:
-    a = datetime.datetime.now()
+    a = time.time_ns()
     f()
-    b = datetime.datetime.now()
+    b = time.time_ns()
     c = b - a
-    print(f'Took: {c.seconds:.2f} seconds')
-    return c.seconds
+    secs = c / (10 ** 9)
+    print(f'- Took: {secs:.2f} seconds')
+    return secs
 
 
 def bench_faiss(index, vectors: np.array, queries: np.array, neighbors: np.array):
     dt = measure(lambda: index.add(vectors))
-    print(f'- FAISS: {vectors.shape[0]/dt:.2f} vectors/s')
+    print(f'- Performance: {vectors.shape[0]/dt:.2f} vectors/s')
 
 
 def bench_usearch(index, vectors: np.array, queries: np.array, neighbors: np.array):
@@ -27,7 +30,26 @@ def bench_usearch(index, vectors: np.array, queries: np.array, neighbors: np.arr
     assert len(index) == 0
     dt = measure(lambda: index.add(labels, vectors))
     assert len(index) == vectors.shape[0]
-    print(f'- USearch: {vectors.shape[0]/dt:.2f} vectors/s')
+    print(f'- Performance: {vectors.shape[0]/dt:.2f} vectors/s')
+
+
+# Showcases how to use Numba to JIT-compile similarity measures for USearch.
+# https://numba.readthedocs.io/en/stable/reference/jit-compilation.html#c-callbacks
+
+signature_f32 = types.float32(
+    types.CPointer(types.float32),
+    types.CPointer(types.float32),
+    types.size_t, types.size_t)
+
+
+@cfunc(signature_f32)
+def inner_product_f32(a, b, n, m):
+    a_array = carray(a, n)
+    b_array = carray(b, n)
+    c = types.float32(0)
+    for i in range(n):
+        c += a_array[i] * b_array[i]
+    return types.float32(1 - c)
 
 
 def main(
@@ -44,31 +66,51 @@ def main(
     neighbors_mat = load_matrix(neighbors)
     dim = vectors_mat.shape[1]
 
-    # Test FAISS
-    index = faiss.IndexHNSWFlat(dim, connectivity)
+    print('USearch: HNSW')
+    index = Index(
+        ndim=dim,
+        expansion_add=expansion_add,
+        expansion_search=expansion_search,
+        connectivity=connectivity,
+    )
+    bench_usearch(index, vectors_mat, queries_mat, neighbors_mat)
+
+    print('USearch: HNSW + Numba JIT')
+    index = Index(
+        ndim=dim,
+        expansion_add=expansion_add,
+        expansion_search=expansion_search,
+        connectivity=connectivity,
+        metric_pointer=inner_product_f32.address,
+    )
+    bench_usearch(index, vectors_mat, queries_mat, neighbors_mat)
+
+    print('USearch: HNSW + Numba JIT + Half Precision')
+    index = Index(
+        ndim=dim,
+        dtype='f16',
+        expansion_add=expansion_add,
+        expansion_search=expansion_search,
+        connectivity=connectivity,
+    )
+    bench_usearch(index, vectors_mat, queries_mat, neighbors_mat)
+
+    print('FAISS: HNSW')
+    index = IndexHNSWFlat(dim, connectivity)
     index.hnsw.efSearch = expansion_search
     index.hnsw.efConstruction = expansion_add
     bench_faiss(index, vectors_mat, queries_mat, neighbors_mat)
 
-    # Test FAISS with default Product Quantization
+    print('FAISS: HNSW + IVFPQ')
     nlist = 10000  # Number of inverted lists (number of partitions or cells).
     nsegment = 16  # Number of segments for PQ (number of subquantizers).
     nbit = 8       # Number of bits to encode each segment.
-    coarse_quantizer = faiss.IndexHNSWFlat(dim, connectivity)
-    index = faiss.IndexIVFPQ(coarse_quantizer, dim, nlist, nsegment, nbit)
+    coarse_quantizer = IndexHNSWFlat(dim, connectivity)
+    index = IndexIVFPQ(coarse_quantizer, dim, nlist, nsegment, nbit)
     index.train(vectors_mat)
     index.nprobe = 10
     bench_faiss(index, vectors_mat, queries_mat, neighbors_mat)
 
-    # Test USearch `Index`
-    index = usearch.Index(
-        ndim=dim,
-        expansion_add=expansion_add,
-        expansion_search=expansion_search,
-        connectivity=connectivity,
-    )
-    bench_usearch(index, vectors_mat, queries_mat, neighbors_mat)
-
 
 if __name__ == '__main__':
     fire.Fire(main)

package/python/lib.cpp

@@ -59,6 +59,25 @@ struct hash_index_w_meta_t : public hash_index_t {
     span_gt<hash_word_t const> buffer() const noexcept { return {buffer_.data(), buffer_.size()}; }
 };
 
+template <typename scalar_at> punned_stateful_metric_t udf(std::size_t metric_uintptr) {
+    return [metric_uintptr](byte_t const* a_bytes, byte_t const* b_bytes, std::size_t n, std::size_t m) -> distance_t {
+        using metric_t = punned_distance_t (*)(scalar_at const*, scalar_at const*, std::size_t, std::size_t);
+        metric_t metric_ptr = reinterpret_cast<metric_t>(metric_uintptr);
+        scalar_at const* a = reinterpret_cast<scalar_at const*>(a_bytes);
+        scalar_at const* b = reinterpret_cast<scalar_at const*>(b_bytes);
+        return metric_ptr(a, b, n / sizeof(scalar_at), m / sizeof(scalar_at));
+    };
+}
+
+punned_stateful_metric_t udf(std::size_t metric_uintptr, accuracy_t accuracy) {
+    switch (accuracy) {
+    case accuracy_t::f8_k: return udf<f8_bits_t>(metric_uintptr);
+    case accuracy_t::f16_k: return udf<f16_bits_t>(metric_uintptr);
+    case accuracy_t::f32_k: return udf<f32_t>(metric_uintptr);
+    case accuracy_t::f64_k: return udf<f64_t>(metric_uintptr);
+    }
+}
+
 static native_index_t make_index(   //
     std::size_t dimensions,         //
     std::size_t capacity,           //
@@ -79,9 +98,8 @@ static native_index_t make_index(   //
     config.max_threads_search = std::thread::hardware_concurrency();
 
     accuracy_t accuracy = accuracy_from_name(scalar_type.c_str(), scalar_type.size());
-    punned_metric_t metric_ptr = reinterpret_cast<punned_metric_t>(metric_uintptr);
-    if (metric_ptr)
-        return native_index_t::udf(dimensions, metric_ptr, accuracy, config);
+    if (metric_uintptr)
+        return native_index_t::udf(dimensions, udf(metric_uintptr, accuracy), accuracy, config);
     else
         return index_from_name<native_index_t>(metric.c_str(), metric.size(), dimensions, accuracy, config);
 }
@@ -146,7 +164,9 @@ static void add_one_to_index(native_index_t& index, label_t label, py::buffer ve
         throw std::invalid_argument("Incompatible scalars in the vector!");
 }
 
-static void add_many_to_index(native_index_t& index, py::buffer labels, py::buffer vectors, bool copy) {
+static void add_many_to_index(                                    //
+    native_index_t& index, py::buffer labels, py::buffer vectors, //
+    bool copy, std::size_t threads = 0) {
 
     py::buffer_info labels_info = labels.request();
     py::buffer_info vectors_info = vectors.request();
@@ -393,7 +413,8 @@ PYBIND11_MODULE(index, m) {
         py::arg("labels"),         //
         py::arg("vectors"),        //
         py::kw_only(),             //
-        py::arg("copy") = true     //
+        py::arg("copy") = true,    //
+        py::arg("threads") = 0     //
     );
 
     i.def(                        //
@@ -415,6 +436,8 @@ PYBIND11_MODULE(index, m) {
     i.def_property_readonly("ndim", &native_index_t::dimensions);
     i.def_property_readonly("connectivity", &native_index_t::connectivity);
     i.def_property_readonly("capacity", &native_index_t::capacity);
+    i.def_property_readonly( //
+        "dtype", [](native_index_t const& index) -> std::string { return accuracy_name(index.accuracy()); });
 
     i.def("save", &save_index<native_index_t>, py::arg("path"));
     i.def("load", &load_index<native_index_t>, py::arg("path"));

package/setup.py

@@ -1,13 +1,20 @@
 import os
 import sys
-from setuptools import setup, find_packages
+from setuptools import setup
 from pybind11.setup_helpers import Pybind11Extension
 
 
 compile_args = ['-std=c++11', '-O3']
+link_args = []
+
+if sys.platform == 'linux':
+    compile_args.append('-fopenmp')
+    link_args.append('-lgomp')
 
 if sys.platform == 'darwin':
-    compile_args.append('-mmacosx-version-min=10.13')
+    # MacOS 10.15 orhigher is needed for `aligned_alloc` support.
+    # https://github.com/unum-cloud/usearch/actions/runs/4975434891/jobs/8902603392
+    compile_args.append('-mmacosx-version-min=10.15')
 
 if sys.platform == 'win32':
     compile_args = ['/std:c++14', '/O2']
@@ -17,7 +24,8 @@ ext_modules = [
     Pybind11Extension(
         'usearch.index',
         ['python/lib.cpp'],
-        extra_compile_args=compile_args
+        extra_compile_args=compile_args,
+        extra_link_args=link_args,
     ),
 ]
 

package/src/advanced.hpp

@@ -14,6 +14,10 @@
 #include <thread>     // `std::thread`
 #include <vector>     // `std::vector`
 
+#if defined(_OPENMP)
+#include <omp.h> // `omp_get_num_threads()`
+#endif
+
 #if __linux__
 #include <sys/auxv.h>
 #endif
@@ -179,12 +183,18 @@ void multithreaded(std::size_t threads, std::size_t tasks, callback_at&& callbac
 
     if (threads == 0)
         threads = std::thread::hardware_concurrency();
-    if (threads == 1) {
+    if (threads == 1 || tasks <= 128) {
         for (std::size_t task_idx = 0; task_idx < tasks; ++task_idx)
             callback(0, task_idx);
         return;
     }
 
+#if defined(_OPENMP)
+    omp_set_num_threads(threads);
+#pragma omp parallel for schedule(dynamic)
+    for (std::size_t i = 0; i < tasks; ++i)
+        callback(omp_get_thread_num(), i);
+#else
     std::vector<std::thread> threads_pool;
     std::size_t tasks_per_thread = (tasks / threads) + ((tasks % threads) != 0);
     for (std::size_t thread_idx = 0; thread_idx != threads; ++thread_idx) {
@@ -194,9 +204,9 @@ void multithreaded(std::size_t threads, std::size_t tasks, callback_at&& callbac
                 callback(thread_idx, task_idx);
         });
     }
-
     for (std::size_t thread_idx = 0; thread_idx != threads; ++thread_idx)
         threads_pool[thread_idx].join();
+#endif
 }
 
 /**
@@ -424,6 +434,7 @@ class auto_index_gt {
     config_t const& config() const noexcept { return root_config_; }
     void clear() noexcept { return index_->clear(); }
 
+    accuracy_t accuracy() const noexcept { return accuracy_; }
     isa_t acceleration() const noexcept { return acceleration_; }
     std::size_t concurrency() const noexcept {
         return (std::min)(root_config_.max_threads_add, root_config_.max_threads_search);

package/src/bench.cpp

@@ -33,7 +33,7 @@
 #include <variant>   // `std::monostate`
 
 #include <clipp.h> // Command Line Interface
-#include <omp.h>   // `omp_get_num_threads()`
+#include <omp.h>   // `omp_set_num_threads()`
 
 #include <simsimd/simsimd.h>