Instructions for calling Direct Search
Libraries from C
(For now, only machines with GNU compilers should be used.)
First, download the Direct Search tarball from
the website. Untar it in a new directory, but don't compile yet. Now
copy the file SearchWrappers.tar
by holding down the shift key and clicking on the link. Untar this file
in the directory with the direct search classes. Typing "make -f
Makefile.linux.c" will make a sample executable on Linux called MySearch
that optimizes the objective function in MyMain.c. You
can modify the sample program MyMain.c to suit your needs.
The user must provide two things to use the direct search
libraries:
- A C subroutine which implements the objective function
- A main routine which calls the C wrappers
You can call the C subroutine whatever you like, but it must
have the following signature:
void objc(x, f, n)
double x[], *f;
long *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.c, 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 C routine to call the direct search
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:
int mymain_()
where mymain_ is the hard-coded name for the subroutine. The
appended underscore is necessary for the code to work with FORTRAN
wrappers as well.
There are eight types of searches provided by the direct
search classes, including five pattern searchs and three simplex
searches. You may access them by calling any of the four subroutines in
the file direct.c , which comes as part
of the direct search library.The functions are as follows:
int cpattrn(choice, obj, n, x, step1, step2, maxf, aux, iaux)
int choice, n, maxf, *iaux;
void (*obj) (double *, double *,
long *);
double x[], step1, step2, aux[];
- The integer choice refers to the search type preferred. The
five types of pattern searches are
- Coordinate Search
- Compass Search
- NLess Search
- Hooke and Jeeves Method
- Edited Hooke and Jeeves (changes by E.
Dolan)
- 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
extern if it's not in your main file.
- The integer n is the dimension of the problem
- Double precision x is the starting point of the
objective function. It will be an array of size n.
- Double precision step1 is the starting step length.
If -1 is passed, a default of 0.25 is used.
- Double precision step2 is the ending step length. If
-1 is passed, a default of 10E-8 is used.
- The integer maxf is the maximum allowable number of
function calls. If -1 is passed, no maximum is set.
- The double precision array aux is of size n+2. The
first value is the final step length. The second value is the minimum
function evaluation. This is followed by an n-sized array containing the
x values at the minimum.
- The integer iaux returns the number of function
evaluations.
- The function returns the completion status, referred to as istat
in the FORTRAN wrappers. Since no failure criteria are currently
implemented in the classes, istat should always return as 1.
int cshh(obj, n, x, right, step1, step2, maxf, stddev, aux,
iaux)
int n, right, maxf, stddev, *iaux;
void (*obj) (double *, double *,
long *);
double x[], step1[], step2, aux[];
- This is a Simplex Search based on the work of Spendley,
Hext, and Himsworth.
- The arguments obj, n, x, step2,maxf,aux,
and iaux have the same meanings as in the cpattrn() subroutine.
- The integer right is set to 1 if the user wants a
right simplex. It is set to 0 if the user prefers a regular simplex.
- The double precision array step1 represents the
starting edgelengths of the simplex. If the user wants a regular
simplex, only one value is required. If the user wants a right simplex,
the program expects an array of n edgelengths. (The n+1 edge will be
calculated automatically.) Set the first value to -1 to use the default
of 2.0 for the edgelengths.
- The integer stddev is set to 1 if the user wants
stopping criteria dependent on standard deviation. If it is 0, the
search will stop based on delta.
- The function returns the completion status, referred to as istat
in the FORTRAN wrappers. Since no failure criteria are currently
implemented in the classes, istat should always return as 1.
int cnm(obj, n, x, right, sigma, alpha, beta, gamma, step1,
step2, maxf, stddev, aux, iaux)
int n, right, maxf, stddev, *iaux;
void (*obj) (double *, double *,
long *);
double x[], step1[], step2, aux[];
double sigma, alpha, beta, gamma;
- This is a Simplex Search based on the work of Nelder and
Meade.
- The arguments obj, n, x, step2,maxf,aux,
and iaux have the same meanings as in the cpattrn() subroutine.
- The arguments right, step1, and stddev
have the same meanings as in the cshh() subroutine.
- The double precision sigma is the shrinking
coeffient. If -1 is passed, a default of 0.5 is used.
- The double precision alpha is the reflection
coeffient. If -1 is passed, a default of 1.0 is used.
- The double precision beta is the contraction
coeffient. If -1 is passed, a default of 0.5 is used.
- The double precision gamma is the expansion
coeffient. If -1 is passed, a default of 2.0 is used.
- The function returns the completion status, referred to as istat
in the FORTRAN wrappers. Since no failure criteria are currently
implemented in the classes, istat should always return as 1.
int csmd(obj, n, x, right, step1, step2, maxf, stddev, aux,
iaux)
int n, right, maxf, stddev, *iaux;
void (*obj) (double *, double *,
long *);
double x[], step1[], step2, aux[];
- This simplex search implements a sequential multidirectional
search.
- The arguments are exactly the same as the subroutine cshh().
Any of these subroutines may be used to find the minimum of
your objective function. The main routine provided in MyMain.c is an
example of an interactive routine which queries the user and calls the
appropriate subroutine. By performing a simple search and replace on the
provided objective function "objc", the user can insert their own
objective function into the calls.
To see how the example program works, you can use and modify
the data file sample.dat. Simply run
"MySearch<sample.dat".
|