usearch 0.14.0 → 0.15.0

package/conanfile.py

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

package/{src → cpp}/bench.cpp

@@ -38,7 +38,7 @@
 
 #include <simsimd/simsimd.h>
 
-#include "punned.hpp"
+#include <usearch/index_punned_dense.hpp>
 
 using namespace unum::usearch;
 using namespace unum;
@@ -432,46 +432,58 @@ struct args_t {
 
     bool big = false;
     bool native = false;
+
     bool quantize_f16 = false;
     bool quantize_f8 = false;
+    bool quantize_b1 = false;
 
     bool metric_ip = false;
     bool metric_l2 = false;
     bool metric_cos = false;
     bool metric_haversine = false;
-};
+    bool metric_hamming = false;
+    bool metric_tanimoto = false;
+    bool metric_sorensen = false;
+
+    metric_kind_t metric() const noexcept {
+        if (metric_l2)
+            return metric_kind_t::l2sq_k;
+        if (metric_cos)
+            return metric_kind_t::cos_k;
+        if (metric_haversine)
+            return metric_kind_t::haversine_k;
+        if (metric_hamming)
+            return metric_kind_t::hamming_k;
+        if (metric_tanimoto)
+            return metric_kind_t::tanimoto_k;
+        if (metric_sorensen)
+            return metric_kind_t::sorensen_k;
+        return metric_kind_t::ip_k;
+    }
 
-template <typename index_at, typename dataset_at> //
-index_at punned_index_for_metric(dataset_at& dataset, args_t const& args, index_config_t config, accuracy_t accuracy) {
-    if (args.metric_l2) {
-        std::printf("-- Metric: Euclidean\n");
-        return index_at::l2sq(dataset.dimensions(), accuracy, config);
-    } else if (args.metric_cos) {
-        std::printf("-- Metric: Angular\n");
-        return index_at::cos(dataset.dimensions(), accuracy, config);
-    } 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);
+    scalar_kind_t accuracy() const noexcept {
+        if (quantize_f16)
+            return scalar_kind_t::f16_k;
+        if (quantize_f8)
+            return scalar_kind_t::f8_k;
+        if (quantize_b1)
+            return scalar_kind_t::b1x8_k;
+        return scalar_kind_t::f32_k;
     }
-}
+};
 
 template <typename index_at, typename dataset_at> //
 void run_punned(dataset_at& dataset, args_t const& args, index_config_t config, index_limits_t limits) {
 
-    accuracy_t accuracy = accuracy_t::f32_k;
-    if (args.quantize_f16)
-        accuracy = accuracy_t::f16_k;
-    if (args.quantize_f8)
-        accuracy = accuracy_t::f8_k;
+    scalar_kind_t accuracy = args.accuracy();
+    std::printf("-- Accuracy: %s\n", scalar_kind_name(accuracy));
 
-    std::printf("-- Accuracy: %s\n", accuracy_name(accuracy));
+    metric_kind_t kind = args.metric();
+    std::printf("-- Metric: %s\n", metric_kind_name(kind));
 
-    index_at index{punned_index_for_metric<index_at>(dataset, args, config, accuracy)};
+    index_at index = index_at::make(dataset.dimensions(), kind, config, accuracy);
     index.reserve(limits);
-    std::printf("-- Hardware acceleration: %s\n", isa_name(index.acceleration()));
+    std::printf("-- Hardware acceleration: %s\n", isa_name(index.isa()));
     std::printf("Will benchmark in-memory\n");
 
     single_shot(dataset, index, true);
@@ -518,7 +530,7 @@ void run_big_or_small(dataset_at& dataset, args_t const& args, index_config_t co
             run_typed<index_gt<ip_gt<float>, std::size_t, neighbor_id_at>>(dataset, args, config, limits);
         }
     } else
-        run_punned<punned_gt<std::size_t, neighbor_id_at>>(dataset, args, config, limits);
+        run_punned<index_punned_dense_gt<std::size_t, neighbor_id_at>>(dataset, args, config, limits);
 }
 
 void report_alternative_setups() {
@@ -537,8 +549,8 @@ void report_expected_losses(persisted_dataset_gt<float, vector_id_t> const& data
 
     auto vec1 = dataset.vector(0);
     auto vec2 = dataset.query(0);
-    std::vector<f16_bits_t> vec1f16(dataset.dimensions());
-    std::vector<f16_bits_t> vec2f16(dataset.dimensions());
+    std::vector<f16_t> vec1f16(dataset.dimensions());
+    std::vector<f16_t> vec2f16(dataset.dimensions());
     std::transform(vec1, vec1 + dataset.dimensions(), vec1f16.data(), [](float v) { return v; });
     std::transform(vec2, vec2 + dataset.dimensions(), vec2f16.data(), [](float v) { return v; });
     std::vector<f8_bits_t> vec1f8(dataset.dimensions());
@@ -548,7 +560,7 @@ void report_expected_losses(persisted_dataset_gt<float, vector_id_t> const& data
 
 #if 0
     auto ip_default = ip_gt<float>{}(vec1, vec2, dataset.dimensions());
-    auto ip_f16 = ip_gt<f16_bits_t, float>{}(vec1f16.data(), vec2f16.data(), dataset.dimensions());
+    auto ip_f16 = ip_gt<f16_t, float>{}(vec1f16.data(), vec2f16.data(), dataset.dimensions());
     auto ip_f8 = ip_gt<f8_bits_t, float>{}(vec1f8.data(), vec2f8.data(), dataset.dimensions());
 
 #if defined(__AVX512F__)
@@ -591,12 +603,16 @@ int main(int argc, char** argv) {
         (option("--rows-take") & value("integer", args.vectors_to_take)).doc("Number of vectors to take"),
         ( //
             option("--native").set(args.native).doc("Use raw templates instead of type-punned classes") |
-            option("--f16quant").set(args.quantize_f16).doc("Enable `f16_t` quantization") |
-            option("--f8quant").set(args.quantize_f8).doc("Enable `f8_t` quantization")),
+            option("-f16", "--f16quant").set(args.quantize_f16).doc("Enable `f16_t` quantization") |
+            option("-f8", "--f8quant").set(args.quantize_f8).doc("Enable `f8_t` quantization") |
+            option("-b1", "--b1quant").set(args.quantize_b1).doc("Enable `b1x8_t` quantization")),
         ( //
             option("--ip").set(args.metric_ip).doc("Choose Inner Product metric") |
             option("--l2sq").set(args.metric_l2).doc("Choose L2 Euclidean metric") |
             option("--cos").set(args.metric_cos).doc("Choose Angular metric") |
+            option("--hamming").set(args.metric_hamming).doc("Choose Hamming metric") |
+            option("--tanimoto").set(args.metric_tanimoto).doc("Choose Tanimoto metric") |
+            option("--sorensen").set(args.metric_sorensen).doc("Choose Sorensen metric") |
             option("--haversine").set(args.metric_haversine).doc("Choose Haversine metric")),
         option("-h", "--help").set(args.help).doc("Print this help information on this tool and exit"));
 
@@ -609,7 +625,7 @@ int main(int argc, char** argv) {
         exit(0);
     }
 
-    // Instead of relying on `multithreaded` from "punned.hpp" we will use OpenMP
+    // Instead of relying on `multithreaded` from "index_punned_dense.hpp" we will use OpenMP
     // to better estimate statistics between tasks batches, without having to recreate
     // the threads.
     omp_set_dynamic(true);
@@ -638,16 +654,16 @@ int main(int argc, char** argv) {
 
     index_config_t config;
     config.connectivity = args.connectivity;
-    config.expansion_add = args.expansion_add;
-    config.expansion_search = args.expansion_search;
+    // config.expansion_add = args.expansion_add;
+    // config.expansion_search = args.expansion_search;
     index_limits_t limits;
     limits.threads_add = limits.threads_search = args.threads;
     limits.elements = dataset.vectors_count();
 
     std::printf("- Index: \n");
     std::printf("-- Connectivity: %zu\n", config.connectivity);
-    std::printf("-- Expansion @ Add: %zu\n", config.expansion_add);
-    std::printf("-- Expansion @ Search: %zu\n", config.expansion_search);
+    // std::printf("-- Expansion @ Add: %zu\n", config.expansion_add);
+    // std::printf("-- Expansion @ Search: %zu\n", config.expansion_search);
 
     if (args.big)
         run_big_or_small<uint40_t>(dataset, args, config, limits);

package/{src → cpp}/test.cpp

@@ -4,7 +4,7 @@
 #include <algorithm>
 #include <stdexcept>
 
-#include "punned.hpp"
+#include <usearch/index_punned_dense.hpp>
 
 using namespace unum::usearch;
 using namespace unum;
@@ -134,20 +134,30 @@ template <typename index_at> void test_sets_moved() {
 
 int main(int, char**) {
 
+    static_assert(!std::is_same<index_gt<ip_gt<>>::value_type, std::true_type>());
+    static_assert(!std::is_same<index_gt<cos_gt<>>::value_type, std::true_type>());
+    static_assert(!std::is_same<index_gt<l2sq_gt<>>::value_type, std::true_type>());
+    // static_assert(!std::is_same<index_gt<hamming_gt<>>::value_type, std::true_type>());
+    // static_assert(!std::is_same<index_gt<tanimoto_gt<>>::value_type, std::true_type>());
+    // static_assert(!std::is_same<index_gt<sorensen_gt<>>::value_type, std::true_type>());
+    // static_assert(!std::is_same<index_gt<jaccard_gt<>>::value_type, std::true_type>());
+    // 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<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<float>(punned_small_t::cos(3));
-    test3d<float>(punned_small_t::l2sq(3));
+    test3d<float>(punned_small_t::make(3, metric_kind_t::cos_k));
+    test3d<float>(punned_small_t::make(3, metric_kind_t::l2sq_k));
 
-    test3d<double>(punned_small_t::cos(3));
-    test3d<double>(punned_small_t::l2sq(3));
+    test3d<double>(punned_small_t::make(3, metric_kind_t::cos_k));
+    test3d<double>(punned_small_t::make(3, metric_kind_t::l2sq_k));
 
-    test3d_punned<float>(punned_small_t::cos(3));
-    test3d_punned<float>(punned_small_t::l2sq(3));
+    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>{});

package/docs/benchmarks.md

@@ -55,7 +55,7 @@ Also worth noting, 8-bit quantization results in almost no accuracy loss and may
 
 Within this repository you will find two commonly used utilities:
 
-- `src/bench.cpp` the produces the `bench` binary for broad USearch benchmarks.
+- `cpp/bench.cpp` the produces the `bench` binary for broad USearch benchmarks.
 - `python/bench.py` for simple benchmarks against FAISS.
 
 To achieve best highest results we suggest compiling locally for the target architecture.
@@ -170,15 +170,6 @@ mkdir -p datasets/deep_1B/ && \
 
 ## Profiling
 
-Enabling Huge Pages:
-
-```sh
-sudo cat /proc/sys/vm/nr_hugepages
-sudo sysctl -w vm.nr_hugepages=2048
-sudo reboot
-sudo cat /proc/sys/vm/nr_hugepages
-```
-
 With `perf`:
 
 ```sh
@@ -189,3 +180,35 @@ sudo -E perf mem -d ./build_release/bench ...
 sudo -E perf record -F 1000 ./build_release/bench ...
 perf record -d -e arm_spe// -- ./build_release/bench ..
 ```
+
+### Caches
+
+```sh
+sudo perf stat -e 'faults,dTLB-loads,dTLB-load-misses,cache-misses,cache-references' ./build_release/bench ...
+```
+
+Typical output on a 1M vectors dataset is:
+
+```txt
+            255426      faults                                                      
+      305988813388      dTLB-loads                                                  
+        8845723783      dTLB-load-misses          #    2.89% of all dTLB cache accesses
+       20094264206      cache-misses              #    6.567 % of all cache refs    
+      305988812745      cache-references                                            
+
+       8.285148010 seconds time elapsed
+
+     500.705967000 seconds user
+       1.371118000 seconds sys
+```
+
+If you notice problems and the stalls are closer to 90%, it might be a good reason to consider enabling Huge Pages and tuning allocations alignment.
+To enable Huge Pages:
+
+```sh
+sudo cat /proc/sys/vm/nr_hugepages
+sudo sysctl -w vm.nr_hugepages=2048
+sudo reboot
+sudo cat /proc/sys/vm/nr_hugepages
+```
+

package/docs/c/index.rst

@@ -0,0 +1,11 @@
+=======
+C SDK
+=======
+
+
+.. mdinclude:: ../../c/README.md
+
+.. toctree::
+   :hidden:
+
+   reference

package/docs/c/reference.rst

@@ -0,0 +1,7 @@
+API Reference
+===============
+
+===============
+usearch
+===============
+.. doxygenfile:: usearch.h

package/docs/compilation.md

@@ -41,7 +41,10 @@ cmake -B ./build_release \
 Linting:
 
 ```sh
-cppcheck --enable=all --suppress=cstyleCast --suppress=unusedFunction include/usearch/usearch.hpp src/punned.hpp
+cppcheck --enable=all --suppress=cstyleCast --suppress=unusedFunction \
+    include/usearch/index.hpp \
+    include/index_punned_dense.hpp \
+    include/index_punned_helpers.hpp
 ```
 
 Benchmarking:
@@ -81,7 +84,7 @@ Benchmarking:
 
 ```sh
 pip install faiss-cpu
-python python/scripts/bench.py \
+python python/scripts/bench.py speed \
     --vectors datasets/wiki_1M/base.1M.fbin \
     --queries datasets/wiki_1M/query.public.100K.fbin \
     --neighbors datasets/wiki_1M/groundtruth.public.100K.ibin
@@ -92,9 +95,8 @@ python python/scripts/bench.py \
 Checking the effect of different embedding dimensions on construction speed:
 
 ```sh
-python python/scripts/bench_params.py dimensions
-python python/scripts/bench_params.py connectivity
-python python/scripts/bench_params.py robustness
+python python/scripts/bench.py dimensions ...
+python python/scripts/bench.py connectivity ...
 ```
 
 ## JavaScript
@@ -115,7 +117,7 @@ cargo publish
 
 ```sh
 gradle clean build
-java -cp . -Djava.library.path=/Users/av/github/usearch/build/libs/usearch/shared java/cloud/unum/usearch/Index.java
+java -cp . -Djava.library.path="$(pwd)/build/libs/usearch/shared" java/cloud/unum/usearch/Index.java
 ```
 
 Or step by-step:
@@ -135,15 +137,14 @@ 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../../../../robin-map/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
+java -cp . -Djava.library.path="$(pwd)/java/cloud/unum/usearch/" Index.java
+java -cp . -Djava.library.path="$(pwd)/java" cloud.unum.usearch.Index
 ```
 
 ## Wolfram
@@ -159,6 +160,12 @@ cd golang
 go test -v
 ```
 
+## Objective-C and Swift
+
+```sh
+swift build
+```
+
 ## C
 
 ### Linux
@@ -186,4 +193,12 @@ docker buildx create --use &&
         --tag unum/usearch:$version \
         --tag unum/usearch:latest \
         --push .
+```
+
+---
+
+Extending metrics in SimSIMD:
+
+```
+git push --set-upstream https://github.com/ashvardanian/simsimd.git HEAD:main
 ```

package/docs/conf.dox

@@ -872,7 +872,7 @@ WARN_LOGFILE           =
 # - Testing
 # - Benchmarks
 
-INPUT                  =    ../include/usearch
+INPUT                  =    ../include/usearch ../c/usearch.h  ../java/cloud/unum/usearch/Index.java
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1290,9 +1290,9 @@ HTML_STYLESHEET        =
 # list). For an example see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_STYLESHEET  = doxygen-awesome-css/doxygen-awesome.css \
-                         doxygen-awesome-css/doxygen-awesome-sidebar-only.css \
-                         doxygen-awesome-css/doxygen-awesome-sidebar-only-darkmode-toggle.css
+HTML_EXTRA_STYLESHEET  = 
+                         
+                         
 
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note
@@ -1302,8 +1302,8 @@ HTML_EXTRA_STYLESHEET  = doxygen-awesome-css/doxygen-awesome.css \
 # files will be copied as-is; there are no commands or markers available.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_FILES       = doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js \
-                         doxygen-awesome-css/doxygen-awesome-interactive-toc.js
+HTML_EXTRA_FILES       = 
+                         
 
 # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen
 # will adjust the colors in the style sheet and background images according to

package/docs/conf.py

@@ -21,7 +21,7 @@ with open('_static/custom.js', 'r+') as js:
 
 extensions = [
     'breathe', 'm2r2',
-    'sphinx.ext.autodoc',
+    'sphinx.ext.autodoc', 'sphinx_js',
     'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
@@ -46,3 +46,5 @@ html_baseurl = '/docs/usearch/'
 
 breathe_projects = {'USearch': '../build/xml'}
 breathe_default_project = 'USearch'
+
+js_source_path = '../javascript/usearch.js'

package/docs/cpp/index.rst

@@ -0,0 +1,11 @@
+=======
+C++ SDK
+=======
+
+
+.. mdinclude:: ../../cpp/README.md
+
+.. toctree::
+   :hidden:
+
+   reference

package/docs/cpp/reference.rst

@@ -0,0 +1,7 @@
+API Reference
+===============
+
+===============
+usearch
+===============
+.. doxygenfile:: index.hpp

package/docs/index.rst

@@ -10,6 +10,16 @@ Overview
    benchmarks
    compilation
 
+.. toctree:: 
+   :hidden:
+   :caption: �
+
+   c/index
+   cpp/index
+   java/index
+   python/index
+   javascript/index
+
 .. toctree:: 
    :hidden:
    :caption: �

package/docs/java/index.rst

@@ -0,0 +1,11 @@
+================
+Java SDK
+================
+
+
+.. mdinclude:: ../../java/README.md
+
+.. toctree::
+   :hidden:
+
+   reference

package/docs/java/reference.rst

@@ -0,0 +1,7 @@
+API Reference
+===============
+
+===============
+usearch
+===============
+.. doxygenfile:: Index.java

package/docs/javascript/index.rst

@@ -0,0 +1,11 @@
+==============
+JavaScript SDK
+==============
+
+
+.. mdinclude:: ../javascript/README.md
+
+.. toctree::
+   :hidden:
+
+   reference

package/docs/javascript/reference.rst

@@ -0,0 +1,9 @@
+API Reference
+===============
+
+==================
+usearch.Index
+==================
+
+.. js:autoclass:: Index
+   :members:

package/docs/python/index.rst

@@ -0,0 +1,11 @@
+==============
+Python SDK
+==============
+
+
+.. mdinclude:: ../python/README.md
+
+.. toctree::
+   :hidden:
+
+   reference

package/docs/python/reference.rst

@@ -0,0 +1,35 @@
+API Reference
+===============
+
+======
+Index
+======
+
+.. automodule:: usearch.index
+    :members:
+    :undoc-members:
+
+======
+IO
+======
+
+.. automodule:: usearch.io
+    :members:
+    :undoc-members:
+
+======
+Client
+======
+
+.. automodule:: usearch.client
+    :members:
+    :undoc-members:
+
+
+======
+Server
+======
+
+.. automodule:: usearch.server
+    :members:
+    :undoc-members:

package/golang/lib.go

@@ -118,7 +118,7 @@ func (ind *Index) Destroy() {
 	if ind.opaque_handle == nil {
 		panic("index not initialized")
 	}
-	C.usearch_destroy(unsafe.Pointer(ind.opaque_handle))
+	C.usearch_free(unsafe.Pointer(ind.opaque_handle))
 	ind.opaque_handle = nil
 	ind.config = IndexConfig{}
 }