DirectSearch

class DirectSearch

DirectSearch is the abstract base class for the PatternSearch and SimplexSearch classes

Inheritance:

Public Fields
static const long NO_MAX: If NO_MAX is used to initialize maxCalls (as it is by default), the search will terminate based only on refinement of the design

Public

Constructors and destructor

DirectSearch(long dim, Vector<double> &startPoint): Constructor
DirectSearch(const DirectSearch & Original): Copy constructor
DirectSearch(long dim, Vector<double> &startPoint, double stopStep, void (*objective)(long vars, Vector<double> &x, double &func, bool &flag, void* an_obj), void * input_obj): special constructor using void function and object pointers
virtual ~DirectSearch(): Destructor
DirectSearch& operator=(const DirectSearch& A): Overloaded assignment operator

Other initialization methods

virtual void ReadInFile(istream & fp): Reads the design in from a file supplied by the user
virtual void CleanSlate(long dim, Vector<double> & startPoint): Reinitializes values in order to reuse the same search object
virtual void CleanSlate(long dim, Vector<double> &startPoint, double stopStep, void (*objective)(long vars, Vector<double> &x, double &func, bool &flag, void* an_obj), void * input_obj): overloaded version of CleanSlate using void function and object pointers
void InitializeDesign(const Matrix<double> *designPtr): Deletes any existing pattern and replaces it with the one pointed to by designPtr
virtual void PrintDesign() const: Prints out search information

Search method

virtual void BeginSearch(): BeginSearch() is an unimplemented virtual void method in the abstract base classes

Accessors and Mutators

long GetFunctionCalls() const: Returns number of objective function evaluations so far
void SetFunctionCalls(long newCalls): Sets number of function calls already used--useful for times when you are using multiple searches for the same optimization; for example, if you wanted to do 100 function calls worth of SMDSearch followed by 100 calls (max) of HJSearch
int GetID() const: Returns the ID Number of the search
void GetMinPoint(Vector<double> & minimum) const: Retrieves the minimum point and assigns it to minimum The vector minimum should be of the correct dimension
void SetMinPoint(Vector<double> & minimum) const: Resets minPoint to the point represented by the input parameter minimum
void GetMinVal(double & value) const: Retrieves the best objective function value found thus far
void SetMinVal(double & value): Resets the minimum value to the value of the input parameter
long GetDimension() const: Returns the dimension of the problem
long GetMaxCalls() const: Returns the number of function calls in the budget; if the value is equal to NO_MAX, will terminate based only on refinement of the design
void SetMaxCalls(long calls): Use to set a function call budget; by default set to the value of NO_MAX, which indicates no budget, in which case the search will terminate based only upon grid refinement
void SetMaxCallsExact(long calls): Sets maxCalls to the value of calls, and sets exact_count to true, so search will terminate precisely when the call budget runs out
Matrix <double> * GetDesign(): Returns a pointer to a matrix initialized from the design matrix
void CopyDesign(Matrix<double>* &designPtr) const: Deep copy of the pattern to a Matrix pointer
double GetStoppingStepLength() const: Returns stoppingStepLength, the smallest step length allowed in the search
void SetStoppingStepLength(double len): Sets stoppingStepLength, the smallest step length allowed in the search, to the value of the input parameter
virtual void SetExact(): Allows the user to specify that the search will terminate precicely upon completion of maxCalls number of function calls
virtual void SetInexact(): Allows the user to specify that the search will terminate upon completion of roughly maxCalls number of function calls, but only after a pattern decrease or "shrink" step
virtual bool IsExact(): Returns the value of exact_count(q

Protected Fields
Matrix <double> * design: A pointer to a design matrix, with each trial direction a column
long dimension: the dimension of the search; i
Vector <double> * minPoint: the point having the lowest value so far
double minValue: best objective function value calculated thus far
long functionCalls: tally of the number of function call
long maxCalls: budget for number of function calls
double stoppingStepLength: the smallest steplength that will be allowed in the search
void* some_object: a void pointer, to be used in cases where additional information must be handled by the search
bool exact_count: A flag that determines whether to let the function call budget go slightly over so the search will wait until it has ordered a decrease in delta
int IDnumber: The ID number of the search

Protected Methods
virtual void ExploratoryMoves(): Exploratory Moves is an unimplemented virtual void function in the abstract base classes
virtual bool Stop(): Gives default stopping criteria based on maxCalls and stoppingStepLength
void fcnCall(long n, Vector<double> &x, double & f, bool& flag, void * nothing): Indirection of the call to the objective function for purposes of keeping an accurate tally of the number of function calls
virtual void CopySearch(const DirectSearch & Original): Used to implement the overloaded assignment operator
bool BreakOnExact(): A utility method used to implement the exact_count choice
void (*fcn_name)(long dim, Vector<double> &x, double & function, bool & success, void* an_object): The function to be minimized

Documentation

DirectSearch is the abstract base class for the PatternSearch and SimplexSearch classes. It contains:

--constructors,
--a virtual destructor,
--data members that will be used throughout all the classes,
--accessors for these data members,
--virtual void placeholders for the algorithmic member functions to be implemented in the concrete classes, and
--a few utility functions.

static const long NO_MAX

If NO_MAX is used to initialize maxCalls (as it is by default), the search will terminate based only on refinement of the design

Constructors and destructor

DirectSearch(long dim, Vector<double> &startPoint)
Constructor. This constructor has two parameters. Other data members will be set to default values, as follows. This is of course in addition to assignments and initializations made in derived classes. Note that fcn_name is set to fcn, the function found in objective.cc and objective.h. The user is responsible for putting his or her objective function into objective.cc in a form that will work with this constructor.

functionCalls = 0
design = NULL
minValue = HUGE_VAL
maxCalls = NO_MAX
stoppingStepLength = 10e-8
some_object = NULL
fcn_name = fcn (found in objective.cc)

Parameters:
dim - the dimension of the problem
startpoint - the start point for the search

DirectSearch(const DirectSearch & Original)
Copy constructor
Parameters:
Original - a reference to the object from which to initialize

DirectSearch(long dim, Vector<double> &startPoint, double stopStep, void (*objective)(long vars, Vector<double> &x, double &func, bool &flag, void* an_obj), void * input_obj)
special constructor using void function and object pointers. The objective function can be sent in as the fourth parameter here; the last parameter is used for any other information that may be necessary; it is used in MAPS, for example, to send in an object from an outside class. Usually, though, the final parameter will simply be set to NULL.
This constructor takes five input parameters.
Parameters:
dim - the dimension of the problem
startPoint - a Vector of doubles, the starting point for the search
stopStep - the stopping step length for the search
objective - a pointer to the function to be minimized
input_obj - used to send additional data as needed--will normally be set to NULL.

virtual ~DirectSearch()
Destructor

DirectSearch& operator=(const DirectSearch& A)
Overloaded assignment operator. note that because DirectSearch is an abstract base class, the object actually returned will be of a type corresponding to one of the concrete classes.
Returns:
DirectSearch&
Parameters:
A - reference to a const DirectSearch object

Other initialization methods

virtual void ReadInFile(istream & fp)
Reads the design in from a file supplied by the user. User may also pass cin as the input stream as desired. This method is unimplemented in this abstract base class; it will be implemented at a lower level in the hierarchy.

virtual void CleanSlate(long dim, Vector<double> & startPoint)
Reinitializes values in order to reuse the same search object. This version of CleanSlate takes two parameters. Other data members are set by default as in the constructor DirectSearch(long, Vector<double>&).
Returns:
void
Parameters:
dim - the dimension of the problem
startPoint - the new starting point for the search
See Also:
CleanSlate(long dim, Vector &startpoint, double stopStep, void (*objective)(long vars, Vector &x, double & func, bool& flag, void* an_obj), void * input_obj)

virtual void CleanSlate(long dim, Vector<double> &startPoint, double stopStep, void (*objective)(long vars, Vector<double> &x, double &func, bool &flag, void* an_obj), void * input_obj)
overloaded version of CleanSlate using void function and object pointers. This version of CleanSlate takes six parameters.
Returns:
void
Parameters:
dim - the dimension of the problem
startPoint - a Vector of doubles, the starting point for the search
stopStep - the stopping step length for the search
objective - a pointer to the function to be minimized
input_obj - used to send additional data as needed--will normally be set to NULL.
See Also:
CleanSlate(long dim, Vector &startpoint)

void InitializeDesign(const Matrix<double> *designPtr)
Deletes any existing pattern and replaces it with the one pointed to by designPtr
Returns:
void
Parameters:
patternSize - the number of "columns", i.e. trial points, in design matrix
pat - a pointer to a design matrix

virtual void PrintDesign() const
Prints out search information
Returns:
void

Search method

virtual void BeginSearch()
BeginSearch() is an unimplemented virtual void method in the abstract base classes. It is to be implemented in the concrete classes. There, BeginSearch() will call the methods that implement the actual search algorithms.

Accessors and Mutators

long GetFunctionCalls() const
Returns number of objective function evaluations so far
Returns:
long

void SetFunctionCalls(long newCalls)
Sets number of function calls already used--useful for times when you are using multiple searches for the same optimization; for example, if you wanted to do 100 function calls worth of SMDSearch followed by 100 calls (max) of HJSearch
Returns:
void
Parameters:
newCalls - the new value to which you wish to set functioCalls.

int GetID() const
Returns the ID Number of the search
Returns:
int

void GetMinPoint(Vector<double> & minimum) const
Retrieves the minimum point and assigns it to minimum The vector minimum should be of the correct dimension
Returns:
void
Parameters:
minimum - a reference to a vector of the correct dimension, which will be assigned the value of minPoint.

void SetMinPoint(Vector<double> & minimum) const
Resets minPoint to the point represented by the input parameter minimum
Returns:
void
Parameters:
minimum - the new minimum point, whose value will be assigned to minPoint

void GetMinVal(double & value) const
Retrieves the best objective function value found thus far. The input parameter will be set to the value of minValue.
Returns:
void
Parameters:
value - a reference to a double, which will be given the value of minValue

void SetMinVal(double & value)
Resets the minimum value to the value of the input parameter
Returns:
void
Parameters:
value - a reference to a double, to whose vale minValue will be set

long GetDimension() const
Returns the dimension of the problem
Returns:
long

long GetMaxCalls() const
Returns the number of function calls in the budget; if the value is equal to NO_MAX, will terminate based only on refinement of the design
Returns:
long

void SetMaxCalls(long calls)
Use to set a function call budget; by default set to the value of NO_MAX, which indicates no budget, in which case the search will terminate based only upon grid refinement
Returns:
void
Parameters:
calls - the number of function calls to which maxCalls will be set

void SetMaxCallsExact(long calls)
Sets maxCalls to the value of calls, and sets exact_count to true, so search will terminate precisely when the call budget runs out
Returns:
void
Parameters:
calls - the number of calls in the call budget

Matrix <double> * GetDesign()
Returns a pointer to a matrix initialized from the design matrix
Returns:
Matrix<double>*

void CopyDesign(Matrix<double>* &designPtr) const
Deep copy of the pattern to a Matrix pointer. Points to a newly allocated chunk of memory upon return. The user should pass just a pointer, without preallocated memory. The user has the responsibility of using delete to free the memory thus allocated when it is no longer needed.
Returns:
void
Parameters:
designPtr - a reference to a Matrix object. Should be void going in.

double GetStoppingStepLength() const
Returns stoppingStepLength, the smallest step length allowed in the search
Returns:
double

void SetStoppingStepLength(double len)
Sets stoppingStepLength, the smallest step length allowed in the search, to the value of the input parameter
Returns:
void
Parameters:
len - the new value for stoppingStepLength

virtual void SetExact()
Allows the user to specify that the search will terminate precicely upon completion of maxCalls number of function calls. NOTE: If you wish to set "exact", you MUST specify maxCalls; otherwise, if the default of -1 is set for maxCalls, the program will take you at your word and exit the search before any evaluations are made.
Returns:
bool

virtual void SetInexact()
Allows the user to specify that the search will terminate upon completion of roughly maxCalls number of function calls, but only after a pattern decrease or "shrink" step.

Returns:
bool

virtual bool IsExact()
Returns the value of exact_count(q.v.)
Returns:
bool

virtual void ExploratoryMoves()

Exploratory Moves is an unimplemented virtual void function in the abstract base classes. It will be implemented in the concrete classes as the workhorse for the algorithmic implementations

virtual bool Stop()

Gives default stopping criteria based on maxCalls and stoppingStepLength

Returns:: bool

void fcnCall(long n, Vector<double> &x, double & f, bool& flag, void * nothing)

Indirection of the call to the objective function for purposes of keeping an accurate tally of the number of function calls

Returns:: void
Parameters:: n - the dimension of the problem
x - the point at which to evaluate the function
f - upon return will hold the function value at the point x
flag - indicates whether the evaluation was possible
nothing - a pointer to be used in cases where extra information is needed. Will usually be set to NULL.

virtual void CopySearch(const DirectSearch & Original)

Used to implement the overloaded assignment operator

Returns:: void
Parameters:: Original - a reference to a DirectSearch object. Note that ordinarily this will actually be an object of a type of one of the concrete classes derived from DirectSearch.

bool BreakOnExact()