Add comments requested in #1289

Signed-off-by: Dusty DeWeese <[email protected]>

Author: HackerFoo

vpr/src/route/edge_groups.cpp

@@ -13,7 +13,7 @@ bool EdgeGroups::add_non_config_edge(int from_node, int to_node) {
 // will form groups of nodes that are connected via non-configurable
 // edges.
 void EdgeGroups::create_sets() {
-    rr_non_config_node_sets_map_.clear();
+    rr_non_config_node_sets_.clear();
 
     // https://en.wikipedia.org/wiki/Component_(graph_theory)#Algorithms
     std::vector<size_t> group_size;
@@ -34,20 +34,20 @@ void EdgeGroups::create_sets() {
     }
 
     // Create compact set of sets.
-    rr_non_config_node_sets_map_.resize(group_size.size());
+    rr_non_config_node_sets_.resize(group_size.size());
     for (size_t i = 0; i < group_size.size(); i++) {
-        rr_non_config_node_sets_map_[i].reserve(group_size[i]);
+        rr_non_config_node_sets_[i].reserve(group_size[i]);
     }
     for (const auto& node : graph_) {
-        rr_non_config_node_sets_map_[node.second.set].push_back(node.first);
+        rr_non_config_node_sets_[node.second.set].push_back(node.first);
     }
 }
 
 // Create t_non_configurable_rr_sets from set data.
 // NOTE: The stored graph is undirected, so this may generate reverse edges that don't exist.
 t_non_configurable_rr_sets EdgeGroups::output_sets() {
     t_non_configurable_rr_sets sets;
-    for (const auto& nodes : rr_non_config_node_sets_map_) {
+    for (const auto& nodes : rr_non_config_node_sets_) {
         std::set<t_node_edge> edge_set;
         std::set<int> node_set(nodes.begin(), nodes.end());
 
@@ -67,7 +67,7 @@ t_non_configurable_rr_sets EdgeGroups::output_sets() {
 // Set device context structures for non-configurable node sets.
 void EdgeGroups::set_device_context(DeviceContext& device_ctx) {
     std::vector<std::vector<int>> rr_non_config_node_sets;
-    for (const auto& item : rr_non_config_node_sets_map_) {
+    for (const auto& item : rr_non_config_node_sets_) {
         rr_non_config_node_sets.emplace_back(std::move(item));
     }
 

vpr/src/route/edge_groups.h

@@ -9,7 +9,16 @@
 #include "vpr_types.h"
 #include "vpr_context.h"
 
-// Class for building a group of connected edges.
+// Class for identifying the components of a graph as sets of nodes.
+// Each node is reachable from any other node in the same set, and
+// unreachable from nodes in any other set.
+// Note that edges are undirected.
+//
+// This is used by the router to group nodes connected by
+// non-configurable edges, because a connection to one node
+// must connect them all.
+//
+// https://en.wikipedia.org/wiki/Component_(graph_theory)
 class EdgeGroups {
   public:
     EdgeGroups() {}
@@ -33,8 +42,8 @@ class EdgeGroups {
 
   private:
     struct node_data {
-        std::unordered_set<int> edges;
-        int set = OPEN;
+        std::unordered_set<int> edges; // Set of indices into graph_
+        int set = OPEN;                // Index into rr_non_config_node_sets_
     };
 
     // Perform a DFS traversal marking everything reachable with the same set id
@@ -43,8 +52,9 @@ class EdgeGroups {
     // Set of non-configurable edges.
     std::unordered_map<int, node_data> graph_;
 
-    // Compact set of node sets. Map key is arbitrary.
-    std::vector<std::vector<int>> rr_non_config_node_sets_map_;
+    // Connected components, representing nodes connected by non-configurable edges.
+    // Order is arbitrary.
+    std::vector<std::vector<int>> rr_non_config_node_sets_;
 };
 
 #endif

vpr/test/test_edge_groups.cpp

@@ -15,6 +15,8 @@ TEST_CASE("edge_groups_create_sets", "[vpr]") {
     // Construct a set of edges that result in these connected sets
     std::vector<std::set<int>> connected_sets{{{1, 2, 3, 4, 5, 6, 7, 8},
                                                {9, 0}}};
+
+    // Build chains from the given connected sets
     int max_node_id = 0;
     std::vector<std::pair<int, int>> edges;
     for (auto set : connected_sets) {
@@ -30,9 +32,14 @@ TEST_CASE("edge_groups_create_sets", "[vpr]") {
 
     // Build the id map for node IDs
     std::vector<int> nodes(max_node_id + 1);
+
+    // Initialize nodes to [0, 1, ..., max_node_id]
     std::iota(nodes.begin(), nodes.end(), 0);
+
+    // Create a Mersenne Twister psuedo-random number generator with seed 1
     std::mt19937 g(1);
 
+    // Run the test many times, the PRNG will give differently shuffled inputs
     for (int i = 0; i < 1000; i++) {
         // Shuffle node IDs
         auto random_nodes = nodes;