Add & fix documentation

Signed-off-by: Dusty DeWeese <[email protected]>

Author: HackerFoo

doc/src/vpr/dusty_sa.rst

@@ -13,7 +13,7 @@ The effect of this is many fast, but slowing sweeps in temperature, focused wher
 
 In addition, move_lim (which controls the number of iterations in the inner loop) is scaled with the target success ratio over the current success ratio, which reduces the time to reach the target ratio.
 
-The schedule terminates when the maximum alpha (``--alpha_max``) is reached. Termination is ensured by the narrowing range between the recorded upper temperature and the minimum success ratio, which will eventually cause alpha to reach its minimum.
+The schedule terminates when the maximum alpha (``--alpha_max``) is reached. Termination is ensured by the narrowing range between the recorded upper temperature and the minimum success ratio, which will eventually cause alpha to reach its maximum.
 
 This algorithm was inspired by Lester Ingber's adaptive simulated annealing algorithm [ASA93]_.
 

vpr/src/base/read_options.cpp

@@ -1568,31 +1568,31 @@ argparse::ArgumentParser create_arg_parser(std::string prog_name, t_options& arg
 
     place_grp.add_argument(args.PlaceAlphaMin, "--alpha_min")
         .help(
-            "Minimum (starting) value of alpha.")
+            "For placement using Dusty's annealing schedule. Minimum (starting) value of alpha.")
         .default_value("0.2")
         .show_in(argparse::ShowIn::HELP_ONLY);
 
     place_grp.add_argument(args.PlaceAlphaMax, "--alpha_max")
         .help(
-            "Maximum (stopping) value of alpha.")
+            "For placement using Dusty's annealing schedule. Maximum (stopping) value of alpha.")
         .default_value("0.9")
         .show_in(argparse::ShowIn::HELP_ONLY);
 
     place_grp.add_argument(args.PlaceAlphaDecay, "--alpha_decay")
         .help(
-            "The value that alpha is scaled by after reset.")
+            "For placement using Dusty's annealing schedule. The value that alpha is scaled by after reset.")
         .default_value("0.7")
         .show_in(argparse::ShowIn::HELP_ONLY);
 
     place_grp.add_argument(args.PlaceSuccessMin, "--anneal_success_min")
         .help(
-            "Minimum success ratio when annealing before resetting the temperature to maintain the target success ratio.")
+            "For placement using Dusty's annealing schedule. Minimum success ratio when annealing before resetting the temperature to maintain the target success ratio.")
         .default_value("0.1")
         .show_in(argparse::ShowIn::HELP_ONLY);
 
     place_grp.add_argument(args.PlaceSuccessTarget, "--anneal_success_target")
         .help(
-            "Target success ratio when annealing.")
+            "For placement using Dusty's annealing schedule. Target success ratio when annealing.")
         .default_value("0.25")
         .show_in(argparse::ShowIn::HELP_ONLY);
 

vpr/src/place/place.cpp

@@ -107,7 +107,7 @@ struct t_placer_prev_inverse_costs {
     double timing_cost;
 };
 
-// Used by update_state()
+// Used by update_annealing_state()
 struct t_annealing_state {
     float t;                  // Temperature
     float rlim;               // Range limit for swaps
@@ -360,11 +360,11 @@ static float starting_t(t_placer_costs* costs,
                         t_pl_blocks_to_be_moved& blocks_affected,
                         const t_placer_opts& placer_opts);
 
-static bool update_state(t_annealing_state* state,
-                         float success_rat,
-                         const t_placer_costs& costs,
-                         const t_placer_opts& placer_opts,
-                         const t_annealing_sched& annealing_sched);
+static bool update_annealing_state(t_annealing_state* state,
+                                   float success_rat,
+                                   const t_placer_costs& costs,
+                                   const t_placer_opts& placer_opts,
+                                   const t_annealing_sched& annealing_sched);
 
 static void update_rlim(float* rlim, float success_rat, const DeviceGrid& grid);
 
@@ -814,7 +814,7 @@ void try_place(const t_placer_opts& placer_opts,
             print_clb_placement("first_iteration_clb_placement.echo");
         }
 #endif
-    } while (update_state(&state, success_rat, costs, placer_opts, annealing_sched));
+    } while (update_annealing_state(&state, success_rat, costs, placer_opts, annealing_sched));
     /* Outer loop of the simmulated annealing ends */
 
     auto pre_quench_timing_stats = timing_ctx.stats;
@@ -1206,12 +1206,18 @@ static void update_rlim(float* rlim, float success_rat, const DeviceGrid& grid)
     *rlim = max(*rlim, (float)1.);
 }
 
-/* Update the temperature according to the annealing schedule selected. */
-static bool update_state(t_annealing_state* state,
-                         float success_rat,
-                         const t_placer_costs& costs,
-                         const t_placer_opts& placer_opts,
-                         const t_annealing_sched& annealing_sched) {
+/* Update the annealing state according to the annealing schedule selected.
+ *   USER_SCHED:  A manual fixed schedule with fixed alpha and exit criteria.
+ *   AUTO_SCHED:  A more sophisticated schedule where alpha varies based on success ratio.
+ *   DUSTY_SCHED: This schedule jumps backward and slows down in response to success ratio.
+ *                See doc/src/vpr/dusty_sa.rst for more details.
+ *
+ * Returns true until the schedule is finished. */
+static bool update_annealing_state(t_annealing_state* state,
+                                   float success_rat,
+                                   const t_placer_costs& costs,
+                                   const t_placer_opts& placer_opts,
+                                   const t_annealing_sched& annealing_sched) {
     /* Return `false` when the exit criterion is met. */
     if (annealing_sched.type == USER_SCHED) {
         state->t *= annealing_sched.alpha_t;
@@ -1253,6 +1259,8 @@ static bool update_state(t_annealing_state* state,
         if (state->t < t_exit || std::isnan(t_exit)) return false;
     }
 
+    // Gradually changes from the initial crit_exponent to the final crit_exponent based on how much the range limit has shrunk.
+    // The idea is that as the range limit shrinks (indicating we are fine-tuning a more optimized placement) we can focus more on a smaller number of critical connections, which a higher crit_exponent achieves.
     update_rlim(&state->rlim, success_rat, device_ctx.grid);
 
     if (placer_opts.place_algorithm == PATH_TIMING_DRIVEN_PLACE) {