usearch 0.2.2 → 0.2.4

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
@@ -170,6 +174,29 @@ class f8_bits_t {
 
 inline f16_bits_t::f16_bits_t(f8_bits_t v) noexcept : f16_bits_t(float(v)) {}
 
+struct cos_f8_t {
+    punned_distance_t operator()(f8_bits_t const* a, f8_bits_t const* b, std::size_t n) const noexcept {
+        std::int32_t ab{}, a2{}, b2{};
+        for (std::size_t i = 0; i != n; i++) {
+            std::int16_t ai{a[i]};
+            std::int16_t bi{b[i]};
+            ab += ai * bi;
+            a2 += square(ai);
+            b2 += square(bi);
+        }
+        return 1.f - ab / (std::sqrt(a2) * std::sqrt(b2));
+    }
+};
+
+struct l2sq_f8_t {
+    punned_distance_t operator()(f8_bits_t const* a, f8_bits_t const* b, std::size_t n) const noexcept {
+        std::int32_t ab_deltas_sq{};
+        for (std::size_t i = 0; i != n; i++)
+            ab_deltas_sq += square(std::int16_t(a[i]) - std::int16_t(b[i]));
+        return ab_deltas_sq;
+    }
+};
+
 struct uuid_t {
     std::uint8_t octets[16];
 };
@@ -179,12 +206,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 +227,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 +457,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);
@@ -484,7 +518,11 @@ class auto_index_gt {
 
   private:
     static index_t* aligned_index_alloc() noexcept {
+#if defined(WINDOWS)
+        return (index_t*)_aligned_malloc(64, 64 * divide_round_up<64>(sizeof(index_t)));
+#else
         return (index_t*)aligned_alloc(64, 64 * divide_round_up<64>(sizeof(index_t)));
+#endif
     }
 
     static void aligned_index_free(index_t* raw) noexcept { free(raw); }
@@ -641,43 +679,40 @@ class auto_index_gt {
         return {pun_metric<f32_t>(ip_gt<f32_t>{}), isa_t::auto_k};
     }
 
-    static metric_and_meta_t ip_metric_f16(std::size_t dimensions) {
+    static metric_and_meta_t cos_metric_f16(std::size_t dimensions) {
         (void)dimensions;
 #if defined(USEARCH_USE_SIMD)
 #if defined(__x86_64__)
-        if (dimensions % 32 == 0)
+        if (dimensions % 16 == 0)
             return {
                 pun_metric<simsimd_f16_t>([](simsimd_f16_t const* a, simsimd_f16_t const* b, size_t d) noexcept {
-                    return 1.f - simsimd_dot_f16x16avx512(a, b, d);
+                    return 1.f - simsimd_cos_f16x16avx512(a, b, d);
                 }),
                 isa_t::avx512_k,
             };
 #elif defined(__aarch64__)
-        if (supports_arm_sve())
-            return {
-                pun_metric<simsimd_f16_t>([](simsimd_f16_t const* a, simsimd_f16_t const* b, size_t d) noexcept {
-                    return 1.f - simsimd_dot_f16sve(a, b, d);
-                }),
-                isa_t::sve_k,
-            };
-        if (dimensions % 8 == 0)
+        if (dimensions % 4 == 0)
             return {
                 pun_metric<simsimd_f16_t>([](simsimd_f16_t const* a, simsimd_f16_t const* b, size_t d) noexcept {
-                    return 1.f - simsimd_dot_f16x8neon(a, b, d);
+                    return 1.f - simsimd_cos_f16x4neon(a, b, d);
                 }),
                 isa_t::neon_k,
             };
 #endif
 #endif
-        return {pun_metric<f16_bits_t>(ip_gt<f16_bits_t, f32_t>{}), isa_t::auto_k};
+        return {pun_metric<f16_bits_t>(cos_gt<f16_bits_t, f32_t>{}), isa_t::auto_k};
     }
 
     static metric_and_meta_t ip_metric(std::size_t dimensions, accuracy_t accuracy) {
         switch (accuracy) {
-            // The tow most common numeric types for the most common metric have  afew optimized versions:
-        case accuracy_t::f16_k: return ip_metric_f16(dimensions);
-        case accuracy_t::f32_k: return ip_metric_f32(dimensions);
-        case accuracy_t::f8_k: return {pun_metric<f8_bits_t>(ip_gt<f8_bits_t, f32_t>{}), isa_t::auto_k};
+        case accuracy_t::f32_k:
+            // The two most common numeric types for the most common metric have optimized versions
+            return ip_metric_f32(dimensions);
+        case accuracy_t::f16_k:
+            // Dot-product accumulates error, Cosine-distance normalizes it
+            return cos_metric_f16(dimensions);
+
+        case accuracy_t::f8_k: return {pun_metric<f8_bits_t>(cos_f8_t{}), isa_t::auto_k};
         case accuracy_t::f64_k: return {pun_metric<f64_t>(ip_gt<f64_t>{}), isa_t::auto_k};
         default: return {};
         }
@@ -685,7 +720,7 @@ class auto_index_gt {
 
     static metric_and_meta_t l2_metric(std::size_t, accuracy_t accuracy) {
         switch (accuracy) {
-        case accuracy_t::f8_k: return {pun_metric<f8_bits_t>(l2sq_gt<f8_bits_t, f32_t>{}), isa_t::auto_k};
+        case accuracy_t::f8_k: return {pun_metric<f8_bits_t>(l2sq_f8_t{}), isa_t::auto_k};
         case accuracy_t::f16_k: return {pun_metric<f16_bits_t>(l2sq_gt<f16_bits_t, f32_t>{}), isa_t::auto_k};
         case accuracy_t::f32_k: return {pun_metric<f32_t>(l2sq_gt<f32_t>{}), isa_t::auto_k};
         case accuracy_t::f64_k: return {pun_metric<f64_t>(l2sq_gt<f64_t>{}), isa_t::auto_k};
@@ -693,10 +728,10 @@ class auto_index_gt {
         }
     }
 
-    static metric_and_meta_t cos_metric(std::size_t, accuracy_t accuracy) {
+    static metric_and_meta_t cos_metric(std::size_t dimensions, accuracy_t accuracy) {
         switch (accuracy) {
-        case accuracy_t::f8_k: return {pun_metric<f8_bits_t>(cos_gt<f8_bits_t, f32_t>{}), isa_t::auto_k};
-        case accuracy_t::f16_k: return {pun_metric<f16_bits_t>(cos_gt<f16_bits_t, f32_t>{}), isa_t::auto_k};
+        case accuracy_t::f8_k: return {pun_metric<f8_bits_t>(cos_f8_t{}), isa_t::auto_k};
+        case accuracy_t::f16_k: return cos_metric_f16(dimensions);
         case accuracy_t::f32_k: return {pun_metric<f32_t>(cos_gt<f32_t>{}), isa_t::auto_k};
         case accuracy_t::f64_k: return {pun_metric<f64_t>(cos_gt<f64_t>{}), isa_t::auto_k};
         default: return {};

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>
 
@@ -400,7 +400,7 @@ struct args_t {
     bool quantize_f16 = false;
     bool quantize_f8 = false;
 
-    bool metric_ip = true;
+    bool metric_ip = false;
     bool metric_l2 = false;
     bool metric_cos = false;
     bool metric_haversine = false;
@@ -408,23 +408,19 @@ struct args_t {
 
 template <typename index_at, typename dataset_at> //
 index_at type_punned_index_for_metric(dataset_at& dataset, args_t const& args, config_t config, accuracy_t accuracy) {
-    if (args.metric_ip) {
-        std::printf("-- Metric: Inner Product\n");
-        return index_at::ip(dataset.dimensions(), accuracy, config);
-    }
     if (args.metric_l2) {
         std::printf("-- Metric: Euclidean\n");
         return index_at::l2(dataset.dimensions(), accuracy, config);
-    }
-    if (args.metric_cos) {
+    } else if (args.metric_cos) {
         std::printf("-- Metric: Angular\n");
         return index_at::cos(dataset.dimensions(), accuracy, config);
-    }
-    if (args.metric_haversine) {
+    } else if (args.metric_haversine) {
         std::printf("-- Metric: Haversine\n");
         return index_at::haversine(accuracy, config);
+    } else {
+        std::printf("-- Metric: Inner Product\n");
+        return index_at::ip(dataset.dimensions(), accuracy, config);
     }
-    throw std::invalid_argument("Unknown metric!");
 }
 
 template <typename index_at, typename dataset_at> //
@@ -472,16 +468,16 @@ template <typename neighbor_id_at, typename dataset_at> //
 void run_big_or_small(dataset_at& dataset, args_t const& args, config_t config) {
     if (args.native) {
         if (args.metric_cos) {
-            std::printf("-- Metric: Inner Product\n");
-            run_typed<index_gt<ip_gt<float>, std::size_t, neighbor_id_at>>(dataset, args, config);
+            std::printf("-- Metric: Angular\n");
+            run_typed<index_gt<cos_gt<float>, std::size_t, neighbor_id_at>>(dataset, args, config);
         } else if (args.metric_l2) {
             std::printf("-- Metric: Euclidean\n");
             run_typed<index_gt<l2sq_gt<float>, std::size_t, neighbor_id_at>>(dataset, args, config);
         } else if (args.metric_haversine) {
-            std::printf("-- Metric: Angular\n");
+            std::printf("-- Metric: Haversine\n");
             run_typed<index_gt<haversine_gt<float>, std::size_t, neighbor_id_at>>(dataset, args, config);
         } else {
-            std::printf("-- Metric: Haversine\n");
+            std::printf("-- Metric: Inner Product\n");
             run_typed<index_gt<ip_gt<float>, std::size_t, neighbor_id_at>>(dataset, args, config);
         }
     } else

package/.github/workflows/package.json

@@ -1,82 +0,0 @@
-{
-  "devDependencies": {
-    "@semantic-release/exec": "github:semantic-release/exec",
-    "@semantic-release/git": "^10.0.1",
-    "conventional-changelog-eslint": "^3.0.9",
-    "semantic-release": "^20.1.3"
-  },
-  "release": {
-    "branches": [
-      "main"
-    ],
-    "debug": true,
-    "ci": true,
-    "dryRun": false,
-    "plugins": [
-      [
-        "@semantic-release/commit-analyzer",
-        {
-          "preset": "eslint",
-          "releaseRules": [
-            {
-              "tag": "Add",
-              "release": "minor"
-            },
-            {
-              "tag": "Improve",
-              "release": "patch"
-            },
-            {
-              "tag": "Make",
-              "release": "patch"
-            },
-            {
-              "tag": "Refactor",
-              "release": false
-            }
-          ]
-        }
-      ],
-      [
-        "@semantic-release/release-notes-generator",
-        {
-          "preset": "eslint",
-          "releaseRules": [
-            {
-              "tag": "Add",
-              "release": "minor"
-            },
-            {
-              "tag": "Improve",
-              "release": "patch"
-            },
-            {
-              "tag": "Make",
-              "release": "patch"
-            },
-            {
-              "tag": "Refactor",
-              "release": false
-            }
-          ]
-        }
-      ],
-      "@semantic-release/github",
-      [
-        "@semantic-release/exec",
-        {
-          "prepareCmd": "echo '${nextRelease.version}' > VERSION"
-        }
-      ],
-      [
-        "@semantic-release/git",
-        {
-          "assets": [
-            "VERSION"
-          ],
-          "message": "Build: Released ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
-        }
-      ]
-    ]
-  }
-}

package/CMakeListsInstructions.md

@@ -1,185 +0,0 @@
-# Compiling USearch
-
-## Build
-
-Before building the first time, please pull submodules.
-
-```sh
-git submodule update --init --recursive
-```
-
-### Linux
-
-```sh
-cmake -B ./build_release \
-    -DCMAKE_CXX_COMPILER="g++-12" \
-    -DCMAKE_BUILD_TYPE=Release \
-    -DUSEARCH_USE_SIMD=1 \
-    -DUSEARCH_USE_OPENMP=1 \
-    -DUSEARCH_USE_JEMALLOC=1 && \
-    make -C ./build_release -j
-
-# To benchmark in C++:
-./build_release/bench \
-    --vectors datasets/wiki_1M/base.1M.fbin \
-    --queries datasets/wiki_1M/query.public.100K.fbin \
-    --neighbors datasets/wiki_1M/groundtruth.public.100K.ibin
-
-# Large benchmark on a 1TB dataset:
-./build_release/bench \
-    --vectors datasets/t2i_1B/base.1B.fbin \
-    --queries datasets/t2i_1B/query.public.100K.fbin \
-    --neighbors datasets/t2i_1B/groundtruth.public.100K.ibin \
-    --output datasets/t2i_1B/index.usearch \
-    --cos
-
-# To benchmark in Python:
-python python/bench.py \
-    --vectors datasets/wiki_1M/base.1M.fbin \
-    --queries datasets/wiki_1M/query.public.100K.fbin \
-    --neighbors datasets/wiki_1M/groundtruth.public.100K.ibin
-```
-
-### MacOS
-
-```sh
-brew install libomp llvm
-cmake \
-    -DCMAKE_C_COMPILER="/opt/homebrew/opt/llvm/bin/clang" \
-    -DCMAKE_CXX_COMPILER="/opt/homebrew/opt/llvm/bin/clang++" \
-    -DUSEARCH_USE_SIMD=1 \
-    -DUSEARCH_USE_OPENMP=1 \
-     -B ./build_release && \
-    make -C ./build_release -j 
-```
-
-### Python
-
-```sh
-pip install -e .
-python python/test.py
-```
-
-### JavaScript
-
-```sh
-npm install
-node javascript/test.js
-npm publish
-```
-
-### Rust
-
-```sh
-cargo test -p usearch
-cargo publish
-```
-
-### Java
-
-```sh
-gradle clean build
-java -cp . -Djava.library.path=/Users/av/github/usearch/build/libs/usearch/shared java/cloud/unum/usearch/Index.java
-```
-
-Or step by-step:
-
-```sh
-cs java/unum/cloud/usearch
-javac -h . Index.java
-
-# Ubuntu:
-g++ -c -fPIC -I${JAVA_HOME}/include -I${JAVA_HOME}/include/linux cloud_unum_usearch_Index.cpp -o cloud_unum_usearch_Index.o
-g++ -shared -fPIC -o libusearch.so cloud_unum_usearch_Index.o -lc
-
-# Windows
-g++ -c -I%JAVA_HOME%\include -I%JAVA_HOME%\include\win32 cloud_unum_usearch_Index.cpp -o cloud_unum_usearch_Index.o
-g++ -shared -o USearchJNI.dll cloud_unum_usearch_Index.o -Wl,--add-stdcall-alias
-
-# MacOS
-g++ -std=c++11 -c -fPIC \
-    -I../../../../include -I../../../../src -I../../../../fp16/include -I../../../../simsimd/include \
-    -I${JAVA_HOME}/include -I${JAVA_HOME}/include/darwin cloud_unum_usearch_Index.cpp -o cloud_unum_usearch_Index.o
-g++ -dynamiclib -o libusearch.dylib cloud_unum_usearch_Index.o -lc
-# Run linking to that directory
-java -cp . -Djava.library.path=/Users/av/github/usearch/java/cloud/unum/usearch/ Index.java
-java -cp . -Djava.library.path=/Users/av/github/usearch/java cloud.unum.usearch.Index
-```
-
-### Wolfram
-
-```sh
-brew install --cask wolfram-engine
-```
-
-## Benchmarks
-
-### Datasets
-
-BigANN benchmark is a good starting point, if you are searching for large collections of high-dimensional vectors.
-Those often come with precomputed ground-truth neighbors, which is handy for recall evaluation.
-
-| Dataset                                 | Scalar Type | Dimensions | Metric |   Size    |
-| :-------------------------------------- | :---------: | :--------: | :----: | :-------: |
-| [Unum UForm Wiki][unum-wiki]            |   float32   |    256     |   IP   |   1 GB    |
-| [Yandex Text-to-Image Sample][unum-t2i] |   float32   |    200     |  Cos   |   1 GB    |
-|                                         |             |            |        |           |
-| [Microsoft SPACEV][spacev]              |    int8     |    100     |   L2   |   93 GB   |
-| [Microsoft Turing-ANNS][turing]         |   float32   |    100     |   L2   |  373 GB   |
-| [Yandex Deep1B][deep]                   |   float32   |     96     |   L2   |  358 GB   |
-| [Yandex Text-to-Image][t2i]             |   float32   |    200     |  Cos   |  750 GB   |
-|                                         |             |            |        |           |
-| [ViT-L/12 LAION][laion]                 |   float32   |    2048    |  Cos   | 2 - 10 TB |
-
-Luckily, smaller samples of those datasets are available.
-
-[unum-wiki]: https://huggingface.co/datasets/unum-cloud/ann-wiki-1m
-[unum-t2i]: https://huggingface.co/datasets/unum-cloud/ann-t2i-1m
-[spacev]: https://github.com/microsoft/SPTAG/tree/main/datasets/SPACEV1B
-[turing]: https://learning2hash.github.io/publications/microsoftturinganns1B/
-[t2i]: https://research.yandex.com/blog/benchmarks-for-billion-scale-similarity-search
-[deep]: https://research.yandex.com/blog/benchmarks-for-billion-scale-similarity-search
-[laion]: https://laion.ai/blog/laion-5b/#download-the-data
-
-### Unum UForm Wiki
-
-```sh
-mkdir -p datasets/wiki_1M/ && \
-    wget -nc https://huggingface.co/datasets/unum-cloud/ann-wiki-1m/resolve/main/base.1M.fbin -P datasets/wiki_1M/ &&
-    wget -nc https://huggingface.co/datasets/unum-cloud/ann-wiki-1m/resolve/main/query.public.100K.fbin -P datasets/wiki_1M/ &&
-    wget -nc https://huggingface.co/datasets/unum-cloud/ann-wiki-1m/resolve/main/groundtruth.public.100K.ibin -P datasets/wiki_1M/
-```
-
-### Yandex Text-to-Image
-
-```sh
-mkdir -p datasets/t2i_1B/ && \
-    wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/T2I/base.1B.fbin -P datasets/t2i_1B/ &&
-    wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/T2I/base.1M.fbin -P datasets/t2i_1B/ &&
-    wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/T2I/query.public.100K.fbin -P datasets/t2i_1B/ &&
-    wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/T2I/groundtruth.public.100K.ibin -P datasets/t2i_1B/
-```
-
-### Yandex Deep1B
-
-```sh
-mkdir -p datasets/deep_1B/ && \
-    wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/DEEP/base.1B.fbin -P datasets/deep_1B/ &&
-    wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/DEEP/base.10M.fbin -P datasets/deep_1B/ &&
-    wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/DEEP/query.public.10K.fbin -P datasets/deep_1B/ &&
-    wget -nc https://storage.yandexcloud.net/yandex-research/ann-datasets/DEEP/groundtruth.public.10K.ibin -P datasets/deep_1B/
-```
-
-### Profiling
-
-With `perf`:
-
-```sh
-# Pass environment variables with `-E`, and `-d` for details
-sudo -E perf stat -d ./build_release/bench ...
-sudo -E perf mem -d ./build_release/bench ...
-# Sample on-CPU functions for the specified command, at 1 Kilo Hertz:
-sudo -E perf record -F 1000 ./build_release/bench ...
-perf record -d -e arm_spe// -- ./build_release/bench ..
-```
-