usearch 0.18.6 → 0.19.0

package/Cargo.toml

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

package/README.md

@@ -69,11 +69,13 @@ Both USearch and FAISS implement the same HNSW algorithm.
 But they differ in a lot of design decisions.
 USearch is designed to be compact and broadly compatible without sacrificing performance.
 
-|            | FAISS, `f32` | USearch, `f32` | USearch, `f16` | USearch, `f8` |
-| :--------- | -----------: | -------------: | -------------: | ------------: |
-| Insertions |       76 K/s |        105 K/s |        115 K/s |   **202 K/s** |
-| Queries    |      118 K/s |        174 K/s |        173 K/s |   **304 K/s** |
-| Recall @1  |          99% |          99.2% |          99.1% |     **99.2%** |
+|              | FAISS, `f32` | USearch, `f32` | USearch, `f16` | USearch, `f8` |
+| :----------- | -----------: | -------------: | -------------: | ------------: |
+| Batch Insert |       16 K/s |         73 K/s |        100 K/s |   **104 K/s** |
+| Batch Search |       82 K/s |        103 K/s |        113 K/s |   **134 K/s** |
+| Bulk Insert  |       76 K/s |        105 K/s |        115 K/s |   **202 K/s** |
+| Bulk Search  |      118 K/s |        174 K/s |        173 K/s |   **304 K/s** |
+| Recall @1    |          99% |          99.2% |          99.1% |     **99.2%** |
 
 > Dataset: 1M vectors sample of the Deep1B dataset.
 > Hardware: `c7g.metal` AWS instance with 64 cores and DDR5 memory.
@@ -81,6 +83,7 @@ USearch is designed to be compact and broadly compatible without sacrificing per
 > connectivity `M=16`,
 > expansion @ construction `efConstruction=128`,
 > and expansion @ search `ef=64`.
+> Batch size is 256.
 > Both libraries were compiled for the target architecture.
 > Jump to the [Performance Tuning][benchmarking] section to read about the effects of those hyper-parameters.
 
@@ -248,7 +251,7 @@ index = Index(
     expansion_search=64, # Control the quality of search, optional
 )
 
-vector = np.array([0.2, 0.6, 0.4], dtype=np.float32)
+vector = np.array([0.2, 0.6, 0.4])
 index.add(42, vector)
 matches, distances, count = index.search(vector, 10)
 
@@ -256,6 +259,7 @@ assert len(index) == 1
 assert count == 1
 assert matches[0] == 42
 assert distances[0] <= 0.001
+assert np.allclose(index[42], vector)
 ```
 
 Python bindings are implemented with [`pybind/pybind11`](https://github.com/pybind/pybind11).
@@ -269,6 +273,13 @@ index.load('index.usearch') # Copy the whole index into memory
 index.view('index.usearch') # View from disk without loading in memory
 ```
 
+If you don't know anything about the index except its path, there are two more endpoints to know:
+
+```py
+Index.metadata('index.usearch') -> IndexMetadata
+Index.restore('index.usearch', view=False) -> Index
+```
+
 #### Batch Operations
 
 Adding or querying a batch of entries is identical to adding a single vector.
@@ -291,7 +302,9 @@ The first controls the number of threads spawned for the task.
 The second controls whether the vector itself will be persisted inside the index.
 If you can preserve the lifetime of the vector somewhere else, you can avoid the copy.
 
-#### User-Defined Metrics in Python
+#### User-Defined Metrics and JIT in Python
+
+##### [Numba][numba]
 
 Assuming the language boundary exists between Python user code and C++ implementation, there are more efficient solutions than passing a Python callable to the engine.
 Luckily, with the help of [Numba][numba], we can JIT compile a function with a matching signature and pass it down to the engine.
@@ -305,7 +318,7 @@ signature = types.float32(
     types.CPointer(types.float32))
 
 @cfunc(signature)
-def python_dot(a, b):
+def inner_product(a, b):
     a_array = carray(a, ndim)
     b_array = carray(b, ndim)
     c = 0.0
@@ -313,19 +326,157 @@ def python_dot(a, b):
         c += a_array[i] * b_array[i]
     return 1 - c
 
-index = Index(ndim=ndim, metric=python_dot.address)
+index = Index(ndim=ndim, metric=CompiledMetric(
+    pointer=inner_product.address,
+    kind=MetricKind.IP,
+    signature=MetricSignature.ArrayArray,
+))
 ```
 
-To use Numba JIT, install USearch with extras:
+Alternatively, you can avoid pre-defining the number of dimensions, and pass it separately:
+
+```py
+signature = types.float32(
+    types.CPointer(types.float32),
+    types.CPointer(types.float32),
+    types.uint64)
+
+@cfunc(signature)
+def inner_product(a, b, ndim):
+    a_array = carray(a, ndim)
+    b_array = carray(b, ndim)
+    c = 0.0
+    for i in range(ndim):
+        c += a_array[i] * b_array[i]
+    return 1 - c
+
+index = Index(ndim=ndim, metric=CompiledMetric(
+    pointer=inner_product.address,
+    kind=MetricKind.IP,
+    signature=MetricSignature.ArrayArraySize,
+))
+```
 
 ```sh
-pip install usearch[jit]
+pip install numba
+```
+
+##### [Cppyy][cppyy]
+
+Similarly, you can use Cppyy with Cling to JIT-compile native C or C++ code and pass it to USearch, which may be a good idea, if you want to explicitly request loop-unrolling or other low-level optimizations!
+
+```py
+import cppyy
+import cppyy.ll
+
+cppyy.cppdef("""
+float inner_product(float *a, float *b) {
+    float result = 0;
+#pragma unroll
+    for (size_t i = 0; i != ndim; ++i)
+        result += a[i] * b[i];
+    return 1 - result;
+}
+""".replace("ndim", str(ndim)))
+
+function = cppyy.gbl.inner_product
+index = Index(ndim=ndim, metric=CompiledMetric(
+    pointer=cppyy.ll.addressof(function),
+    kind=MetricKind.IP,
+    signature=MetricSignature.ArrayArraySize,
+))
+```
+
+##### [PeachPy][peachpy]
+
+We have covered JIT-ing Python with Numba and C++ with Cppyy and Cling.
+How about writing Assembly directly?
+That is also possible.
+Below is an example of constructing the "Inner Product" distance for 8-dimensional `f32` vectors for x86 using [PeachPy][peachpy].
+
+```py
+from peachpy import (
+    Argument,
+    ptr,
+    float_,
+    const_float_,
+)
+from peachpy.x86_64 import (
+    abi,
+    Function,
+    uarch,
+    isa,
+    GeneralPurposeRegister64,
+    LOAD,
+    YMMRegister,
+    VSUBPS,
+    VADDPS,
+    VHADDPS,
+    VMOVUPS,
+    VFMADD231PS,
+    VPERM2F128,
+    VXORPS,
+    RETURN,
+)
+
+a = Argument(ptr(const_float_), name="a")
+b = Argument(ptr(const_float_), name="b")
+
+with Function(
+    "inner_product", (a, b), float_, target=uarch.default + isa.avx2
+) as asm_function:
+    
+    # Request two 64-bit general-purpose registers for addresses
+    reg_a, reg_b = GeneralPurposeRegister64(), GeneralPurposeRegister64()
+    LOAD.ARGUMENT(reg_a, a)
+    LOAD.ARGUMENT(reg_b, b)
+
+    # Load the vectors
+    ymm_a = YMMRegister()
+    ymm_b = YMMRegister()
+    VMOVUPS(ymm_a, [reg_a])
+    VMOVUPS(ymm_b, [reg_b])
+
+    # Prepare the accumulator
+    ymm_c = YMMRegister()
+    ymm_one = YMMRegister()
+    VXORPS(ymm_c, ymm_c, ymm_c)
+    VXORPS(ymm_one, ymm_one, ymm_one)
+
+    # Accumulate A and B product into C
+    VFMADD231PS(ymm_c, ymm_a, ymm_b)
+
+    # Reduce the contents of a YMM register
+    ymm_c_permuted = YMMRegister()
+    VPERM2F128(ymm_c_permuted, ymm_c, ymm_c, 1)
+    VADDPS(ymm_c, ymm_c, ymm_c_permuted)
+    VHADDPS(ymm_c, ymm_c, ymm_c)
+    VHADDPS(ymm_c, ymm_c, ymm_c)
+
+    # Negate the values, to go from "similarity" to "distance"
+    VSUBPS(ymm_c, ymm_one, ymm_c)
+
+    # A common convention is to return floats in XMM registers
+    RETURN(ymm_c.as_xmm)
+
+python_function = asm_function.finalize(abi.detect()).encode().load()
+metric = CompiledMetric(
+    pointer=python_function.loader.code_address,
+    kind=MetricKind.IP,
+    signature=MetricSignature.ArrayArray,
+)
+index = Index(ndim=ndim, metric=metric)
 ```
 
 [numba]: https://numba.readthedocs.io/en/stable/reference/jit-compilation.html#c-callbacks
+[cppyy]: https://cppyy.readthedocs.io/en/latest/
+[peachpy]: https://github.com/Maratyszcza/PeachPy
 
 #### Tooling
 
+To work with `bbin`, `fbin`, `ibin`, `hbin` matrix files USearch provides `load_matrix` and `save_matrix`.
+Such files are standard in k-ANN tasks and represent a binary object with all the scalars, prepended by two 32-bit integers - the number of rows and columns in the matrix.
+
 ```py
 from usearch.index import Index
 from usearch.io import load_matrix, save_matrix
@@ -335,6 +486,28 @@ index = Index(ndim=vectors.shape[1])
 index.add(labels, vectors)
 ```
 
+One may often want to evaluate the quality of the constructed index before running in production.
+The trivial way is to measure `recall@1` on the entries already present in the index.
+
+```py
+from usearch.eval import recall_members
+
+assert recall_members(index, exact=True) == 1
+print(recall_members(index, exact=False))
+```
+
+In case you have some ground-truth data for more than one entry, you compare search results against expected values:
+
+```py
+from usearch.eval import relevance, dcg, ndcg, random_vectors
+
+vectors = random_vectors(index=index)
+matches_approximate = index.search(vectors)
+matches_exact = index.search(vectors, exact=True)
+relevance_scores = relevance(matches_exact, matches_approximate)
+print(dcg(relevance_scores), ndcg(relevance_scores))
+```
+
 ### JavaScript
 
 #### Installation

package/conanfile.py

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

package/cpp/bench.cpp

@@ -483,7 +483,7 @@ void run_punned(dataset_at& dataset, args_t const& args, index_config_t config,
 
     index_at index = index_at::make(dataset.dimensions(), kind, config, accuracy);
     index.reserve(limits);
-    std::printf("-- Hardware acceleration: %s\n", isa_name(index.isa()));
+    std::printf("-- Hardware acceleration: %s\n", isa_name(index.metric().isa_));
     std::printf("Will benchmark in-memory\n");
 
     single_shot(dataset, index, true);
@@ -535,7 +535,7 @@ void run_big_or_small(dataset_at& dataset, args_t const& args, index_config_t co
 
 void report_alternative_setups() {
     using set_member_t = std::uint32_t;
-    using sets_index_t = index_gt<jaccard_gt<set_member_t>, std::size_t, std::uint32_t, set_member_t>;
+    using sets_index_t = index_gt<jaccard_gt<set_member_t>, std::size_t, std::uint32_t>;
     set_member_t set_a[] = {10, 12, 15};
     set_member_t set_b[] = {11, 12, 15, 16};
     sets_index_t index;

package/cpp/test.cpp

@@ -20,7 +20,8 @@ template <typename scalar_at, typename index_at> void test3d(index_at&& index) {
 
     using scalar_t = scalar_at;
     using view_t = span_gt<scalar_t const>;
-    using distance_t = typename index_at::distance_t;
+    using index_t = typename std::remove_reference<index_at>::type;
+    using distance_t = typename index_t::distance_t;
 
     scalar_t vec[3] = {10, 20, 15};
     scalar_t vec_a[3] = {15, 16, 17};
@@ -67,6 +68,7 @@ template <typename scalar_at, typename index_at> void test3d(index_at&& index) {
     expect(std::abs(matched_distances[0]) < 0.01);
 
     // Search again over mapped index
+    index_metadata("tmp.usearch");
     index.view("tmp.usearch");
     matched_count = index.search(view_t{&vec[0], 3ul}, 5).dump_to(matched_labels, matched_distances);
     expect(matched_count == 3);
@@ -144,11 +146,11 @@ int main(int, char**) {
     // static_assert(!std::is_same<index_gt<pearson_correlation_gt<>>::value_type, std::true_type>());
     // static_assert(!std::is_same<index_gt<haversine_gt<>>::value_type, std::true_type>());
 
-    test3d<float>(index_gt<cos_gt<float>, point_id_t, std::uint32_t, float>{});
-    test3d<float>(index_gt<l2sq_gt<float>, point_id_t, std::uint32_t, float>{});
+    test3d<float>(index_gt<cos_gt<float>, point_id_t, std::uint32_t>{});
+    test3d<float>(index_gt<l2sq_gt<float>, point_id_t, std::uint32_t>{});
 
-    test3d<double>(index_gt<cos_gt<double>, point_id_t, std::uint32_t, double>{});
-    test3d<double>(index_gt<l2sq_gt<double>, point_id_t, std::uint32_t, double>{});
+    test3d<double>(index_gt<cos_gt<double>, point_id_t, std::uint32_t>{});
+    test3d<double>(index_gt<l2sq_gt<double>, point_id_t, std::uint32_t>{});
 
     test3d<float>(punned_small_t::make(3, metric_kind_t::cos_k));
     test3d<float>(punned_small_t::make(3, metric_kind_t::l2sq_k));
@@ -159,11 +161,11 @@ int main(int, char**) {
     test3d_punned<float>(punned_small_t::make(3, metric_kind_t::cos_k));
     test3d_punned<float>(punned_small_t::make(3, metric_kind_t::l2sq_k));
 
-    test_sets(index_gt<jaccard_gt<std::int32_t, float>, point_id_t, std::uint32_t, std::int32_t>{});
-    test_sets(index_gt<jaccard_gt<std::int64_t, float>, point_id_t, std::uint32_t, std::int64_t>{});
+    test_sets(index_gt<jaccard_gt<std::int32_t, float>, point_id_t, std::uint32_t>{});
+    test_sets(index_gt<jaccard_gt<std::int64_t, float>, point_id_t, std::uint32_t>{});
 
-    test_sets_moved<index_gt<jaccard_gt<std::int32_t, float>, point_id_t, std::uint32_t, std::int32_t>>();
-    test_sets_moved<index_gt<jaccard_gt<std::int64_t, float>, point_id_t, std::uint32_t, std::int64_t>>();
+    test_sets_moved<index_gt<jaccard_gt<std::int32_t, float>, point_id_t, std::uint32_t>>();
+    test_sets_moved<index_gt<jaccard_gt<std::int64_t, float>, point_id_t, std::uint32_t>>();
 
     return 0;
 }

package/docs/compilation.md

@@ -11,14 +11,16 @@ git submodule update --init --recursive
 Linux:
 
 ```sh
+sudo apt-get update
+sudo apt-get install cmake g++-12 build-essential libjemalloc-dev
 cmake -B ./build_release \
     -DCMAKE_CXX_COMPILER="g++-12" \
     -DCMAKE_BUILD_TYPE=Release \
-    -DUSEARCH_USE_JEMALLOC=1 \
+    -DUSEARCH_BUILD_TEST=1 \
     -DUSEARCH_USE_OPENMP=1 \
     -DUSEARCH_USE_SIMSIMD=1 \
+    -DUSEARCH_USE_JEMALLOC=1 \
     -DUSEARCH_BUILD_BENCHMARK=1 \
-    -DUSEARCH_BUILD_TEST=1 \
     && \
     make -C ./build_release -j
 ```