doxygen comments for congestion related matrices in NetCostHandler

Author: soheilshahrouz

vpr/src/base/stats.h

@@ -28,7 +28,7 @@ void routing_stats(const Netlist<>& net_list,
 /**
  * @brief Calculates the routing channel width at each grid location.
  *
- * Iterates through all RR nodes and counts how many wires pass through each (x, y) location
+ * Iterates through all RR nodes and counts how many wires pass through each (layer, x, y) location
  * for both horizontal (CHANX) and vertical (CHANY) channels.
  *
  * @return A pair of 3D matrices:
@@ -73,6 +73,8 @@ void print_device_utilization(const float target_device_utilization);
  *   - Occupancy percentage (occupancy / capacity)
  *   - Channel capacity
  *
+ *   TODO: extend to 3D
+ *
  * @param filename      Output file path.
  * @param occupancy     Matrix of occupancy counts.
  * @param capacity_list List of channel capacities (per y for chanx, per x for chany).

vpr/src/place/net_cost_handler.cpp

@@ -1842,7 +1842,7 @@ double NetCostHandler::estimate_routing_chan_util(bool compute_congestion_cost /
     congestion_modeling_started_ = true;
 
     double cong_cost = 0.;
-    // Compute congestion cost using recomputed bounding boxes and channel utilization map
+    // Compute congestion cost using computed bounding boxes and channel utilization map
     if (compute_congestion_cost) {
         for (ClusterNetId net_id : cluster_ctx.clb_nlist.nets()) {
             if (!cluster_ctx.clb_nlist.net_is_ignored(net_id)) {

vpr/src/place/net_cost_handler.h

@@ -143,15 +143,22 @@ class NetCostHandler {
     /**
      * @brief Estimates routing channel utilization and computes the congestion cost
      * for each net.
+     * @param compute_congestion_cost Indicates whether computing congestion cost is needed.
      *
      * For each net, distributes estimated wirelength across its bounding box
      * and accumulates demand for different routing channels. Normalizes by channel widths
      * (e.g. a value of 0.5 means 50% of the wiring in a channel is expected to be used).
      *
-     * @return Total congestion cost.
+     * @note This method assumes that net bounding boxes are already computed.
+     *
+     * @return Total congestion cost if requested.
      */
     double estimate_routing_chan_util(bool compute_congestion_cost = true);
 
+    /**
+     * @brief Returns the estimated routing channel usage for each location in the grid.
+     *        The channel usage estimates are computed in estimate_routing_chan_util().
+     */
     const ChannelData<vtr::NdMatrix<double, 3>>& get_chan_util() const;
 
   private:
@@ -268,10 +275,21 @@ class NetCostHandler {
      */
      ChannelData<vtr::PrefixSum1D<int>> acc_chan_width_;
 
-     ChannelData<vtr::PrefixSum2D<double>> acc_chan_util_;
-
+     /**
+     * @brief Estimated routing usage per channel segment,
+     *        indexed by [layer][x][y]. Values represent normalized wire demand
+     *        contribution from all nets distributed over their bounding boxes.
+     */
      ChannelData<vtr::NdMatrix<double, 3>> chan_util_;
 
+     /**
+      * @brief Accumulated (prefix sum) channel utilization in each direction (x/y),
+      *        on the base layer. Enables fast computation of average utilization
+      *        over a net’s bounding box during congestion cost estimation.
+      */
+     ChannelData<vtr::PrefixSum2D<double>> acc_chan_util_;
+
+     /// Available channel width per grid location, indexed by [layer][x][y].
      ChannelData<vtr::NdMatrix<int, 3>> chan_width_;
 
     /**

vpr/src/route/route_utilization.cpp

@@ -23,7 +23,7 @@ ChannelData<vtr::NdMatrix<double, 3>> RoutingChanUtilEstimator::estimate_routing
         // Compute net bounding boxes
         net_cost_handler_->comp_bb_cong_cost(e_cost_methods::NORMAL);
 
-        // Estimate routing channel utilization using
+        // Estimate routing channel usage
         net_cost_handler_->estimate_routing_chan_util(/*compute_congestion_cost=*/false);
 
         return net_cost_handler_->get_chan_util();