TAO solvers that minimize an objective function require the application to evaluate the objective function. Some solvers may also require the application to evaluate derivatives of the objective function. Routines that perform these computations must be identified to the application object and must follow a strict calling sequence.
Routines that evaluate an objective function
,
should follow the form:
EvaluateObjective(TAO_APPLICATION,Vec,double*,void*);The first argument is the application object, the second argument is the n-dimensional vector that identifies where the objective should be evaluated, and the fourth argument is an application context. This routine should use the third argument to return objective value, evaluated at the given point specified the by the vector in the second argument.
This routine, and the application context, should be passed to the
application object using
the routine
TaoAppSetObjectiveRoutine(TAO_APPLICATION, int(*)(TAO_APPLICATION,Vec,double*,void*), void*);The first argument in this routine is the application object, the second argument is a function pointer to the routine that evaluates the objective, and the third argument is the pointer an appropriate application context.
Although final argument may point to anything, it must be cast as a (void*) type. This pointer will be passed back to the developer in the fourth argument of the routine that evaluates the objective. In this routine, the pointer can be cast back to the appropriate type. Examples of these structures and there usage are provides in the distribution.
Most TAO solvers also require gradient information from the
application .
The gradient of the objective function can be specified in a similar manner.
Routines that evaluate the gradient should have the calling sequence
EvaluateTheGradient(TAO_APPLICATION,Vec,Vec,void*);In this routine, the first argument is the application object, the second argument is the variable vector, the third argument is the gradient, and the fourth argument is the user-defined application context. Only the third argument in this routine is different from the arguments in the routine that evaluates the objective function. The numbers in the gradient vector have no meaning when passed into this routine, but should represent the gradient of the objective at the specified point at the end of the routine. This routine, and the user-defined pointer, can be passed to the application object using the routine:
TaoAppSetGradientRoutine(TAO_APPLICATION, int (*)(TAO_APPLICATION,Vec,Vec,void*), void *);In this routine, the first argument is the application object, the second argument is the function pointer, and the third object is the application context, cast to (void*).
Instead of evaluating the objective and its gradient in separate
routines, TAO also allows the user to evaluate the function and the gradient
at the same routine. In fact, some solvers are more efficient when
both function and gradient information can be computed in the same routine.
These routines should follow the form
EvaluateFunctionGradient(TAO_APPLICATION,Vec,double*,Vec,void*);where the first argument is the TAO solver, and the second argument points to the input vector for use in evaluating the function and gradient. The third argument should return the function value, while the fourth argument should return the gradient vector, and the fifth argument is a pointer to a user-defined context. This context and the name of the routine should be set with the call:
TaoAppSetObjectiveAndGradientRoutine(TAO_APPLICATION, int (*)(TAO_APPLICATION,Vec,double*,Vec,void*), void *);The arguments of this routine are the TAO application, a function name, and a pointer to a user-defined context.
The TAO example problems demonstrate the use of these application contexts as well as specific instances of function, gradient, and Hessian evaluation routines. All of these routines should return the integer 0 after successful completion and a nonzero integer if the function is undefined at that point or an error occurred.