setup.html.svn-base

OPT++

      <li> void (*USERFCN2)(mode, ndim, x, fx, gx, Hx, result):  for NFL2
      <li> void (*USERFCNLSQ0)(ndim, x, lsfx, result):  for LSQNLF or
      <li> void (*USERFCNLSQ1)(mode, ndim, x, lsfx, lsgx, result):  for LSQNLF
    </ul>
</ul>

The arguments of these functions are fairly straightforward.
<em>ndim</em> is an integer that specifies the dimension of the
problem, <em>x</em> is a ColumnVector that contains the values of the
optimization variables, <em>fx</em> is the value of the objective
function at <em>x</em>, <em>gx</em> is a ColumnVector containing the
gradient of the objective function at <em>x</em>, <em>Hx</em> is a
SymmetricMatrix containing the Hessian of the objective function at
<em>x</em>, <em>mode</em> is an integer encoding of the type of
evaluation requested (i.e., function, gradient, Hessian), and
<em>result</em> is an integer encoding of the type of evaluations
available.  For the least squares operator, <em>lsfx</em> is a ColumnVector
with each entry containing the value of one of the least squares terms and 
<em>lsgx</em> is a Matrix containing the Jacobian of the least squares 
operator at <em>x</em>.
The ColumnVector, Matrix, and SymmetricMatrix objects are described
in the <a href="http://robertnz.net/nm11.htm"> NEWMAT
documentation</a>.  The <a href="#example"> Example Problems</a>
demonstrate how to implement the user-defined functions.

Nonlinear constraints are quite similar in nature to the objective
function.  In fact, they are constructed using the function objects in
the <a href="#problem"> Problem Setup</a> section.  The interfaces for
the subroutines that evaluate the nonlinear constraints, however, are
slightly different from those for evaluating the objective function.
The interfaces are as follows:

<ul>
  <li> void (*USERNLNCON0)(ndim, x, cx, result): for nonlinear
  constraints with no analytic first or second derivatives
  <li> void (*USERNLNCON1)(mode, ndim, x, cx, cgx, result): for
  nonlinear constraints with analytic or finite-difference first
  derivative, but no analyatice second derivative
  <li> void (*USERNLNCON2)(mode, ndim, x, cx, cgx, cHx, result): for
  nonlinear constraints with analytic first and second derivatives
</ul>

The arguments of these functions are fairly straightforward.
<em>ndim</em> is an integer that specifies the dimension of the
problem, <em>x</em> is a ColumnVector that contains the values of the
optimization variables, <em>cx</em> is a ColumnVector with each entry
containing the value of one of the nonlinear constraints at
<em>x</em>, <em>cgx</em> is a Matrix with each column containing the
gradient of one of the nonlinear constraints at <em>x</em>,
<em>cHx</em> is an OptppArray of SymmetricMatrix with each matrix
containing the Hessian of one of the nonlinear constraints at
<em>x</em>, <em>mode</em> is an integer encoding of the type of
evaluation requested (i.e., function, gradient, Hessian), and
<em>result</em> is an integer encoding of the type of evaluations
available.  A description of OptppArray can be found in the <a
href="annotated.html"> detailed documentation</a>.  The ColumnVector
and SymmetricMatrix objects are described in the <a
href="http://robertnz.net/nm11.htm"> NEWMAT documentation</a>.  The
<a href="#example"> Example Problems</a> demonstrate how to implement
the user-defined functions.  In particular, <a href="example2.html">
Example 2</a> demonstrates the use of constraints.

\section algorithm Algorithm Setup

Once the nonlinear function (see <a href="#problem"> Problem
Setup</a>) has been set up, it is time to construct the algorithm
object.  This defines the optimization algorithm to be used and
provides it with a pointer to the problem to be solved.  Once this is
done, any algorithmic parameters can be set, and the problem can be
solved.  The full set of algorithms provided and their constructors
can be found throughout the documentation.  We list the most common
ones here, grouped according to the type of problem expected.

<ul>
  <li> problem has no analytic derivatives (NLF0)
    <ul>
      <li>OptPDS(&nlp):  parallel direct search method; handles general
          constraints, but only bounds robustly
      <li>OptGSS(&nlp, &gsb):  generating set search method; handles 
          unconstrained problems only
    </ul>
  <li> problem has analytic or finite-difference first derivative
       (NLF1 or FDNLF1)
    <ul>
      <li> OptCG(&nlp):  conjugate gradient method; handles
           unconstrained problems only
      <li> OptLBFGS(&nlp):  limited-memory quasi-Newton method for unconstrained
           problems; uses L-BFGS for Hessian approximation
      <li> OptQNewton(&nlp):  quasi-Newton method for unconstrained
           problems; uses BFGS for Hessian approximation
      <li> OptFDNewton(&nlp):  Newton method for unconstrained
           problems; uses second-order finite differences for Hessian
           approximation
      <li> OptBCQNewton(&nlp):  quasi-Newton method for
	   bound-constrained problems; uses BFGS for Hessian
	   approximation
      <li> OptBaQNewton(&nlp):  quasi-Newton method for
           bound-constrained problems; uses BFGS for Hessian
	   approximation
      <li> OptBCEllipsoid(&nlp):  ellipsoid method for
           bound-constrained problems
      <li> OptFDNIPS(&nlp):  Newton nonlinear interior-point
           method for generally constrained problems; uses
	   second-order finite differences for Hessian
	   approximation
      <li> OptQNIPS(&nlp):  quasi-Newton nonlinear interior-point
           method for generally constrained problems; uses BFGS for
	   Hessian approximation
    </ul>
  <li> problem has analytic first and second derivatives (NLF2)
    <ul>
      <li> OptNewton(&nlp):  Newton method for unconstrained
           problems
      <li> OptBCNewton(&nlp):  Newton method for bound-constrained
	   problems
      <li> OptBaNewton(&nlp):  Newton method for bound-constrained
           problems
      <li> OptNIPS(&nlp):  nonlinear interior-point method for
	   generally constrained problems
    </ul>
  <li> problem has least squares function operator (LSQNLF)
    <ul>
      <li> OptDHNIPS(&nlp):  Disaggregated Hessian Newton nonlinear 
           interior-point method for generally constrained problems; 
           uses Gauss-Newton approximations to compute objective function
           gradient and Hessian;
           uses quasi-Newton approximations for constraint Hessians;
    </ul>
</ul>

In these constructors, <em>nlp</em> is the nonlinear function/problem
object created as described in the <a href="#problem"> Problem
Setup</a> section and <em>gsb</em> is the generating set method described in
the <a href="gensetGuide-format.html"> Generating Set Search </a> section.  
All of the Newton methods have a choice of
globalization strategy: line search, trust region, or trust
region-PDS.  Furthermore, there are numerous algorithmic parameters
that can be set.  These can be found in the <a href="annotated.html">
detailed documentation</a> for each particular method.

Once the algorithm object has been instantiated and the desired
algorithmic parameters set, the problem can then be solved by calling
that algorithm's optimize method.  Tutorial examples of how to do set
up and use the optimization algorithms can be found in the <a
href="#example"> Example Problems</a>.

\section example Example Problems

In order to clarify the explanations given above, we now step through
a couple of example problems.  These examples are intended to serve as
a very basic tutorial.  We recommend looking at the <a
href="examples.html"> additional examples</a> provided in the
documentation in order to obtain a broader view of the capabilities of
OPT++.  In addition, the <a href="annotated.html"> detailed
documentation</a> contains a complete list of the capabilities
available.

<ul>
  <li> \ref example1
  <li> \ref example2
</ul>

<p> Previous Section:  \ref InstallDoc | Next Section:  \ref AlternativeFunctions
| Back to the <a href="index.html"> Main Page</a> </p>

Last revised <em> July 25, 2006</em>

*/