usearch 0.19.3 → 0.21.0

package/.github/workflows/prerelease.yml

@@ -17,6 +17,33 @@ permissions:
 
 jobs:
 
+  build_test:
+    name: Test USearch
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        ref: main-dev
+    - run: git submodule update --init --recursive
+    - name: Prepare Environment
+      run: |
+        sudo apt update && 
+        sudo apt install -y cmake g++-12 build-essential libjemalloc-dev
+    - name: Build
+      run: |
+        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=0 &&
+        make -C ./build_release -j
+    - name: Run tests
+      run: ./build_release/test
+      
+      
   test_python_311:
     name: Test Python
     runs-on: ${{ matrix.os }}

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "usearch"
-version = "0.19.3"
+version = "0.21.0"
 authors = ["Ashot Vardanian <1983160+ashvardanian@users.noreply.github.com>"]
 description = "Smaller & Faster Single-File Vector Search Engine from Unum"
 edition = "2021"

package/README.md

@@ -167,7 +167,7 @@ index.add(/* label: */ 42, /* vector: */ {&vec[0], 3});
 auto results = index.search(/* query: */ {&vec[0], 3}, 5 /* neighbors */);
 
 for (std::size_t i = 0; i != results.size(); ++i)
-    results[i].element.label, results[i].element.vector, results[i].distance;
+    results[i].member.label, results[i].member.vector, results[i].member.id, results[i].distance;
 ```
 
 The `add` is thread-safe for concurrent index construction.
@@ -759,9 +759,28 @@ index = Index(ndim=2048, metric=MetricKind.BitwiseTanimoto)
 labels = np.arange(len(molecules))
 
 index.add(labels, fingerprints)
-matches = index.search(fingerprints, 10)
+matches: Matches = index.search(fingerprints, 10)
 ```
 
+Of if you need a bit of our SIMD superpowers - take some Chemsitry-oriented precompiled metrics from [SimSIMD][simsimd].
+
+```python
+import simsimd as sisi
+
+index = Index(
+    ndim=166, # MACCS fingerprints are 166-dimensional
+    metric=CompiledMetric(
+        pointer=sisi.to_int(sisi.tanimoto_maccs_neon), # For Arm Neon
+        signature=MetricSignature.ArrayArray,
+        kind=MetricKind.Tanimoto,
+    ),
+)
+
+index.add(42, np.packbits([1] * 166))
+matches: Matches = index.search(np.packbits([1] * 166))
+```
+
+[simsimd]: https://github.com/ashvardanian/simsimd
 [smiles]: https://en.wikipedia.org/wiki/Simplified_molecular-input_line-entry_system
 [rdkit-fingerprints]: https://www.rdkit.org/docs/RDKit_Book.html#additional-information-about-the-fingerprints
 

package/c/test.c

@@ -1,182 +1,294 @@
-#include <assert.h>
+#include <stdio.h>
 #include <errno.h>
 #include <stdio.h>
 #include <stdlib.h>
-#include <string.h>
 #include <sys/stat.h>
-#include <time.h>
 
 #include "usearch.h"
 
-float* read_fvecs_file(const char* filename, size_t* num_vectors, size_t* vector_dim) {
-    struct stat st;
-    FILE* file;
-    size_t cnt;
-    float skip;
-
-    ;
-    if (stat(filename, &st) == -1) {
-        printf("Failed to read file: %s err: %d: %s\n", filename, errno, strerror(errno));
-        return NULL;
+#define ASSERT(must_be_true, message)           \
+    if (!(must_be_true)) {                      \
+        printf("Assert: %s\n", message);        \
+        exit(-1);                               \
     }
 
-    file = fopen(filename, "rb");
-    if (file == NULL) {
-        printf("Failed to open file: %s\n", filename);
-        return NULL;
-    }
 
-    // Read the number of vectors and vector dimension from the file
-    cnt = fread(vector_dim, sizeof(int), 1, file);
-    assert(cnt == 1);
-    if (st.st_size % ((*vector_dim + 1) * sizeof(float)) != 0) {
-        printf("File does not contain a whole number of vectors.\n Vector dim: %ld, file size: %ld\n", *vector_dim,
-               st.st_size);
-        fclose(file);
-        return NULL;
-    }
+void parse_vectors_from_file(char const* file_path, size_t* count, size_t* dimension, float** data) {
 
-    *num_vectors = st.st_size / ((*vector_dim + 1) * sizeof(float));
+    // Open the file
+    struct stat st = {};
+    ASSERT(stat(file_path, &st) == 0, "Failed to get metadata of the file");
+    FILE* file = fopen(file_path, "rb");
+    ASSERT(file, "Failed to open the file");
 
-    // Allocate memory for the array
-    float* data = (float*)malloc(*num_vectors * *vector_dim * sizeof(float));
-    if (data == NULL) {
-        printf("Memory allocation failed.\n");
-        fclose(file);
-        return NULL;
-    }
+    // Read vectors dimension and calculate count
+    int dim = 0;
+    size_t read = fread(&dim, sizeof(int), 1, file);
+    ASSERT(read == 1, "Failed to read from the file");
+    ASSERT(st.st_size % ((dim + 1) * sizeof(float)) == 0, "File does not contain a whole number of vectors");
+    *dimension = (size_t)dim;
+    *count = st.st_size / ((dim + 1) * sizeof(float));
 
-    // Read the data from the file into the array
-    for (size_t i = 0; i < *num_vectors; i++) {
-        cnt = fread(data + i * *vector_dim, sizeof(float), *vector_dim, file);
-        assert(cnt == *vector_dim);
-        if (i == *num_vectors - 1) {
+    // Allocate memory for the vectors' data
+    *data = (float*)malloc(*count * *dimension * sizeof(float));
+    ASSERT(*data, "Failed to allocate memory");
+
+    // Read the data
+    for (size_t i = 0; i < *count; ++i) {
+        read = fread(*data + i * *dimension, sizeof(float), *dimension, file);
+        ASSERT(read == *dimension, "Failed to read from the file");
+         if (i == *count - 1)
             break;
-        }
-        cnt = fread(&skip, sizeof(float), 1, file);
-        assert(cnt == 1);
+
+        // Skip
+        float skip;
+        read = fread(&skip, sizeof(float), 1, file);
+        ASSERT(read == 1, "Failed to read from the file");
     }
 
     fclose(file);
-    return data;
 }
 
-// log every this many iterations in test loops
-const int LOG_GRANULARITY = 10000;
-
-void test_index(float* data, size_t num_vectors, size_t vector_dim) {
+usearch_init_options_t create_options(size_t vector_dimension) {
     usearch_init_options_t opts;
-    usearch_index_t idx;
-    usearch_error_t error = NULL;
-    clock_t start;
     opts.connectivity = 2; // 32 in faiss
-    opts.dimensions = vector_dim;
+    opts.dimensions = vector_dimension;
     opts.expansion_add = 40;    // 40 in faiss
     opts.expansion_search = 16; // 10 in faiss
     opts.metric_kind = usearch_metric_ip_k;
     opts.metric = NULL;
     opts.quantization = usearch_scalar_f32_k;
+    return opts;
+}
+
+void test_init(size_t vectors_count, size_t vector_dimension) {
+    printf("Test: Index Initialization...\n");
+
+    // Init index
+    usearch_index_t idx = NULL;
+    usearch_error_t error = NULL;
+    usearch_init_options_t opts = create_options(vector_dimension);
+    idx = usearch_init(&opts, &error);
+    ASSERT(!error, error);
+    usearch_free(idx, &error);
+    ASSERT(!error, error);
+
+    // Init second time
+    idx = usearch_init(&opts, &error);
+    ASSERT(!error, error);
+
+    ASSERT(usearch_size(idx, &error) == 0, error);
+    ASSERT(usearch_capacity(idx, &error) == 0, error);
+    ASSERT(usearch_dimensions(idx, &error) == vector_dimension, error);
+    ASSERT(usearch_connectivity(idx, &error) == opts.connectivity, error);
+
+    // Reserve
+    usearch_reserve(idx, vectors_count, &error);
+    ASSERT(!error, error);
+    ASSERT(usearch_size(idx, &error) == 0, error);
+    ASSERT(usearch_capacity(idx, &error) == vectors_count, error);
+    ASSERT(usearch_dimensions(idx, &error) == vector_dimension, error);
+    ASSERT(usearch_connectivity(idx, &error) == opts.connectivity, error);
+
+    usearch_free(idx, &error);
+    ASSERT(!error, error);
+
+    printf("Test: Index Initialization - PASSED\n");
+}
 
-    // results arrays
-    int k = 10;
-    num_vectors /= 10;
-    usearch_label_t* labels = (usearch_label_t*)calloc(k, sizeof(usearch_label_t));
-    float* distances = (float*)calloc(k, sizeof(float));
+void test_add_vector(size_t vectors_count, size_t vector_dimension, float const* data) {
+    printf("Test: Add Vector...\n");
 
-    fprintf(stderr, "read %ld vectors of dimension %ld\n", num_vectors, vector_dim);
-    fprintf(stderr, "initializing usearch...\n");
+    usearch_index_t idx = NULL;
+    usearch_error_t error = NULL;
+    usearch_init_options_t opts = create_options(vector_dimension);
     idx = usearch_init(&opts, &error);
-    if (error != NULL) {
-        fprintf(stderr, "usearch error: %s\n", error);
-        assert(false);
+    usearch_reserve(idx, vectors_count, &error);
+
+    // Add vectors
+    for (size_t i = 0; i < vectors_count; ++i) {
+        usearch_label_t label = i;
+        usearch_add(idx, label, data + i * vector_dimension, usearch_scalar_f32_k, &error);
+        ASSERT(!error, error);
     }
 
-    fprintf(stderr, "reserving capacity...\n");
-    usearch_reserve(idx, num_vectors, &error);
-    assert(!error);
+    ASSERT(usearch_size(idx, &error) == vectors_count, error);
+    ASSERT(usearch_capacity(idx, &error) == vectors_count, error);
 
-    fprintf(stderr, "adding vectors...\n");
-    for (size_t i = 0; i < num_vectors; i++) {
-        if (i % LOG_GRANULARITY == 0) {
-            fprintf(stderr, "added %ld vectors...\n", i);
-        }
+    // Check vectors in the index
+    for (size_t i = 0; i < vectors_count; ++i) {
         usearch_label_t label = i;
-        usearch_add(idx, label, data + i * vector_dim, usearch_scalar_f32_k, &error);
-        assert(!error);
+        ASSERT(usearch_contains(idx, label, &error), error);
     }
+    ASSERT(!usearch_contains(idx, -1, &error), error); // Non existing label
+
+    usearch_free(idx, &error);
+    printf("Test: Add Vector - PASSED\n");
+}
+
+void test_find_vector(size_t vectors_count, size_t vector_dimension, float const* data) {
+    printf("Test: Find Vector...\n");
 
-    fprintf(stderr, "checking containment of vectors...\n");
-    for (size_t i = 0; i < num_vectors; i++) {
-        if (i % LOG_GRANULARITY == 0) {
-            fprintf(stderr, "checked %ld vectors...\n", i);
-        }
+    usearch_index_t idx = NULL;
+    usearch_error_t error = NULL;
+    usearch_init_options_t opts = create_options(vector_dimension);
+    idx = usearch_init(&opts, &error);
+    usearch_reserve(idx, vectors_count, &error);
+
+    // Create result buffers
+    int results_count = 10;
+    usearch_label_t* labels = (usearch_label_t*)malloc(results_count * sizeof(usearch_label_t));
+    float* distances = (float*)malloc(results_count * sizeof(float));
+    ASSERT(labels && distances, "Failed to allocate memory");
+
+    // Add vectors
+    for (size_t i = 0; i < vectors_count; ++i) {
         usearch_label_t label = i;
-        assert(usearch_contains(idx, label, &error));
-        assert(!error);
+        usearch_add(idx, label, data + i * vector_dimension, usearch_scalar_f32_k, &error);
+        ASSERT(!error, error);
     }
 
-    assert(!usearch_contains(idx, -1, &error));
-    assert(!error);
-
-    fprintf(stderr, "searching vectors...\n");
-    for (size_t i = 0; i < num_vectors; i++) {
-        if (i % LOG_GRANULARITY == 0) {
-            fprintf(stderr, "searched %ld vectors...\n", i);
-        }
-        const void *query_vector = data + i * vector_dim;
-        usearch_search(idx, query_vector, usearch_scalar_f32_k, k, labels, distances, &error);
-        assert(!error);
+    // Find the vectors
+    for (size_t i = 0; i < vectors_count; i++) {
+        const void *query_vector = data + i * vector_dimension;
+        size_t found_count = usearch_search(idx, query_vector, usearch_scalar_f32_k, results_count, labels, distances, &error);
+        ASSERT(!error, error);
+        ASSERT(found_count = results_count, "Vector is missing");
     }
 
-    fprintf(stderr, "saving the index...\n");
-    start = clock();
-    usearch_save(idx, "usearch_index.bin", &error);
-    assert(!error);
-    fprintf(stderr, "saving took %.2f ms\n", ((double)(clock() - start)) / CLOCKS_PER_SEC * 1000);
+    usearch_free(idx, &error);
+    printf("Test: Find Vector - PASSED\n");
+}
+
+void test_remove_vector(size_t vectors_count, size_t vector_dimension, float const* data) {
+    printf("Test: Remove Vector...\n");
+
+    usearch_index_t idx = NULL;
+    usearch_error_t error = NULL;
+    usearch_init_options_t opts = create_options(vector_dimension);
+    idx = usearch_init(&opts, &error);
+    usearch_reserve(idx, vectors_count, &error);
+
+    // Add vectors
+    for (size_t i = 0; i < vectors_count; ++i) {
+        usearch_label_t label = i;
+        usearch_add(idx, label, data + i * vector_dimension, usearch_scalar_f32_k, &error);
+        ASSERT(!error, error);
+    }
+
+    // Remove the vectors
+    for (size_t i = 0; i < vectors_count; i++) {
+        usearch_label_t label = i;
+        usearch_remove(idx, label, &error);
+        ASSERT(error, "Currently, Remove is not supported");
+    }
+
+    usearch_free(idx, &error);
+    printf("Test: Remove Vector - PASSED\n");
+}
 
-    fprintf(stderr, "destroying the index...\n");
-    start = clock();
+void test_save_load(size_t vectors_count, size_t vector_dimension, float const* data) {
+    printf("Test: Save/Load...\n");
+
+    usearch_index_t idx = NULL;
+    usearch_error_t error = NULL;
+    usearch_init_options_t opts = create_options(vector_dimension);
+    idx = usearch_init(&opts, &error);
+    usearch_reserve(idx, vectors_count, &error);
+
+    // Add vectors
+    for (size_t i = 0; i < vectors_count; ++i) {
+        usearch_label_t label = i;
+        usearch_add(idx, label, data + i * vector_dimension, usearch_scalar_f32_k, &error);
+        ASSERT(!error, error);
+    }
+
+    // Save and free the index
+    usearch_save(idx, "usearch_index.bin", &error);
+    ASSERT(!error, error);
     usearch_free(idx, &error);
-    assert(!error);
-    fprintf(stderr, "destroying the index took %.2f ms\n", ((double)(clock() - start)) / CLOCKS_PER_SEC * 1000);
+    ASSERT(!error, error);
 
-    fprintf(stderr, "loading the index...\n");
-    start = clock();
+    // Reinit
     idx = usearch_init(&opts, &error);
-    assert(!error);
-    assert(usearch_size(idx, &error) == 0);
-    assert(!error);
+    ASSERT(!error, error);
+    ASSERT(usearch_size(idx, &error) == 0, error);
+
+    // Load
     usearch_load(idx, "usearch_index.bin", &error);
-    assert(!error);
-    fprintf(stderr, "loading the index took %.2f ms\n", ((double)(clock() - start)) / CLOCKS_PER_SEC * 1000);
-    assert(usearch_size(idx, &error) == num_vectors);
-    assert(!error);
+    ASSERT(!error, error);
+    ASSERT(usearch_size(idx, &error) == vectors_count, error);
+    ASSERT(usearch_capacity(idx, &error) == vectors_count, error);
+    ASSERT(usearch_dimensions(idx, &error) == vector_dimension, error);
+    ASSERT(usearch_connectivity(idx, &error) == opts.connectivity, error);
+
+    // Check vectors in the index
+    for (size_t i = 0; i < vectors_count; ++i) {
+        usearch_label_t label = i;
+        ASSERT(usearch_contains(idx, label, &error), error);
+    }
+
     usearch_free(idx, &error);
+    printf("Test: Save/Load - PASSED\n");
+}
+
+void test_view(size_t vectors_count, size_t vector_dimension, float const* data) {
+    printf("Test: View...\n");
 
-    fprintf(stderr, "viewing the index...\n");
-    start = clock();
+    usearch_index_t idx = NULL;
+    usearch_error_t error = NULL;
+    usearch_init_options_t opts = create_options(vector_dimension);
     idx = usearch_init(&opts, &error);
-    assert(!error);
-    assert(usearch_size(idx, &error) == 0);
-    assert(!error);
-    usearch_view(idx, "usearch_index.bin", &error);
-    assert(!error);
-    fprintf(stderr, "viewing the index took %.2f ms\n", ((double)(clock() - start)) / CLOCKS_PER_SEC * 1000);
-    assert(usearch_size(idx, &error) == num_vectors);
-    assert(!error);
+    usearch_reserve(idx, vectors_count, &error);
+
+    // Add vectors
+    for (size_t i = 0; i < vectors_count; ++i) {
+        usearch_label_t label = i;
+        usearch_add(idx, label, data + i * vector_dimension, usearch_scalar_f32_k, &error);
+        ASSERT(!error, error);
+    }
+
+    // Save and free the index
+    usearch_save(idx, "usearch_index.bin", &error);
+    ASSERT(!error, error);
     usearch_free(idx, &error);
+    ASSERT(!error, error);
+
+    // Reinit
+    idx = usearch_init(&opts, &error);
+    ASSERT(!error, error);
+
+    // View
+    usearch_view(idx, "usearch_index.bin", &error);
+    ASSERT(!error, error);
 
+    usearch_free(idx, &error);
+    printf("Test: View - PASSED\n");
 }
 
-int main() {
-    const char* filename = "sift/sift_base.fvecs";
-    size_t num_vectors = 0, vector_dim = 0;
-    float* data = read_fvecs_file(filename, &num_vectors, &vector_dim);
-    if (data != NULL) {
+int main(int argc, char* argv[]) {
+    // Resolve file path
+    char const* filename = "sample.fvecs";
+    if (argc == 2)
+        filename = argv[1];
 
-        test_index(data, num_vectors, vector_dim);
+    // Read data from the file
+    float* data = NULL;
+    size_t vectors_count = 0;
+    size_t vector_dimension = 0;
+    parse_vectors_from_file(filename, &vectors_count, &vector_dimension, &data);
+    vectors_count = vectors_count > 100000 ? 100000 : vectors_count; // Just limit vectors
+
+    // Test
+    test_init(vectors_count, vector_dimension);
+    test_add_vector(vectors_count, vector_dimension, data);
+    test_find_vector(vectors_count, vector_dimension, data);
+    test_remove_vector(vectors_count, vector_dimension, data);
+    test_save_load(vectors_count, vector_dimension, data);
+    test_view(vectors_count, vector_dimension, data);
+
+    // Free vectors' buffer
+    free(data);
 
-        free(data); // Remember to free the dynamically allocated memory
-    }
     return 0;
 }

package/conanfile.py

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

package/cpp/CMakeLists.txt

@@ -13,7 +13,9 @@ endif()
 # 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} -fsanitize=address")
+    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")
@@ -22,7 +24,9 @@ if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
 
 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} -fsanitize=address")
+    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} -fopenmp")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -pedantic")

package/cpp/bench.cpp

@@ -24,6 +24,7 @@
 
 #include <sys/stat.h> // `stat`
 
+#include <algorithm>
 #include <csignal>
 #include <cstdio>
 #include <iostream>  // `std::cerr`
@@ -32,6 +33,7 @@
 #include <string>    // `std::to_string`
 #include <thread>    // `std::thread::hardware_concurrency()`
 #include <variant>   // `std::monostate`
+#include <vector>
 
 #include <clipp.h> // Command Line Interface
 #include <omp.h>   // `omp_set_num_threads()`
@@ -243,10 +245,10 @@ struct running_stats_printer_t {
         std::size_t new_progress = progress.load();
         if (new_progress - last_printed_progress < step)
             return;
-        print(new_progress);
+        print(new_progress, total);
     }
 
-    void print(std::size_t progress) {
+    void print(std::size_t progress, std::size_t total) {
 
         constexpr char bars_k[] = "||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||";
         constexpr std::size_t bars_len_k = 60;
@@ -267,6 +269,7 @@ struct running_stats_printer_t {
 
         last_printed_progress = progress;
         last_printed_time = time_new;
+        this->total = total;
     }
 };
 
@@ -332,6 +335,8 @@ template <typename dataset_at, typename index_at> //
 static void single_shot(dataset_at& dataset, index_at& index, bool construct = true) {
     using label_t = typename index_at::label_t;
     using distance_t = typename index_at::distance_t;
+    using join_result_t = typename index_at::join_result_t;
+    constexpr std::size_t missing_label = std::numeric_limits<label_t>::max();
 
     std::printf("\n");
     std::printf("------------\n");
@@ -348,7 +353,7 @@ static void single_shot(dataset_at& dataset, index_at& index, bool construct = t
     search_many(index, dataset.queries_count(), dataset.query(0), dataset.dimensions(), dataset.neighborhood_size(),
                 found_neighbors.data(), found_distances.data());
 
-    // Evaluate quality
+    // Evaluate search quality
     std::size_t recall_at_1 = 0, recall_full = 0;
     for (std::size_t i = 0; i != dataset.queries_count(); ++i) {
         auto expected = dataset.neighborhood(i);
@@ -360,6 +365,38 @@ 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());
 
+    // Perform joins
+    std::vector<label_t> man_to_woman(dataset.vectors_count());
+    std::vector<label_t> woman_to_man(dataset.vectors_count());
+    std::size_t join_attempts = 0;
+    {
+        index_at& men = index;
+        index_at women = index.copy().index;
+        std::fill(man_to_woman.begin(), man_to_woman.end(), missing_label);
+        std::fill(woman_to_man.begin(), woman_to_man.end(), missing_label);
+        {
+            executor_default_t executor(index.limits().threads());
+            running_stats_printer_t printer{1, "Join"};
+            join_result_t result = index_at::join(          //
+                men, women, join_config_t{executor.size()}, //
+                man_to_woman.data(), woman_to_man.data(),   //
+                executor, [&](std::size_t progress, std::size_t total) {
+                    if (progress % 1000 == 0)
+                        printer.print(progress, total);
+                });
+            join_attempts = result.cycles;
+        }
+    }
+    // Evaluate join quality
+    std::size_t recall_join = 0, unmatched_count = 0;
+    for (std::size_t i = 0; i != index.size(); ++i) {
+        recall_join += man_to_woman[i] == i;
+        unmatched_count += man_to_woman[i] == missing_label;
+    }
+    std::printf("Recall Joins %.2f %%\n", recall_join * 100.f / index.size());
+    std::printf("Unmatched %.2f %% (%zu items)\n", unmatched_count * 100.f / index.size(), unmatched_count);
+    std::printf("Proposals %.2f / man (%zu total)\n", join_attempts * 1.f / index.size(), join_attempts);
+
     // Paginate
     std::vector<vector_id_t> hints(dataset.queries_count());
     for (std::size_t i = 0; i != hints.size(); ++i)
@@ -491,7 +528,7 @@ void run_punned(dataset_at& dataset, args_t const& args, index_config_t config,
 
     std::printf("Will benchmark an on-disk view\n");
 
-    index_at index_view = index.fork();
+    index_at index_view = index.fork().index;
     index_view.view(args.path_output.c_str());
     single_shot(dataset, index_view, false);
 }