Instructions for calling MAPS
from Fortran
Amy Yates
(These instructions assume use of g++, gcc, and g77. For questions
about the C++ implementation of MAPS, check out the User's Manual at http://www.cs.wm.edu/~va/software/maps/manual.html)
In order to use MAPS and its associated classes, you will
need to download the following file:
- maps.tgz
(This file contains the MAPS implementation, the files necessary for
FORTRAN migration, and all of the files available from netlib that are
required.)
Place
this in a directory of your choosing. Then type "tar zxvf maps.tgz" to
create a directory called Maps with all of the necessary files. (If
your version of tar doesn't support the z option, then type "gunzip
maps.tgz" and then "tar xvf maps.tar".) Once you have extracted
the maps file, go into the Maps directory and type "make install" to
extract and compile the netlib files. Under Solaris, you may have
trouble compiling the libf2c directory. There are instructions in the
file libf2c/makefile.u which should help.
Now you can make the C++ version of MAPS by typing "make
maps". This makes one test executable called "maps", as described in the
MAPS User's Manual. You can also make a FORTRAN version by typing "make
fmaps". This will create the archive libmaps.a and give you a test
executable called fmaps based on the file "MyMain.f".
If you have followed these instructions, you should now have
four libraries in your directory: libBLAS.a, libf2c.a, libLAPACK.a, and
libmaps.a. If you choose to create files of your own in a
different directory, simply copy these libraries over.
The user must provide two things to use the callable
subroutines in FORTRAN:
- A FORTRAN subroutine which implements the objective function
- A main routine which calls the FORTRAN wrappers
You
can call the FORTRAN subroutine whatever you like, but it must have the
following signature:
objf(x, f, n)
double precision x(n), f
integer n
where n is the dimension of the problem, x is the array of
points to evaluate, and f is the function evaluation. The order of
arguments is hardcoded in the C++, and must be maintained. An example of
a subroutine that implements an objective function is given in the file MyMain.f,
along with a main routine to call the wrappers. The objective function
also shows how bounds can be constructed by heavily penalizing x values
outside the bounds.
Next, you will write a FORTRAN routine to call the version
of MAPS you are interested in. While this routine will serve as the main
program, it must actually be considered a subroutine to interact with
the C++ classes. It should be initiated with the line:
subroutine mymain
where
mymain is the hard-coded name for the subroutine.
Two ways of using MAPS are provided. The first subroutine,
cmaps, is a more complicated implementation, which requires a lot of
user input. The second version, emaps, can be called if the user prefers
mostly default settings. The file callmaps.f
shows the subroutines and describes the input in detail. To sum up, the
functions are as follows:
subroutine cmaps(obj, dim, maxf, maxi, delta, cor, search,
trend,
c
weight, lower, upper, start, seed, gfx, iter,
c
aux)
- obj is a pointer to the subroutine containing the objective
function evaluation. Name this subroutine whatever you want. Just be
sure it follows the signature given above and declare it as external if
it's not in your main file.
- The integer dim is the dimension of the problem
- The integer maxf is the total number of function calls
allowable.
- The integer maxi is the number of function calls allowable
for initialization.
- Double precision delta is the initial mesh size. If the user
passes -1, MAPS will compute an initial delta and pass it back inside
this variable.
- The integer cor is the correlation method to use for
Kriging. (0 - Exponential Isotropic, 1 - Gaussian Isotropic, 2 -
Exponential Product, 3 - Gaussian Product, 4 - Cubic Isotropic) The
default of -1 uses Gaussian Isotropic.
- The integer array search tells what type of search to
perform. If the first element is 0 or -1, a Compass Search is performed
and no other elements are required. If the first element is 1, a
Multicompass Search is selected and the software will expect 3 more
array elements. ( search(2): Number of searches, search(3): Max calls
(-1 for no maximum), search(4): Random stream between 10 and 255 )
- The integer trend tells MAPS to use a constant trend if 0 or
-1 and a quadratic trend if 1.
- The double precision array weight contains 1-5 elements. The
simplest way to apply a weighting scheme is to make the first element
-1. In this case, default values are used to create a dynamic weighting
scheme, and no other elements are required. Other options for the first
element are:
- 0 - Weight Multiple
- weight(2) = initial weight
- weight(3) = the multiple, m, which the previous iteration's
weight is multiplied by
- 1 - Weight Target Value
- weight(2) = initial weight
- weight(3) = weight of insignificance
- weight(4) = % of non-design function evaluations at which to
reach weight of insignificance
- 2 - Weight Delta Multiple
- weight(2) = initial weight
- weight(3) = the multiple, dm, to multiply the weight by
after grid refinement
- 3 - Weight Dynamic Gross
- weight(2) = initial weight
- weight(3) = tolerance
- weight(4) = mb (bad multiplier)
- weight(5) = mg (good multiplier)
- 4 - Dynamic Weight
- weight(2) = initial weight
- weight(3) = mb (bad multiplier)
- weight(4) = mg (good multiplier)
- lower and upper are dim-dimensional arrays which specify the
lower and upper bounds of the problem
- Double precision array start is the starting point of the
objective function. If the first element is -1, MAPS will choose the
starting point and no other elements are required. Otherwise, dim
elements are expected.
- Integer seed is the random seed desired by the user. If -1
is passed, MAPS will choose a random seed and pass it back through this
variable.
- The integer gfx tells the level of graphics output desired
(only available for 1-D and 2-D problems). If gfx=0, no data files are
created. If gfx=1, data at termination is created, and the prefix of the
objective function is used to create filenames. If gfx=2, data files
are created at each iteration with the file prefix "iter".
- The logical iter tells MAPS whether to print the iteration
history to standard output. iter=true will print the history.
- The double precision array aux of size dim+2 returns
information from maps. The first element is the smallest function
evaluation. The next dim elements are the values of x at this point.
subroutine
emaps(obj, dim, maxf, maxi, lower, upper, start, seed, gfx, iter, aux)
- all variables have the same meaning as cmaps arguments
Either
of these subroutines may be used to call MAPS. An example of the mymain
subroutine is given in the distribution in the file MyMain.f. This file
reads from standard input, but you can redirect the data file
"example_f.dat" to run a test case by typing "fmaps <
example_f.dat". This can be compared with the standalone C++ program by
running "maps < example_cc.dat". (This program calls the standalone
executable "myobj" to evaluate the objective function.)
To make compilation as simple as possible, copy all of the
library files to the directory where you want to work. Write your
objective function and your main subroutine and compile using:
g77 -Wall -c [*.f]
substituting
whatever FORTRAN files you have created. This will give you object
files. To compile with maps, simply type:
g++ -Wall -o name_me *.o -L./ -lmaps -lLAPACK -lBLAS -lf2c
-lm
where
name_me is the executable name you choose and *.o are the object files
you created. Make sure the library files are listed exactly in this
order when compiling.
STANDARD DISCLAIMER:
Permission to use, copy, modify, and distribute this software for any
purpose without fee is hereby granted, provided that this entire notice
is included in all copies of any software which is or includes a copy
or modification of this software and in all copies of the supporting
documentation for such software. THIS SOFTWARE IS BEING PROVIDED "AS
IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTY. IN PARTICULAR, THE AUTHOR
OFFERS NO REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE
MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR
PURPOSE.