Added documentation and commented the Filtered Robust on Stiched Vamana

Author: AntonisZks

include/GreedySearch.h

@@ -55,6 +55,26 @@ template <typename graph_t, typename query_t> std::pair<std::set<graph_t>, std::
     const EXEC_MODE execMode = CREATE
 );
 
+/**
+ * @brief Greedy search algorithm for finding the k nearest nodes in a graph relative to a query vector.
+ * 
+ * This function implements a greedy search that iteratively explores the closest nodes to the query vector.
+ * It maintains a candidate set of nodes to visit and a visited set of nodes already processed. This version
+ * of the function is used with a FilteredVamanaIndex, which applies additional filtering criteria to the search.
+ * 
+ * @param graph_t Type of data stored in the graph nodes
+ * @param query_t Type of the query vector
+ * @param index The FilteredVamanaIndex to search
+ * @param S Starting nodes for the search
+ * @param xq Query vector for distance computation
+ * @param k Number of nearest nodes to return
+ * @param L Maximum number of nodes in the candidate set
+ * @param queryFilters A vector of CategoricalAttributeFilter objects to apply to the search
+ * @param mode Execution mode for the algorithm
+ * 
+ * @return Pair of sets: the first set contains the k nearest nodes, and the second set contains all visited nodes
+ * 
+ */
 template <typename graph_t, typename query_t> std::pair<std::set<graph_t>, std::set<graph_t>> FilteredGreedySearch(
     const FilteredVamanaIndex<graph_t>& index, 
     const std::vector<GraphNode<graph_t>>& S, 

include/RobustPrune.h

@@ -30,5 +30,19 @@ template <typename graph_t> class FilteredVamanaIndex;
 template <typename graph_t>
 void RobustPrune(VamanaIndex<graph_t>& index, GraphNode<graph_t>& p_node, std::set<graph_t>& V, float alpha, int R);
 
+/**
+ * @brief Prunes the neighbors of a given node in a graph based on a robust pruning algorithm with filtering.
+ *
+ * This function modifies the neighbors of the given node `p_node` in the graph `G` by selecting
+ * a subset of neighbors that are within a certain distance threshold defined by `alpha` and `R`,
+ * while also applying additional filtering criteria.
+ *
+ * @tparam graph_t The type of the graph nodes.
+ * @param G The graph containing the node to be pruned.
+ * @param p_node The node whose neighbors are to be pruned.
+ * @param V A set of graph nodes to be considered for pruning.
+ * @param alpha A float value used as a multiplier for the distance threshold.
+ * @param R An integer specifying the maximum number of neighbors to retain.
+ */
 template <typename graph_t>
 void FilteredRobustPrune(FilteredVamanaIndex<graph_t>& index, GraphNode<graph_t>& p_node,std::set<graph_t>& V, float alpha,int R);

src/VIA/Algorithms/GreedySearch.cpp

@@ -118,7 +118,10 @@ GreedySearch(const VamanaIndex<graph_t>& index, const GraphNode<graph_t>& s, con
 
     // Limit the size of candidates to L by keeping the closest L elements to the query
     if (candidates.size() > static_cast<size_t>(L)) {
-      std::set<graph_t, EuclideanDistanceOrder<graph_t, query_t>> newCandidates{EuclideanDistanceOrder<graph_t, query_t>(xq, index.getDistanceMatrix(), execMode==CREATE)};
+      std::set<graph_t, EuclideanDistanceOrder<graph_t, query_t>> newCandidates{
+        EuclideanDistanceOrder<graph_t, query_t>(xq, index.getDistanceMatrix(), execMode==CREATE)
+      };
+
       for (auto candidate : candidates) {
         newCandidates.insert(candidate);
       }
@@ -137,7 +140,10 @@ GreedySearch(const VamanaIndex<graph_t>& index, const GraphNode<graph_t>& s, con
   }
 
   // Final selection of k closest candidates after main loop
-  std::set<graph_t, EuclideanDistanceOrder<graph_t, query_t>> newCandidates{EuclideanDistanceOrder<graph_t, query_t>(xq, index.getDistanceMatrix(), execMode==CREATE)};
+  std::set<graph_t, EuclideanDistanceOrder<graph_t, query_t>> newCandidates{
+    EuclideanDistanceOrder<graph_t, query_t>(xq, index.getDistanceMatrix(), execMode==CREATE)
+  };
+  
   for (auto candidate : candidates) {
     newCandidates.insert(candidate);
   }
@@ -153,6 +159,26 @@ GreedySearch(const VamanaIndex<graph_t>& index, const GraphNode<graph_t>& s, con
 
 }
 
+/**
+ * @brief Greedy search algorithm for finding the k nearest nodes in a graph relative to a query vector.
+ * 
+ * This function implements a greedy search that iteratively explores the closest nodes to the query vector.
+ * It maintains a candidate set of nodes to visit and a visited set of nodes already processed. This version
+ * of the function is used with a FilteredVamanaIndex, which applies additional filtering criteria to the search.
+ * 
+ * @param graph_t Type of data stored in the graph nodes
+ * @param query_t Type of the query vector
+ * @param index The FilteredVamanaIndex to search
+ * @param S Starting nodes for the search
+ * @param xq Query vector for distance computation
+ * @param k Number of nearest nodes to return
+ * @param L Maximum number of nodes in the candidate set
+ * @param queryFilters A vector of CategoricalAttributeFilter objects to apply to the search
+ * @param mode Execution mode for the algorithm
+ * 
+ * @return Pair of sets: the first set contains the k nearest nodes, and the second set contains all visited nodes
+ * 
+ */
 template <typename graph_t, typename query_t>
 std::pair<std::set<graph_t>, std::set<graph_t>> FilteredGreedySearch(
   const FilteredVamanaIndex<graph_t>& index, const std::vector<GraphNode<graph_t>>& S, const query_t& xq,  
@@ -241,7 +267,10 @@ std::pair<std::set<graph_t>, std::set<graph_t>> FilteredGreedySearch(
     // Limit the size of candidates to L by keeping the closest L elements to the query
     if (candidates.size() > static_cast<size_t>(L)) {
 
-      std::set<graph_t, EuclideanDistanceOrder<graph_t, query_t>> newCandidates{EuclideanDistanceOrder<graph_t, query_t>(xq, index.getDistanceMatrix(), mode==CREATE)};
+      std::set<graph_t, EuclideanDistanceOrder<graph_t, query_t>> newCandidates{
+        EuclideanDistanceOrder<graph_t, query_t>(xq, index.getDistanceMatrix(), mode==CREATE)
+      };
+
       for (auto candidate : candidates) {
         newCandidates.insert(candidate);
       }
@@ -261,7 +290,10 @@ std::pair<std::set<graph_t>, std::set<graph_t>> FilteredGreedySearch(
   }
 
   // Final selection of k closest candidates after main loop
-  std::set<graph_t, EuclideanDistanceOrder<graph_t, query_t>> newCandidates{EuclideanDistanceOrder<graph_t, query_t>(xq, index.getDistanceMatrix(), mode==CREATE)};
+  std::set<graph_t, EuclideanDistanceOrder<graph_t, query_t>> newCandidates{
+    EuclideanDistanceOrder<graph_t, query_t>(xq, index.getDistanceMatrix(), mode==CREATE)
+  };
+
   for (auto candidate : candidates) {
     newCandidates.insert(candidate);
   }

src/VIA/Algorithms/RobustPrune.cpp

@@ -60,22 +60,20 @@ void RobustPrune(VamanaIndex<graph_t>& index, GraphNode<graph_t>& p_node, std::s
   for (auto neighbor : *neighbors) {
     V.insert(neighbor);
   }
-  // Remove p_node itself from V
+
+  // Remove p_node itself from V, and clear the neighbors of p_node
   V.erase(p);
-  // Clear the neighbors of p_node
   p_node.clearNeighbors();
 
   // Continue pruning until V is empty or the desired number of neighbors is reached
   while (!V.empty()) {
 
-    // Find the closest neighbor to p_node in V
+    // Find the closest neighbor to p_node in V, and initialize the distance to p_star
     graph_t p_star = getSetItemAtIndex(0, V);
-    // float p_star_distance = euclideanDistance(p, p_star);
     float p_star_distance = index.getDistanceMatrix()[p.getIndex()][p_star.getIndex()];
 
     // Update p_star if a closer neighbor is found
     for (auto p_tone : V) {
-      // float currentDistance = euclideanDistance(p, p_tone);
       float currentDistance = index.getDistanceMatrix()[p.getIndex()][p_tone.getIndex()];
 
       if (currentDistance < p_star_distance) {
@@ -95,17 +93,34 @@ void RobustPrune(VamanaIndex<graph_t>& index, GraphNode<graph_t>& p_node, std::s
     // Create a copy of V to avoid modifying the original set during iteration
     std::set<graph_t> V_copy = V;
     for (auto p_tone : V_copy) {
+
       // Remove neighbors that are too far from p_star based on alpha and euclideanDistance
-      // if ((alpha * euclideanDistance(p_star, p_tone)) <= euclideanDistance(p, p_tone)) {
-      //   V.erase(p_tone);
-      // }
-      if ((alpha * index.getDistanceMatrix()[p_star.getIndex()][p_tone.getIndex()]) <= index.getDistanceMatrix()[p.getIndex()][p_tone.getIndex()]) {
+      double distance1 = index.getDistanceMatrix()[p_star.getIndex()][p_tone.getIndex()];
+      double distance2 = index.getDistanceMatrix()[p.getIndex()][p_tone.getIndex()];
+      
+      if ((alpha * distance1) <= distance2) {
         V.erase(p_tone);
       }
+
     }
   }
+
 }
 
+/**
+ * @brief Prunes the neighbors of a given node in a graph based on a robust pruning algorithm with filtering.
+ *
+ * This function modifies the neighbors of the given node `p_node` in the graph `G` by selecting
+ * a subset of neighbors that are within a certain distance threshold defined by `alpha` and `R`,
+ * while also applying additional filtering criteria.
+ *
+ * @tparam graph_t The type of the graph nodes.
+ * @param G The graph containing the node to be pruned.
+ * @param p_node The node whose neighbors are to be pruned.
+ * @param V A set of graph nodes to be considered for pruning.
+ * @param alpha A float value used as a multiplier for the distance threshold.
+ * @param R An integer specifying the maximum number of neighbors to retain.
+ */
 template <typename graph_t>
 void FilteredRobustPrune(FilteredVamanaIndex<graph_t>& index, GraphNode<graph_t>& p_node, std::set<graph_t>& V, float alpha, int R) {
 
@@ -118,23 +133,19 @@ void FilteredRobustPrune(FilteredVamanaIndex<graph_t>& index, GraphNode<graph_t>
     V.insert(neighbor);
   }
 
-  // Remove p_node itself from V
+  // Remove p_node itself from V, and clear the neighbors of p_node
   V.erase(p);
-
-  // Clear the neighbors of p_node
   p_node.clearNeighbors();
 
   // Continue pruning until V is empty or the desired number of neighbors is reached
   while (!V.empty()) {
 
     // Find the closest neighbor to p_node in V
     graph_t p_star = getSetItemAtIndex(0, V);
-    // float p_star_distance = euclideanDistance(p, p_star);
     float p_star_distance = index.getDistanceMatrix()[p.getIndex()][p_star.getIndex()];
 
     // Update p_star if a closer neighbor is found
     for (auto p_tone : V) {
-      // float currentDistance = euclideanDistance(p, p_tone);
       float currentDistance = index.getDistanceMatrix()[p.getIndex()][p_tone.getIndex()];
       if (currentDistance < p_star_distance) {
         p_star_distance = currentDistance;
@@ -166,18 +177,24 @@ void FilteredRobustPrune(FilteredVamanaIndex<graph_t>& index, GraphNode<graph_t>
         }
       }
 
-      // Remove nodes that do NOT satisfy the filtering condition
-      // if ((alpha * euclideanDistance(p_star, p_tone)) <= euclideanDistance(p, p_tone)) {
-      //   V.erase(p_tone);
-      // }
-      if ((alpha * index.getDistanceMatrix()[p_star.getIndex()][p_tone.getIndex()]) <= index.getDistanceMatrix()[p.getIndex()][p_tone.getIndex()]) {
+      // Remove neighbors that are too far from p_star based on alpha and euclideanDistance
+      double distance1 = index.getDistanceMatrix()[p_star.getIndex()][p_tone.getIndex()];
+      double distance2 = index.getDistanceMatrix()[p.getIndex()][p_tone.getIndex()];
+
+      if ((alpha * distance1) <= distance2) {
         V.erase(p_tone);
       }
 
     }
   }
+
 }
 
+
+/// Explicit instantiations for RobustPrune and FilteredRobustPrune
+
+
+// Explicit instantiation for RobustPrune with float data type and DataVector query type
 template void RobustPrune<DataVector<float>>(
   VamanaIndex<DataVector<float>>& index, 
   GraphNode<DataVector<float>>& p_node, 
@@ -186,6 +203,7 @@ template void RobustPrune<DataVector<float>>(
   int R
 );
 
+// Explicit instantiation for FilteredRobustPrune with float data type and DataVector query type
 template void RobustPrune<BaseDataVector<float>>(
   VamanaIndex<BaseDataVector<float>>& index, 
   GraphNode<BaseDataVector<float>>& p_node, 
@@ -194,6 +212,7 @@ template void RobustPrune<BaseDataVector<float>>(
   int R
 );
 
+// Explicit instantiation for FilteredRobustPrune with float data type and DataVector query type
 template void FilteredRobustPrune<BaseDataVector<float>>(
   FilteredVamanaIndex<BaseDataVector<float>>& index, 
   GraphNode<BaseDataVector<float>>& p_node, 

src/VIA/Algorithms/StichedVamanaIndex.cpp

@@ -87,16 +87,21 @@ void StichedVamanaIndex<vamana_t>::createGraph(
 
   });
 
-  // Filtered Robust Prune for every v in V (the nodes of the graph)
-  for (unsigned int i = 0; i < this->G.getNodesCount(); i++) {
 
-    GraphNode<vamana_t>* currentNode = this->G.getNode(i);
-    std::set<vamana_t> neighbors = currentNode->getNeighborsSet();
 
-    // Run Filtered Robust Prune for the current node and its neighbors
-    FilteredRobustPrune(*this, *currentNode, neighbors, alpha, R_stiched);
+  // NOTE: Without the Filtered Robust we get better results...
 
-  }
+
+  // // Filtered Robust Prune for every v in V (the nodes of the graph)
+  // for (unsigned int i = 0; i < this->G.getNodesCount(); i++) {
+
+  //   GraphNode<vamana_t>* currentNode = this->G.getNode(i);
+  //   std::set<vamana_t> neighbors = currentNode->getNeighborsSet();
+
+  //   // Run Filtered Robust Prune for the current node and its neighbors
+  //   FilteredRobustPrune(*this, *currentNode, neighbors, alpha, R_stiched);
+
+  // }
 
   // Free up the memory allocated for the distance matrix
   for (unsigned int i = 0; i < n; i++) {