examples: add search example project

Author: Neiko2002

.gitignore

@@ -57,3 +57,11 @@ Thumbs.db
 
 # Agent rules
 .agents/
+
+# Python generated files & virtual environments
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+*.png
+

cpp/deglib/include/graph/sizebounded_graph.h

@@ -681,44 +681,13 @@ class SizeBoundedGraph : public deglib::graph::MutableGraph {
 
     // add the entry vertex index to the vertices which gets checked next and ignore it for further checks
     checked_ids[entry_vertex_index] = checked_ids_tag;
-    next_vertices.emplace(entry_vertex_index, 0);
+    next_vertices.emplace(entry_vertex_index, 0.0f);
     if(include_entry)
-      results.emplace(entry_vertex_index, 0);
+      results.emplace(entry_vertex_index, 0.0f);
     const auto query = this->feature_by_index(entry_vertex_index);
 
-    // add the neighbors of the entry vertex to the next vertices queue
-    {
-      const auto neighbor_indices = this->neighbors_by_index(entry_vertex_index);
-      const auto neighbor_weights = this->weights_by_index(entry_vertex_index);
-      memory::prefetch(reinterpret_cast<const char*>(neighbor_indices));
-      memory::prefetch(reinterpret_cast<const char*>(neighbor_weights));
-      for (uint8_t i = 0; i < this->edges_per_vertex_; i++) {
-        const auto neighbor_index = neighbor_indices[i];
-
-        if (checked_ids[neighbor_index] != checked_ids_tag) {
-          checked_ids[neighbor_index] = checked_ids_tag;
-
-          const auto neighbor_distance = neighbor_weights[i];
-          next_vertices.emplace(neighbor_index, neighbor_distance);
-          results.emplace(neighbor_index, neighbor_distance);
-
-          // update the search radius
-          if (results.size() > k) 
-            results.pop();
-
-          // early stop after to many computations
-          if(max_distance_computation_count > 0 && ++distance_computation_count >= max_distance_computation_count)
-            return results;
-        }
-      }
-    }
-
     // search radius
-    auto radius = results.top().getDistance();
-
-    // experimental: eps replacement parameter
-    const auto eps = (max_distance_computation_count > 0) ? std::log10(float(max_distance_computation_count)/k) : 0.0f;
-    auto exploration_radius = radius * ((radius < 0) ? (1 - eps) : (1 + eps));
+    auto radius = std::numeric_limits<float>::max();
 
     // iterate as long as good elements are in the next_vertices queue and max_calcs is not yet reached
     auto good_neighbors = std::array<uint32_t, 256>();    // this limits the neighbor count to 256 using Variable Length Array wrapped in a macro
@@ -728,27 +697,13 @@ class SizeBoundedGraph : public deglib::graph::MutableGraph {
       const auto next_vertex = next_vertices.top();
       next_vertices.pop();
 
-      // if no weight of this neighbor would survive the distance estimation check, stop here
-      if (next_vertex.getDistance() > exploration_radius)
-        break;
-
       uint8_t good_neighbor_count = 0;
-      {
-        const auto neighbor_indices = this->neighbors_by_index(next_vertex.getInternalIndex());
-        const auto neighbor_weights = this->weights_by_index(next_vertex.getInternalIndex());
-        memory::prefetch(reinterpret_cast<const char*>(neighbor_indices));
-        memory::prefetch(reinterpret_cast<const char*>(neighbor_weights));
-        for (uint8_t i = 0; i < this->edges_per_vertex_; i++) {
-          const auto neighbor_index = neighbor_indices[i];
-
-          if (checked_ids[neighbor_index] != checked_ids_tag)  {
-            checked_ids[neighbor_index] = checked_ids_tag;
-
-            // distance estimation check: allow only edges with a worst case distance < r
-            // this produces slighly better results and brings the sizebound graph on par with the readonly graph when comparing speed vs quality
-            if(next_vertex.getDistance() + neighbor_weights[i] < exploration_radius)
-              good_neighbors[good_neighbor_count++] = neighbor_index;
-          }
+      const auto neighbor_indices = this->neighbors_by_index(next_vertex.getInternalIndex());
+      for (uint8_t i = 0; i < this->edges_per_vertex_; i++) {
+        const auto neighbor_index = neighbor_indices[i];
+        if (checked_ids[neighbor_index] != checked_ids_tag)  {
+          checked_ids[neighbor_index] = checked_ids_tag;
+          good_neighbors[good_neighbor_count++] = neighbor_index;
         }
       }
 
@@ -775,7 +730,6 @@ class SizeBoundedGraph : public deglib::graph::MutableGraph {
           if (results.size() > k) {
             results.pop();
             radius = results.top().getDistance();
-            exploration_radius = radius * ((radius < 0) ? (1 - eps) : (1 + eps));
           }
         }
 

cpp/test/CMakeLists.txt

@@ -10,7 +10,10 @@ set(TEST_MAIN ${CMAKE_CURRENT_SOURCE_DIR}/test_main.cpp)
 
 # Static library for GoogleTest to avoid compiling gmock-gtest-all.cc multiple times
 add_library(gtest STATIC ${GTEST_SOURCE})
-target_include_directories(gtest PUBLIC ${GTEST_INCLUDE})
+target_include_directories(gtest SYSTEM PUBLIC ${GTEST_INCLUDE})
+if(CMAKE_CXX_COMPILER_ID MATCHES "Clang|GNU")
+    target_compile_options(gtest PRIVATE -Wno-character-conversion)
+endif()
 
 # Helper macro: creates a test executable with shared gtest + deglib setup
 macro(add_deglib_test name source)

docs/tutorials/installation.rst

@@ -29,7 +29,7 @@ This can be useful if you want to:
     python -m venv venv && . venv/bin/activate
 
     # install build dependencies
-    pip install setuptools==83.0.0 pybind11==3.0.4 build
+    pip install setuptools==83.0.0 pybind11==3.0.4 build==1.5.0
     python setup.py copy_build_files  # copy c++ library to ./lib/
 
     # install

examples/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.py[cod]
+.venv/
+*.png

examples/README.md

@@ -0,0 +1,37 @@
+# DEG Examples
+
+This directory contains standalone Python projects demonstrating various features and benchmark workflows of the Dynamic Exploration Graph (DEG).
+
+Each directory inside `examples/` is a self-contained [`uv`](https://docs.astral.sh/uv/) project with its own `pyproject.toml`.
+
+## Prerequisites & UV Setup
+
+We use [`uv`](https://docs.astral.sh/uv/) for fast Python environment and dependency management.
+
+### 1. Install `uv`
+
+- **macOS / Linux**:
+  ```bash
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+  ```
+- **Windows (PowerShell)**:
+  ```powershell
+  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+  ```
+- **Via Pip**:
+  ```bash
+  pip install uv
+  ```
+
+### 2. Environment Setup
+
+Navigating into any example directory and running `uv sync` or `uv run` will automatically set up a isolated Python virtual environment, build the local `deglib` C++ bindings, and install all required dependencies:
+
+```bash
+cd examples/paper_reproduction
+uv sync
+```
+
+## Projects
+
+- [`paper_reproduction`](./paper_reproduction/): Reproduce DEG paper search benchmarks (Recall vs QPS) on datasets mentioned in the root `readme.md` (`Audio`, `Enron`, `SIFT1M`, `DEEP1M`, `GloVe-100`).

examples/static_data/README.md

@@ -0,0 +1,48 @@
+# DEG Paper Reproduction Benchmark
+
+This example project demonstrates how to download paper datasets from `readme.md`, build a DEG graph with preset parameters, run search queries, measure Recall vs. QPS (Queries Per Second), and display the results plot interactively.
+
+## Available Datasets
+
+- `audio` (192D, 53k base vectors, L2 distance)
+- `enron` (1369D, 94k base vectors, L2 distance)
+- `sift1m` (128D, 1M base vectors, L2 distance)
+- `deep1m` (96D, 1M base vectors, L2 distance)
+- `glove-100` (100D, 1.18M base vectors, Angular / InnerProduct distance)
+
+## Prerequisites & UV Setup
+
+1. **Install `uv`** (if not already installed):
+   - **Linux/macOS**: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+   - **Windows (PowerShell)**: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
+   - **Pip**: `pip install uv`
+
+2. **Sync Dependencies**:
+   Inside this directory, initialize the environment and install dependencies (including building local `deglib` bindings):
+   ```bash
+   uv sync
+   ```
+
+## Running the Benchmark
+
+`uv run` automatically uses the managed virtual environment.
+
+### 1. Run Full Benchmark (e.g. SIFT1M)
+
+```bash
+uv run main.py --dataset sift1m
+```
+
+### 2. Fast Test Run (e.g. Audio dataset with 1,000 vectors)
+
+```bash
+uv run main.py --dataset audio --max-base-vecs 1000
+```
+
+## Options
+
+- `--dataset`: Dataset name (`sift1m`, `audio`, `enron`, `deep1m`, `glove-100`). Default: `sift1m`.
+- `--cache-dir`: Persistent cache folder for datasets. Default: `~/.cache/deg_datasets`.
+- `--output-plot`: Optional path to also save the plot to a PNG image (e.g. `--output-plot recall_vs_qps.png`).
+- `--no-show`: Disable opening the interactive plot window (useful for headless CI environments).
+- `--max-base-vecs`: Limit base vectors for fast debugging / testing.