[APPack] Updated Max Candidate Distance Interface

The max candidate distance is used by APPack to decide which molecules
to ignore when packing, based on their distance from the cluster being
formed.

Cleaned up the interface of this by pre-computing the max candidate
distance of all logical blocks ahead of time and reading from these
pre-computed values during packing.

Added a command-line option to allow the user to override some or all of
these max distance thresholds. By default, VPR will select values based
on the type of logical block and the primitives it contains.

Fixed issue with APPack creating too many IO blocks for some circuits
due to the max candidate distance thresholds for IO blocks being too
low.

More tuning should be done on these values once the mass legalizer has
been cleaned up a bit more.

Author: AlexandreSinger

doc/src/vpr/command_line_usage.rst

@@ -1270,6 +1270,49 @@ Analytical Placement is generally split into three stages:
 
     **Default:** ``0.5``
 
+.. option:: --appack_max_dist_th { auto | <regex>:<float>,<float> }
+
+   Sets the maximum candidate distance thresholds for the logical block types
+   used by APPack. APPack uses the primitive-level placement produced by the
+   global placer to cluster primitives together. APPack uses the thresholds
+   here to ignore primitives which are too far away from the cluster being formed.
+
+   When this option is set to "auto", VPR will select good values for these
+   thresholds based on the primitives contained within each logical block type.
+
+   Using this option, the user can set the maximum candidate distance threshold
+   of logical block types to something else. The strings passed in by the user
+   should be of the form ``<regex>:<float>,<float>`` where the regex string is
+   used to match the name of the logical block type to set, the first float
+   is a scaling term, and the second float is an offset. The threshold will
+   be set to max(scale * (W + H), offset), where W and H are the width and height
+   of the device. This allows the user to specify a threshold based on the
+   size of the device, while also preventing the number from going below "offset".
+   When multiple strings are provided, the thresholds are set from left to right,
+   and any logical block types which have been unset will be set to their "auto"
+   values.
+
+   For example:
+
+     .. code-block:: none
+
+        --appack_max_dist_th .*:0.1,0 "clb|memory:0,5"
+
+   Would set all logical block types to be 0.1 * (W + H), except for the clb and
+   memory block, which will be set to a fixed value of 5.
+
+   Another example:
+
+     .. code-block:: none
+
+        --appack_max_dist_th "clb|LAB:0.2,5"
+
+   This will set all of the logical block types to their "auto" thresholds, except
+   for logical blocks with the name clb/LAB which will be set to 0.2 * (W + H) or
+   5 (whichever is larger).
+
+    **Default:** ``auto``
+
 .. option:: --ap_verbosity <int>
 
     Controls the verbosity of the AP flow output.

vpr/src/analytical_place/full_legalizer.cpp

@@ -520,6 +520,7 @@ void APPack::legalize(const PartialPlacement& p_placement) {
     // Run the Packer stage with the flat placement as a hint.
     try_pack(vpr_setup_.PackerOpts,
              vpr_setup_.AnalysisOpts,
+             vpr_setup_.APOpts,
              arch_,
              vpr_setup_.PackerRRGraph,
              prepacker_,

vpr/src/base/SetupVPR.cpp

@@ -550,6 +550,7 @@ void SetupAPOpts(const t_options& options,
     apOpts.full_legalizer_type = options.ap_full_legalizer.value();
     apOpts.detailed_placer_type = options.ap_detailed_placer.value();
     apOpts.ap_timing_tradeoff = options.ap_timing_tradeoff.value();
+    apOpts.appack_max_dist_th = options.appack_max_dist_th.value();
     apOpts.log_verbosity = options.ap_verbosity.value();
 }
 

vpr/src/base/read_options.cpp

@@ -1945,6 +1945,31 @@ argparse::ArgumentParser create_arg_parser(const std::string& prog_name, t_optio
         .default_value("0.5")
         .show_in(argparse::ShowIn::HELP_ONLY);
 
+    ap_grp.add_argument(args.appack_max_dist_th, "--appack_max_dist_th")
+        .help(
+            "Sets the maximum candidate distance thresholds for the logical block types"
+            "used by APPack. APPack uses the primitive-level placement produced by the"
+            "global placer to cluster primitives together. APPack uses the thresholds"
+            "here to ignore primitives which are too far away from the cluster being formed."
+            "\n"
+            "When this option is set to auto, VPR will select good values for these"
+            "thresholds based on the primitives contained within each logical block type."
+            "\n"
+            "Using this option, the user can set the maximum candidate distance threshold"
+            "of logical block types to something else. The strings passed in by the user"
+            "should be of the form <regex>:<float>,<float> where the regex string is"
+            "used to match the name of the logical block type to set, the first float"
+            "is a scaling term, and the second float is an offset. The threshold will"
+            "be set to max(scale * (W + H), offset), where W and H are the width and height"
+            "of the device. This allows the user to specify a threshold based on the"
+            "size of the device, while also preventing the number from going below offset"
+            "When multiple strings are provided, the thresholds are set from left to right,"
+            "and any logical block types which have been unset will be set to their auto"
+            "values.")
+        .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

@@ -102,6 +102,7 @@ struct t_options {
     argparse::ArgValue<e_ap_partial_legalizer> ap_partial_legalizer;
     argparse::ArgValue<e_ap_full_legalizer> ap_full_legalizer;
     argparse::ArgValue<e_ap_detailed_placer> ap_detailed_placer;
+    argparse::ArgValue<std::vector<std::string>> appack_max_dist_th;
     argparse::ArgValue<int> ap_verbosity;
     argparse::ArgValue<float> ap_timing_tradeoff;
 

vpr/src/base/vpr_api.cpp

@@ -658,7 +658,7 @@ bool vpr_pack(t_vpr_setup& vpr_setup, const t_arch& arch) {
                                                        vpr_setup.PackerOpts.device_layout,
                                                        vpr_setup.AnalysisOpts);
 
-    return try_pack(vpr_setup.PackerOpts, vpr_setup.AnalysisOpts,
+    return try_pack(vpr_setup.PackerOpts, vpr_setup.AnalysisOpts, vpr_setup.APOpts,
                     arch,
                     vpr_setup.PackerRRGraph,
                     prepacker,

vpr/src/base/vpr_types.h

@@ -1113,6 +1113,9 @@ struct t_placer_opts {
  *   @param ap_timing_tradeoff
  *              A trade-off parameter used to decide how focused the AP flow
  *              should be on optimizing timing over wirelength.
+ *   @param appack_max_dist_th
+ *              Array of string passed by the user to configure the max candidate
+ *              distance thresholds.
  *   @param log_verbosity
  *              The verbosity level of log messages in the AP flow, with higher
  *              values leading to more verbose messages.
@@ -1130,6 +1133,8 @@ struct t_ap_opts {
 
     float ap_timing_tradeoff;
 
+    std::vector<std::string> appack_max_dist_th;
+
     int log_verbosity;
 };
 

vpr/src/pack/appack_context.h

@@ -8,12 +8,12 @@
 
 #pragma once
 
-#include <algorithm>
-#include <limits>
+#include "appack_max_dist_th_manager.h"
 #include "device_grid.h"
 #include "flat_placement_types.h"
 #include "physical_types.h"
 #include "vpr_context.h"
+#include "vpr_types.h"
 #include "vpr_utils.h"
 
 /**
@@ -25,29 +25,10 @@
  */
 struct t_appack_options {
     // Constructor for the appack options.
-    t_appack_options(const FlatPlacementInfo& flat_placement_info,
-                     const DeviceGrid& device_grid) {
+    t_appack_options(const FlatPlacementInfo& flat_placement_info) {
         // If the flat placement info is valid, we want to use APPack.
         // TODO: Should probably check that all the information is valid here.
         use_appack = flat_placement_info.valid;
-
-        // Set the max candidate distance as being some fraction of the longest
-        // distance on the device (from the bottom corner to the top corner).
-        // We also use an offset for the minimum this distance can be to prevent
-        // small devices from finding candidates.
-        float max_candidate_distance_scale = 0.1f;
-        float max_candidate_distance_offset = 15.0f;
-        // Longest L1 distance on the device.
-        float longest_distance = device_grid.width() + device_grid.height();
-        max_candidate_distance = std::max(max_candidate_distance_scale * longest_distance,
-                                          max_candidate_distance_offset);
-
-        // Infer the logical block type in the architecture. This will be used
-        // for the max candidate distance optimization to use a more aggressive
-        // distance.
-        t_logical_block_type_ptr logic_block_type = infer_logic_block_type(device_grid);
-        if (logic_block_type != nullptr)
-            logic_block_type_index = logic_block_type->index;
     }
 
     // Whether to use APPack or not.
@@ -88,22 +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);
 
-    // =========== Candidate selection distance ============================ //
-    // When selecting candidates, what distance from the cluster will we
-    // consider? Any candidate beyond this distance will not be proposed.
-    // This is set in the constructor.
-    // TODO: It may be a good idea to have max different distances for different
-    //       types of molecules / clusters. For example, CLBs vs DSPs
-    float max_candidate_distance = std::numeric_limits<float>::max();
-
-    // A scaling applied to the max candidate distance of all clusters that are
-    // not logic blocks.
-    static constexpr float max_candidate_distance_non_lb_scale = 3.5f;
-
-    // TODO: This should be an option similar to the target pin utilization
-    //       so we can specify the max distance per block type!
-    int logic_block_type_index = -1;
-
     // =========== Unrelated clustering ==================================== //
     // After searching for candidates by connectivity and timing, the user may
     // turn on unrelated clustering, which will allow molecules which are
@@ -144,9 +109,21 @@ struct APPackContext : public Context {
     /**
      * @brief Constructor for the APPack context.
      */
-    APPackContext(const FlatPlacementInfo& fplace_info, const DeviceGrid& device_grid)
-        : appack_options(fplace_info, device_grid)
-        , flat_placement_info(fplace_info) {}
+    APPackContext(const FlatPlacementInfo& fplace_info,
+                  const t_ap_opts& ap_opts,
+                  const std::vector<t_logical_block_type> logical_block_types,
+                  const DeviceGrid& device_grid)
+        : appack_options(fplace_info)
+        , flat_placement_info(fplace_info) {
+
+        // If the flat placement info has been provided, calculate max distance
+        // thresholds for all logical block types.
+        if (fplace_info.valid) {
+            max_distance_threshold_manager.init(ap_opts.appack_max_dist_th,
+                                                logical_block_types,
+                                                device_grid);
+        }
+    }
 
     /**
      * @brief Options used to configure APPack.
@@ -157,4 +134,8 @@ struct APPackContext : public Context {
      * @brief The flat placement information passed into APPack.
      */
     const FlatPlacementInfo& flat_placement_info;
+
+    // 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;
 };