Documentation

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

Author: HackerFoo

doc/src/vpr/command_line_usage.rst

@@ -680,46 +680,6 @@ If any of init_t, exit_t or alpha_t is specified, the user schedule, with a fixe
 
     **Default:** ``0.8``
 
-.. option:: --alpha_min <float>
-
-    The minimum (starting) update factor (alpha) used.
-    Ranges between 0 and alpha_max.
-    Setting this flag selects Dusty's annealing schedule.
-
-    **Default:** ``0.2``
-
-.. option:: --alpha_max <float>
-
-    The maximum (stopping) update factor (alpha) used after which simulated annealing will complete.
-    Ranges between alpha_min and 1.
-    Setting this flag selects Dusty's annealing schedule.
-
-    **Default:** ``0.9``
-
-.. option:: --alpha_decay <float>
-
-    The rate at which alpha will approach 1: alpha(n) = 1 - (1 - alpha(n-1)) * alpha_decay
-    Ranges between 0 and 1.
-    Setting this flag selects Dusty's annealing schedule.
-
-    **Default:** ``0.7``
-
-.. option:: --anneal_success_min <float>
-
-   The minimum success ratio after which the temperature will reset to maintain the target success ratio.
-   Ranges between 0 and anneal_success_target.
-   Setting this flag selects Dusty's annealing schedule.
-
-    **Default:** ``0.1``
-
-.. option:: --anneal_success_target <float>
-
-   The temperature after each reset is selected to keep this target success ratio.
-   Ranges between anneal_success_target and 1.
-   Setting this flag selects Dusty's annealing schedule.
-
-    **Default:** ``0.25``
-
 .. option:: --fix_pins {free | random | <file.pads>}
 
     Controls how the placer handles I/O pads during placement.
@@ -757,6 +717,44 @@ If any of init_t, exit_t or alpha_t is specified, the user schedule, with a fixe
 
     **Default:** ``0.0``
 
+.. _dusty_sa_options:
+Setting any of the following options selects `Dusty's annealing schedule <dusty_sa.rst>`_.
+
+.. option:: --alpha_min <float>
+
+    The minimum (starting) update factor (alpha) used.
+    Ranges between 0 and alpha_max.
+
+    **Default:** ``0.2``
+
+.. option:: --alpha_max <float>
+
+    The maximum (stopping) update factor (alpha) used after which simulated annealing will complete.
+    Ranges between alpha_min and 1.
+
+    **Default:** ``0.9``
+
+.. option:: --alpha_decay <float>
+
+    The rate at which alpha will approach 1: alpha(n) = 1 - (1 - alpha(n-1)) * alpha_decay
+    Ranges between 0 and 1.
+
+    **Default:** ``0.7``
+
+.. option:: --anneal_success_min <float>
+
+   The minimum success ratio after which the temperature will reset to maintain the target success ratio.
+   Ranges between 0 and anneal_success_target.
+
+    **Default:** ``0.1``
+
+.. option:: --anneal_success_target <float>
+
+   The temperature after each reset is selected to keep this target success ratio.
+   Ranges between anneal_success_target and 1.
+
+    **Default:** ``0.25``
+
 .. _timing_driven_placer_options:
 
 Timing-Driven Placer Options

doc/src/vpr/dusty_sa.rst

@@ -0,0 +1,22 @@
+Dusty's Simulated Annealing Schedule
+====================================
+
+This simulated annealing schedule is designed to quickly characterize the search space and maintain a target success ratio (accepted moves.)
+
+It starts at the minimum alpha (``--alpha_min``) to allow it to quickly find the target.
+
+For each alpha, the temperature decays by a factor of alpha after each outer loop iteration.
+
+The temperature before which the success ratio drops below the target (``--anneal_success_target``) is recorded; after hitting the minimum success ratio (``--anneal_success_min``), the temperature resets to a little before recorded temperature, and alpha parameter itself decays according to ``--alpha_decay``.
+
+The effect of this is many fast, but slowing sweeps in temperature, focused where they can make the most effective progress. Unlike fixed and adaptive schedules that monotonically decrease temperature, this allows the global properties of the search space to affect the schedule.
+
+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.
+
+This algorithm was inspired by Lester Ingber's adaptive simulated annealing algorithm [ASA93]_.
+
+See ``update_state()`` in ``place.cpp`` for the algorithm details.
+
+.. [ASA93] Ingber, Lester. "Adaptive simulated annealing (ASA)." Global optimization C-code, Caltech Alumni Association, Pasadena, CA (1993).

vpr/src/base/read_options.cpp

@@ -2222,19 +2222,19 @@ void set_conditional_defaults(t_options& args) {
         args.quench_recompute_divider.set(args.inner_loop_recompute_divider, Provenance::INFERRED);
     }
 
-    //Are we using the automatic, or user-specified annealing schedule?
-    if (args.PlaceAlphaMin.provenance() == Provenance::SPECIFIED
+    //Which schedule?
+    if (args.PlaceAlphaMin.provenance() == Provenance::SPECIFIED // Any of these flags select Dusty's schedule
         || args.PlaceAlphaMax.provenance() == Provenance::SPECIFIED
         || args.PlaceAlphaDecay.provenance() == Provenance::SPECIFIED
         || args.PlaceSuccessMin.provenance() == Provenance::SPECIFIED
         || args.PlaceSuccessTarget.provenance() == Provenance::SPECIFIED) {
         args.anneal_sched_type.set(DUSTY_SCHED, Provenance::INFERRED);
-    } else if (args.PlaceInitT.provenance() == Provenance::SPECIFIED
+    } else if (args.PlaceInitT.provenance() == Provenance::SPECIFIED // Any of these flags select a manual schedule
                || args.PlaceExitT.provenance() == Provenance::SPECIFIED
                || args.PlaceAlphaT.provenance() == Provenance::SPECIFIED) {
         args.anneal_sched_type.set(USER_SCHED, Provenance::INFERRED);
     } else {
-        args.anneal_sched_type.set(AUTO_SCHED, Provenance::INFERRED);
+        args.anneal_sched_type.set(AUTO_SCHED, Provenance::INFERRED); // Otherwise use the automatic schedule
     }
 
     //Are the pad locations specified?

vpr/src/place/place.cpp

@@ -58,6 +58,8 @@ using std::min;
  * cost computation. 0.01 means that there is a 1% error tolerance.       */
 #define ERROR_TOL .01
 
+/* The final rlim (range limit) is 1, which is the smallest value that can *
+ * still make progress, since an rlim of 0 wouldn't allow any swaps.       */
 #define FINAL_RLIM 1
 
 /* This defines the maximum number of swap attempts before invoking the   *
@@ -105,15 +107,16 @@ struct t_placer_prev_inverse_costs {
     double timing_cost;
 };
 
+// Used by update_state()
 struct t_annealing_state {
-    float t;
-    float rlim;
-    float inverse_delta_rlim;
-    float alpha;
-    float restart_t;
-    float crit_exponent;
-    int move_lim_max;
-    int move_lim;
+    float t;                  // Temperature
+    float rlim;               // Range limit for swaps
+    float inverse_delta_rlim; // used to calculate crit_exponent
+    float alpha;              // Temperature decays by this factor each outer iteration
+    float restart_t;          // Temperature used after restart due to minimum success ratio
+    float crit_exponent;      // Used by timing-driven placement to "sharpen" timing criticality
+    int move_lim_max;         // Maximum move limit
+    int move_lim;             // Current move limit
 };
 
 constexpr float INVALID_DELAY = std::numeric_limits<float>::quiet_NaN();