/** \page AlternativeFunctions Alternate Forms of Nonlinear Objects \section problem Problem Setup There are alternate forms of the function that accept a vptr as the final argument. A vptr is a void pointer that the user can use for any desired purpose, such as application reentry. The most common constructors are shown below.

- NLF0(ndim, fcn, init_fcn, constraint, vptr): problem has no analytic derivative information available
- NLF1(ndim, fcn, init_fcn, constraint, vptr): problem has analytic first derivatives available, but no analytic second derivatives
- NLF2(ndim, fcn, init_fcn, constraint,vptr): problem has analytic first and second derivatives available
- FDNLF1(ndim, fcn, init_fcn, constraint, vptr): problem has no analytic derivative information available, but finite differences are used to approximate first derivatives
- LSQNLF(ndim, lsqterms, lsqfcn, init_fcn, constraint,vptr): problem has a least squares operator, Gauss-Newton is used to approximate Jacobian and Hessian

For completeness, we describe the other arguments to the constructor. The arguments to the constructors must be defined before instantiating the function object. The following description holds for the first four nonlinear function objects, which have identical argument lists. We will define the argument list for the LSQNLF later. The first argument, ndim, is an integer specifying the dimension of the problem. The second argument, fcn, is a pointer to the subroutine that evaluates the function. The form of this pointer/subroutine is described in more detail in the User-Defined Functions subsection. The third argument, init_fcn, is a pointer to the subroutine that initializes the function. Again, the form of this pointer/subroutine is described in the User-Defined Functions subsection. The fourth argument, constraint, is a pointer to a constraint object. If the optimization problem of interest has no constraints, this argument can be excluded. Otherwise, it can be constructed as described in the %Constraint Setup subsection. For the LSQNLF object, the first argument, ndim, is an integer specifying the dimension of the problem. The second argument, lsqterms, is an integer specifying the number of least square terms in the function. The third argument, lsqfcn, is a pointer to the subroutine that evaluates the least squares operator. The form of this pointer/subroutine is described in more detail in the User-Defined Functions subsection. The remaining arguments have the same meaning as previously defined. User-Defined Functions In addition to the main routine, the user must provide additional C++ code that performs the initialization of the problem, the evaluation of the objective function, and the evaluation of any nonlinear constraints. This code must also include the computation of any analytic derivative information that is to be provided. These subroutines may appear in the same file as the main routine or in a separate file, and they must satisfy the interfaces listed below. The function interfaces are the following:

- void (*USERFCN0V)(ndim, x, fx, result, vptr): for NLF0 and FDNLF1
- void (*USERFCN1V)(mode, ndim, x, fx, gx, result, vptr): for NLF1
- void (*USERFCN2V)(mode, ndim, x, fx, gx, Hx, result, vptr): for NFL2
- void (*USERFCNLSQ0V)(ndim, x, lsfx, result, vptr): for LSQNLF or
- void (*USERFCNLSQ1V)(mode, ndim, x, lsfx, lsgx, result, vptr): for LSQNLF

The arguments of these functions are fairly straightforward. ndim is an integer that specifies the dimension of the problem, x is a ColumnVector that contains the values of the optimization variables, fx is the value of the objective function at x, gx is a ColumnVector containing the gradient of the objective function at x, Hx is a SymmetricMatrix containing the Hessian of the objective function at x, mode is an integer encoding of the type of evaluation requested (i.e., function, gradient, Hessian), result is an integer encoding of the type of evaluations available and vptr is a void pointer which contains user-specified information. For the least squares operator, lsfx is a ColumnVector with each entry containing the value of one of the least squares terms and lsgx is a Matrix containing the Jacobian of the least squares operator at x. The ColumnVector, Matrix, and SymmetricMatrix objects are described in the NEWMAT documentation.

Previous Section: \ref SetUp | Next Section: \ref GUI_XMLDoc | Back to the Main Page

Last revised April 18, 2007 */