asa-readme.html

simulated annealing code ASA

an  element  passed  by a subroutine or as a physical coefficient in a
cost function.
<P>
ASA has  been  run  successfully  on  many  machines  under  many
compilers.   To  check out your own system, you can run `make` (or the
equivalent set of commands in  the  ASA-Makefile),  and  compare  your
asa_out  and  asa_usr_out  files  to the asa_test_asa and asa_test_usr
files, respectively, provided with this code.  No attempt was made  to
optimize any compiler, so that the test runs do not really signify any
testing of compilers or architectures; rather they  are  meant  to  be
used  as  a  guide  to  determine  what  you  might expect on your own
machine.
<P>
The major sections below describe the compilation procedures, the
Program  Options  available  to  you  to  control the code, the use of
templates to set up your user module and interface to the asa  module,
and how to submit bug reports.
<P>
If  you  already  have  your  own  cost function defined, you can
insert it into asa_usr_cst.c.  If you wish to insert more OPTIONS,  as
<P>
a quick guide to get started, you can search through asa_usr.c and the
ASA-Makefile for all  occurrences  of  &quot;MY_TEMPLATE_&quot;  to  insert  the
necessary   definitions   required  to  run  ASA.   If  you  use  both
<A HREF="#OPTIONS-FILE-TRUE">OPTIONS_FILE</A> and <A HREF="#OPTIONS-FILE-DATA-TRUE">OPTIONS_FILE_DATA</A> set to TRUE, then usually most such
information  can  be  placed  in  the  asa_opt file, and then only the
<A HREF="#double-cost-function-">cost_function</A>  ()  must  be  inserted.   The  place  to   insert   the
<A HREF="#double-cost-function-">cost_function</A> () is marked by &quot;MY_TEMPLATE_cost.&quot;
<P>
7.  <A NAME="ASA-Makefile-Compilation-Procedures">ASA-Makefile/Compilation Procedures</A> [<A HREF="#To-Top-of-ASA-READMEhtml">To-Top-of-ASA-README.html</A>]
<P>
The  ASA-Makefile  is  intended  to  be  a  template for your own
Makefile.  For quick use, just copy this file to Makefile, which  will
be recognized by any standard make tool.
<P>
The  PostScript(R)  ASA-README.ps  and  ASCII  ASA-README.txt and
ASA-README+.txt  files  were  generated   using   `make   doc`.    The
ASA-Makefile   describes  some  options  for  formatting  these  files
differently.  Use `make` or `make all` to compile and run asa_run, the
executable  prepared  for the test function.  Examine the ASA-Makefile
to determine the &quot;clean&quot; options available.
<P>
Since complex problems by their nature are often quite unique, it
is  unlikely  that  the  default  parameters  are  just right for your
problem.  However, experience has shown that if you a  priori  do  not
have  any  reason  to determine your own parameters, then you might do
just fine using  these  defaults,  and  these  are  recommended  as  a
first-order  guess.  These defaults can be changed simply by adding to
the DEFINE_OPTIONS line in the ASA-Makefile,  by  passing  options  on
your  command  line, and by changing structure elements in the user or
asa module as described below.  Depending on  how  you  integrate  ASA
into  your  own user modules, you may wish to modify this ASA-Makefile
or at least  use  some  of  these  options  in  your  own  compilation
procedures.
<P>
Note   that  the  ASA-Makefile  is  just  a  convenience,  not  a
necessity, to use ASA.  E.g., on systems which  do  not  support  this
utility,  you may simply compile the files following the guidelines in
the ASA-Makefile, taking care to pass the  correct  DEFINE_OPTIONS  to
your  compilation  commands  at your shell prompt.  Still another way,
albeit not as convenient, is  to  make  the  desired  changes  in  the
asa_usr_asa.h, and asa.h or asa_usr.h files as required.
<P>
Since   the   ASA-Makefile   contains   comments   giving   short
descriptions of some options, it should be considered as an  extension
of this documentation file.  For convenience, most of this information
is  repeated  below.   However,  to  see  how  they  can  be  used  in
compilations, please read through the ASA-Makefile.
<P>
For  example, to run the ASA test problem using the gcc compiler,
you could just type at your &quot;%&quot; prompt:
<BR>

% cp ASA-Makefile Makefile<BR>
% gcc -g -DASA_TEST=TRUE -o asa_run asa_usr.c asa_usr_cst.c asa.c -lm<BR>
% asa_run<BR>

<BR>
<P>
If you have defined your own cost function  in  asa_usr_cst.c  or
within the &quot;MY_TEMPLATE_&quot; guides in asa_usr.c, then <A HREF="#ASA-TEST-FALSE">ASA_TEST</A> should be
set to  FALSE  (the  default  if  <A HREF="#ASA-TEST-FALSE">ASA_TEST</A>  is  not  defined  in  your
compilation lines or in the ASA-Makefile).  The code for <A HREF="#ASA-TEST-FALSE">ASA_TEST</A>=TRUE
is given just above these guides as a template to  use  for  your  own
cost function.
<P>
The  easiest  way  for many users to quickly use ASA likely is to
invoke the <A HREF="#COST-FILE-TRUE">COST_FILE</A>, <A HREF="#OPTIONS-FILE-TRUE">OPTIONS_FILE</A>, and <A HREF="#OPTIONS-FILE-DATA-TRUE">OPTIONS_FILE_DATA</A> OPTIONS (the
default),  using  the  files  asa_usr_cst.c  and asa_opt as templates.
This   is   further   described   below   and   illustrated   in   the
<A HREF="http://www.ingber.com/asa_examples.txt">http://www.ingber.com/asa_examples.txt</A>  file  in  the  section  Use of
<A HREF="#COST-FILE-TRUE">COST_FILE</A> on Shubert Problem.
<P>
7.1.  <A NAME="DLL-ASA-Makefile">DLL ASA-Makefile</A> [<A HREF="#To-Top-of-ASA-READMEhtml">To-Top-of-ASA-README.html</A>]
<P>
Under Cygwin (cygwin.com), set <A HREF="#ASA-LIB-FALSE">ASA_LIB</A> to TRUE and <A HREF="#INCL-STDOUT-TRUE">INCL_STDOUT</A> to
FALSE (OPTIONS described below), with the command
<BR>
<BR> % make asadll
<BR>
to  produce  a DLL to call asa_main() as a DLL function under windows.
(Ignore  any  undefined  references  to   WinMain.)   Note  that   per
instructions  given  in  the ASA-Makefile, -mno-cygwin -mrtd should be
included in CFLAGS.
<P>
If paths are used to access files  in  code,  under  Windows  use
absolute   paths   with   &quot;\\&quot;   (double   back   slash)  to  separate
folders/directories,  instead  of  relative  paths  with  &quot;/&quot;  (single
forward slash) separators as on other Unix platforms.
<P>
8.  <A NAME="Generic-ASA-Interfaces">Generic ASA Interfaces</A> [<A HREF="#To-Top-of-ASA-READMEhtml">To-Top-of-ASA-README.html</A>]
<P>
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.
<P>
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 <A HREF="#ASA-LIB-FALSE">ASA_LIB</A> set to TRUE.
<P>
I have led many projects that required ASA  to  interface  with  Java,
Maple,  Matlab,  MySQL, etc.  The approach briefly described below can
<P>
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.
<P>
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.
<P>
The  generic  approach  is to utilize at least the OPTIONS <A HREF="#ASA-LIB-FALSE">ASA_LIB</A> and
<A HREF="#OPTIONAL-DATA-PTR-FALSE">OPTIONAL_DATA_PTR</A>, setting them to TRUE.  <A HREF="#ASA-LIB-FALSE">ASA_LIB</A> permits  the  entire
ASA code to be called as a simple function.  Its sole parameter can be
a  struct  defined  by  <A HREF="#OPTIONAL-PTR-TYPE-USER-TYPE">OPTIONAL_PTR_TYPE</A>,   e.g.,   <A HREF="#OPTIONAL-PTR-TYPE-USER-TYPE">OPTIONAL_PTR_TYPE</A>
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,
<A HREF="#ASA-LIB-FALSE">ASA_LIB</A>  can be used to create a DLL to be called by Windows programs.
<P>
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.
<P>
The  other  language passes information and data to project.c required
by  ASA,  where  it   is   packed   into   the   struct   defined   by
<A HREF="#OPTIONAL-PTR-TYPE-USER-TYPE">OPTIONAL_PTR_TYPE</A>.   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
<A HREF="#OPTIONAL-DATA-PTR-FALSE">OPTIONAL_DATA_PTR</A>, the pointer to Project struct is set to the pointer
path to <A HREF="#OPTIONS--gt-Asa-Data-Ptr">Asa_Data_Ptr</A>.   <A HREF="#OPTIONS--gt-Asa-Data-Ptr">Asa_Data_Ptr</A>  is  now  passed  throughout  the
entire  ASA  code  via  the OPTIONS pointer, project parameters can be
adaptively changed, etc.
<P>
After the call to <A HREF="#double-asa-">asa ()</A> in asa_usr.c, its output can be  packed  into
the  project struct, before memory is freed.  The pointer <A HREF="#OPTIONS--gt-Asa-Data-Ptr">Asa_Data_Ptr</A>
should be set to NULL instead of freed; see the comment  in  asa_usr.c
at the place <A HREF="#OPTIONS--gt-Asa-Data-Ptr">Asa_Data_Ptr</A> is freed in the default code.
<P>
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
<P>
ASA-Makefile.
<P>
9.  <A NAME="User-Options">User Options</A> [<A HREF="#To-Top-of-ASA-READMEhtml">To-Top-of-ASA-README.html</A>]
<P>
Program Options, i.e., the USER_DEFINES typedef on  the  OPTIONS,
USER_OPTIONS,  RECUR_USER_OPTIONS,  etc.,  are  turned  on  during the
running of <A HREF="#double-asa-">asa ()</A>.  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 <A HREF="#OPTIONS--gt-Reanneal-Parameters-TRUE-">Reanneal_Parameters</A>, and an example
of  the  latter  is <A HREF="#ASA-SAMPLE-FALSE">ASA_SAMPLE</A>.  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 <A HREF="#SELF-OPTIMIZE-FALSE">SELF_OPTIMIZE</A>, might be
facilitated by having control of  some  Program  Options  at  separate
levels.
<P>
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 <A HREF="#OPTIONS-FILE-TRUE">OPTIONS_FILE</A>
and  <A HREF="#RECUR-OPTIONS-FILE-FALSE">RECUR_OPTIONS_FILE</A> exist.  I have tried to strike some reasonable
balance between these goals and constraints.
<P>
The DEFINE_OPTIONS are organized  into  two  groups:  Pre-Compile
Options  and  (Pre-Compile)  Printing Options.  In a