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
      1. Coordinate Search
      2. Compass Search
      3. NLess Search
      4. Hooke and Jeeves Method
      5. 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".