usearch 2.5.1 → 2.6.1

package/.github/workflows/release.yml

@@ -418,6 +418,13 @@ jobs:
           verbose: true
           print-hash: true
 
+      - name: Publish to Anaconda
+        run: |
+          pip install anaconda-client
+          export ANACONDA_API_TOKEN=${{ secrets.ANACONDA_API_TOKEN }}
+          anaconda login --token $ANACONDA_API_TOKEN
+          anaconda upload -u unum-cloud ./dist/artifact/*.tar.bz2
+
   publish_javascript:
     name: Publish JavaScript
     needs: versioning

package/.vscode/settings.json

@@ -145,6 +145,7 @@
         "SLOC",
         "sorensen",
         "tanimoto",
+        "tqdm",
         "uninitialize",
         "unumusearch",
         "usearch",

package/CITATION.cff

@@ -5,7 +5,7 @@ authors:
   given-names: "Ash"
   orcid: "https://orcid.org/0000-0002-4882-1815"
 title: "USearch by Unum Cloud"
-version: 2.5.1
+version: 2.6.1
 doi: 10.5281/zenodo.7949416
 date-released: 2022-06-12
 url: "https://github.com/unum-cloud/usearch"

package/Cargo.toml

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

package/README.md

@@ -392,7 +392,7 @@ doi = {10.5281/zenodo.7949416},
 author = {Vardanian, Ash},
 title = {{USearch by Unum Cloud}},
 url = {https://github.com/unum-cloud/usearch},
-version = {2.5.1},
+version = {2.6.1},
 year = {2022},
 month = jun,
 }

package/conanfile.py

@@ -7,7 +7,7 @@ required_conan_version = ">=1.53.0"
 class USearchConan(ConanFile):
 
     name = "usearch"
-    version = '2.5.1'
+    version = '2.6.1'
     license = "Apache-2.0"
     description = "Smaller & Faster Single-File Vector Search Engine from Unum"
     homepage = "https://github.com/unum-cloud/usearch"

package/cpp/README.md

@@ -2,8 +2,8 @@
 
 ## Installation
 
-To use in a C++ project simply copy the `include/usearch/index.hpp` header into your project.
-Alternatively fetch it with CMake:
+To use in a C++ project, copy the `include/usearch/*` headers into your project.
+Alternatively, fetch it with CMake:
 
 ```cmake
 FetchContent_Declare(usearch GIT_REPOSITORY https://github.com/unum-cloud/usearch.git)
@@ -12,13 +12,17 @@ FetchContent_MakeAvailable(usearch)
 
 ## Quickstart
 
-Once included, the low-level C++11 interface is as simple as it gets: `reserve()`, `add()`, `search()`, `size()`, `capacity()`, `save()`, `load()`, `view()`.
-This covers 90% of use-cases.
+Once included, the high-level C++11 interface is as simple as it gets: `reserve()`, `add()`, `search()`, `size()`, `capacity()`, `save()`, `load()`, `view()`.
+This covers 90% of use cases.
 
-```c++
+```cpp
 using namespace unum::usearch;
 
-index_gt<metric_cos_gt<float>> index;
+metric_punned_t metric(256, metric_kind_t::l2sq_k, scalar_kind_t::f32_k);
+
+// If you plan to store more than 4 Billion entries - use `index_dense_big_t`.
+// Or directly instantiate the template variant you need - `index_dense_gt<key_t, internal_id_t>`.
+index_dense_t index = index_dense_t::make(metric);
 float vec[3] = {0.1, 0.3, 0.2};
 
 index.reserve(10);
@@ -30,10 +34,19 @@ for (std::size_t i = 0; i != results.size(); ++i)
 ```
 
 The `add` is thread-safe for concurrent index construction.
+It also has an overload for different vector types, casting them under the hood.
+The same applies to the `search`, `get`, `cluster`, and `distance_between` functions.
+
+```cpp
+double vec_double[3] = {0.1, 0.3, 0.2};
+_Float16 vec_half[3] = {0.1, 0.3, 0.2};
+index.add(43, {&vec_double[0], 3});
+index.add(44, {&vec_half[0], 3});
+```
 
 ## Serialization
 
-```c++
+```cpp
 index.save("index.usearch");
 index.load("index.usearch"); // Copying from disk
 index.view("index.usearch"); // Memory-mapping from disk
@@ -44,23 +57,14 @@ index.view("index.usearch"); // Memory-mapping from disk
 For advanced users, more compile-time abstractions are available.
 
 ```cpp
-template <typename metric_at = metric_ip_gt<float>,            //
-          typename key_at = std::size_t,              // `uint32_t`, `uuid_t`...
-          typename id_at = std::uint32_t,               // `uint40_t`, `uint64_t`...
-          typename scalar_at = float,                   // `double`, `half`, `char`...
-          typename allocator_at = std::allocator<char>> //
+template <typename distance_at = default_distance_t,              // `float`
+          typename key_at = default_key_t,                        // `int64_t`, `uuid_t`
+          typename compressed_slot_at = default_slot_t,           // `uint32_t`, `uint40_t`
+          typename dynamic_allocator_at = std::allocator<byte_t>, //
+          typename tape_allocator_at = dynamic_allocator_at>      //
 class index_gt;
 ```
 
-You may want to use a custom memory allocator or a rare scalar type, but most often, you would start by defining a custom similarity measure.
-The function object should have the following signature to support different-length vectors.
-
-```cpp
-struct custom_metric_t {
-    T operator()(T const* a, T const* b, std::size_t a_length, std::size_t b_length) const;
-};
-```
-
 The following distances are pre-packaged:
 
 - `metric_cos_gt<scalar_t>` for "Cosine" or "Angular" distance.
@@ -81,7 +85,7 @@ Instead of spawning additional threads within USearch, we focus on the thread sa
 ```cpp
 #pragma omp parallel for
     for (std::size_t i = 0; i < n; ++i)
-        native.add(key, span_t{vector, dims}, index_update_config_t { .thread = omp_get_thread_num() });
+        native.add(key, span_t{vector, dims});
 ```
 
 During initialization, we allocate enough temporary memory for all the cores on the machine.

package/csharp/nuget/nuget-package.props

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Project>
   <PropertyGroup>
-    <Version Condition="'$(Version)' == ''">2.5.1</Version>
+    <Version Condition="'$(Version)' == ''">2.6.1</Version>
 
     <Authors>Unum</Authors>
     <Company>Unum</Company>

package/include/usearch/index.hpp

@@ -10,7 +10,7 @@
 #define UNUM_USEARCH_HPP
 
 #define USEARCH_VERSION_MAJOR 2
-#define USEARCH_VERSION_MINOR 5
+#define USEARCH_VERSION_MINOR 6
 #define USEARCH_VERSION_PATCH 1
 
 // Inferring C++ version

package/include/usearch/index_plugins.hpp

@@ -1602,7 +1602,7 @@ class flat_hash_multi_set_gt {
         auto slot_pointer = bucket_pointer + sizeof(bucket_header_t) + sizeof(element_t) * in_bucket_index;
         return {
             *reinterpret_cast<bucket_header_t*>(bucket_pointer),
-            std::uint64_t(1ull) << in_bucket_index,
+            static_cast<std::uint64_t>(1ull) << in_bucket_index,
             *reinterpret_cast<element_t*>(slot_pointer),
         };
     }

package/package.json

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

package/python/lib.cpp

@@ -532,49 +532,69 @@ static void search_typed_brute_force(                                //
         threads = std::thread::hardware_concurrency();
 
     std::size_t tasks_count = static_cast<std::size_t>(dataset_count * queries_count);
+    executor_default_t executor{threads};
 
     // Progress status
     progress_t progress_{progress};
     std::atomic<std::size_t> processed{0};
 
-    // Allocate temporary memory to store the distance matrix
-    // Previous version didn't need temporary memory, but the performance was much lower
     struct dense_key_and_distance_t {
         u32_t offset;
         f32_t distance;
     };
-    std::vector<dense_key_and_distance_t> keys_and_distances(tasks_count);
-
-    executor_default_t{threads}.dynamic(tasks_count, [&](std::size_t thread_idx, std::size_t task_idx) {
-        std::size_t dataset_idx = task_idx / queries_count;
-        std::size_t query_idx = task_idx % queries_count;
+    auto less = [](dense_key_and_distance_t const& a, dense_key_and_distance_t const& b) {
+        return a.distance < b.distance;
+    };
 
+    // Allocate temporary memory to store the distance matrix
+    // Previous version didn't need temporary memory, but the performance was much lower.
+    // In the new design we keep two buffers - original and transposed, as in-place transpositions
+    // of non-rectangular matrixes is expensive.
+    std::vector<dense_key_and_distance_t> keys_and_distances(tasks_count * 2);
+    dense_key_and_distance_t* keys_and_distances_per_dataset = keys_and_distances.data();
+    dense_key_and_distance_t* keys_and_distances_per_query = keys_and_distances_per_dataset + tasks_count;
+    executor.dynamic(dataset_count, [&](std::size_t thread_idx, std::size_t dataset_idx) {
         byte_t const* dataset = dataset_data + dataset_idx * dataset_info.strides[0];
+        for (std::size_t query_idx = 0; query_idx != queries_count; ++query_idx) {
         byte_t const* query = queries_data + query_idx * queries_info.strides[0];
         distance_t distance = metric(dataset, query);
-
-        keys_and_distances[task_idx] = {static_cast<u32_t>(query_idx), static_cast<f32_t>(distance)};
+            std::size_t task_idx = dataset_idx * queries_count + query_idx;
+            keys_and_distances_per_dataset[task_idx].offset = static_cast<u32_t>(dataset_idx);
+            keys_and_distances_per_dataset[task_idx].distance = static_cast<f32_t>(distance);
+        }
 
         // We don't want to check for signals from multiple threads
-        ++processed;
+        processed += queries_count;
         if (thread_idx == 0)
             if (PyErr_CheckSignals() != 0 || !progress_(processed.load(), tasks_count))
                 return false;
         return true;
     });
+    if (processed.load() != tasks_count)
+        return;
+
+    // Transpose in a single thread to avoid contention writing into the same memory buffers
+    for (std::size_t query_idx = 0; query_idx != queries_count; ++query_idx) {
+        for (std::size_t dataset_idx = 0; dataset_idx != dataset_count; ++dataset_idx) {
+            std::size_t from_idx = queries_count * dataset_idx + query_idx;
+            std::size_t to_idx = dataset_count * query_idx + dataset_idx;
+            keys_and_distances_per_query[to_idx] = keys_and_distances_per_dataset[from_idx];
+        }
+    }
 
     // Partial-sort every query result
-    executor_default_t{threads}.fixed(queries_count, [&](std::size_t, std::size_t query_idx) {
-        auto start = keys_and_distances.data() + query_idx * dataset_count;
-        std::partial_sort(start, start + wanted, start + dataset_count,
-                          [](dense_key_and_distance_t const& a, dense_key_and_distance_t const& b) {
-                              return a.distance < b.distance;
-                          });
-
+    executor.fixed(queries_count, [&](std::size_t, std::size_t query_idx) {
         dense_key_t* keys = &keys_py2d(query_idx, 0);
         distance_t* distances = &distances_py2d(query_idx, 0);
+        auto start = keys_and_distances_per_query + dataset_count * query_idx;
+        if (wanted > 1) {
+            std::partial_sort(start, start + wanted, start + dataset_count, less);
         for (std::size_t i = 0; i != wanted; ++i)
             keys[i] = static_cast<dense_key_t>(start[i].offset), distances[i] = start[i].distance;
+        } else {
+            auto max_it = std::max_element(start, start + dataset_count, less);
+            keys[0] = static_cast<dense_key_t>(max_it->offset), distances[0] = max_it->distance;
+        }
     });
 
     // At the end report the latest numbers, because the reporter thread may be finished earlier

package/python/scripts/bench_exact.py

@@ -0,0 +1,44 @@
+from time import time
+
+from usearch.index import search, MetricKind, ScalarKind
+from usearch.compiled import hardware_acceleration
+from faiss import IndexFlatL2, knn
+import numpy as np
+import fire
+
+
+def run(
+    n: int = 10**5,
+    q: int = 10,
+    k: int = 100,
+    ndim: int = 256,
+    half: bool = False,
+):
+    usearch_dtype = ScalarKind.F16 if half else ScalarKind.F32
+    acceleration = hardware_acceleration(
+        dtype=usearch_dtype,
+        ndim=ndim,
+        metric_kind=MetricKind.L2sq,
+    )
+    print("Hardware acceleration in USearch: ", acceleration)
+
+    x = np.random.random((n, ndim))
+    x = x.astype(np.float16) if half else x.astype(np.float32)
+
+    start = time()
+    _ = search(
+        x,
+        x[:q],
+        k,
+        MetricKind.L2sq,
+        exact=True,
+    ).keys
+    print("USearch: ", time() - start)
+
+    start = time()
+    _ = knn(x, x[:q], k)[1]
+    print("FAISS:   ", time() - start)
+
+
+if __name__ == "__main__":
+    fire.Fire(run)

package/python/scripts/test_tooling.py

@@ -11,7 +11,7 @@ from usearch.index import Match, Matches, BatchMatches, Index, Indexes
 
 
 dimensions = [3, 97, 256]
-batch_sizes = [1, 77]
+batch_sizes = [1, 77, 100]
 
 
 @pytest.mark.parametrize("rows", batch_sizes)
@@ -56,15 +56,16 @@ def test_exact_search(rows: int, cols: int):
     :param int cols: The number of columns in the matrix.
     """
     original = np.random.rand(rows, cols)
+    keys = np.arange(rows)
     matches: BatchMatches = search(original, original, min(10, rows), exact=True)
     top_matches = (
         [int(m.keys[0]) for m in matches] if rows > 1 else int(matches.keys[0])
     )
-    assert np.all(top_matches == np.arange(rows))
+    assert np.all(top_matches == keys)
 
-    matches: Matches = search(original, original[0], min(10, rows), exact=True)
+    matches: Matches = search(original, original[-1], min(10, rows), exact=True)
     top_match = int(matches.keys[0])
-    assert top_match == 0
+    assert top_match == keys[-1]
 
 
 def test_matches_creation_and_methods():

package/python/usearch/index.py

@@ -180,7 +180,7 @@ def _search_in_compiled(
         vectors = vectors.reshape(1, len(vectors))
     count_vectors = vectors.shape[0]
 
-    def distil_batch(
+    def distill_batch(
         batch_matches: BatchMatches,
     ) -> Union[BatchMatches, Matches]:
         return batch_matches[0] if count_vectors == 1 else batch_matches
@@ -188,22 +188,22 @@ def _search_in_compiled(
     # Create progress bar if needed
     if log:
         name = log if isinstance(log, str) else "Search"
-        pbar = tqdm(
+        progress_bar = tqdm(
             desc=name,
             total=count_vectors,
             unit="vector",
         )
 
         def update_progress_bar(processed: int, total: int) -> bool:
-            pbar.update(processed - pbar.n)
+            progress_bar.update(processed - progress_bar.n)
             return progress if progress else True
 
         tuple_ = compiled_callable(vectors, progress=update_progress_bar, **kwargs)
-        pbar.close()
+        progress_bar.close()
     else:
         tuple_ = compiled_callable(vectors, **kwargs)
 
-    return distil_batch(BatchMatches(*tuple_))
+    return distill_batch(BatchMatches(*tuple_))
 
 
 def _add_to_compiled(

package/wasmer.toml

@@ -1,6 +1,6 @@
 [package]
 name="unum/usearch"
-version="2.5.1"
+version="2.6.1"
 description="Smaller & Faster Single-File Vector Search Engine from Unum"
 license="Apache-2.0"
 readme="README.md"