asa-readme+.txt

simulated annealing code ASA

     () at the end of the asa_usr.c file.

          As described in the DLL ASA-Makefile sub-Section  of  Section  7,
     the  ASA-Makefile  and ASA_LIB can be used to create a DLL for Windows
     programs.

     9.1.9.  HAVE_ANSI=TRUE

          Setting HAVE_ANSI=FALSE will permit you to use  an  older  K&R  C
     compiler.   This  option  can  be  used  if  you  do  not have an ANSI
     compiler,  overriding  the  default  HAVE_ANSI=TRUE.    If   you   use
     HAVE_ANSI=FALSE,  change  CC  and  CDEBUGFLAGS  as  described  in  the
     ASA-Makefile.

     9.1.10.  IO_PROTOTYPES=FALSE

          Most  newer  operating  systems  do  not  like  any   other   I/O
     prototyping  other  than  those  in  their  own  include files.  Other
     machines, like a Dec-3100 under Ultrix  complain  that  the  ANSI  I/O
     prototypes  were inconsistent.  A Sun under 4.1.x gcc gave warnings if
     no I/O prototypes were present.  The  defaults  in  asa_usr_asa.h  use
     newer   system  prototypes.   IO_PROTOTYPES=TRUE  will  uncomment  out
     declarations for such items as  fprintf,  fflush,  fclose,  exit,  and
     fscanf.

     9.1.11.  TIME_CALC=FALSE

          Some systems do not have the time include files used here; others
     have different scales for time.  Setting  TIME_CALC=TRUE  will  permit
     use of the time routines.

     9.1.12.  TIME_STD=FALSE

          Some systems, e.g., hpux and Cygwin (with -mno-cygwin), use other
     Unix-standard macros to access time.  Setting TIME_STD=TRUE when using
     TIME_CALC=TRUE will use these time routines instead.

     9.1.13.  TIME_GETRUSAGE=TRUE

          An  additional  module  for  using TIME_CALC set to TRUE, setting
     TIME_GETRUSAGE to FALSE, is  more  portable  to  compile  across  some
     platforms,  e.g.,  Cygwin  (with  -mno-cygwin),  but  it  can  require
     different parameters for timing results.  Comments have been placed in
     the code in asa.c.



                                     - 17 -





     Adaptive Simulated Annealing (ASA)                       Lester Ingber




     9.1.14.  INT_LONG=TRUE

          Some  smaller  systems choke on 'long int' and this option can be
     set to INT_LONG=FALSE to turn off warnings and possibly  some  errors.
     The cast LONG_INT is used to define 'int' or 'long int' appropriately.

     9.1.15.  INT_ALLOC=FALSE

          The cast on *number_parameters is set to ALLOC_INT which defaults
     to  LONG_INT.  On some machines, ALLOC_INT might have to be set to int
     if there is a strict requirement to use an (unsigned) int for  calloc,
     while  'long  int'  still  can  be  used for other aspects of ASA.  If
     ALLOC_INT is to be set to int, set INT_ALLOC to TRUE.

     9.1.16.  SMALL_FLOAT=1.0E-18

          SMALL_FLOAT is a measure of accuracy permitted in log and  divide
     operations  in asa, i.e., which is not precisely equivalent to a given
     machine's precision.  There also  are  Pre-Compile  DEFINE_OPTIONS  to
     separately set constants for minimum and maximum doubles and precision
     permitted  by  your  machine.   Experts  who  require  the  very  best
     precision can fine-tune these parameters in the code.

          Such  issues  arise  because the fat tail of ASA, associated with
     high parameter temperatures,  is  very  important  for  searching  the
     breadth  of  the  ranges  especially  in the initial stages of search.
     However, the parameter temperatures require small values at the  final
     stages  of the search to converge to the best solution, albeit this is
     reached very quickly given the  exponential  schedule  proven  in  the
     referenced  publications  to  be  permissible with ASA.  Note that the
     test problem in asa_usr_cst.c and asa_usr.c is  a  particularly  nasty
     one, with 1E20 local minima and requiring ASA to search over 12 orders
     of magnitude of the cost function before correctly finding the  global
     minimum.     Thus,   intermediate   values   disagree   somewhat   for
     SMALL_FLOAT=1.0E-12 from the settings using  SMALL_FLOAT=1.0E-18  (the
     default);   they  agree  if  SMALL_FLOAT=1.0E-12  while  also  setting
     MIN_DOUBLE=1.0E-18.   The   results   diverge   when   the   parameter
     temperatures  get  down to the range of E-12, limiting the accuracy of
     the SMALL_FLOAT=1.0E-12 run.

          On  some  machines  that   have   register   variables   assigned
     inconsistently  with  other  doubles,  there  can arise some numerical
     differences in some systems.  There has been no such problem found  on
     Sun/Solaris 2.x using gcc, but some problems have been noticed on some
     Intel chips using different gcc optimizations.

     9.1.17.  MIN_DOUBLE=SMALL_FLOAT

          You can define your own machine's minimum positive double here if
     you know it.





                                     - 18 -





     Adaptive Simulated Annealing (ASA)                       Lester Ingber




     9.1.18.  MAX_DOUBLE=1.0/SMALL_FLOAT

          You can define your own machine's maximum double here if you know
     it.

     9.1.19.  EPS_DOUBLE=SMALL_FLOAT

          You can define your own machine's maximum precision here  if  you
     know it.

     9.1.20.  CHECK_EXPONENT=FALSE

          When  CHECK_EXPONENT is set to TRUE, the macro EXPONENT_CHECK(x),
     defined in asa.h in terms of MIN_DOUBLE and MAX_DOUBLE, checks that an
     exponent  x is within a valid range and, if not, adjusts its magnitude
     to fit in the range.

     9.1.21.  NO_PARAM_TEMP_TEST=FALSE

          If  NO_PARAM_TEMP_TEST  is  set  to  TRUE,  then  all   parameter
     temperatures  less  than EPS_DOUBLE are set to EPS_DOUBLE, and no exit
     is called.

     9.1.22.  NO_COST_TEMP_TEST=FALSE

          If NO_COST_TEMP_TEST is set to TRUE, then a cost temperature less
     than EPS_DOUBLE is set to EPS_DOUBLE, and no exit is called.

     9.1.23.  SELF_OPTIMIZE=FALSE

          The  user module contains a template to illustrate how ASA may be
     used  to  self-optimize  its  Program  Options.   This  can  be   very
     CPU-expensive  and  is  of  course  dependent  on  how you define your
     recursive cost function (recur_cost_function in the user module).  The
     example  given returns from recur_cost_function the number of function
     evaluations taken to optimization the  test  cost_function,  with  the
     constraint  to only accept optimizations of the cost_function that are
     lower than a specified value.  A few lines of code can be  uncommented
     in asa_usr.c to force a fast exit for this demo; search for FAST EXIT.
     (Note that this also could achieved by  using  OPTIONS->Immediate_Exit
     discussed below.)

          The  ASA_TEMPLATE_SELFOPT  example uses OPTIONS_FILE=FALSE in the
     Pre-Compile Options.  Note that DEFINE_OPTIONS  OPTIONS_FILE=TRUE  and
     OPTIONS_FILE_DATA=TRUE  here  would  take  data  from  asa_opt for the
     lower-level program using the cost_function ().   Both  DEFINE_OPTIONS
     RECUR_OPTIONS_FILE and RECUR_OPTIONS_FILE_DATA would have to be set to
     TRUE to use  asa_opt_recur  to  read  in  both  the  OPTIONS  and  the
     recur_cost_parameters data (which you would have to write in the style
     of asa_opt) for the top-level recur_cost_function ().

          This can be useful when approaching  a  new  system,  and  it  is
     suspected  that  the  default  ASA  Program  Options  are  not  at all


                                     - 19 -





     Adaptive Simulated Annealing (ASA)                       Lester Ingber




     efficient for this system.   It  is  suggested  that  a  trimmed  cost
     function  or data set be used to get a reasonable guess for a good set
     of Program Options.  ASA has demonstrated that it typically  is  quite
     robust  under a given set of Program Options, so it might not make too
     much sense to spend  lots  of  resources  performing  additional  fine
     tuning of the these options.  Also, it is possible you might crash the
     code  by  permitting  ranges  of  Program  Options  that  cause   your
     particular cost_function to return garbage to asa ().

     9.1.24.  ASA_TEST=FALSE

          Setting  ASA_TEST  to  TRUE  will  permit  running  the  ASA test
     problem.   This  has  been  added  to  the   DEFINE_OPTIONS   in   the
     ASA-Makefile  so  that just running make will run the test problem for
     the new user.  No attempt was made to optimize  any  OPTIONS  for  the
     ASA_TEST problem as it appears in the standard code.

     9.1.25.  ASA_TEST_POINT=FALSE

          The  code  used  for  the  ASA_TEST  problem  closely follows the
     reference given in asa_usr.c, and was rewritten from code given to the
     author in 1992.  Other researchers have sent the author different code
     for this system, and all results agree within round-off errors.

          However, note that the actual problem stated in the reference  in
     asa_usr.c is harder, requiring the finding of an optimal point and not
     an optimal region.  The code for that problem is  given  in  asa_usr.c
     when  ASA_TEST_POINT  is  set  to  TRUE  (having the effect of setting
     COST_FILE      to      FALSE       in       asa_usr_asa.h).        The
     http://www.ingber.com/asa_examples.txt   file   illustrates  how  that
     global minimum can be attained.

     9.1.26.  MY_TEMPLATE=TRUE

          When MY_TEMPLATE is set  to  TRUE  (the  default),  locations  in
     asa_usr.c  and  asa_usr_asa.h  become  active sites for your own code.
     Searching asa_usr.c for "MY_TEMPLATE_" provides a guide for additional
     code  to  add  for  your  own  system.   For  example,  just above the
     occurrence of the guides for  MY_TEMPLATE_cost  is  the  corresponding
     code  for ASA_TEST=TRUE.  Keeping the default of ASA_TEST set to FALSE
     permits such changes without overwriting the test example.

     9.1.27.  USER_INITIAL_COST_TEMP=FALSE

          Setting USER_INITIAL_COST_TEMP to TRUE permits you to specify the
     initial  cost temperature in the User_Cost_Temperature [] array.  This
     can be useful in problems where you want to  start  the  search  at  a
     specific scale.

     9.1.28.  RATIO_TEMPERATURE_SCALES=FALSE

          Different   rates   of   parameter  annealing  can  be  set  with
     RATIO_TEMPERATURE_SCALES set to TRUE.  This requires initializing  the


                                     - 20 -





     Adaptive Simulated Annealing (ASA)                       Lester Ingber




     User_Temperature_Ratio [] array in the user module as discussed below.

     9.1.29.  USER_INITIAL_PARAMETERS_TEMPS=FALSE

          Setting USER_INITIAL_PARAMETERS_TEMPS  to  TRUE  permits  you  to
     specify     the     initial     parameter    temperatures    in    the
     User_Parameter_Temperature  []  array.   This   can   be   useful   in
     constrained  problems,  where  greater  efficiency  can be achieved in
     focussing the search than might be permitted just by setting upper and
     lower bounds.

     9.1.30.  DELTA_PARAMETERS=FALSE

          Different   increments,  used  during  reannealing  to  set  each
     parameter's numerical derivatives, can be  set  with  DELTA_PARAMETERS
     set  to  TRUE.  This requires initializing the User_Delta_Parameter []
     array in the user module as discussed below.

     9.1.31.  QUENCH_PARAMETERS=FALSE

          This DEFINE_OPTIONS permits you to alter the basic  algorithm  to
     perform  selective  "quenching," i.e., faster temperature cooling than
     permitted by the ASA algorithm.  This can be  very  useful,  e.g.,  to
     quench the system down to some region of interest, and then to perform
     proper annealing for the rest of the run.  However, note that once you
     decide