The new
.if t $T sub {0 ~ roman cost}$
.if n T_0cost
is taken to be the minimum of the current initial cost temperature and
the maximum of the absolute values of the best and last cost functions
and their difference.  The new
.if t $k sub {roman cost}$
.if n k_cost
is calculated taking
.if t $T sub { roman cost}$
.if n T_cost
as the maximum of the current value and the absolute value of the
difference between the last and best saved minima of the cost function,
constrained not to exceed the current initial cost temperature.  This
procedure essentially resets the scale of the annealing of the cost
temperature within the scale of the current best or last saved
minimum.
.PP
This default algorithm for reannealing the cost temperature, taking
advantage of the ASA importance sampling that relates most specifically
to the parameter temperatures, while often is quite efficient for some
systems, may lead to problems in dwelling too long in local minima for
other systems.  In such case, the user may also experiment with
alternative algorithms effected using the Reanneal_Cost OPTIONS,
discussed below.  For example, ASA provides an alternative calculation
for the cost temperature, when Reanneal_Cost < -1 or > 1, that
periodically calculates the initial and current cost temperatures or
just the initial cost temperature, resp., as a deviation over a sample
of cost functions.
.PP
These reannealing algorithms can be changed adaptively by the user as
described below in the sections USER_REANNEAL_COST and
USER_REANNEAL_PARAMETERS.
.NH 2
Efficiency Versus Necessity
.XS
\*(SN 		Efficiency Versus Necessity
.XE
.PP
ASA is not necessarily an \*Qefficient\*U code.  For example, if you
know that your cost function to be optimized is something close to a
parabola, then a simple gradient Newton search method most likely would
be faster than ASA.  ASA is believed to be faster and more robust than
other simulated annealing techniques for \f2most\f1 complex problems
with multiple local optima; again, be careful to note that some
problems are best treated by other algorithms.  If you do not know much
about the structure of your system, and especially if it has complex
constraints, and you need to search for a global optimum, then this ASA
code is heartily recommended to you.
.PP
In the context of efficiency and necessity, the user should be alert to
recognize that any sampling or optimization program generally should be
considered as complementary, not as a substitute, to gaining knowledge
of a particular system.  Unlike relatively \*Qcanned\*U codes that
exist for (quasi\-)linear systems, nonlinear systems typically are
non\-typical.  Often some homework must be done to understand the
system, and tuning often is required of numerical algorithms such as
ASA.  For example, while principal component analyses (PCA) often
suffices to generate good (quasi\-)orthogonal or (quasi\-)independent
sets of parameters, this is not true for general nonlinear systems.
While such innovations as reannealing take good advantage of ASA which
offers independent distributions for each parameter, this generally may
not be a good substitute for a user\-defined front\-end, e.g., before the
call to asa\ () or even embedded within the cost_function (), to interpret
and define relevant parameters.
.PP
The ASA\-NOTES file contains the sections @@Number of Generated States
Required and @@Judging Importance\-Sampling, recommending use of log\-log
plots to extrapolate the number of generated states required to attain
a global minimum, possibly as a function of selected OPTIONS.
.NH 1
Outline of Use
.XS
\*(SN 	Outline of Use
.XE
.PP
Set up the ASA interface: Your program should be divided into two basic
modules.  (1) The user calling procedure, containing the cost function
to be minimized (or its negative if you require a global maximum), is
contained in asa_usr.c, asa_usr.h and asa_usr_cst.c.  (2) The ASA optimization
procedure, is contained in asa.c and asa.h.  The file asa_usr_asa.h
contains definitions and macros common to both asa.h and asa_usr.h.
Furthermore, there are some options to explore/read below.  It is
assumed there will be no confusion over the standard uses of the term
\*Qparameter\*U in different contexts, e.g., as an element passed by a
subroutine or as a physical coefficient in a cost function.
.PP
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.
.PP
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.
.PP
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 a quick guide
to get started, you can search through asa_usr.c and the ASA\-Makefile for all
occurrences of \*QMY_TEMPLATE_\*U to insert the necessary definitions
required to run ASA.  If you use both OPTIONS_FILE and
OPTIONS_FILE_DATA set to TRUE, then usually most such information can
be placed in the asa_opt file, and then only the cost_function () must
be inserted.  The place to insert the cost_function () is marked by
\*QMY_TEMPLATE_cost.\*U
.NH 1
ASA\-Makefile/Compilation Procedures
.XS
\*(SN 	ASA\-Makefile/Compilation Procedures
.nr Mc \*(SN
.XE
.PP
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.
.PP
The PostScript\(rg 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 \*Qclean\*U
options available.
.PP
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 \f2a priori\f1 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.
.PP
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.
.PP
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.
.PP
For example, to run the ASA test problem using the gcc compiler, you
could just type at your \*Q%\*U prompt:
.nf
.in +8n
% cp ASA-Makefile Makefile
% gcc -g -DASA_TEST=TRUE -o asa_run asa_usr.c asa_usr_cst.c asa.c -lm
% asa_run
.in 0
.fi
.PP
If you have defined your own cost function in asa_usr_cst.c or within the
\*QMY_TEMPLATE_\*U guides in asa_usr.c, then ASA_TEST should be set to
FALSE (the default if ASA_TEST is not defined in your compilation lines
or in the ASA\-Makefile).  The code for ASA_TEST=TRUE is given just above
these guides as a template to use for your own cost function.
.PP
The easiest way for many users to quickly use ASA likely is to invoke the
COST_FILE, OPTIONS_FILE, and OPTIONS_FILE_DATA OPTIONS (the default),
using the files asa_usr_cst.c and asa_opt as templates.  This is further
described below and illustrated in the http://www.ingber.com/asa_examples.txt
file in the section Use of COST_FILE on Shubert Problem.
.NH 2
DLL ASA\-Makefile
.XS
\*(SN 		DLL ASA\-Makefile
.XE
.nr Md \*(SN
.PP
Under Cygwin (cygwin.com), set ASA_LIB to TRUE and INCL_STDOUT to FALSE
(OPTIONS described below), with the command
.in +8n
% make asadll
.in 0
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.
.PP
If paths are used to access files in code, under Windows use absolute
paths with \*Q\\\\\*U (double back slash) to separate folders/directories,
instead of relative paths with \*Q/\*U (single forward slash) separators
as on other Unix platforms.
.NH 1
Generic ASA Interfaces
.XS
\*(SN 	Generic ASA Interfaces
.XE
.PP
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.
.LP
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.
.LP
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.
.LP
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.
.LP
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 \n(Md, ASA_LIB can be used to create
a DLL to be called by Windows programs.
.LP
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.
.LP
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.
.LP
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.
.LP
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.
.NH 1
User Options
.XS
\*(SN 	User Options
.XE
.PP
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.
.PP
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.
.PP
The DEFINE_OPTIONS are organized into two groups: Pre\-Compile Options
and (Pre\-Compile) Printing Options.  In addition, there are 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.
.PP
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.
.NH 2
Pre-Compile DEFINE_OPTIONS
.XS
\*(SN 		Pre-Compile DEFINE_OPTIONS
.XE
.LP
.NH 3
USER_COST_FUNCTION=cost_function
.XS
\*(SN 			USER_COST_FUNCTION=cost_function
.XE
.PP
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.
.NH 3
RECUR_USER_COST_FUNCTION=recur_cost_function
.XS
\*(SN 			RECUR_USER_COST_FUNCTION=recur_cost_function
.XE
.PP
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.
.NH 3
OPTIONS_FILE=TRUE
.XS
\*(SN 			OPTIONS_FILE=TRUE
.XE
.PP
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.
.NH 3
OPTIONS_FILE_DATA=TRUE
.XS
\*(SN 			OPTIONS_FILE_DATA=TRUE
.XE
.PP
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