asa-readme.html

simulated annealing code ASA

3.2.4.  <A NAME="ASA-README-html">ASA-README.html</A> [<A HREF="#To-Top-of-ASA-READMEhtml">To-Top-of-ASA-README.html</A>]
<P>
ASA-README.html is an HTML version which enables easier access to
subsections of this file.  Cross-references have been  kept  local  to
this  file,  so  you may view it under a local browser if you download
the HTML source file.
<P>
The   background   image   file   asa_back.jpg   referenced    in
ASA-README.html          can          be         downloaded         as
<A HREF="http://www.ingber.com/asa_back.jpg">http://www.ingber.com/asa_back.jpg</A> from the ASA archive.
<P>
3.3.  <A NAME="Additional-Documentation">Additional Documentation</A> [<A HREF="#To-Top-of-ASA-READMEhtml">To-Top-of-ASA-README.html</A>]
<P>
ASA-CHANGES is a terse record of major changes made  in  the  ASA
code.   It  has  three  sections,  CHANGES,  CONTRIBUTORS, and VERSION
DATES.
<P>
ASA-NOTES  is   a   collection   of   recommended   enhancements,
modifications,  comments,  caveats,  etc.,  that might be of interest.
There is a CONTENTS of sections headers that can be used to search  on
topics in your browser or editor.
<P>
There  are  three  files  in  the  ASA  archive  that  should  be
considered    as     appendices     to     the     ASA-NOTES     file:
<A HREF="http://www.ingber.com/asa_contrib.txt">http://www.ingber.com/asa_contrib.txt</A>,
<A HREF="http://www.ingber.com/asa_examples.txt">http://www.ingber.com/asa_examples.txt</A>,                            and
<A HREF="http://www.ingber.com/asa_papers.html">http://www.ingber.com/asa_papers.html</A> under WWW.
<P>
The file <A HREF="http://www.ingber.com/asa_contrib.txt">http://www.ingber.com/asa_contrib.txt</A> in the ASA archive
contains some code contributed by users.  For example, references  are
giving  to  asamin,  a  MATLAB gateway routine to ASA, and to function
support for <A HREF="#ASA-PARALLEL-FALSE">ASA_PARALLEL</A>.  There is a  CONTENTS  of  sections  headers
that  can  be  used to search on topics in your browser or editor.  In
this file I have included the first 1987 VFSR code, the  precursor  to
the  ASA  code,  as  used  on a specific project, including the RATFOR
vfsr.r and vfsr_com.r code, subsequently compiled into FORTRAN to  run
on  a  Lawrence  Livermore  supercomputer.   I do not support this old
RATFOR code.
<P>
The  file  <A HREF="http://www.ingber.com/asa_examples.txt">http://www.ingber.com/asa_examples.txt</A>  in   the   ASA
archive contains some example problems using ASA.  There is a CONTENTS
of sections headers that can be used  to  search  on  topics  in  your
browser  or  editor.  This file contains some &quot;toy&quot; problems optimized
using ASA, which  can  provide  immediate  examples  on  how  you  can
optimize your own problem.
<P>
The  file <A HREF="http://www.ingber.com/asa_papers.html">http://www.ingber.com/asa_papers.html</A> is an addendum to
the ASA-NOTES file in the ASA  code,  containing  references  to  some
patents and papers using ASA or its precursor VFSR.
<P>
The  file  asa_new.txt  in  the  ASA  archive  is a list of major
changes  in  ASA.   The  files   ASA-README.txt,   ASA-README.ps   and
ASA-README.pdf included with the code also are available independently
as                               <A HREF="http://www.ingber.com/ASA-README.txt">http://www.ingber.com/ASA-README.txt</A>,
<A HREF="http://www.ingber.com/ASA-README.ps.gz">http://www.ingber.com/ASA-README.ps.gz</A>,
<A HREF="http://www.ingber.com/ASA-README.html">http://www.ingber.com/ASA-README.html</A>,
<A HREF="http://www.ingber.com/ASA-README.pdf">http://www.ingber.com/ASA-README.pdf.</A>
<P>
There  is  a  set of <A HREF="#ASA-TEMPLATE-FALSE">ASA_TEMPLATE</A>'s available in the ASA-Makefile
and in the user module (some also in the asa module) to illustrate use
of  particular  OPTIONS,  as listed under <A HREF="#ASA-TEMPLATE-FALSE">ASA_TEMPLATE</A> below.  You can
search on these <A HREF="#ASA-TEMPLATE-FALSE">ASA_TEMPLATE</A>'s in your browser or editor  to  see  how
these  are implemented.  Note that some OPTIONS require your input, as
described below, and code may fail until you add your own code.   Once
you  have  determined  the  most  common set of DEFINE_OPTIONS you are
likely to use, you might place these in your own TEMPLATE at  the  top
of asa_usr_asa.h at the location specified, e.g.,
<BR>

#if <A HREF="#MY-TEMPLATE-TRUE">MY_TEMPLATE</A>                 /* MY_TEMPLATE_asa_user */<BR>
/* you can add your own set of #define here */<BR>
#define ... TRUE<BR>
#define ... 100<BR>
#endif<BR>

<BR>
<P>
See  <A HREF="http://www.ingber.com/utils_file_formats.txt">http://www.ingber.com/utils_file_formats.txt</A>  for some links
to information on gzip, PostScript, PDF, tar, and shar utilities.  The
file 00index_utils in that directory gives short statements describing
these      files,      which      may       be       accessed       as
<A HREF="http://www.ingber.com/index_utils.html">http://www.ingber.com/index_utils.html</A> under WWW.
<P>
3.4.  <A NAME="Use-of-Documentation-for-Tuning">Use of Documentation for Tuning</A> [<A HREF="#To-Top-of-ASA-READMEhtml">To-Top-of-ASA-README.html</A>]
<P>
I'm often asked how how I can help someone tune their system, and
they send me their cost function or a list of the ASA OPTIONS they are
using.   Most  often,  the  best help I can provide is based on my own
experience that  nonlinear  systems  typically  are  non-typical.   In
practice,  that means that trying to figure out the nature of the cost
function under sampling in order to tune ASA (or likely  to  similarly
tune  a  hard problem under any sampling algorithm), by examining just
the cost function, likely will not be as productive as generating more
intermediate  printout,  e.g.,  setting  <A HREF="#ASA-PRINT-MORE-FALSE">ASA_PRINT_MORE</A>  to  TRUE, and
looking  at  this  output  as  a  &quot;grey  box&quot;  of  insight  into  your
optimization  problem.  Larger files with more information is provided
by setting <A HREF="#ASA-PIPE-FILE-FALSE">ASA_PIPE_FILE</A> to TRUE.   Treat  the  output  of  ASA  as  a
simulation  in  the  ASA  parameter  space,  which  usually is quite a
different space than the variable space of your system.
<P>
For example, you should  be  able  to  see  where  and  how  your
solution  might  be  getting  stuck  in a local minima for a very long
time, or where the last saved state is still fluctuating across a wide
portion  of  your  state space.  These observations should suggest how
you might try speeding up or slowing down annealing/quenching  of  the
parameter space and/or tightening or loosening the acceptance criteria
at different stages by modifying the OPTIONS, e.g., starting with  the
OPTIONS that can be easily adjusted using the asa_opt file.
<P>
The  ASA-NOTES  file  that  comes with the ASA code provides some
guidelines for tuning that may provide some insights,  especially  the
section  Some  Tuning Guidelines.  An especially important guide is to
examine the output of ASA at several stages of  sampling,  to  see  if
changes  in  parameter  and  temperatures are reasonably correlated to
changes in the cost function.  Examples of useful OPTIONS  that  often
give  quick  changes  in tuning in some &quot;toy&quot; problems are in the file
<A HREF="http://www.ingber.com/asa_examples.txt">http://www.ingber.com/asa_examples.txt</A> under WWW.  Some of the reprint
files  of published papers in the ingber.com provide other examples in
harder systems, and perhaps you might find  some  examples  of  harder
systems      using      ASA     similar     to     your     own     in
<A HREF="http://www.ingber.com/asa_papers.html">http://www.ingber.com/asa_papers.html</A> under WWW.  This is the best way
<P>
to add some Art to the Science of annealing.
<P>
While  the  upside  of  using  ASA  is  that  is has many OPTIONS
available for tuning, derived in large part from  feedback  from  many
users over many years, making it extremely robust across many systems,
the downside is that the learning curve can be steep especially if the
default  settings  or simple tweaking in asa_opt do not work very well
for your particular system, and you then must turn to using  more  ASA
OPTIONS.    Most   of   these   OPTIONS  have  useful  guides  in  the
ASA_TEMPLATEs in asa_usr.c, as well as being documented here.  If  you
really  get  stuck,  you  may  consider  working with someone else who
already has climbed this learning curve  and  whose  experience  might
offer quick help.
<P>
4.  <A NAME="Availability-of-ASA-Code">Availability of ASA Code</A> [<A HREF="#To-Top-of-ASA-READMEhtml">To-Top-of-ASA-README.html</A>]
<P>
4.1.  <A NAME="ingber-com">ingber.com</A> [<A HREF="#To-Top-of-ASA-READMEhtml">To-Top-of-ASA-README.html</A>]
<P>
The  latest  Adaptive  Simulated  Annealing  (ASA)  code and some
related   papers   can   be    accessed    from    the    home    page
<A HREF="http://www.ingber.com/">http://www.ingber.com/</A>  under WWW, or retrieved via anonymous ftp from
ftp.ingber.com.
<P>
Interactively [brackets signify machine prompts]:
<BR>
[your_machine%] ftp ftp.ingber.com<BR>
[Name (...):] anonymous<BR>
[Password:] your_e-mail_address<BR>
[ftp&gt;] binary<BR>
[ftp&gt;] ls<BR>
[ftp&gt;] get file_of_interest<BR>
[ftp&gt;] quit<BR>

<BR>
<P>
The home page <A HREF="http://www.ingber.com/">http://www.ingber.com/</A> under  WWW,  and  the  ASCII
version 00index.txt, contain an index of the other files.
<P>
The latest version of ASA, ASA-x.y (x and y are version numbers),
can be obtained in two formats:  <A HREF="http://www.ingber.com/ASA.tar.gz">http://www.ingber.com/ASA.tar.gz</A>  and
<A HREF="http://www.ingber.com/ASA.zip">http://www.ingber.com/ASA.zip.</A>   The  tar'd  versions is compressed in
gzip format, and ASA.tar.gz.  In the zip'd version, ASA.zip, all files
have been processed for DOS format.
<P>
Patches  ASA-diff-x1.y1-x2.y2  up  to  the present version can be
prepared if a good case for doing so is presented, e.g. to  facilitate
updating  your  own  modified  codes.   These  may  be concatenated as
required before applying.  If you require a  specific  patch,  contact
<A HREF="mailto:[e-mail]">[e-mail].</A>
<P>
4.2.  <A NAME="Electronic-Mail">Electronic Mail</A> [<A HREF="#To-Top-of-ASA-READMEhtml">To-Top-of-ASA-README.html</A>]
<P>
If  you  do  not have WWW or FTP access, get the Guide to Offline
Internet    Access,    returned    by    sending    an    e-mail    to
<A HREF="mailto:[e-mail]">[e-mail]</A>     with     only     the     words     &quot;send
usenet/news.answers/internet-services/access-via-email&quot; in the body of
the  message.   The  guide gives information on using e-mail to access
just about all InterNet information and documents.  You  will  receive
the information in utils_access-via-email.txt in the ASA archive.
<P>
5.  <A NAME="Background">Background</A> [<A HREF="#To-Top-of-ASA-READMEhtml">To-Top-of-ASA-README.html</A>]
<P>
5.1.  <A NAME="Context">Context</A> [<A HREF="#To-Top-of-ASA-READMEhtml">To-Top-of-ASA-README.html</A>]
<P>
Too  often the management of complex systems is ill-served by not
utilizing the best tools available.  For example, requirements set  by
decision-makers  often  are  not  formulated  in  the same language as
constructs formulated by powerful mathematical formalisms, and so  the
products  of  analyses are not properly or maximally utilized, even if
and when they come  close  to  faithfully  representing  the  powerful
intuitions  they  are  supposed  to  model.   In  turn,  even powerful
mathematical constructs are ill-served, especially when  dealing  with
multivariate  nonlinear  complex  systems,  when  these formalisms are
butchered into quasi-linear approximations to satisfy  constraints  of
numerical  algorithms  familiar to particular analysts, but which tend
to  destroy  the  power  of  the  intuitive  constructs  developed  by
decision-makers.
<P>
In   order   to   deal   with  fitting  parameters  or  exploring
sensitivities of variables, as models  of  systems  have  become  more
sophisticated   in   describing   complex   behavior,  it  has  become
increasingly  important  to  retain  and  respect  the  nonlinearities
inherent  in  these  models, as they are indeed present in the complex
systems they model.  ASA can help to handle these  fits  of  nonlinear
models of real-world data.
<P>
It  helps  to  visualize  the  problems presented by such complex
systems as a geographical terrain.  For example, consider  a  mountain