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.)

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

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 mymainwhere 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.

- all variables have the same meaning as cmaps arguments

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 -lmwhere 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.