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.
.PP
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.
.NH 3
RECUR_OPTIONS_FILE=FALSE
.XS
\*(SN 			RECUR_OPTIONS_FILE=FALSE
.XE
.PP
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.
.NH 3
RECUR_OPTIONS_FILE_DATA=FALSE
.XS
\*(SN 			RECUR_OPTIONS_FILE_DATA=FALSE
.XE
.PP
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.
.PP
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.
.NH 3
COST_FILE=TRUE
.XS
\*(SN 			COST_FILE=TRUE
.XE
.PP
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.
.PP
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 \*Qasa (\*U) 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.
.PP
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.
.NH 3
ASA_LIB=FALSE
.XS
\*(SN 			ASA_LIB=FALSE
.XE
.PP
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 USER_ASA_OUT), this can be a
convenient way of using the same asa_run executable for many runs.
.PP
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 () at the end of
the asa_usr.c file.
.PP
As described in the DLL ASA\-Makefile sub-Section of Section \n(Md, the
ASA\-Makefile and ASA_LIB can be used to create a DLL for Windows programs.
.NH 3
HAVE_ANSI=TRUE
.XS
\*(SN 			HAVE_ANSI=TRUE
.XE
.PP
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.
.NH 3
IO_PROTOTYPES=FALSE
.XS
\*(SN 			IO_PROTOTYPES=FALSE
.XE
.PP
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.
.NH 3
TIME_CALC=FALSE
.XS
\*(SN 			TIME_CALC=FALSE
.XE
.PP
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.
.NH 3
TIME_STD=FALSE
.XS
\*(SN 			TIME_STD=FALSE
.XE
.PP
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.
.NH 3
TIME_GETRUSAGE=TRUE
.XS
\*(SN 			TIME_GETRUSAGE=TRUE
.XE
.PP
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.
.NH 3
INT_LONG=TRUE
.XS
\*(SN 			INT_LONG=TRUE
.XE
.PP
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.
.NH 3
INT_ALLOC=FALSE
.XS
\*(SN 			INT_ALLOC=FALSE
.XE
.PP
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.
.NH 3
SMALL_FLOAT=1.0E-18
.XS
\*(SN 			SMALL_FLOAT=1.0E-18
.XE
.PP
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.
.PP
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.
.PP
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.
.NH 3
MIN_DOUBLE=SMALL_FLOAT
.XS
\*(SN 			MIN_DOUBLE=SMALL_FLOAT
.XE
.PP
You can define your own machine's minimum positive double here if you
know it.
.NH 3
MAX_DOUBLE=1.0/SMALL_FLOAT
.XS
\*(SN 			MAX_DOUBLE=1.0/SMALL_FLOAT
.XE
.PP
You can define your own machine's maximum double here if you know it.
.NH 3
EPS_DOUBLE=SMALL_FLOAT
.XS
\*(SN 			EPS_DOUBLE=SMALL_FLOAT
.XE
.PP
You can define your own machine's maximum precision here if you know
it.
.NH 3
CHECK_EXPONENT=FALSE
.XS
\*(SN 			CHECK_EXPONENT=FALSE
.XE
.PP
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.
.NH 3
NO_PARAM_TEMP_TEST=FALSE
.XS
\*(SN 			NO_PARAM_TEMP_TEST=FALSE
.XE
.PP
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.
.NH 3
NO_COST_TEMP_TEST=FALSE
.XS
\*(SN 			NO_COST_TEMP_TEST=FALSE
.XE
.PP
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.
.NH 3
SELF_OPTIMIZE=FALSE
.XS
\*(SN 			SELF_OPTIMIZE=FALSE
.XE
.PP
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.)
.PP
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 ().
.PP
This can be useful when approaching a new system, and it is suspected
that the default ASA Program Options are not at all 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\ ().
.NH 3
ASA_TEST=FALSE
.XS
\*(SN 			ASA_TEST=FALSE
.XE
.PP
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.
.NH 3
ASA_TEST_POINT=FALSE
.XS
\*(SN 			ASA_TEST_POINT=FALSE
.XE
.PP
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.
.PP
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.
.NH 3
MY_TEMPLATE=TRUE
.XS
\*(SN 			MY_TEMPLATE=TRUE
.XE
.PP
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
\*QMY_TEMPLATE_\*U 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.
.NH 3
USER_INITIAL_COST_TEMP=FALSE
.XS
\*(SN 			USER_INITIAL_COST_TEMP=FALSE
.XE
.PP
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.
.NH 3
RATIO_TEMPERATURE_SCALES=FALSE
.XS
\*(SN 			RATIO_TEMPERATURE_SCALES=FALSE
.XE
.PP
Different rates of parameter annealing can be set with
RATIO_TEMPERATURE_SCALES set to TRUE.  This requires initializing the
User_Temperature_Ratio [] array in the user module as discussed below.
.NH 3
USER_INITIAL_PARAMETERS_TEMPS=FALSE
.XS
\*(SN 			USER_INITIAL_PARAMETERS_TEMPS=FALSE
.XE
.PP
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
sett