Merge pull request #3231 from AlexandreSinger/feature-appack-update

[APPack] Tuned Up APPack Code

Author: AlexandreSinger

doc/src/vpr/command_line_usage.rst

@@ -1384,6 +1384,41 @@ Analytical Placement is generally split into three stages:
 
     **Default:** ``auto``
 
+.. option:: --appack_unrelated_clustering_args { auto | <regex>:<float>,<float> }
+
+   Sets parameters used for unrelated clustering (the max search distance and max attempts)
+   used by APPack.
+   APPack uses the primitive-level placement produced by the
+   global placer to cluster primitives together. APPack uses this information
+   to help increase the density of clusters (if needed) by searching for
+   unrelated molecules to pack together. It does this by searching out from
+   the centroid of the cluster being created until it finds a valid molecule.
+   If a valid molecule is found, but it fails, the packer may do another attempt
+   (up to a maximum number of attempts).
+   This argument allows the user to select the maximum distance the code will
+   search and how many attempts it will try to search for each cluster.
+
+   When this option is set to auto, VPR will select good values for these
+   parameters based on the primitives contained within each logical block type.
+
+   This option is similar to the appack_max_dist_th argument, where the
+   parameters are passed by the user in the form <regex>:<float>,<float> where
+   regex is used to match the name of the logical block type to set, the
+   first float is the max unrelated tile distance, and the second float
+   is the max unrelated clustering attempts.
+
+   For example:
+
+     .. code-block:: none
+
+        --appack_max_dist_th "clb|LAB:10,5"
+
+   This will set all of the logical block types to their "auto" parameters, except
+   for logical blocks with the name clb/LAB which will have a max search distance of
+   10 tiles and a maximum of 5 unrelated clustering attempts.
+
+    **Default:** ``auto``
+
 .. option:: --ap_high_fanout_threshold <int>
 
     Defines the threshold for high fanout nets within AP flow.

libs/libarchfpga/src/arch_util.cpp

@@ -1029,6 +1029,32 @@ bool pb_type_contains_blif_model(const t_pb_type* pb_type, const std::string& bl
     return false;
 }
 
+bool pb_type_contains_memory_pbs(const t_pb_type* pb_type) {
+    // TODO: This should be a graph traversal instead of a recursive function.
+
+    if (pb_type == nullptr)
+        return false;
+
+    // Check if this pb_type is a memory class. If so return true. This acts as
+    // a base case for the recursion.
+    if (pb_type->class_type == e_pb_type_class::MEMORY_CLASS)
+        return true;
+
+    // Go through all modes of this pb_type and check if any of those modes'
+    // children have memory pb_types, if so return true.
+    for (int mode_idx = 0; mode_idx < pb_type->num_modes; mode_idx++) {
+        const t_mode& mode = pb_type->modes[mode_idx];
+        for (int child_idx = 0; child_idx < mode.num_pb_type_children; child_idx++) {
+            if (pb_type_contains_memory_pbs(&mode.pb_type_children[child_idx]))
+                return true;
+        }
+    }
+
+    // If this pb_type is not a memory and its modes do not have memory pbs in
+    // them, then this pb_type is not a memory.
+    return false;
+}
+
 bool has_sequential_annotation(const t_pb_type* pb_type, const t_model_ports* port, enum e_pin_to_pin_delay_annotations annot_type) {
     VTR_ASSERT(annot_type == E_ANNOT_PIN_TO_PIN_DELAY_TSETUP
                || annot_type == E_ANNOT_PIN_TO_PIN_DELAY_THOLD

libs/libarchfpga/src/arch_util.h

@@ -96,6 +96,12 @@ bool block_type_contains_blif_model(t_logical_block_type_ptr type, const std::st
 //Returns true of a pb_type (or it's children) contain the specified blif model name
 bool pb_type_contains_blif_model(const t_pb_type* pb_type, const std::string& blif_model_name);
 
+/**
+ * @brief Recursive helper method to deduce if the given pb_type is or contains
+ *        pb_types which are of the memory class.
+ */
+bool pb_type_contains_memory_pbs(const t_pb_type* pb_type);
+
 bool has_sequential_annotation(const t_pb_type* pb_type, const t_model_ports* port, enum e_pin_to_pin_delay_annotations annot_type);
 bool has_combinational_annotation(const t_pb_type* pb_type, std::string_view in_port, std::string_view out_port);
 

vpr/src/analytical_place/analytical_solver.cpp

@@ -877,6 +877,17 @@ std::pair<double, double> B2BSolver::get_delay_derivative(APBlockId driver_blk,
     VTR_ASSERT_SAFE_MSG(p_placement.block_layer_nums[driver_blk] == layer_num && p_placement.block_layer_nums[sink_blk] == layer_num,
                         "3D FPGAs not supported yet in the B2B solver");
 
+    // Special case: If the distance between the driver and sink is as large as
+    // the device, we cannot take the forward difference (since it will go off
+    // chip). We can still approximate the derivative by taking one tile step
+    // back and getting the central difference at that point. This avoids the
+    // boundary condition, which should be very rare to occur.
+    // TODO: Investigate better ways of doing this.
+    if ((int)flat_dx + 1 > (int)device_grid_width_ - 1)
+        flat_dx = device_grid_width_ - 2;
+    if ((int)flat_dy + 1 > (int)device_grid_height_ - 1)
+        flat_dy = device_grid_height_ - 2;
+
     // Get the physical tile location of the legalized driver block. The PlaceDelayModel
     // may use this position to determine the physical tile the wire is coming from.
     // When the placement is being solved, the driver may be moved to a physical tile
@@ -899,8 +910,10 @@ std::pair<double, double> B2BSolver::get_delay_derivative(APBlockId driver_blk,
 
     int tile_dx = sink_block_loc.x - driver_block_loc.x;
     int tile_dy = sink_block_loc.y - driver_block_loc.y;
-    VTR_ASSERT_SAFE(tile_dx < (int)device_grid_width_);
-    VTR_ASSERT_SAFE(tile_dy < (int)device_grid_height_);
+    // The following asserts are to protect the "delay" calls used for the forward
+    // difference calculations below.
+    VTR_ASSERT_SAFE(tile_dx + 1 < (int)device_grid_width_);
+    VTR_ASSERT_SAFE(tile_dy + 1 < (int)device_grid_height_);
 
     // Get the delay of a wire going from the given driver block location to the
     // given sink block location. This should only use the physical tile type of

vpr/src/base/read_options.cpp

@@ -2010,6 +2010,32 @@ argparse::ArgumentParser create_arg_parser(const std::string& prog_name, t_optio
         .default_value({"auto"})
         .show_in(argparse::ShowIn::HELP_ONLY);
 
+    ap_grp.add_argument(args.appack_unrelated_clustering_args, "--appack_unrelated_clustering_args")
+        .help(
+            "Sets parameters used for unrelated clustering (the max search distance and max attempts) "
+            "used by APPack. "
+            "APPack uses the primitive-level placement produced by the "
+            "global placer to cluster primitives together. APPack uses this information "
+            "to help increase the density of clusters (if needed) by searching for "
+            "unrelated molecules to pack together. It does this by searching out from "
+            "the centroid of the cluster being created until it finds a valid molecule. "
+            "If a valid molecule is found, but it fails, the packer may do another attempt "
+            "(up to a maximum number of attempts). "
+            "This argument allows the user to select the maximum distance the code will "
+            "search and how many attempts it will try to search for each cluster."
+            "\n"
+            "When this option is set to auto, VPR will select good values for these "
+            "parameters based on the primitives contained within each logical block type."
+            "\n"
+            "This option is similar to the appack_max_dist_th argument, where the "
+            "parameters are passed by the user in the form <regex>:<float>,<float> where "
+            "regex is used to match the name of the logical block type to set, the "
+            "first float is the max unrelated tile distance, and the second float "
+            "is the max unrelated clustering attempts.")
+        .nargs('+')
+        .default_value({"auto"})
+        .show_in(argparse::ShowIn::HELP_ONLY);
+
     ap_grp.add_argument<int>(args.ap_verbosity, "--ap_verbosity")
         .help(
             "Controls how verbose the AP flow's log messages will be. Higher "

vpr/src/base/read_options.h

@@ -106,6 +106,7 @@ struct t_options {
     argparse::ArgValue<e_ap_detailed_placer> ap_detailed_placer;
     argparse::ArgValue<std::vector<std::string>> ap_partial_legalizer_target_density;
     argparse::ArgValue<std::vector<std::string>> appack_max_dist_th;
+    argparse::ArgValue<std::vector<std::string>> appack_unrelated_clustering_args;
     argparse::ArgValue<int> ap_verbosity;
     argparse::ArgValue<float> ap_timing_tradeoff;
     argparse::ArgValue<int> ap_high_fanout_threshold;

vpr/src/base/setup_vpr.cpp

@@ -586,6 +586,7 @@ void setup_ap_opts(const t_options& options,
     apOpts.ap_high_fanout_threshold = options.ap_high_fanout_threshold.value();
     apOpts.ap_partial_legalizer_target_density = options.ap_partial_legalizer_target_density.value();
     apOpts.appack_max_dist_th = options.appack_max_dist_th.value();
+    apOpts.appack_unrelated_clustering_args = options.appack_unrelated_clustering_args.value();
     apOpts.num_threads = options.num_workers.value();
     apOpts.log_verbosity = options.ap_verbosity.value();
     apOpts.generate_mass_report = options.ap_generate_mass_report.value();

vpr/src/base/vpr_types.h

@@ -1128,6 +1128,9 @@ struct t_placer_opts {
  *   @param appack_max_dist_th
  *              Array of string passed by the user to configure the max candidate
  *              distance thresholds.
+ *   @param appack_unrelated_clustering_args
+ *              Array of strings passed by the user to configure the unrelated
+ *              clustering parameters used by APPack.
  *   @param num_threads
  *              The number of threads the AP flow can use.
  *   @param log_verbosity
@@ -1155,6 +1158,8 @@ struct t_ap_opts {
 
     std::vector<std::string> appack_max_dist_th;
 
+    std::vector<std::string> appack_unrelated_clustering_args;
+
     unsigned num_threads;
 
     int log_verbosity;

vpr/src/pack/appack_context.h

@@ -8,6 +8,7 @@
  */
 
 #include "appack_max_dist_th_manager.h"
+#include "appack_unrelated_clustering_manager.h"
 #include "device_grid.h"
 #include "flat_placement_types.h"
 #include "physical_types.h"
@@ -68,43 +69,6 @@ struct t_appack_options {
     // Squared scaling factor for the quadratic decay term.
     static constexpr float quad_fac_sqr = (1.0f - attenuation_th) / (dist_th * dist_th);
 
-    // =========== Unrelated clustering ==================================== //
-    // After searching for candidates by connectivity and timing, the user may
-    // turn on unrelated clustering, which will allow molecules which are
-    // unrelated to the cluster being created to be attempted to be packed in.
-    // APPack uses flat placement information to decide which unrelated
-    // molecules to try.
-
-    // APPack will search for unrelated molecules in the tile which contains
-    // the flat location of the cluster. It will then look farther out, tile
-    // by tile. This parameter is the maximum distance from the cluster's tile
-    // that APPack will search. Setting this to 0 would only allow APPack to
-    // search within the cluster's tile. Setting this to a higher number would
-    // allow APPack to search farther away; but may bring in molecules which
-    // do not "want" to be in the cluster.
-    //
-    //      [block_type_index] -> unrelated_tile_distance
-    std::vector<float> max_unrelated_tile_distance;
-
-    // Unrelated clustering occurs after all other candidate selection methods
-    // have failed. This attempts to cluster in molecules that are not attracted
-    // (using the packer's heuristics) to the molecules within a given cluster.
-    // This parameter sets how many times we will attempt unrelated
-    // clustering between failures of unrelated clustering. If a molecule used
-    // for unrelated clustering failed to cluster it will not be attempted
-    // again for that cluster (note: if it succeeds, the number of attempts get
-    // reset).
-    // NOTE: A similar option exists in the candidate selector class. This was
-    //       duplicated since it is very likely that APPack would need a
-    //       different value for this option than the non-APPack flow.
-    //
-    //      [block_type_index] -> max_unrelated_attempts
-    std::vector<int> max_unrelated_clustering_attempts;
-    // By default, we perform 10 unrelated clustering attempts. This is used
-    // to aggresivly resolve density while adhering to the GP solution as much
-    // as possible.
-    static constexpr int default_max_unrelated_clustering_attempts = 10;
-
     // TODO: Investigate adding flat placement info to seed selection.
 };
 
@@ -126,22 +90,16 @@ struct APPackContext : public Context {
         , flat_placement_info(fplace_info) {
 
         // If the flat placement info has been provided, calculate max distance
-        // thresholds for all logical block types.
+        // thresholds for all logical block types and the unrelated clustering
+        // arguments.
         if (fplace_info.valid) {
             max_distance_threshold_manager.init(ap_opts.appack_max_dist_th,
                                                 logical_block_types,
                                                 device_grid);
-        }
 
-        // Set the max unrelated tile distances for all logical block types.
-        // By default, we set this to a low value to only allow unrelated molecules
-        // that are very close to the cluster being created.
-        // NOTE: Molecules within the same tile as the centroid are considered to have
-        //       0 distance. The distance is computed relative to the bounds of the
-        //       tile containing the centroid.
-        appack_options.max_unrelated_tile_distance.resize(logical_block_types.size(), 1.0);
-        appack_options.max_unrelated_clustering_attempts.resize(logical_block_types.size(),
-                                                                appack_options.default_max_unrelated_clustering_attempts);
+            unrelated_clustering_manager.init(ap_opts.appack_unrelated_clustering_args,
+                                              logical_block_types);
+        }
     }
 
     /**
@@ -157,4 +115,9 @@ struct APPackContext : public Context {
     // When selecting candidates, what distance from the cluster will we
     // consider? Any candidate beyond this distance will not be proposed.
     APPackMaxDistThManager max_distance_threshold_manager;
+
+    // When performing unrelated clustering, the following manager class decides
+    // how far we should search for unrelated candidates and how many attempts
+    // we should perform.
+    APPackUnrelatedClusteringManager unrelated_clustering_manager;
 };

vpr/src/pack/appack_max_dist_th_manager.cpp

@@ -2,14 +2,15 @@
  * @file
  * @author  Alex Singer
  * @date    May 2025
- * @breif   Definition of the max distance threshold manager class.
+ * @brief   Definition of the max distance threshold manager class.
  */
 
 #include "appack_max_dist_th_manager.h"
 #include <string>
 #include <unordered_map>
 #include <vector>
 #include "ap_argparse_utils.h"
+#include "arch_util.h"
 #include "device_grid.h"
 #include "physical_types.h"
 #include "physical_types_util.h"
@@ -18,14 +19,6 @@
 #include "vtr_assert.h"
 #include "vtr_log.h"
 
-/**
- * @brief Recursive helper method to deduce if the given pb_type is or contains
- *        pb_types which are of the memory class.
- *
- * TODO: This should be a graph traversal instead of a recursive function.
- */
-static bool has_memory_pbs(const t_pb_type* pb_type);
-
 void APPackMaxDistThManager::init(const std::vector<std::string>& max_dist_ths,
                                   const std::vector<t_logical_block_type>& logical_block_types,
                                   const DeviceGrid& device_grid) {
@@ -85,7 +78,7 @@ void APPackMaxDistThManager::auto_set_max_distance_thresholds(const std::vector<
             continue;
 
         // Find which type(s) this logical block type looks like.
-        bool has_memory = has_memory_pbs(lb_ty.pb_type);
+        bool has_memory = pb_type_contains_memory_pbs(lb_ty.pb_type);
         bool is_logic_block_type = (lb_ty.index == logic_block_type->index);
         bool is_io_block = pick_physical_type(&lb_ty)->is_io();
 
@@ -113,30 +106,6 @@ void APPackMaxDistThManager::auto_set_max_distance_thresholds(const std::vector<
     }
 }
 
-static bool has_memory_pbs(const t_pb_type* pb_type) {
-    if (pb_type == nullptr)
-        return false;
-
-    // Check if this pb_type is a memory class. If so return true. This acts as
-    // a base case for the recursion.
-    if (pb_type->class_type == e_pb_type_class::MEMORY_CLASS)
-        return true;
-
-    // Go through all modes of this pb_type and check if any of those modes'
-    // children have memory pb_types, if so return true.
-    for (int mode_idx = 0; mode_idx < pb_type->num_modes; mode_idx++) {
-        const t_mode& mode = pb_type->modes[mode_idx];
-        for (int child_idx = 0; child_idx < mode.num_pb_type_children; child_idx++) {
-            if (has_memory_pbs(&mode.pb_type_children[child_idx]))
-                return true;
-        }
-    }
-
-    // If this pb_type is not a memory and its modes do not have memory pbs in
-    // them, then this pb_type is not a memory.
-    return false;
-}
-
 void APPackMaxDistThManager::set_max_distance_thresholds_from_strings(
     const std::vector<std::string>& max_dist_ths,
     const std::vector<t_logical_block_type>& logical_block_types) {