add comments

Author: soheilshahrouz

vpr/src/place/net_cost_handler.cpp

@@ -155,24 +155,12 @@ NetCostHandler::NetCostHandler(const t_placer_opts& placer_opts,
 }
 
 void NetCostHandler::alloc_and_load_chan_w_factors_for_place_cost_(float place_cost_exp) {
-    /* Allocates and loads the chanx_place_cost_fac and chany_place_cost_fac *
-     * arrays with the inverse of the average number of tracks per channel   *
-     * between [subhigh] and [sublow].  This is only useful for the cost     *
-     * function that takes the length of the net bounding box in each        *
-     * dimension divided by the average number of tracks in that direction.  *
-     * For other cost functions, you don't have to bother calling this       *
-     * routine; when using the cost function described above, however, you   *
-     * must always call this routine after you call init_chan and before     *
-     * you do any placement cost determination. The place_cost_exp factor    *
-     * specifies to what power the width of the channel should be taken --   *
-     * larger numbers make narrower channels more expensive.                 */
-
     auto& device_ctx = g_vpr_ctx.device();
 
     const size_t grid_height = device_ctx.grid.height();
     const size_t grid_width = device_ctx.grid.width();
 
-    /* Access arrays below as chan?_place_cost_fac[subhigh][sublow]. Since subhigh must be greater than or
+    /* Access arrays below as chan?_place_cost_fac_(subhigh, sublow). Since subhigh must be greater than or
      * equal to sublow, we will only access the lower half of a matrix, but we allocate the whole matrix anyway
      * for simplicity, so we can use the vtr utility matrix functions. */
     chanx_place_cost_fac_.resize({grid_height + 1, grid_height + 1});
@@ -189,7 +177,7 @@ void NetCostHandler::alloc_and_load_chan_w_factors_for_place_cost_(float place_c
     }
 
     /* Now compute the inverse of the average number of tracks per channel *
-     * between high and low.  The cost function divides by the average     *
+     * between high and low. The cost function divides by the average      *
      * number of tracks per channel, so by storing the inverse I convert   *
      * this to a faster multiplication.  Take this final number to the     *
      * place_cost_exp power -- numbers other than one mean this is no      *
@@ -1400,6 +1388,7 @@ void NetCostHandler::get_layer_bb_from_scratch_(ClusterNetId net_id,
     }
 }
 
+
 double NetCostHandler::get_net_cube_bb_cost_(ClusterNetId net_id, bool use_ts) {
     // Finds the cost due to one net by looking at its coordinate bounding box.
     auto& cluster_ctx = g_vpr_ctx.clustering();
@@ -1415,6 +1404,12 @@ double NetCostHandler::get_net_cube_bb_cost_(ClusterNetId net_id, bool use_ts) {
     /* Cost = wire length along channel * cross_count / average      *
      * channel capacity.   Do this for x, then y direction and add.  */
 
+    /* For average channel width factor, I'll always include the channel immediately
+     * below and the channel immediately to the left of the bounding box, so both bb.ymin
+     * and bb.xmin are subtracted by 1 before being used as indices of chan?_place_cost_fac_.
+     * chan?_place_cost_fac_ objects can handle -1 indices internally.
+     */
+
     double ncost;
     ncost = (bb.xmax - bb.xmin + 1) * crossing * chanx_place_cost_fac_(bb.ymax, bb.ymin - 1);
     ncost += (bb.ymax - bb.ymin + 1) * crossing * chany_place_cost_fac_(bb.xmax, bb.xmin - 1);
@@ -1452,6 +1447,12 @@ double NetCostHandler::get_net_per_layer_bb_cost_(ClusterNetId net_id , bool use
         /* Cost = wire length along channel * cross_count / average      *
          * channel capacity.   Do this for x, then y direction and add.  */
 
+        /* For average channel width factor, I'll always include the channel immediately
+         * below and the channel immediately to the left of the bounding box, so both bb.ymin
+         * and bb.xmin are subtracted by 1 before being used as indices of chan?_place_cost_fac_.
+         * chan?_place_cost_fac_ objects can handle -1 indices internally.
+         */
+
         ncost += (bb[layer_num].xmax - bb[layer_num].xmin + 1) * crossing
                  * chanx_place_cost_fac_(bb[layer_num].ymax, bb[layer_num].ymin - 1);
 

vpr/src/place/net_cost_handler.h

@@ -190,10 +190,28 @@ class NetCostHandler {
     vtr::vector<ClusterNetId, double> proposed_net_cost_;
     vtr::vector<ClusterNetId, NetUpdateState> bb_update_status_;
 
+    /**
+     * @brief This class is used to store the inverse of average channel
+     * width between two channels inclusive. The difference of this class
+     * with vtr::NdMatrix<float, 2> is that its index spaces starts from -1.
+     * When the inverse average channel width is factored in, the channel
+     * immediately below and the channel immediately to the left of the
+     * bounding box are also considered. This class makes sure that when
+     * the left and bottom edges of the bounding boxes are moved by one unit,
+     * the indices used to access inverse average channel width are still valid.
+     */
     class ChanPlaceCostFacContainer : public vtr::NdMatrix<float, 2> {
       public:
-        inline float& operator()(int i, int j) {
-            return this->operator[]((size_t)(i+1)).operator[]((size_t)(j+1));
+        /**
+         * @brief Returns the inverse average channel width between channels low
+         * and high inclusive.
+         * @param high The high channel number.
+         * @param low The low channel number.
+         * @return The inverse average channel width between the given channel
+         * numbers.
+         */
+        inline float& operator()(int high, int low) {
+            return this->operator[]((size_t)(high + 1)).operator[]((size_t)(low + 1));
         }
 
       private:
@@ -203,14 +221,14 @@ class NetCostHandler {
     /**
      * @brief Matrices below are used to precompute the inverse of the average
      * number of tracks per channel between [subhigh] and [sublow].  Access
-     * them as chan?_place_cost_fac[subhigh][sublow].  They are used to
+     * them as chan?_place_cost_fac(subhigh, sublow).  They are used to
      * speed up the computation of the cost function that takes the length
      * of the net bounding box in each dimension, divided by the average
      * number of tracks in that direction; for other cost functions they
      * will never be used.
      */
-    ChanPlaceCostFacContainer chanx_place_cost_fac_; // [0...device_ctx.grid.width()-2]
-    ChanPlaceCostFacContainer chany_place_cost_fac_; // [0...device_ctx.grid.height()-2]
+    ChanPlaceCostFacContainer chanx_place_cost_fac_; // [-1...device_ctx.grid.width()-1]
+    ChanPlaceCostFacContainer chany_place_cost_fac_; // [-1...device_ctx.grid.height()-1]
 
 
   private:
@@ -253,6 +271,13 @@ class NetCostHandler {
     /**
      * @brief Allocates and loads the chanx_place_cost_fac and chany_place_cost_fac arrays with the inverse of
      * the average number of tracks per channel between [subhigh] and [sublow].
+     *
+     * @details This is only useful for the cost function that takes the length of the net bounding box in each
+     * dimension divided by the average number of tracks in that direction. For other cost functions, you don't
+     * have to bother calling this routine; when using the cost function described above, however, you must always
+     * call this routine before you do any placement cost determination. The place_cost_exp factor specifies to
+     * what power the width of the channel should be taken -- larger numbers make narrower channels more expensive.
+     *
      * @param place_cost_exp It is an exponent to which you take the average inverse channel capacity;
      * a higher value would favour wider channels more over narrower channels during placement (usually we use 1).
      */