refactor(deglib): unify explore into search_intern and add std::span bounds-checked API

- Replace public raw-pointer search with bounds-checked std::span<const float> API.
- Eliminate duplicated exploreImpl code across SizeBoundedGraph and ReadOnlyGraph.
- Unify graph traversal into single searchImpl template
- Standardize parameter ordering across search() and explore(): (target, k, eps, include_entry, filter, max_dist).
- Grant friend access to EvenRegularGraphBuilder for protected search_intern calls.

Author: Neiko2002

cpp/bench/include/benchmark.h

@@ -11,6 +11,7 @@
 #include <fmt/ranges.h>
 
 #include <atomic>
+#include <span>
 #include <filesystem>
 #include <fstream>
 #include <limits>
@@ -85,8 +86,8 @@ static float test_approx_anns(const deglib::search::SearchGraph& graph,
                               const deglib::graph::Filter* filter = nullptr) {
     auto corrects = std::vector<float>(threads);
     deglib::concurrent::parallel_for(0, test_size, threads, [&](size_t i, size_t thread_id) {
-        auto query = reinterpret_cast<const std::byte*>(query_repository.getFeature(uint32_t(i)));
-        auto result_queue = graph.search(entry_vertex_indices, query, eps, k, filter);
+        auto query = reinterpret_cast<const float*>(query_repository.getFeature(uint32_t(i)));
+        auto result_queue = graph.search(std::span<const float>(query, graph.getFeatureSpace().dim()), k, eps, filter);
 
         if (result_queue.size() != k) {
             fmt::print(stderr, "ANNS with k={} got only {} results for query {}\n", k, result_queue.size(), i);
@@ -121,7 +122,7 @@ static float test_approx_explore(const deglib::search::SearchGraph& graph,
     auto corrects = std::vector<float>(threads);
     deglib::concurrent::parallel_for(0, entry_vertex_indices.size(), threads, [&](size_t i, size_t thread_id) {
         const auto entry_vertex_index = entry_vertex_indices[i][0];
-        auto result_queue = graph.explore(entry_vertex_index, k, include_entry, max_distance_count);
+        auto result_queue = graph.explore(entry_vertex_index, k, max_distance_count, 0.0f, include_entry);
 
         if (result_queue.size() != k) {
             fmt::print(stderr,
@@ -166,8 +167,8 @@ static std::vector<float> estimate_recall(const deglib::search::SearchGraph& gra
         std::atomic<size_t> correct{0};
 
         deglib::concurrent::parallel_for(0, query_repository.size(), threads, [&](size_t i, size_t thread_id) {
-            auto query = reinterpret_cast<const std::byte*>(query_repository.getFeature(uint32_t(i)));
-            auto result_queue = graph.search(entry_vertex_indices, query, eps, k, nullptr, max_distance_count);
+            auto query = reinterpret_cast<const float*>(query_repository.getFeature(uint32_t(i)));
+            auto result_queue = graph.search(std::span<const float>(query, graph.getFeatureSpace().dim()), k, eps, nullptr, max_distance_count);
 
             const auto& gt = answer[i];
             total += result_queue.size();

cpp/benchmark/include/benchmark.h

@@ -6,6 +6,7 @@
 #include <fmt/base.h>
 #include <fmt/format.h>
 #include <fmt/ranges.h>  
+#include <span>
 
 #include <deglib/deglib.h>
 #include "stopwatch.h"
@@ -40,8 +41,8 @@ static float test_approx_anns(const deglib::search::SearchGraph& graph, const st
     auto corrects = std::vector<float>(threads);
     deglib::concurrent::parallel_for(0, test_size, threads, [&] (size_t i, size_t thread_id) {
 
-        auto query = reinterpret_cast<const std::byte*>(query_repository.getFeature(uint32_t(i)));
-        auto result_queue = graph.search(entry_vertex_indices, query, eps, k, filter);
+        auto query = reinterpret_cast<const float*>(query_repository.getFeature(uint32_t(i)));
+        auto result_queue = graph.search(std::span<const float>(query, graph.getFeatureSpace().dim()), k, eps, filter);
 
         if (result_queue.size() != k) {
             fmt::print(stderr, "ANNS with k={} got only {} results for query {}\n", k, result_queue.size(), i);
@@ -76,7 +77,7 @@ static float test_approx_explore(const deglib::search::SearchGraph& graph, const
     deglib::concurrent::parallel_for(0, entry_vertex_indices.size(), threads, [&] (size_t i, size_t thread_id) {
 
         const auto entry_vertex_index = entry_vertex_indices[i][0];
-        auto result_queue = graph.explore(entry_vertex_index, k, include_entry, max_distance_count); // TODO missing filter
+        auto result_queue = graph.explore(entry_vertex_index, k, max_distance_count, 0.0f, include_entry); // TODO missing filter
 
         if (result_queue.size() != k) {
             fmt::print(stderr, "Exploration with k={} got only {} results for query {}\n", k, result_queue.size(), i);

cpp/benchmark/src/deglib_build_bench.cpp

@@ -3,6 +3,7 @@
 #include <unordered_set>
 #include <filesystem>
 #include <atomic>
+#include <span>
 
 #include <fmt/core.h>
 
@@ -632,8 +633,8 @@ static std::vector<float> estimate_recall(const deglib::search::SearchGraph& gra
         deglib::concurrent::parallel_for(0, query_repository.size(), threads, [&](size_t i_idx, size_t)
         {
             const int i = (int)i_idx;
-            auto query = reinterpret_cast<const std::byte*>(query_repository.getFeature(uint32_t(i)));
-            auto result_queue = graph.search(entry_vertex_indices, query, eps, k, nullptr, max_distance_count);
+            auto query = reinterpret_cast<const float*>(query_repository.getFeature(uint32_t(i)));
+            auto result_queue = graph.search(std::span<const float>(query, graph.getFeatureSpace().dim()), k, eps, nullptr, max_distance_count);
 
             const auto& gt = answer[i];
             total.fetch_add(result_queue.size(), std::memory_order_relaxed);

cpp/deglib/include/deglib/builder.h

@@ -520,7 +520,7 @@ class EvenRegularGraphBuilder {
       // find good neighbor candidates for the new vertex
       auto distrib = deglib::random::DeterministicUniformIntDistribution<uint32_t>(0, uint32_t(graph.size() - 1));
       const std::vector<uint32_t> entry_vertex_indices = { distrib(this->rnd_) };
-      auto top_list = graph.search(entry_vertex_indices, new_vertex_feature, this->extend_eps_, std::max(uint32_t(this->extend_k_), edges_per_vertex*2)); // need 2x otherwise it might lock during neighbor selection
+      auto top_list = graph.search_intern(entry_vertex_indices, new_vertex_feature, std::max(uint32_t(this->extend_k_), edges_per_vertex*2), this->extend_eps_); // need 2x otherwise it might lock during neighbor selection
       const auto candidates = topListAscending(top_list);
 
       // their should always be enough neighbors (search candidates), otherwise the graph would be broken
@@ -634,7 +634,7 @@ class EvenRegularGraphBuilder {
 
       // find good neighbors for the new vertex
       const std::vector<uint32_t> entry_vertex_indices = { 0 };
-      auto top_list = graph.search(entry_vertex_indices, new_vertex_feature, this->extend_eps_, std::max(uint32_t(this->extend_k_), edges_per_vertex));
+      auto top_list = graph.search_intern(entry_vertex_indices, new_vertex_feature, std::max(uint32_t(this->extend_k_), edges_per_vertex), this->extend_eps_);
       const auto results = topListAscending(top_list);
 
       // their should always be enough neighbors (search results), otherwise the graph would be broken
@@ -1153,7 +1153,7 @@ class EvenRegularGraphBuilder {
         {
           const auto vertex2_feature = graph.getFeatureVector(vertex2);
           const std::vector<uint32_t> entry_vertex_indices = { vertex3, vertex4 };
-          auto top_list = graph.search(entry_vertex_indices, vertex2_feature, this->improve_eps_, improve_k_);
+          auto top_list = graph.search_intern(entry_vertex_indices, vertex2_feature, improve_k_, this->improve_eps_);
 
           // find a good new vertex3
           float best_gain = total_gain;
@@ -1228,7 +1228,7 @@ class EvenRegularGraphBuilder {
           // find a good (not yet connected) vertex for vertex1/vertex4
           const std::vector<uint32_t> entry_vertex_indices = { vertex2, vertex3 };
           const auto vertex4_feature = graph.getFeatureVector(vertex4);
-          auto top_list = graph.search(entry_vertex_indices, vertex4_feature, this->improve_eps_, improve_k_);
+          auto top_list = graph.search_intern(entry_vertex_indices, vertex4_feature, improve_k_, this->improve_eps_);
 
           float best_gain = 0;
           uint32_t best_selected_neighbor = 0;
@@ -1420,7 +1420,7 @@ class EvenRegularGraphBuilder {
         // RangeSearch from (a) to target (b): find good (e) and its neighbor (f) with
         // e != b, f != b, and not adjacent to b: (N(b) ∩ {e,f} = ∅)
         const auto b_feat = graph.getFeatureVector(b);
-        auto rs = graph.search({ s,t }, b_feat, eps, k); 
+        auto rs = graph.search_intern({ s,t }, b_feat, k, eps); 
         float best_delta = std::numeric_limits<float>::lowest();
         uint32_t best_e = 0, best_f = 0;
         float best_w_ef = 0.f, best_w_eb = 0.f, best_w_fb = 0.f;
@@ -1498,7 +1498,7 @@ class EvenRegularGraphBuilder {
       float best_score = std::numeric_limits<float>::lowest();
       {
         const auto b_feat = graph.getFeatureVector(b);
-        auto rs_bc = graph.search({ s,t }, b_feat, eps, k); 
+        auto rs_bc = graph.search_intern({ s,t }, b_feat, k, eps); 
 
         // Choose the best (c,d) pair by maximizing (gain - d(b,c) + d(c,d))
         float best_w_bc = 0.f, best_w_cd = 0.f;

cpp/deglib/include/deglib/graph/readonly_graph.h

@@ -343,15 +343,13 @@ class ReadOnlyGraph : public deglib::search::SearchGraph {
    * The result set contains internal indices. 
    */
   template <deglib::DistanceFunction COMPARATOR, bool use_max_distance_count, bool use_filter>
-  deglib::search::ResultSet searchImpl(const std::vector<uint32_t>& entry_vertex_indices, const std::byte* query, const float eps, const uint32_t initial_k, const deglib::graph::Filter* filter, const uint32_t max_distance_computation_count) const
+  deglib::search::ResultSet searchImpl(const std::vector<uint32_t>& entry_vertex_indices, const std::byte* query, const uint32_t initial_k, const float eps, const bool include_entry, const deglib::graph::Filter* filter, const uint32_t max_distance_computation_count) const
   {
+    uint32_t distance_computation_count = 0;
     const auto dist_func_param = this->feature_space_.get_dist_func_param();
     const auto feature_size = this->feature_space_.get_data_size();
-    const size_t degree = this->edges_per_vertex_;
     const size_t vertex_count = this->size();
-
     size_t k = std::min(vertex_count, static_cast<size_t>(initial_k));
-    uint32_t distance_computation_count = 0;
 
     // set of checked vertex ids
     const auto vl = visited_list_pool_->getFreeVisitedList();
@@ -360,12 +358,12 @@ class ReadOnlyGraph : public deglib::search::SearchGraph {
 
     // items to traverse next
     auto next_vertices = deglib::search::UncheckedSet();
-    next_vertices.reserve(k*degree);
+    next_vertices.reserve(k*this->edges_per_vertex_);
 
     // result set
     // TODO: custom priority queue with an internal Variable Length Array wrapped in a macro with linear-scan search and memcopy 
-    auto results = deglib::search::ResultSet();
-    results.reserve(k);
+    auto results = deglib::search::ResultSet();   
+    results.reserve(k+1);
 
     // if the filter only contains few valid ids brute force them all
     if constexpr (use_filter) {
@@ -400,13 +398,15 @@ class ReadOnlyGraph : public deglib::search::SearchGraph {
         const auto feature = reinterpret_cast<const float*>(this->feature_by_index(index));
         const auto distance = COMPARATOR::compare(query, feature, dist_func_param);
         next_vertices.emplace(index, distance);
-        if constexpr (use_filter) {
-          if(filter->is_valid(this->label_by_index(index)))  {
+        if (include_entry) {
+          if constexpr (use_filter) {
+            if(filter->is_valid(this->label_by_index(index)))  {
+              results.emplace(index, distance);
+            }
+          } else {
             results.emplace(index, distance);
-          }
-        } else {
-          results.emplace(index, distance);
-        }   
+          }   
+        }
 
         // early stop after to many computations
         if constexpr (use_max_distance_count) {
@@ -435,7 +435,7 @@ class ReadOnlyGraph : public deglib::search::SearchGraph {
 
       size_t good_neighbor_count = 0;
       const auto neighbor_indices = this->neighbors_by_index(next_vertex.getInternalIndex());
-      for (size_t i = 0; i < degree; i++) {
+      for (size_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;
@@ -491,124 +491,26 @@ class ReadOnlyGraph : public deglib::search::SearchGraph {
     return results;
   }
 
-  /**
-   * The result set contains internal indices. 
-   */
-  deglib::search::ResultSet search(const std::vector<uint32_t>& entry_vertex_indices, const std::byte* query, const float eps, const uint32_t k, const deglib::graph::Filter* filter = nullptr, const uint32_t max_distance_computation_count = 0) const override
-  {
-    return feature_space_.compute([&]<deglib::DistanceFunction Dist>(Dist) {
-      if(filter) {
-        if(max_distance_computation_count == 0) {
-          return searchImpl<Dist, false, true>(entry_vertex_indices, query, eps, k, filter, 0);
-        } else {
-          return searchImpl<Dist, true, true>(entry_vertex_indices, query, eps, k, filter, max_distance_computation_count);
-        }
-      } else {
-        if(max_distance_computation_count == 0) {
-          return searchImpl<Dist, false, false>(entry_vertex_indices, query, eps, k, nullptr, 0);
-        } else {
-          return searchImpl<Dist, true, false>(entry_vertex_indices, query, eps, k, nullptr, max_distance_computation_count);
-        }
-      }
-    });
-  }
-
-  /**
-   * The result set contains internal indices. 
-   */
-  template <deglib::DistanceFunction COMPARATOR>
-  deglib::search::ResultSet exploreImpl(const uint32_t entry_vertex_index, const uint32_t k, const bool include_entry, const uint32_t max_distance_computation_count) const
-  {
-    uint32_t distance_computation_count = 0;
-    const auto dist_func_param = this->feature_space_.get_dist_func_param();
-    const auto feature_size = this->feature_space_.get_data_size();
-
-    // set of checked vertex ids
-    const auto vl = visited_list_pool_->getFreeVisitedList();
-    auto* checked_ids = vl->get_visited();
-    const auto checked_ids_tag = vl->get_tag();
-
-    // items to traverse next
-    auto next_vertices = deglib::search::UncheckedSet();
-    next_vertices.reserve(k*this->edges_per_vertex_);
-
-    // result set
-    auto results = deglib::search::ResultSet();   
-    results.reserve(k);
-
-    // 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.0f);
-    if(include_entry)
-      results.emplace(entry_vertex_index, 0.0f);
-    const auto query = this->feature_by_index(entry_vertex_index);
-
-    // search radius
-    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
-    while (next_vertices.empty() == false)
+  protected:
+    deglib::search::ResultSet search_intern(const std::vector<uint32_t>& entry_vertex_indices, const std::byte* query, const uint32_t k, const float eps = 0.0f, const bool include_entry = true, const deglib::graph::Filter* filter = nullptr, const uint32_t max_distance_computation_count = 0) const override
     {
-      // next vertex to check
-      const auto next_vertex = next_vertices.top();
-      next_vertices.pop();
-
-      uint8_t good_neighbor_count = 0;
-      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;
-        }
-      }
-
-      if (good_neighbor_count == 0)
-        continue;
-
-      memory::prefetch(reinterpret_cast<const char*>(this->feature_by_index(good_neighbors[0])), feature_size);
-      for (uint8_t i = 0; i < good_neighbor_count; i++) {
-        memory::prefetch(reinterpret_cast<const char*>(this->feature_by_index(good_neighbors[std::min(i + 1, good_neighbor_count - 1)])), feature_size);
-
-        const auto neighbor_index = good_neighbors[i];
-        const auto neighbor_feature_vector = this->feature_by_index(neighbor_index);
-        const auto neighbor_distance = COMPARATOR::compare(query, neighbor_feature_vector, dist_func_param);
-
-        if (neighbor_distance < radius) {
-
-          // check the neighborhood of this vertex later
-          next_vertices.emplace(neighbor_index, neighbor_distance);
-
-          // remember the vertex, if its better than the worst in the result list
-          results.emplace(neighbor_index, neighbor_distance);
-
-          // update the search radius
-          if (results.size() > k) {
-            results.pop();
-            radius = results.top().getDistance();
+      return feature_space_.compute([&]<deglib::DistanceFunction Dist>(Dist) {
+        if(filter) {
+          if(max_distance_computation_count == 0) {
+            return searchImpl<Dist, false, true>(entry_vertex_indices, query, k, eps, include_entry, filter, 0);
+          } else {
+            return searchImpl<Dist, true, true>(entry_vertex_indices, query, k, eps, include_entry, filter, max_distance_computation_count);
+          }
+        } else {
+          if(max_distance_computation_count == 0) {
+            return searchImpl<Dist, false, false>(entry_vertex_indices, query, k, eps, include_entry, nullptr, 0);
+          } else {
+            return searchImpl<Dist, true, false>(entry_vertex_indices, query, k, eps, include_entry, nullptr, max_distance_computation_count);
           }
         }
-
-        // early stop after to many computations
-        if(max_distance_computation_count > 0 && ++distance_computation_count >= max_distance_computation_count)
-          return results;
-      }
+      });
     }
 
-    return results;
-  }  
-
-  /**
-   * The result set contains internal indices. 
-   */
-  deglib::search::ResultSet explore(const uint32_t entry_vertex_index, const uint32_t k, const bool include_entry, const uint32_t max_distance_computation_count = 0) const override
-  {
-    return feature_space_.compute([&]<deglib::DistanceFunction Dist>(Dist) {
-      return exploreImpl<Dist>(entry_vertex_index, k, include_entry, max_distance_computation_count);
-    });
-  }
-
 };