asa-readme+.txt

simulated annealing code ASA

                                     - 12 -





     Adaptive Simulated Annealing (ASA)                       Lester Ingber




     (Ignore  any  undefined  references  to  _WinMain.)   Note  that   per
     instructions  given  in  the ASA-Makefile, -mno-cygwin -mrtd should be
     included in CFLAGS.

          If paths are used to access files  in  code,  under  Windows  use
     absolute   paths   with   "\\"   (double   back   slash)  to  separate
     folders/directories,  instead  of  relative  paths  with  "/"  (single
     forward slash) separators as on other Unix platforms.

     8.  Generic ASA Interfaces

          The  sections  above describe how to quickly adapt ASA for use in
     many problems.  However, complex projects often require  sophisticated
     use of multiple languages to handle data and multiple algorithms.  ASA
     has many OPTIONS that enable users to interface ASA with such  complex
     projects.

     ASA  should  compile  under  C++  as  well  as under C compilers.  For
     example, I regularly test this by running projects under both gcc  and
     g++.   This  can  be  very  useful  when  ASA is called from other C++
     programs, e.g., when using ASA_LIB set to TRUE.

     I have led many projects that required ASA  to  interface  with  Java,
     Maple,  Matlab,  MySQL, etc.  The approach briefly described below can
     be applied to any language that permits a simple interface to C  code.
     This  definitely requires some expert experience in C, so you may have
     to find a local C guru, since I cannot help  you  with  your  specific
     project.

     Some  specific  interfaces  have  been prepared by other people, and I
     have included some of them in the asa_contrib.txt file.  The  tradeoff
     for  their  simple  use  is that these approaches are limited to using
     just a few ASA OPTIONS as they typically have  trimmed  down  the  ASA
     code.

     The  generic  approach  is to utilize at least the OPTIONS ASA_LIB and
     OPTIONAL_DATA_PTR, setting them to TRUE.  ASA_LIB permits  the  entire
     ASA code to be called as a simple function.  Its sole parameter can be
     a  struct  defined  by  OPTIONAL_PTR_TYPE,   e.g.,   OPTIONAL_PTR_TYPE
     PROJECT,  defined  in  asa_usr_asa.h.   A small include file common to
     asa_usr_asa.h and to the larger complex project, e.g.,  project.h,  is
     used  to  define  the  constituents  of  the  the  PROJECT struct.  As
     described above in the DLL  ASA-Makefile  sub-Section  of  Section  7,
     ASA_LIB  can be used to create a DLL to be called by Windows programs.

     A small C function, e.g., project.c, is to be used for  the  interface
     between ASA and the other language.  Similarly, another small function
     also may be used to interface the project  to  handle  the  interface,
     e.g.,  project.m,  project.java,  project.mpl,  etc.   Inversely,  the
     interface  may  (also)  be  between  the  cost  function,   e.g.,   in
     asa_usr_cst.c  or  asa_usr.c,  and  the project.  Then the application
     below is used to pass information between the cost  function  and  the
     other language.


                                     - 13 -





     Adaptive Simulated Annealing (ASA)                       Lester Ingber




     The  other  language passes information and data to project.c required
     by  ASA,  where  it   is   packed   into   the   struct   defined   by
     OPTIONAL_PTR_TYPE.   Multiple or recursive calls to ASA can be handled
     by including a flag in this struct, e.g., to turn  on  different  cost
     functions.   Also added to this struct are placeholders for the output
     of ASA required by the project.  This struct is passed to the ASA code
     by  calling  asa_main () defined in asa_usr.c with a parameter PROJECT
     *Project.  In asa_main (),  in  the  section  defining  properties  of
     OPTIONAL_DATA_PTR, the pointer to Project struct is set to the pointer
     path to Asa_Data_Ptr.   Asa_Data_Ptr  is  now  passed  throughout  the
     entire  ASA  code  via  the OPTIONS pointer, project parameters can be
     adaptively changed, etc.

     After the call to asa () in asa_usr.c, its output can be  packed  into
     the  project struct, before memory is freed.  The pointer Asa_Data_Ptr
     should be set to NULL instead of freed; see the comment  in  asa_usr.c
     at the place Asa_Data_Ptr is freed in the default code.

     It is wise to create #define PROJECT and #endif pairs wherever changes
     to any ASA code are made, define PROJECT to TRUE in asa_usr_asa.h,  so
     that  it  will  be  easy  to  modify  updated ASA code, etc.  Probably
     several such changes will have to be made in  asa_usr.c.   Control  of
     OPTIONS  likely  will  best  be  handled  in asa_usr_asa.h than in the
     ASA-Makefile.

     9.  User Options

          Program Options, i.e., the USER_DEFINES typedef on  the  OPTIONS,
     USER_OPTIONS,  RECUR_USER_OPTIONS,  etc.,  are  turned  on  during the
     running of asa ().  The DEFINE_OPTIONS are compiled in by the  use  of
     arguments  to  the compilation or by setting them in the asa_usr_asa.h
     file.  An example of the former is Reanneal_Parameters, and an example
     of  the  latter  is ASA_SAMPLE.  The basic code is kept small for most
     users by using the Pre-Compile DEFINE_OPTIONS to  pull  in  additional
     DEFINE_OPTIONS  only if required.  The Program Options are intended to
     be used adaptively and/or to pull in additional code for  cases  where
     repeated  or  recursive  use, e.g., when using SELF_OPTIMIZE, might be
     facilitated by having control of  some  Program  Options  at  separate
     levels.

          Note  that  even  when  the DEFINE_OPTIONS or Program Options are
     used to pull in new code, separate  levels  of  control  also  can  be
     achieved,  albeit  usually  at the price of incurring some overhead in
     setting values at some levels of recursion  or  repeated  calls.   For
     example, in cases where new arrays or functions come into play, enough
     parameters are passed between the asa and user  modules  to  calculate
     the  defaults  as  well as different values adaptively.  In some often
     used cases, separate DEFINE_OPTIONS are given, e.g., both OPTIONS_FILE
     and  RECUR_OPTIONS_FILE exist.  I have tried to strike some reasonable
     balance between these goals and constraints.

          The DEFINE_OPTIONS are organized  into  two  groups:  Pre-Compile
     Options  and  (Pre-Compile)  Printing Options.  In addition, there are


                                     - 14 -





     Adaptive Simulated Annealing (ASA)                       Lester Ingber




     some alternatives to  explore  under  Compiler  Choices  and  Document
     Formatting.   Below  are  the DEFINE_OPTIONS with their defaults.  The
     Program Options are  further  discussed  in  other  sections  in  this
     document.

          Note  that  the  Pre-Compile  DEFINE_OPTIONS  are  all in capital
     letters,  and  the   adaptive   Program   Options   (under   structure
     USER_OPTIONS in the user module and under structure OPTIONS in the asa
     module) are in capital and lower-case letters.  In  this  file,  often
     just  the  term  OPTIONS  may refer to the set of all options when the
     context is clear.

     9.1.  Pre-Compile DEFINE_OPTIONS


     9.1.1.  USER_COST_FUNCTION=cost_function

          The default name of the cost function is cost_function.  This can
     be   changed  in  asa_usr_asa.h  (or  the  ASA-Makefile)  by  defining
     USER_COST_FUNCTION.  This of course requires compiling in the new cost
     function and its prototype.

     9.1.2.  RECUR_USER_COST_FUNCTION=recur_cost_function

          When SELF_OPTIMIZE is TRUE, the default name of  the  recur  cost
     function is recur_cost_function.  This can be changed in asa_usr_asa.h
     (or the ASA-Makefile) by defining RECUR_USER_COST_FUNCTION.   This  of
     course  requires compiling in the new cost function and its prototype.

     9.1.3.  OPTIONS_FILE=TRUE

          You can elect to read in many of the Program Options from asa_opt
     by  setting  OPTIONS_FILE=TRUE.   OPTIONS_FILE=TRUE  can be set in the
     ASA-Makefile in compilation commands or in asa_usr_asa.h.

     9.1.4.  OPTIONS_FILE_DATA=TRUE

          If OPTIONS_FILE is set to TRUE, then setting OPTIONS_FILE_DATA to
     TRUE  permits  reading  most  initialization  data from asa_opt, i.e.,
     number of parameters, minimum and maximum ranges, initial values,  and
     integer  or  real  types.   This should suffice for most applications,
     just  requiring   insertion   of   the   user's   cost_function   into
     asa_usr_cst.c or asa_usr.c.

          If OPTIONS_FILE, OPTIONS_FILE_DATA and QUENCH_COST are TRUE, then
     *User_Quench_Cost_Scale is read in  from  asa_opt.   If  OPTIONS_FILE,
     OPTIONS_FILE_DATA,  QUENCH_COST,  and QUENCH_PARAMETERS are TRUE, then
     *User_Quench_Cost_Scale and User_Quench_Param_Scale [] all are read in
     from asa_opt.






                                     - 15 -





     Adaptive Simulated Annealing (ASA)                       Lester Ingber




     9.1.5.  RECUR_OPTIONS_FILE=FALSE

          When  SELF_OPTIMIZE is TRUE, you can elect to read in many of the
     Program Options for the top-level program  from  asa_opt_recur  (which
     you  will  have  to  create  in  the  style  of  asa_opt),  by setting
     RECUR_OPTIONS_FILE=TRUE.

     9.1.6.  RECUR_OPTIONS_FILE_DATA=FALSE

          When SELF_OPTIMIZE is TRUE, if RECUR_OPTIONS_FILE is set to TRUE,
     then  setting  RECUR_OPTIONS_FILE_DATA  to  TRUE  permits reading most
     initialization data from asa_opt_recur (which you will have to  create
     in  the  style  of  asa_opt),  i.e., number of parameters, minimum and
     maximum ranges, initial values, and integer or real types.

          If RECUR_OPTIONS_FILE,  RECUR_OPTIONS_FILE_DATA  and  QUENCH_COST
     are  TRUE, then *User_Quench_Cost_Scale is read in from asa_opt_recur.
     If  RECUR_OPTIONS_FILE,  RECUR_OPTIONS_FILE_DATA,   QUENCH_COST,   and
     QUENCH_PARAMETERS   are   TRUE,   then   *User_Quench_Cost_Scale   and
     User_Quench_Param_Scale [] all are read in from asa_opt_recur.

     9.1.7.  COST_FILE=TRUE

          If COST_FILE is set to TRUE, then you can use a separate file  to
     define  your  cost function.  When used together with OPTIONS_FILE and
     OPTIONS_FILE_DATA both set to TRUE, most users may be able to just use
     their  own asa_usr_cst.c file for their cost_function () together with
     the asa_opt data file, and not  have  to  work  through  some  of  the
     examples and templates contained in asa_usr.c.

          When  COST_FILE  is  set to TRUE, the file asa_usr_cst.c contains
     cost_function ().  If you wish to change the name of cost_function  ()
     in  asa_usr_cst.c,  then you must also change this name in the call to
     asa () in asa_usr.c (search  under  "asa  (")  and  in  the  prototype
     listing in asa_usr.h (in the HAVE_ANSI set to TRUE or FALSE section as
     appropriate).  You may wish to copy the appropriate parameter list  in
     asa_usr_cst.c just before the ASA_TEST problem to be sure of using the
     proper format expected by asa() in asa.c.

          The  http://www.ingber.com/asa_examples.txt   file   contains   a
     section  Use  of  COST_FILE  on  Shubert Problem which illustrates the
     simple modifications of ASA required to use COST_FILE.

     9.1.8.  ASA_LIB=FALSE

          Setting ASA_LIB=TRUE will facilitate your  running  asa ()  as  a
     library  call  from another program, calling asa_main () in asa_usr.c.
     In the templates  provided,  all  initializations  and  cost  function
     definitions  are set up in the user module.  For example, you may wish
     to have some data read in to a module that  calls  asa_main  (),  then
     parses  out  this  information  to  the  arrays  in  asa_main  ()  and
     initialize_parameters (and possibly recur_initialize_parameters).   In
     conjunction   with   setting  printout  to  stdout  (see  ASA_OUT  and


                                     - 16 -





     Adaptive Simulated Annealing (ASA)                       Lester Ingber




     USER_ASA_OUT), this can be a convenient way of using the same  asa_run
     executable for many runs.

          When  ASA_LIB  is  TRUE,  another  function  becomes available in
     asa_usr.c, asa_seed (), which can be used to change the  initial  seed
     used in runs made by asa_main ().  If this routine is not called, then
     the default initial seed is used.  An example of  using  this  routine
     when  calling asa_main () is given with ASA_TEMPLATE_LIB, using a main