usearch 0.4.0 → 0.8.1

package/rust/lib.cpp

@@ -4,9 +4,9 @@
 using namespace unum::usearch;
 using namespace unum;
 
-using native_index_t = typename Index::native_index_t;
+using punned_t = typename Index::punned_t;
 
-Index::Index(std::shared_ptr<native_index_t> index) : index_(index) {}
+Index::Index(std::shared_ptr<punned_t> index) : index_(index) {}
 
 void Index::add_in_thread(uint32_t label, rust::Slice<float const> vector, size_t thread) const {
     add_config_t config;
@@ -22,7 +22,8 @@ Matches Index::search_in_thread(rust::Slice<float const> vector, size_t count, s
         results.labels.push_back(0), results.distances.push_back(0);
     search_config_t config;
     config.thread = thread;
-    results.count = index_->search(vector.data(), count, results.labels.data(), results.distances.data(), config);
+    results.count =
+        index_->search(vector.data(), count, config).dump_to(results.labels.data(), results.distances.data());
     results.labels.truncate(results.count);
     results.distances.truncate(results.count);
     return results;
@@ -38,7 +39,7 @@ Matches Index::search(rust::Slice<float const> vector, size_t count) const {
     results.distances.reserve(count);
     for (size_t i = 0; i != count; ++i)
         results.labels.push_back(0), results.distances.push_back(0);
-    results.count = index_->search(vector.data(), count, results.labels.data(), results.distances.data());
+    results.count = index_->search(vector.data(), count).dump_to(results.labels.data(), results.distances.data());
     results.labels.truncate(results.count);
     results.distances.truncate(results.count);
     return results;
@@ -57,31 +58,31 @@ void Index::view(rust::Str path) const { index_->view(std::string(path).c_str())
 
 accuracy_t accuracy(rust::Str quant) { return accuracy_from_name(quant.data(), quant.size()); }
 
-std::unique_ptr<Index> wrap(native_index_t&& index) {
-    std::shared_ptr<native_index_t> native = std::make_shared<native_index_t>(std::move(index));
+std::unique_ptr<Index> wrap(punned_t&& index) {
+    std::shared_ptr<punned_t> native = std::make_shared<punned_t>(std::move(index));
     return std::unique_ptr<Index>(new Index(native));
 }
 
 config_t config(size_t connectivity, size_t exp_add, size_t exp_search) {
     config_t result;
-    result.connectivity = connectivity ? connectivity : config_t::connectivity_default_k;
-    result.expansion_add = exp_add ? exp_add : config_t::expansion_add_default_k;
-    result.expansion_search = exp_search ? exp_search : config_t::expansion_search_default_k;
+    result.connectivity = connectivity ? connectivity : default_connectivity();
+    result.expansion_add = exp_add ? exp_add : default_expansion_add();
+    result.expansion_search = exp_search ? exp_search : default_expansion_search();
     return result;
 }
 
 std::unique_ptr<Index> new_ip(size_t dims, rust::Str quant, size_t connectivity, size_t exp_add, size_t exp_search) {
-    return wrap(native_index_t::ip(dims, accuracy(quant), config(connectivity, exp_add, exp_search)));
+    return wrap(punned_t::ip(dims, accuracy(quant), config(connectivity, exp_add, exp_search)));
 }
 
-std::unique_ptr<Index> new_l2(size_t dims, rust::Str quant, size_t connectivity, size_t exp_add, size_t exp_search) {
-    return wrap(native_index_t::l2(dims, accuracy(quant), config(connectivity, exp_add, exp_search)));
+std::unique_ptr<Index> new_l2sq(size_t dims, rust::Str quant, size_t connectivity, size_t exp_add, size_t exp_search) {
+    return wrap(punned_t::l2sq(dims, accuracy(quant), config(connectivity, exp_add, exp_search)));
 }
 
 std::unique_ptr<Index> new_cos(size_t dims, rust::Str quant, size_t connectivity, size_t exp_add, size_t exp_search) {
-    return wrap(native_index_t::cos(dims, accuracy(quant), config(connectivity, exp_add, exp_search)));
+    return wrap(punned_t::cos(dims, accuracy(quant), config(connectivity, exp_add, exp_search)));
 }
 
 std::unique_ptr<Index> new_haversine(rust::Str quant, size_t connectivity, size_t exp_add, size_t exp_search) {
-    return wrap(native_index_t::haversine(accuracy(quant), config(connectivity, exp_add, exp_search)));
+    return wrap(punned_t::haversine(accuracy(quant), config(connectivity, exp_add, exp_search)));
 }

package/rust/lib.hpp

@@ -3,7 +3,7 @@
 
 #include <memory> // `std::shared_ptr`
 
-#include "advanced.hpp"
+#include "punned.hpp"
 
 struct Matches;
 
@@ -15,9 +15,9 @@ class Index {
   public:
     using label_t = std::uint32_t;
     using distance_t = unum::usearch::punned_distance_t;
-    using native_index_t = unum::usearch::auto_index_gt<label_t>;
+    using punned_t = unum::usearch::punned_gt<label_t>;
 
-    Index(std::shared_ptr<native_index_t> index);
+    Index(std::shared_ptr<punned_t> index);
 
     void reserve(size_t) const;
 
@@ -37,10 +37,10 @@ class Index {
     void view(rust::Str path) const;
 
   private:
-    std::shared_ptr<native_index_t> index_;
+    std::shared_ptr<punned_t> index_;
 };
 
 std::unique_ptr<Index> new_ip(size_t dims, rust::Str quant, size_t connectivity, size_t exp_add, size_t exp_search);
-std::unique_ptr<Index> new_l2(size_t dims, rust::Str quant, size_t connectivity, size_t exp_add, size_t exp_search);
+std::unique_ptr<Index> new_l2sq(size_t dims, rust::Str quant, size_t connectivity, size_t exp_add, size_t exp_search);
 std::unique_ptr<Index> new_cos(size_t dims, rust::Str quant, size_t connectivity, size_t exp_add, size_t exp_search);
 std::unique_ptr<Index> new_haversine(rust::Str quant, size_t connectivity, size_t exp_add, size_t exp_search);

package/rust/lib.rs

@@ -15,7 +15,7 @@ pub mod ffi {
         type Index;
 
         fn new_ip(dimensions: usize, quantization: &str, connectivity: usize, expansion_add: usize, expansion_search: usize) -> Result<UniquePtr<Index>>;
-        fn new_l2(dimensions: usize, quantization: &str, connectivity: usize, expansion_add: usize, expansion_search: usize) -> Result<UniquePtr<Index>>;
+        fn new_l2sq(dimensions: usize, quantization: &str, connectivity: usize, expansion_add: usize, expansion_search: usize) -> Result<UniquePtr<Index>>;
         fn new_cos(dimensions: usize, quantization: &str, connectivity: usize, expansion_add: usize, expansion_search: usize) -> Result<UniquePtr<Index>>;
         fn new_haversine(quantization: &str, connectivity: usize, expansion_add: usize, expansion_search: usize) -> Result<UniquePtr<Index>>;
 
@@ -42,7 +42,7 @@ pub mod ffi {
 #[cfg(test)]
 mod tests {
     use crate::ffi::new_ip;
-    use crate::ffi::new_l2;
+    use crate::ffi::new_l2sq;
     use crate::ffi::new_cos;
     use crate::ffi::new_haversine;
 
@@ -76,7 +76,7 @@ mod tests {
     
         // Make sure every function is called at least once
         assert!(new_ip(5,  &quant, 0, 0, 0).is_ok());
-        assert!(new_l2(5,  &quant, 0, 0, 0).is_ok());
+        assert!(new_l2sq(5,  &quant, 0, 0, 0).is_ok());
         assert!(new_cos(5,  &quant, 0, 0, 0).is_ok());
         assert!(new_haversine(&quant, 0, 0, 0).is_ok());
     }

package/setup.py

@@ -1,5 +1,6 @@
 import os
 import sys
+import platform
 from setuptools import setup
 from pybind11.setup_helpers import Pybind11Extension
 
@@ -10,15 +11,21 @@ link_args = []
 if sys.platform == 'linux':
     compile_args.append('-fopenmp')
     link_args.append('-lgomp')
+    compile_args.append('-Wno-unknown-pragmas')
 
 if sys.platform == 'darwin':
     # 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')
+    compile_args.append('-Wno-unknown-pragmas')
 
 if sys.platform == 'win32':
     compile_args = ['/std:c++14', '/O2']
 
+if platform.machine() == 'arm64':
+    compile_args.append('-march=armv8.2-a+simd+fp16+fp16fml+dotprod')
+elif platform.machine() in ('i386', 'AMD64', 'x86_64'):
+    compile_args.append('-march=haswell')
 
 ext_modules = [
     Pybind11Extension(

package/src/CMakeLists.txt

@@ -0,0 +1,107 @@
+cmake_minimum_required(VERSION 3.1)
+
+option(USEARCH_USE_OPENMP "Use OpenMP for a thread pool" OFF)
+option(USEARCH_USE_SIMSIMD "Use SimSIMD hardware-accelerated metrics" OFF)
+option(USEARCH_USE_JEMALLOC "Use JeMalloc for faster memory allocations" OFF)
+
+# Make "Release" by default
+if(NOT CMAKE_BUILD_TYPE)
+    set(CMAKE_BUILD_TYPE Release)
+endif()
+
+# List of all possible compiler IDs:
+# https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_COMPILER_ID.html
+if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -fsanitize=address")
+    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -Wall -Wextra -Wno-conversion -Wno-unknown-pragmas")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -march=native")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fmax-errors=1")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fopenmp")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -pedantic")
+
+elseif(CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -Wfatal-errors")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fopenmp")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -pedantic")
+
+elseif(CMAKE_CXX_COMPILER_ID STREQUAL "NVIDIA" OR CMAKE_CXX_COMPILER_ID STREQUAL "NVHPC")
+    set(CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} --expt-relaxed-constexpr --extended-lambda")
+    set(CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} -gencode arch=compute_86,code=sm_86")
+    set_property(SOURCE bench.cpp PROPERTY LANGUAGE CUDA)
+    set_target_properties(bench PROPERTIES POSITION_INDEPENDENT_CODE ON)
+    set_target_properties(bench PROPERTIES CUDA_ARCHITECTURES "86")
+
+elseif(CMAKE_CXX_COMPILER_ID STREQUAL "IntelLLVM")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -w")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -ferror-limit=1")
+
+elseif(CMAKE_CXX_COMPILER_ID MATCHES "MSVC")
+    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} /DEBUG")
+    set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} /O2")
+    set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "${CMAKE_CXX_FLAGS_RELWITHDEBINFO} /O2 /DEBUG")
+else()
+    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -g -O0")
+    set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -O3")
+    set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "${CMAKE_CXX_FLAGS_RELWITHDEBINFO} -O3 -pg -g")
+endif()
+
+if(APPLE)
+    set(CMAKE_THREAD_LIBS_INIT "-lpthread")
+    set(CMAKE_HAVE_THREADS_LIBRARY 1)
+    set(CMAKE_USE_WIN32_THREADS_INIT 0)
+    set(CMAKE_USE_PTHREADS_INIT 1)
+    set(THREADS_PREFER_PTHREAD_FLAG ON)
+endif()
+
+find_package(Threads REQUIRED)
+
+if(${USEARCH_USE_OPENMP})
+    find_package(OpenMP REQUIRED)
+    include_directories(${OPENMP_INCLUDE_DIRS})
+endif()
+
+if(${USEARCH_USE_JEMALLOC})
+    include(jemalloc)
+endif()
+
+include(clipp)
+
+set(USEARCH_PUNNED_INCLUDE_DIRS
+    "${CMAKE_CURRENT_SOURCE_DIR}/../include"
+    "${CMAKE_CURRENT_SOURCE_DIR}/../fp16/include"
+    "${CMAKE_CURRENT_SOURCE_DIR}/../simsimd/include"
+    "${CMAKE_CURRENT_SOURCE_DIR}/"
+)
+
+if(${USEARCH_BUILD_TEST})
+    add_executable(test test.cpp)
+    target_link_libraries(test PRIVATE Threads::Threads)
+    target_include_directories(test PRIVATE ${USEARCH_PUNNED_INCLUDE_DIRS})
+    set_target_properties(test PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
+
+    if(${CMAKE_VERSION} VERSION_EQUAL 3.13 OR ${CMAKE_VERSION} VERSION_GREATER 3.13)
+        include(CTest)
+        enable_testing()
+        add_test(NAME test COMMAND test)
+    endif()
+endif()
+
+if(${USEARCH_BUILD_BENCHMARK})
+    add_executable(bench bench.cpp)
+    target_link_libraries(bench PRIVATE Threads::Threads)
+    target_include_directories(bench PRIVATE ${USEARCH_PUNNED_INCLUDE_DIRS})
+    set_target_properties(bench PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
+
+    if(${USEARCH_USE_SIMSIMD})
+        target_compile_definitions(bench PRIVATE USEARCH_USE_SIMSIMD=1)
+    endif()
+
+    if(${USEARCH_USE_OPENMP})
+        target_compile_definitions(bench PRIVATE USEARCH_USE_OPENMP=1)
+        target_link_libraries(bench PRIVATE ${OPENMP_LIBRARIES})
+    endif()
+
+    if(${USEARCH_USE_JEMALLOC})
+        target_link_libraries(bench PRIVATE ${JEMALLOC_LIBRARIES})
+    endif()
+endif()

package/src/bench.cpp

@@ -29,6 +29,7 @@
 #include <iostream>  // `std::cerr`
 #include <numeric>   // `std::iota`
 #include <stdexcept> // `std::invalid_argument`
+#include <string>    // `std::to_string`
 #include <thread>    // `std::thread::hardware_concurrency()`
 #include <variant>   // `std::monostate`
 
@@ -37,7 +38,7 @@
 
 #include <simsimd/simsimd.h>
 
-#include "advanced.hpp"
+#include "punned.hpp"
 
 using namespace unum::usearch;
 using namespace unum;
@@ -227,7 +228,7 @@ struct running_stats_printer_t {
     running_stats_printer_t(std::size_t n, char const* msg) {
         std::printf("%s. %zu items\n", msg, n);
         total = n;
-        start_time = std::chrono::high_resolution_clock::now();
+        last_printed_time = start_time = std::chrono::high_resolution_clock::now();
     }
 
     ~running_stats_printer_t() {
@@ -279,7 +280,8 @@ void index_many(index_at& native, std::size_t n, vector_id_at const* ids, real_a
         add_config_t config;
         config.thread = omp_get_thread_num();
         config.store_vector = true;
-        native.add(ids[i], vector_view_t{vectors + dims * i, dims}, config);
+        vector_view_t vector{vectors + dims * i, dims};
+        native.add(ids[i], vector, config);
         printer.progress++;
         if (omp_get_thread_num() == 0)
             printer.refresh();
@@ -291,16 +293,35 @@ void search_many( //
     index_at& native, std::size_t n, real_at const* vectors, std::size_t dims, std::size_t wanted, vector_id_at* ids,
     real_at* distances) {
 
-    running_stats_printer_t printer{n, "Search"};
+    std::string name = "Search " + std::to_string(wanted);
+    running_stats_printer_t printer{n, name.c_str()};
 
 #pragma omp parallel for schedule(static, 32)
     for (std::size_t i = 0; i < n; ++i) {
         search_config_t config;
         config.thread = omp_get_thread_num();
-        native.search(                                       //
-            vector_view_t{vectors + dims * i, dims}, wanted, //
-            ids + wanted * i, distances + wanted * i,        //
-            config);
+        vector_view_t vector{vectors + dims * i, dims};
+        native.search(vector, wanted, config).dump_to(ids + wanted * i, distances + wanted * i);
+        printer.progress++;
+        if (omp_get_thread_num() == 0)
+            printer.refresh();
+    }
+}
+
+template <typename index_at, typename vector_id_at, typename real_at>
+void paginate_many( //
+    index_at& native, std::size_t n, real_at const* vectors, std::size_t dims, std::size_t wanted,
+    vector_id_at const* hints) {
+
+    std::string name = "Paginate " + std::to_string(wanted);
+    running_stats_printer_t printer{n, name.c_str()};
+
+#pragma omp parallel for schedule(static, 32)
+    for (std::size_t i = 0; i < n; ++i) {
+        search_config_t config;
+        config.thread = omp_get_thread_num();
+        vector_view_t vector{vectors + dims * i, dims};
+        native.search_around(hints[i], vector, wanted, config);
         printer.progress++;
         if (omp_get_thread_num() == 0)
             printer.refresh();
@@ -338,6 +359,15 @@ static void single_shot(dataset_at& dataset, index_at& index, bool construct = t
 
     std::printf("Recall@1 %.2f %%\n", recall_at_1 * 100.f / dataset.queries_count());
     std::printf("Recall %.2f %%\n", recall_full * 100.f / dataset.queries_count());
+
+    // Paginate
+    std::vector<vector_id_t> hints(dataset.queries_count());
+    for (std::size_t i = 0; i != hints.size(); ++i)
+        hints[i] = dataset.neighborhood(i)[0];
+    paginate_many(index, dataset.queries_count(), dataset.query(0), dataset.dimensions(), 10, hints.data());
+    paginate_many(index, dataset.queries_count(), dataset.query(0), dataset.dimensions(), 100, hints.data());
+    paginate_many(index, dataset.queries_count(), dataset.query(0), dataset.dimensions(), 1000, hints.data());
+
     std::printf("------------\n");
     std::printf("\n");
 }
@@ -390,9 +420,9 @@ struct args_t {
     std::string path_neighbors;
     std::string path_output = "last.usearch";
 
-    std::size_t connectivity = config_t::connectivity_default_k;
-    std::size_t expansion_add = config_t::expansion_add_default_k;
-    std::size_t expansion_search = config_t::expansion_search_default_k;
+    std::size_t connectivity = default_connectivity();
+    std::size_t expansion_add = default_expansion_add();
+    std::size_t expansion_search = default_expansion_search();
     std::size_t threads = std::thread::hardware_concurrency();
 
     std::size_t vectors_to_skip = 0;
@@ -415,7 +445,7 @@ 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_l2) {
         std::printf("-- Metric: Euclidean\n");
-        return index_at::l2(dataset.dimensions(), accuracy, config);
+        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);
@@ -486,7 +516,7 @@ void run_big_or_small(dataset_at& dataset, args_t const& args, config_t config)
             run_typed<index_gt<ip_gt<float>, std::size_t, neighbor_id_at>>(dataset, args, config);
         }
     } else
-        run_type_punned<auto_index_gt<std::size_t, neighbor_id_at>>(dataset, args, config);
+        run_type_punned<punned_gt<std::size_t, neighbor_id_at>>(dataset, args, config);
 }
 
 void report_alternative_setups() {
@@ -563,7 +593,7 @@ int main(int argc, char** argv) {
             option("--f8quant").set(args.quantize_f8).doc("Enable `f8_t` quantization")),
         ( //
             option("--ip").set(args.metric_ip).doc("Choose Inner Product metric") |
-            option("--l2").set(args.metric_l2).doc("Choose L2 Euclidean metric") |
+            option("--l2sq").set(args.metric_l2).doc("Choose L2 Euclidean metric") |
             option("--cos").set(args.metric_cos).doc("Choose Angular 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"));
@@ -577,7 +607,7 @@ int main(int argc, char** argv) {
         exit(0);
     }
 
-    // Instead of relying on `multithreaded` from "advanced.hpp" we will use OpenMP
+    // Instead of relying on `multithreaded` from "punned.hpp" we will use OpenMP
     // to better estimate statistics between tasks batches, without having to recreate
     // the threads.
     omp_set_dynamic(true);