usearch 0.2.4 → 0.8.0

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,12 +38,13 @@
 
 #include <simsimd/simsimd.h>
 
-#include "advanced.hpp"
+#include "punned.hpp"
 
 using namespace unum::usearch;
 using namespace unum;
 
 using vector_id_t = std::uint32_t;
+using vector_view_t = span_gt<float const>;
 
 template <typename element_at>
 std::size_t offset_of(element_at const* begin, element_at const* end, element_at v) noexcept {
@@ -226,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() {
@@ -271,12 +273,15 @@ struct running_stats_printer_t {
 template <typename index_at, typename vector_id_at, typename real_at>
 void index_many(index_at& native, std::size_t n, vector_id_at const* ids, real_at const* vectors, std::size_t dims) {
 
-    using span_t = span_gt<float const>;
     running_stats_printer_t printer{n, "Indexing"};
 
 #pragma omp parallel for schedule(static, 32)
     for (std::size_t i = 0; i < n; ++i) {
-        native.add(ids[i], span_t{vectors + dims * i, dims}, omp_get_thread_num(), true);
+        add_config_t config;
+        config.thread = omp_get_thread_num();
+        config.store_vector = true;
+        vector_view_t vector{vectors + dims * i, dims};
+        native.add(ids[i], vector, config);
         printer.progress++;
         if (omp_get_thread_num() == 0)
             printer.refresh();
@@ -284,18 +289,39 @@ void index_many(index_at& native, std::size_t n, vector_id_at const* ids, real_a
 }
 
 template <typename index_at, typename vector_id_at, typename real_at>
-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) {
+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) {
 
-    using span_t = span_gt<float const>;
-    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) {
-        native.search(                                //
-            span_t{vectors + dims * i, dims}, wanted, //
-            ids + wanted * i, distances + wanted * i, //
-            omp_get_thread_num());
+        search_config_t config;
+        config.thread = omp_get_thread_num();
+        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();
@@ -333,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");
 }
@@ -385,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;
@@ -410,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);
@@ -481,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() {
@@ -558,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"));
@@ -572,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);