/** \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
*/