deglib 0.2.6__tar.gz → 0.2.7__tar.gz

{deglib-0.2.6/src/deglib.egg-info → deglib-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deglib
-Version: 0.2.6
+Version: 0.2.7
 Summary: Python bindings for the Dynamic Exploration Graph library by Nico Hezel
 Author: Nico Hezel
 Author-email: Bruno Schilling <bruno.schilling@htw-berlin.de>
@@ -47,7 +47,7 @@ Python bindings for the high-performance C++ Dynamic Exploration Graph (DEG) lib
   - [Graph Optimization, Quantization & Reranking Pipeline](#graph-optimization-quantization--reranking-pipeline)
 - [Concepts & Parameters](#concepts--parameters)
   - [OptimizationTarget](#optimizationtarget)
-  - [Search Parameter `eps`](#search-parameter-eps)
+  - [Unified Search Parameter `eps_or_ef`](#unified-search-parameter-eps_or_ef)
   - [Supported Metrics & Data Types](#supported-metrics--data-types)
 - [Example Projects](#example-projects)
 - [API Reference](#api-reference)
@@ -68,8 +68,10 @@ To build and install the package directly from the repository:
 
 ```bash
 cd python/
-python setup.py copy_build_files
-pip install .
+uv venv
+uv pip install setuptools==83.0.0 pybind11==3.0.4 build==1.5.0 wheel==0.48.0
+uv run python setup.py copy_build_files
+uv pip install . --no-build-isolation
 ```
 
 ---
@@ -89,7 +91,7 @@ data = np.random.random((num_samples, dims)).astype(np.float32)
 query = np.random.random(dims).astype(np.float32)
 
 # 2. Build index directly from data (multithreaded by default)
-graph = deglib.builder.build_from_data(data, edges_per_vertex=32, callback="progress")
+graph = deglib.builder.build_from_data(data, edges_per_vertex=32, show_progress=True)
 
 # 3. Query top-k nearest neighbors
 indices, distances = graph.search(query, k=10, eps=0.1)
@@ -106,7 +108,7 @@ All search graphs are represented by `DynamicExplorationGraph`, backed by one of
 
 1. **Fixed-Capacity Mutable (`SizeBoundedGraph`)**: Memory is preallocated for a fixed maximum capacity. Fast and memory-efficient for static/batch datasets.
    ```python
-   space = deglib.FloatSpace.create(dims=128, metric=deglib.Metric.FP32_L2)
+   space = deglib.FloatSpace.create(dim=128, metric=deglib.Metric.FP32_L2)
    graph = deglib.create_empty(capacity=10_000, feature_space=space, edges_per_vertex=32)
    ```
 
@@ -125,7 +127,7 @@ All search graphs are represented by `DynamicExplorationGraph`, backed by one of
 ### Saving and Loading Graphs
 
 ```python
-# Save mutable graph to disk
+# Save graph to disk (supports both mutable and read-only graphs)
 graph.save_graph("index.deg")
 
 # Load as compact, optimized read-only graph for production search
@@ -184,7 +186,7 @@ from deglib.search import Filter, rerank
 allowed_ids = np.array([1, 5, 10, 42, 99], dtype=np.int32)
 search_filter = Filter(allowed_ids)
 
-indices, distances = graph.search(query, k=5, eps=0.1, filter_labels=search_filter)
+indices, distances = graph.search(query, k=5, eps_or_ef=0.1, filter_labels=search_filter)
 
 # Exact distance reranking across candidates
 queries = np.random.random((10, dims)).astype(np.float32)
@@ -205,11 +207,19 @@ top_indices, top_distances = rerank(
 
 ### Exploratory Search & Graph Navigation
 
-DEG supports exploratory search directly from existing vertex labels:
+DEG supports exploratory search directly from existing vertex labels (single or batch):
 
 ```python
 # Explore graph starting from entry vertex label 105
-explored_labels, distances = graph.explore(entry_external_label=105, k=10, eps=0.1, include_entry=False)
+explored_labels, distances = graph.explore(entry_external_label=105, k=10, eps_or_ef=0.1, include_entry=False)
+
+# Batch exploration from multiple entry vertices in parallel
+batch_entries = np.array([105, 210, 315], dtype=np.uint32)
+batch_labels, batch_distances = graph.explore(batch_entries, k=10, eps_or_ef=0.1, threads=4)
+
+# Retrieve graph neighbors directly
+neighbors = graph.get_neighbors(105)
+batch_neighbors = graph.get_neighbors_batch(batch_entries, threads=4)  # shape: (3, edges_per_vertex)
 ```
 
 ---
@@ -221,7 +231,8 @@ A complete end-to-end pipeline demonstrating **FLAS pre-sorting**, **multithread
 ```python
 import numpy as np
 import deglib
-from deglib.optimization import presort, prune_non_rng_edges, ScalarQuantizerInt8
+from deglib.optimization import presort, prune_non_mrng_edges
+from deglib.transformation import ScalarQuantizerInt8
 from deglib.search import create_searcher
 
 num_vectors, dims = 10_000, 128
@@ -229,7 +240,7 @@ data = np.random.randn(num_vectors, dims).astype(np.float32)
 query = np.random.randn(dims).astype(np.float32)
 
 # 1. Pre-sort vectors using FLAS for improved memory locality and index construction speed
-perm = presort(data, metric=deglib.Metric.FP32_InnerProduct, callback="progress")
+perm = presort(data, metric=deglib.Metric.FP32_InnerProduct, show_progress=True)
 sorted_data = data[perm]
 
 # 2. Build exploration graph on unquantized/original data
@@ -237,11 +248,11 @@ graph = deglib.builder.build_from_data(
     sorted_data,
     metric=deglib.Metric.FP32_InnerProduct,
     edges_per_vertex=32,
-    callback="progress",
+    show_progress=True,
 )
 
-# 3. Prune redundant non-RNG edges to optimize graph topology
-pruned_count = prune_non_rng_edges(graph)
+# 3. Prune redundant non-MRNG edges to optimize graph topology
+pruned_count = prune_non_mrng_edges(graph)
 print(f"Pruned {pruned_count} redundant edges.")
 
 # 4. Fit Int8 quantizer on base dataset and quantize features for memory reduction and ultra-fast search
@@ -251,19 +262,20 @@ quant_int8_data = quantizer.quantize(sorted_data)
 int8_space = deglib.FloatSpace.create(dims, deglib.Metric.Int8_InnerProduct)
 
 # 5. Convert mutable graph to a compact ReadOnlyGraph equipped with the quantized features
-readonly_graph = graph.to_readonly(feature_space=int8_space, custom_features=quant_int8_data)
+readonly_graph = graph.to_readonly(
+    feature_space=int8_space, custom_features=quant_int8_data, transformations=[quantizer]
+)
 
 # 6. Create high-performance Searcher equipped with base vectors for exact candidate reranking
 rerank_space = deglib.FloatSpace.create(dims, deglib.Metric.FP32_InnerProduct)
 searcher = create_searcher(
     graph=readonly_graph,
-    quantizer=quantizer,
-    refine_space=rerank_space,
-    refine_data=sorted_data,
+    rerank_space=rerank_space,
+    rerank_data=sorted_data,
 )
 
 # 7. Query search (query is automatically quantized and top candidates are reranked)
-indices, distances = searcher.search(query, k=10, eps=0.1, rerank_factor=1.5, return_distances=True)
+indices, distances = searcher.search(query, k=10, eps_or_ef=0.1, rerank_factor=1.5, return_distances=True)
 print("Top-10 nearest neighbor indices:", indices)
 print("Top-10 exact distances:", distances)
 ```

{deglib-0.2.6 → deglib-0.2.7}/README.md

@@ -19,7 +19,7 @@ Python bindings for the high-performance C++ Dynamic Exploration Graph (DEG) lib
   - [Graph Optimization, Quantization & Reranking Pipeline](#graph-optimization-quantization--reranking-pipeline)
 - [Concepts & Parameters](#concepts--parameters)
   - [OptimizationTarget](#optimizationtarget)
-  - [Search Parameter `eps`](#search-parameter-eps)
+  - [Unified Search Parameter `eps_or_ef`](#unified-search-parameter-eps_or_ef)
   - [Supported Metrics & Data Types](#supported-metrics--data-types)
 - [Example Projects](#example-projects)
 - [API Reference](#api-reference)
@@ -40,8 +40,10 @@ To build and install the package directly from the repository:
 
 ```bash
 cd python/
-python setup.py copy_build_files
-pip install .
+uv venv
+uv pip install setuptools==83.0.0 pybind11==3.0.4 build==1.5.0 wheel==0.48.0
+uv run python setup.py copy_build_files
+uv pip install . --no-build-isolation
 ```
 
 ---
@@ -61,7 +63,7 @@ data = np.random.random((num_samples, dims)).astype(np.float32)
 query = np.random.random(dims).astype(np.float32)
 
 # 2. Build index directly from data (multithreaded by default)
-graph = deglib.builder.build_from_data(data, edges_per_vertex=32, callback="progress")
+graph = deglib.builder.build_from_data(data, edges_per_vertex=32, show_progress=True)
 
 # 3. Query top-k nearest neighbors
 indices, distances = graph.search(query, k=10, eps=0.1)
@@ -78,7 +80,7 @@ All search graphs are represented by `DynamicExplorationGraph`, backed by one of
 
 1. **Fixed-Capacity Mutable (`SizeBoundedGraph`)**: Memory is preallocated for a fixed maximum capacity. Fast and memory-efficient for static/batch datasets.
    ```python
-   space = deglib.FloatSpace.create(dims=128, metric=deglib.Metric.FP32_L2)
+   space = deglib.FloatSpace.create(dim=128, metric=deglib.Metric.FP32_L2)
    graph = deglib.create_empty(capacity=10_000, feature_space=space, edges_per_vertex=32)
    ```
 
@@ -97,7 +99,7 @@ All search graphs are represented by `DynamicExplorationGraph`, backed by one of
 ### Saving and Loading Graphs
 
 ```python
-# Save mutable graph to disk
+# Save graph to disk (supports both mutable and read-only graphs)
 graph.save_graph("index.deg")
 
 # Load as compact, optimized read-only graph for production search
@@ -156,7 +158,7 @@ from deglib.search import Filter, rerank
 allowed_ids = np.array([1, 5, 10, 42, 99], dtype=np.int32)
 search_filter = Filter(allowed_ids)
 
-indices, distances = graph.search(query, k=5, eps=0.1, filter_labels=search_filter)
+indices, distances = graph.search(query, k=5, eps_or_ef=0.1, filter_labels=search_filter)
 
 # Exact distance reranking across candidates
 queries = np.random.random((10, dims)).astype(np.float32)
@@ -177,11 +179,19 @@ top_indices, top_distances = rerank(
 
 ### Exploratory Search & Graph Navigation
 
-DEG supports exploratory search directly from existing vertex labels:
+DEG supports exploratory search directly from existing vertex labels (single or batch):
 
 ```python
 # Explore graph starting from entry vertex label 105
-explored_labels, distances = graph.explore(entry_external_label=105, k=10, eps=0.1, include_entry=False)
+explored_labels, distances = graph.explore(entry_external_label=105, k=10, eps_or_ef=0.1, include_entry=False)
+
+# Batch exploration from multiple entry vertices in parallel
+batch_entries = np.array([105, 210, 315], dtype=np.uint32)
+batch_labels, batch_distances = graph.explore(batch_entries, k=10, eps_or_ef=0.1, threads=4)
+
+# Retrieve graph neighbors directly
+neighbors = graph.get_neighbors(105)
+batch_neighbors = graph.get_neighbors_batch(batch_entries, threads=4)  # shape: (3, edges_per_vertex)
 ```
 
 ---
@@ -193,7 +203,8 @@ A complete end-to-end pipeline demonstrating **FLAS pre-sorting**, **multithread
 ```python
 import numpy as np
 import deglib
-from deglib.optimization import presort, prune_non_rng_edges, ScalarQuantizerInt8
+from deglib.optimization import presort, prune_non_mrng_edges
+from deglib.transformation import ScalarQuantizerInt8
 from deglib.search import create_searcher
 
 num_vectors, dims = 10_000, 128
@@ -201,7 +212,7 @@ data = np.random.randn(num_vectors, dims).astype(np.float32)
 query = np.random.randn(dims).astype(np.float32)
 
 # 1. Pre-sort vectors using FLAS for improved memory locality and index construction speed
-perm = presort(data, metric=deglib.Metric.FP32_InnerProduct, callback="progress")
+perm = presort(data, metric=deglib.Metric.FP32_InnerProduct, show_progress=True)
 sorted_data = data[perm]
 
 # 2. Build exploration graph on unquantized/original data
@@ -209,11 +220,11 @@ graph = deglib.builder.build_from_data(
     sorted_data,
     metric=deglib.Metric.FP32_InnerProduct,
     edges_per_vertex=32,
-    callback="progress",
+    show_progress=True,
 )
 
-# 3. Prune redundant non-RNG edges to optimize graph topology
-pruned_count = prune_non_rng_edges(graph)
+# 3. Prune redundant non-MRNG edges to optimize graph topology
+pruned_count = prune_non_mrng_edges(graph)
 print(f"Pruned {pruned_count} redundant edges.")
 
 # 4. Fit Int8 quantizer on base dataset and quantize features for memory reduction and ultra-fast search
@@ -223,19 +234,20 @@ quant_int8_data = quantizer.quantize(sorted_data)
 int8_space = deglib.FloatSpace.create(dims, deglib.Metric.Int8_InnerProduct)
 
 # 5. Convert mutable graph to a compact ReadOnlyGraph equipped with the quantized features
-readonly_graph = graph.to_readonly(feature_space=int8_space, custom_features=quant_int8_data)
+readonly_graph = graph.to_readonly(
+    feature_space=int8_space, custom_features=quant_int8_data, transformations=[quantizer]
+)
 
 # 6. Create high-performance Searcher equipped with base vectors for exact candidate reranking
 rerank_space = deglib.FloatSpace.create(dims, deglib.Metric.FP32_InnerProduct)
 searcher = create_searcher(
     graph=readonly_graph,
-    quantizer=quantizer,
-    refine_space=rerank_space,
-    refine_data=sorted_data,
+    rerank_space=rerank_space,
+    rerank_data=sorted_data,
 )
 
 # 7. Query search (query is automatically quantized and top candidates are reranked)
-indices, distances = searcher.search(query, k=10, eps=0.1, rerank_factor=1.5, return_distances=True)
+indices, distances = searcher.search(query, k=10, eps_or_ef=0.1, rerank_factor=1.5, return_distances=True)
 print("Top-10 nearest neighbor indices:", indices)
 print("Top-10 exact distances:", distances)
 ```

{deglib-0.2.6 → deglib-0.2.7}/lib/CMakeLists.txt

@@ -48,7 +48,7 @@ if (FORCE_AVX2)
   elseif(CMAKE_CXX_COMPILER_ID STREQUAL "Clang" OR CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
     check_cxx_compiler_flag("-mavx2" COMPILER_SUPPORTS_AVX2)
     if(COMPILER_SUPPORTS_AVX2)
-      target_compile_options(compile-options INTERFACE -O3 -mavx2 -mfma -fpic -w -pthread -ftree-vectorize)
+      target_compile_options(compile-options INTERFACE -O3 -mavx2 -mfma -mf16c -fpic -w -pthread -ftree-vectorize)
     else()
       target_compile_options(compile-options INTERFACE -O3 -fpic -w -pthread -ftree-vectorize)
     endif()
@@ -57,7 +57,7 @@ if (FORCE_AVX2)
     if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")
       check_cxx_compiler_flag("-mavx2" COMPILER_SUPPORTS_AVX2)
       if(COMPILER_SUPPORTS_AVX2)
-        target_compile_options(compile-options INTERFACE -mavx2 -mfma)
+        target_compile_options(compile-options INTERFACE -mavx2 -mfma -mf16c)
       endif()
     endif()
   else()

{deglib-0.2.6 → deglib-0.2.7}/lib/bench/include/benchmark.h

@@ -8,7 +8,6 @@
 #include "dataset.h"
 #include "file_io.h"
 #include "logging.h"
-#include "stats.h"
 #include "stopwatch.h"
 
 #include <deglib/deglib.h>
@@ -17,15 +16,52 @@
 #include <fmt/ostream.h>
 #include <fmt/ranges.h>
 
+#include <algorithm>
 #include <atomic>
 #include <filesystem>
 #include <fstream>
 #include <limits>
 #include <random>
 #include <span>
+#include <vector>
 
 namespace deglib::benchmark {
 
+/**
+ * Analyze a search graph, compute all statistics via deglib::analysis, and log them.
+ *
+ * @param graph The search graph to analyze
+ * @param base_gt Optional contiguous BaseGroundTruth buffer
+ * @return GraphStats with all computed statistics
+ */
+inline deglib::analysis::GraphStats analyze_graph(
+    const deglib::graph::InternalGraph& graph,
+    const BaseGroundTruth& base_gt = {}
+) {
+    auto stats = deglib::analysis::analyze_graph(graph, base_gt.data(), base_gt.rows, base_gt.k);
+
+    log("Graph Statistics:\n");
+    log("  Vertices: {}\n", stats.vertex_count);
+    log("  Total edges: {}\n", stats.edge_count);
+    log("  Feature dimensions: {}\n", stats.feature_dims);
+    log("  Edges per vertex (k): {}\n", stats.edges_per_vertex);
+    log("  Out-degree: avg={:.2f}, min={}, max={}\n", stats.avg_out_degree, stats.min_out_degree, stats.max_out_degree);
+    log("  In-degree:  avg={:.2f}, min={}, max={}, source_vertices={}\n", stats.avg_in_degree, stats.min_in_degree, stats.max_in_degree, stats.source_vertices);
+
+    if (stats.graph_quality >= 0.0f) {
+        log("  Graph Quality: {:.2f}%\n", stats.graph_quality * 100.0f);
+    }
+    if (stats.search_reachability >= 0.0f) {
+        log("  Search Reachability: {:.2f}%\n", stats.search_reachability * 100.0f);
+    }
+    if (stats.exploration_reachability >= 0.0f) {
+        log("  Exploration Reachability: {:.2f}%\n", stats.exploration_reachability * 100.0f);
+    }
+
+    log("  Estimated memory: {:.2f} MB\n", stats.memory_bytes / (1024.0 * 1024.0));
+    return stats;
+}
+
 /**
  * @brief Compute baseline time per query using linear distance computation.
  */

{deglib-0.2.6 → deglib-0.2.7}/lib/bench/include/build.h

@@ -24,10 +24,10 @@ namespace deglib::benchmark {
 enum DataStreamType { AddAll, AddHalf, AddAllRemoveHalf, AddHalfRemoveAndAddOneAtATime };
 
 /**
- * Create a random exploration graph from the given StaticFeatureRepository.
+ * Create a random exploration graph from the given FeatureRepository.
  */
 inline deglib::graph::SizeBoundedGraph create_random_graph(
-    const deglib::StaticFeatureRepository& repository,
+    const deglib::FeatureRepository& repository,
     deglib::distances::Metric metric,
     const uint8_t k,
     const uint32_t max_size = 0,
@@ -47,7 +47,7 @@ inline deglib::graph::SizeBoundedGraph create_random_graph(
 }
 
 inline void create_graph(
-    const deglib::StaticFeatureRepository& repository,
+    const deglib::FeatureRepository& repository,
     const DataStreamType data_stream_type,
     const std::string& graph_file,
     deglib::distances::Metric metric,
@@ -165,7 +165,7 @@ inline void create_graph(
         duration_ms / 1000);
 
     graph.saveGraph(graph_file.c_str());
-    log("The graph contains {} non-RNG edges\n", deglib::analysis::calc_non_rng_edges(graph));
+    log("The graph contains {} non-MRNG edges\n", deglib::analysis::calc_non_mrng_edges(graph));
 }
 
 inline void optimize_graph(
@@ -211,8 +211,8 @@ inline void optimize_graph(
 
     builder.build(improvement_callback, true);
 
-    log("Optimization complete. Final AEW: {:.2f}, non-RNG edges: {}\n", deglib::analysis::calc_avg_edge_weight(graph, scale),
-        deglib::analysis::calc_non_rng_edges(graph));
+    log("Optimization complete. Final AEW: {:.2f}, non-MRNG edges: {}\n", deglib::analysis::calc_avg_edge_weight(graph, scale),
+        deglib::analysis::calc_non_mrng_edges(graph));
 }
 
 }  // namespace deglib::benchmark