usearch 2.6.1 → 2.7.1

package/cpp/CMakeLists.txt

@@ -1,123 +1,14 @@
-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_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -O3")
-    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -g")
-    set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "${CMAKE_CXX_FLAGS_RELWITHDEBINFO} -O3 -g")
-    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -fsanitize=address -fsanitize=leak -fsanitize=alignment -fsanitize=undefined")
-    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} -pedantic")
-    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fdiagnostics-color=always")
-    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -ftime-report")
-
-    if(${USEARCH_USE_OPENMP})
-        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fopenmp")
-    endif()
-
-elseif(CMAKE_CXX_COMPILER_ID MATCHES "Clang")
-    set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -O3")
-    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -g")
-    set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "${CMAKE_CXX_FLAGS_RELWITHDEBINFO} -O3 -g")
-    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -fsanitize=address -fsanitize=leak -fsanitize=alignment -fsanitize=undefined")
-    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -Wfatal-errors")
-    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -pedantic")
-    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fcolor-diagnostics")
-    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -ftime-trace")
-
-    if(${USEARCH_USE_OPENMP})
-        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fopenmp")
-    endif()
-
-elseif(CMAKE_CXX_COMPILER_ID STREQUAL "NVIDIA" OR CMAKE_CXX_COMPILER_ID STREQUAL "NVHPC")
-    set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -O3")
-    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")
-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})
-    set_target_properties(test PROPERTIES CXX_STANDARD 17)
-
-    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})
-    set_target_properties(bench PROPERTIES CXX_STANDARD 17)
-
-    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()
+if (USEARCH_BUILD_TEST_CPP)
+    add_executable(test_cpp test.cpp)
+    setup_target(test_cpp)
+    include(CTest)
+    enable_testing()
+    add_test(NAME test_cpp COMMAND test_cpp)
+endif ()
+
+if (USEARCH_BUILD_BENCH_CPP)
+    include(clipp)
+    add_executable(bench_cpp bench.cpp)
+    setup_target(bench_cpp)
+    target_include_directories(bench_cpp PRIVATE ${clipp_SOURCE_DIR}/include)
+endif ()

package/cpp/bench.cpp

@@ -135,18 +135,6 @@ struct alignas(32) persisted_matrix_gt {
     std::size_t size_bytes() const noexcept { return rows * row_size_bytes(); }
 };
 
-template <typename scalar_at> //
-struct vectors_view_gt {
-    using scalar_t = scalar_at;
-
-    scalar_t const* begin_{};
-    std::size_t count_{};
-    std::size_t stride_{};
-
-    std::size_t size() const noexcept { return count_; }
-    scalar_t const* at(std::size_t i) const noexcept { return begin_ + i * stride_; }
-};
-
 template <typename scalar_at, typename vector_id_at> //
 struct persisted_dataset_gt {
     using scalar_t = scalar_at;

package/cpp/test.cpp

@@ -1,9 +1,12 @@
 /**
  * @brief A trivial test.
  */
-#include <algorithm>
+#include <algorithm> // `std::shuffle`
+#include <cassert>   // `assert`
+#include <random>    // `std::default_random_engine`
 #include <stdexcept>
 #include <unordered_map>
+#include <vector> // for std::vector
 
 #include <usearch/index.hpp>
 #include <usearch/index_dense.hpp>
@@ -234,6 +237,26 @@ template <typename key_at, typename slot_at> void test_tanimoto(std::size_t dime
     });
 }
 
+void test_exact_search(std::size_t dataset_count, std::size_t queries_count, std::size_t wanted_count) {
+    std::size_t dimensions = 10;
+    metric_punned_t metric(dimensions, metric_kind_t::cos_k);
+
+    std::random_device rd;
+    std::mt19937 gen(rd());
+    std::uniform_real_distribution<> dis(0.0, 1.0);
+    std::vector<float> dataset(dataset_count * dimensions);
+    std::generate(dataset.begin(), dataset.end(), [&] { return dis(gen); });
+
+    exact_search_t search;
+    auto results = search(                                                        //
+        (byte_t const*)dataset.data(), dataset_count, dimensions * sizeof(float), //
+        (byte_t const*)dataset.data(), queries_count, dimensions * sizeof(float), //
+        wanted_count, metric);
+
+    for (std::size_t i = 0; i < results.size(); ++i)
+        assert(results.at(i)[0].offset == i); // Validate the top match
+}
+
 template <typename index_at> void test_sets(index_at&& index) {
 
     using index_t = typename std::remove_reference<index_at>::type;
@@ -272,6 +295,11 @@ template <typename index_at> void test_sets_moved(index_config_t const& config)
 
 int main(int, char**) {
 
+    for (std::size_t dataset_count : {10, 100})
+        for (std::size_t queries_count : {1, 10})
+            for (std::size_t wanted_count : {1, 5})
+                test_exact_search(dataset_count, queries_count, wanted_count);
+
     for (std::size_t collection_size : {10, 500})
         for (std::size_t dimensions : {97, 256}) {
             std::printf("Indexing %zu vectors with cos: <float, std::int64_t, std::uint32_t> \n", collection_size);

package/csharp/nuget/nuget-package.props

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

package/docs/compilation.md

@@ -13,15 +13,16 @@ Linux:
 
 ```sh
 sudo apt-get update
-sudo apt-get install cmake g++-12 build-essential libjemalloc-dev
+sudo apt-get install cmake build-essential libjemalloc-dev
 cmake -B ./build_release \
-    -DCMAKE_CXX_COMPILER="g++-12" \
     -DCMAKE_BUILD_TYPE=Release \
-    -DUSEARCH_BUILD_TEST=1 \
     -DUSEARCH_USE_OPENMP=1 \
     -DUSEARCH_USE_SIMSIMD=1 \
     -DUSEARCH_USE_JEMALLOC=1 \
-    -DUSEARCH_BUILD_BENCHMARK=1 \
+    -DUSEARCH_BUILD_TEST_CPP=1 \
+    -DUSEARCH_BUILD_BENCH_CPP=1 \
+    -DUSEARCH_BUILD_LIB_C=1 \
+    -DUSEARCH_BUILD_TEST_C=1 \
     && \
     make -C ./build_release -j
 ```
@@ -35,8 +36,8 @@ cmake -B ./build_release \
     -DCMAKE_CXX_COMPILER="/opt/homebrew/opt/llvm/bin/clang++" \
     -DUSEARCH_USE_OPENMP=1 \
     -DUSEARCH_USE_SIMSIMD=1 \
-    -DUSEARCH_BUILD_BENCHMARK=1 \
-    -DUSEARCH_BUILD_TEST=1 \
+    -DUSEARCH_BUILD_BENCH_CPP=1 \
+    -DUSEARCH_BUILD_TEST_CPP=1 \
     && \
     make -C ./build_release -j
 ```
@@ -53,7 +54,9 @@ cppcheck --enable=all --force --suppress=cstyleCast --suppress=unusedFunction \
 Testing:
 
 ```sh
-cmake -DCMAKE_BUILD_TYPE=Debug -B ./build_debug && make -C ./build_debug && ./build_debug/test
+cmake -DUSEARCH_BUILD_TEST_CPP=1 -B ./build_debug
+cmake --build ./build_debug --config Debug
+./build_debug/test_cpp
 ```
 
 ## Python 3
@@ -85,7 +88,7 @@ cibuildwheel --platform linux
 Node.JS:
 
 ```sh
-npm install && node javascript/test.js
+npm install && node --test ./javascript/usearch.test.js
 npm publish
 ```
 
@@ -93,7 +96,7 @@ WebAssembly:
 
 ```sh
 emcmake cmake -B ./build -DCMAKE_CXX_FLAGS="${CMAKE_CXX_FLAGS} -s TOTAL_MEMORY=64MB" && emmake make -C ./build
-node ./build/test.js
+node ./build/usearch.test.js
 ```
 
 If you don't yet have `emcmake` installed:
@@ -124,7 +127,7 @@ 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
+g++ -shared -fPIC -o libusearch_c.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
@@ -152,22 +155,26 @@ swift test -v
 ## C 99
 
 There are a few ways to compile the C 99 USearch SDK.
-Using the Makefile:
+Using the Makefile, specifying the targets you need:
 
 ```sh
 make -C ./c libusearch_c.so
 ```
 
-Using CMake:
+With options:
 
 ```sh
-cmake -B ./build_release -DUSEARCH_BUILD_CLIB=1 && make -C ./build_release -j
+make USEARCH_USE_OPENMP=1 USEARCH_USE_SIMSIMD=1 -C ./c libusearch_c.so
 ```
 
-Linux:
+Using CMake:
 
 ```sh
-g++ -std=c++11 -shared -fPIC c/lib.cpp -I ./include/  -I ./fp16/include/ -o libusearch_c.so
+cmake -B ./build_release -DUSEARCH_BUILD_LIB_C=1 -DUSEARCH_BUILD_TEST_C=1 -DUSEARCH_USE_OPENMP=1 -DUSEARCH_USE_SIMSIMD=1 
+cmake --build ./build_release --config Release -j
+./build_release/test_c
+# On Windows:
+.\build_release\test_c.exe
 ```
 
 
@@ -177,7 +184,7 @@ GoLang bindings are based on C.
 So one should first compile the C library, link it with GoLang, and only then run tests.
 
 ```sh
-make -C ./c libusearch_c.so && mv ./c/libusearch_c.so ./golang/libusearch_c.so 
+make -C ./c libusearch_c.so && mv ./c/libusearch_c.so ./golang/ && cp ./c/usearch.h ./golang/
 cd golang && go test -v ; cd ..
 ```
 

package/docs/conf.py

@@ -50,4 +50,4 @@ html_baseurl = "/docs/usearch/"
 breathe_projects = {"USearch": "../build/xml"}
 breathe_default_project = "USearch"
 
-js_source_path = "../javascript/docs.js"
+js_source_path = "../javascript/usearch.js"

package/golang/README.md

@@ -7,7 +7,7 @@
 Download and install from the Debian package from the latest release.
 Substitute `<release_tag>`, `<arch>`, and `<usearch_version>` with your settings.
 
-```
+```sh
 wget https://github.com/unum-cloud/usearch/releases/download/<release_tag>/usearch_linux_<arch>_<usearch_version>.deb
 dpkg -i usearch_<arch>_<usearch_version>.deb
 ```
@@ -17,7 +17,7 @@ dpkg -i usearch_<arch>_<usearch_version>.deb
 Run a `winlibinstaller.bat` script from the main repository in the folder where you will run `go run`.
 That will install the USearch library and include in the same folder` where the script was run.
 
-```
+```sh
 .\usearch\winlibinstaller.bat
 ```
 
@@ -25,10 +25,11 @@ That will install the USearch library and include in the same folder` where the
 
 Download and unpack a zip archive from the latest release.
 Move the USearch library and the include file to their respective folders.
-```
+
+```sh
 wget https://github.com/unum-cloud/usearch/releases/download/<release_tag>/usearch_macOS_<arch>_<usearch_version>.zip
 unzip usearch_macOS_<arch>_<usearch_version>.zip
-sudo mv libusearch.so /usr/local/lib && sudo mv usearch.h /usr/local/include
+sudo mv libusearch_c.so /usr/local/lib && sudo mv usearch.h /usr/local/include
 
 ```
 
@@ -36,60 +37,60 @@ sudo mv libusearch.so /usr/local/lib && sudo mv usearch.h /usr/local/include
 
 1. Create a `go.mod` file:
 
-	```
-	module usearch_example
+```
+module usearch_example
 
-	go <go_version>
-	```
+go <go_version>
+```
 
 2. Create an `example.go`:
 
-	```golang
-	package main
-
-	import (
-		"fmt"
-		usearch "github.com/unum-cloud/usearch/golang"
-	)
-
-	func main() {
-
-		// Create Index
-		vector_size := 3
-		vectors_count := 100
-		conf := usearch.DefaultConfig(uint(vector_size))
-		index,err := usearch.NewIndex(conf)
-		if err != nil {
-			panic("Failed to create Index")
-		}
-		defer index.Destroy()
-		
-		// Add to Index
-		err = index.Reserve(uint(vectors_count))
-		for i := 0; i < vectors_count; i++ {
-			err = index.Add(usearch.Key(i), []float32{float32(i), float32(i+1), float32(i+2)})
-			if err != nil {
-				panic("Failed to add")
-			}
-		}
-
-		// Search
-		keys, distances, err := index.Search([]float32{0.0, 1.0, 2.0}, 3)
-		if err != nil {
-			panic("Failed to search")
-		}
-		fmt.Println(keys, distances)
-	}
-	```
+```golang
+package main
+
+import (
+"fmt"
+usearch "github.com/unum-cloud/usearch/golang"
+)
+
+func main() {
+
+   	// Create Index
+   	vector_size := 3
+   	vectors_count := 100
+   	conf := usearch.DefaultConfig(uint(vector_size))
+   	index,err := usearch.NewIndex(conf)
+   	if err != nil {
+   		panic("Failed to create Index")
+   	}
+   	defer index.Destroy()
+
+   	// Add to Index
+   	err = index.Reserve(uint(vectors_count))
+   	for i := 0; i < vectors_count; i++ {
+   		err = index.Add(usearch.Key(i), []float32{float32(i), float32(i+1), float32(i+2)})
+      	if err != nil {
+      		panic("Failed to add")
+      	}
+   	}
+
+   	// Search
+   	keys, distances, err := index.Search([]float32{0.0, 1.0, 2.0}, 3)
+   	if err != nil {
+    	panic("Failed to search")
+   	}
+   	fmt.Println(keys, distances)
+}
+```
 
 3. Get USearch:
 
-	```
-	go get github.com/unum-cloud/usearch/golang
-	```
+```sh
+go get github.com/unum-cloud/usearch/golang
+```
 
 4. Run:
 
-	```
-	go run example.go
-	```
+```sh
+go run example.go
+```

package/golang/lib.go

@@ -6,7 +6,7 @@ import (
 )
 
 /*
-#cgo LDFLAGS: -L. -lusearch
+#cgo LDFLAGS: -L. -lusearch_c
 #include "usearch.h"
 #include <stdlib.h>
 */

package/golang/lib_test.go

@@ -3,6 +3,7 @@ package usearch
 import (
 	"runtime"
 	"testing"
+	"math"
 )
 
 func TestUSearch(t *testing.T) {
@@ -98,7 +99,9 @@ func TestUSearch(t *testing.T) {
 		if err != nil {
 			t.Fatalf("Failed to search: %s", err)
 		}
-		if keys[0] != 42 || distances[0] != 0.0 {
+
+		const tolerance = 1e-2  // For example, this sets the tolerance to 0.01
+		if keys[0] != 42 || math.Abs(float64(distances[0])) > tolerance {
 			t.Fatalf("Expected result 42 with distance 0, got key %d with distance %f", keys[0], distances[0])
 		}
 	})

package/include/usearch/index.hpp

@@ -10,7 +10,7 @@
 #define UNUM_USEARCH_HPP
 
 #define USEARCH_VERSION_MAJOR 2
-#define USEARCH_VERSION_MINOR 6
+#define USEARCH_VERSION_MINOR 7
 #define USEARCH_VERSION_PATCH 1
 
 // Inferring C++ version
@@ -268,7 +268,7 @@ template <typename scalar_at> class span_gt {
  *  @brief  Similar to `std::vector`, but doesn't support dynamic resizing.
  *          On the bright side, this can't throw exceptions.
  */
-template <typename scalar_at, typename allocator_at> class buffer_gt {
+template <typename scalar_at, typename allocator_at = std::allocator<scalar_at>> class buffer_gt {
     scalar_at* data_;
     std::size_t size_;