[APPack] Updated How APPack Adheres to Given Placement

The original implementation of APPack was focused on reconstructing a
given flat placement. This can cause issues if the given flat placement
disagrees with the decisions of the packer.

Instead, updated APPack so that it treats the flat placement as a hint
to help guide how it performs clustering.

Added the following new features:
- APPack computes the location of clusters based on the centroid of the
  molecules packed within.
- APPack attenuates the gain terms of candidates based on their distance
  from the cluster.
- APPack drops candidates which are too far from the cluster being
  created.

Remove adding molecules near to the position of the cluster. This had
similar affects to unrelated clustering and should be investigated
separately later.

With these changes to APPack, the AP flow now improves WL of circuits by
1-3% at the expense of up to 15% runtime compared to the default VPR
flow.

Author: AlexandreSinger

vpr/src/analytical_place/detailed_placer.cpp

@@ -7,13 +7,13 @@
 
 #include "detailed_placer.h"
 #include <memory>
-#include "FlatPlacementInfo.h"
 #include "PlacementDelayModelCreator.h"
 #include "ap_flow_enums.h"
 #include "atom_netlist.h"
 #include "clustered_netlist.h"
 #include "clustered_netlist_utils.h"
 #include "echo_files.h"
+#include "flat_placement_types.h"
 #include "globals.h"
 #include "physical_types.h"
 #include "place_and_route.h"
@@ -22,6 +22,7 @@
 #include "vpr_error.h"
 #include "vpr_types.h"
 #include "vpr_utils.h"
+#include "vtr_time.h"
 
 std::unique_ptr<DetailedPlacer> make_detailed_placer(e_ap_detailed_placer detailed_placer_type,
                                                      const BlkLocRegistry& curr_clustered_placement,
@@ -89,6 +90,9 @@ AnnealerDetailedPlacer::AnnealerDetailedPlacer(const BlkLocRegistry& curr_cluste
 }
 
 void AnnealerDetailedPlacer::optimize_placement() {
+    // Create a scoped timer for the detailed placer.
+    vtr::ScopedStartFinishTimer full_legalizer_timer("AP Detailed Placer");
+
     // Prevent the annealer from directly modifying the global legal placement.
     // It should only modify its own, local placement.
     g_vpr_ctx.mutable_placement().lock_loc_vars();

vpr/src/analytical_place/full_legalizer.cpp

@@ -16,23 +16,23 @@
 #include <unordered_set>
 #include <vector>
 
-#include "FlatPlacementInfo.h"
-#include "ap_flow_enums.h"
-#include "blk_loc_registry.h"
-#include "device_grid.h"
-#include "load_flat_place.h"
-#include "noc_place_utils.h"
-#include "partial_placement.h"
 #include "ShowSetup.h"
+#include "ap_flow_enums.h"
 #include "ap_netlist_fwd.h"
+#include "blk_loc_registry.h"
 #include "check_netlist.h"
 #include "cluster_legalizer.h"
 #include "cluster_util.h"
 #include "clustered_netlist.h"
+#include "device_grid.h"
+#include "flat_placement_types.h"
 #include "globals.h"
 #include "initial_placement.h"
+#include "load_flat_place.h"
 #include "logic_types.h"
+#include "noc_place_utils.h"
 #include "pack.h"
+#include "partial_placement.h"
 #include "physical_types.h"
 #include "place.h"
 #include "place_and_route.h"

vpr/src/analytical_place/global_placer.cpp

@@ -69,18 +69,24 @@ SimPLGlobalPlacer::SimPLGlobalPlacer(e_partial_legalizer partial_legalizer_type,
     // This can be a long method. Good to time this to see how long it takes to
     // construct the global placer.
     vtr::ScopedStartFinishTimer global_placer_building_timer("Constructing Global Placer");
+
     // Build the solver.
+    VTR_LOGV(log_verbosity_ >= 10, "\tBuilding the solver...\n");
     solver_ = make_analytical_solver(e_analytical_solver::QP_HYBRID,
                                      ap_netlist_);
+
     // Build the density manager used by the partial legalizer.
+    VTR_LOGV(log_verbosity_ >= 10, "\tBuilding the density manager...\n");
     density_manager_ = std::make_shared<FlatPlacementDensityManager>(ap_netlist_,
                                                                      prepacker,
                                                                      atom_netlist,
                                                                      device_grid,
                                                                      logical_block_types,
                                                                      physical_tile_types,
                                                                      log_verbosity_);
+
     // Build the partial legalizer
+    VTR_LOGV(log_verbosity_ >= 10, "\tBuilding the partial legalizer...\n");
     partial_legalizer_ = make_partial_legalizer(partial_legalizer_type,
                                                 ap_netlist_,
                                                 density_manager_,

vpr/src/base/FlatPlacementInfo.h renamed to vpr/src/base/flat_placement_types.h

@@ -1,16 +1,54 @@
 /**
  * @file
  * @author  Alex Singer
- * @date    January 2025
- * @brief   Declaration of the FlatPlacementInfo object, which is used to store
- *          flat placement information used by the packer.
+ * @date    March 2025
+ * @brief   Declaration of flat placement types used throughout VPR.
  */
 
 #pragma once
 
 #include "atom_netlist.h"
+#include "vtr_assert.h"
 #include "vtr_vector.h"
 
+/**
+ * @brief A structure representing a flat placement location on the device.
+ *
+ * This is related to the t_pl_loc type; however this uses floating point
+ * coordinates, allowing for blocks to be placed in illegal positions.
+ */
+struct t_flat_pl_loc {
+    float x;     /**< The x-coordinate of the location. */
+    float y;     /**< The y-coordinate of the location. */
+    float layer; /**< The layer of the location. */
+
+    /**
+     * @brief Adds the coordinates of another t_flat_pl_loc to this one.
+     *
+     * @param other The other t_flat_pl_loc whose coordinates are to be added.
+     * @return A reference to this t_flat_pl_loc after addition.
+     */
+    t_flat_pl_loc& operator+=(const t_flat_pl_loc& other) {
+        x += other.x;
+        y += other.y;
+        layer += other.layer;
+        return *this;
+    }
+
+    /**
+     * @brief Divides the coordinates of this t_flat_pl_loc by a divisor.
+     *
+     * @param divisor The value by which to divide the coordinates.
+     * @return A reference to this t_flat_pl_loc after division.
+     */
+    t_flat_pl_loc& operator/=(float divisor) {
+        x /= divisor;
+        y /= divisor;
+        layer /= divisor;
+        return *this;
+    }
+};
+
 /**
  * @brief Flat placement storage class.
  *
@@ -55,6 +93,15 @@ class FlatPlacementInfo {
     ///        object, false otherwise.
     bool valid;
 
+    /**
+     * @brief Get the flat placement location of the given atom block.
+     */
+    inline t_flat_pl_loc get_pos(AtomBlockId blk_id) const {
+        VTR_ASSERT_SAFE_MSG(blk_id.is_valid(), "Block ID is invalid");
+        VTR_ASSERT_SAFE_MSG(valid, "FlatPlacementInfo not initialized");
+        return {blk_x_pos[blk_id], blk_y_pos[blk_id], blk_layer[blk_id]};
+    }
+
     /**
      * @brief Default constructor of this class.
      *

vpr/src/base/flat_placement_utils.h

@@ -0,0 +1,22 @@
+/**
+ * @file
+ * @author  Alex Singer
+ * @date    March 2025
+ * @brief   Utility methods for working with flat placements.
+ */
+
+#pragma once
+
+#include <cstdlib>
+#include "flat_placement_types.h"
+
+/**
+ * @brief Returns the manhattan distance (L1 distance) between two flat
+ *        placement locations.
+ */
+inline float get_manhattan_distance(const t_flat_pl_loc& loc_a,
+                                    const t_flat_pl_loc& loc_b) {
+    return std::abs(loc_a.x - loc_b.x) +
+           std::abs(loc_a.y - loc_b.y) +
+           std::abs(loc_a.layer - loc_b.layer);
+}

vpr/src/base/load_flat_place.cpp

@@ -14,7 +14,7 @@
 #include "atom_lookup.h"
 #include "atom_netlist.h"
 #include "clustered_netlist.h"
-#include "FlatPlacementInfo.h"
+#include "flat_placement_types.h"
 #include "globals.h"
 #include "vpr_context.h"
 #include "vpr_error.h"

vpr/src/base/place_and_route.cpp

@@ -4,7 +4,7 @@
 #include <cmath>
 #include <algorithm>
 
-#include "FlatPlacementInfo.h"
+#include "flat_placement_types.h"
 #include "place_macro.h"
 #include "vtr_assert.h"
 #include "vtr_log.h"

vpr/src/base/vpr_api.cpp

@@ -17,7 +17,7 @@
 #include <memory>
 #include <vector>
 
-#include "FlatPlacementInfo.h"
+#include "flat_placement_types.h"
 #include "cluster_util.h"
 #include "physical_types.h"
 #include "place_macro.h"

vpr/src/base/vpr_context.h

@@ -5,7 +5,7 @@
 #include <vector>
 #include <mutex>
 
-#include "FlatPlacementInfo.h"
+#include "flat_placement_types.h"
 #include "physical_types.h"
 #include "place_macro.h"
 #include "user_place_constraints.h"

vpr/src/pack/cluster_legalizer.h

@@ -445,6 +445,13 @@ class ClusterLegalizer {
         return cluster.pr;
     }
 
+    /// @brief Gets the molecules currently packed within the given cluster.
+    inline const std::vector<PackMoleculeId>& get_cluster_molecules(LegalizationClusterId cluster_id) const {
+        VTR_ASSERT_SAFE(cluster_id.is_valid() && (size_t)cluster_id < legalization_clusters_.size());
+        const LegalizationCluster& cluster = legalization_clusters_[cluster_id];
+        return cluster.molecules;
+    }
+
     /// @brief Gets the current number of molecules in the cluster.
     inline size_t get_num_molecules_in_cluster(LegalizationClusterId cluster_id) const {
         VTR_ASSERT_SAFE(cluster_id.is_valid() && (size_t)cluster_id < legalization_clusters_.size());