lines 8-393 of file: include/cppad/ipopt/solve.hpp

{xrst_begin ipopt_solve}
{xrst_spell
   bvector
   fg
   gl
   infeasibility
   iterates
   lagrange
   maxiter
   naninf
   ng
   nx
   rll
   unrecoverable
   xl
   zl
}

Use Ipopt to Solve a Nonlinear Programming Problem
##################################################

Syntax
******

| # ``include <cppad/ipopt/solve.hpp>``
| ``ipopt::solve`` (
| |tab| *options* , *xi* , *xl* , *xu* , *gl* , *gu* , *fg_eval* , *solution*
| )

Purpose
*******
The function ``ipopt::solve`` solves nonlinear programming
problems of the form

.. math::

   \begin{array}{rll}
   {\rm minimize}      & f (x)
   \\
   {\rm subject \; to} & gl \leq g(x) \leq gu
   \\
                  & xl  \leq x   \leq xu
   \end{array}

This is done using
`Ipopt <http://www.coin-or.org/projects/Ipopt.xml>`_
optimizer and CppAD for the derivative and sparsity calculations.

Include File
************
If :ref:`cmake@include_ipopt` is on the cmake command line,
the file ``cppad/ipopt/solve.hpp`` is included by ``cppad/cppad.hpp`` .
Otherwise,
``cppad/ipopt/solve.hpp`` can be included directly
(If ``cppad/cppad.hpp`` has not yet been included,
``cppad/ipopt/solve.hpp`` will automatically include it.)

Bvector
*******
The type *Bvector* must be a :ref:`SimpleVector-name` class with
:ref:`elements of type<SimpleVector@Elements of Specified Type>`
``bool`` .

Dvector
*******
The type *DVector* must be a :ref:`SimpleVector-name` class with
:ref:`elements of type<SimpleVector@Elements of Specified Type>`
``double`` .

options
*******
The argument *options* has prototype

   ``const std::string`` *options*

It contains a list of options.
Each option, including the last option,
is terminated by the ``'\n'`` character.
Each line consists of two or three tokens separated by one or more spaces.

Retape
======
You can set the retape flag with the following syntax:

   ``Retape`` *value*

If the value is ``true`` , ``ipopt::solve`` with retape the
:ref:`operation sequence<glossary@Operation@Sequence>` for each
new value of *x* .
If the value is ``false`` , ``ipopt::solve``
will tape the operation sequence at the value
of *xi* and use that sequence for the entire optimization process.
The default value is ``false`` .

Sparse
======
You can set the sparse Jacobian and Hessian flag with the following syntax:

   ``Sparse`` *value* *direction*

If the value is ``true`` , ``ipopt::solve`` will use a sparse
matrix representation for the computation of Jacobians and Hessians.
Otherwise, it will use a full matrix representation for
these calculations.
The default for *value* is ``false`` .
If sparse is true, retape must be false.

It is unclear if :ref:`sparse_jacobian-name` would be faster user
forward or reverse mode so you are able to choose the direction.
If

   *value* == ``true &&`` *direction* == ``forward``

the Jacobians will be calculated using ``SparseJacobianForward`` .
If

   *value* == ``true &&`` *direction* == ``reverse``

the Jacobians will be calculated using ``SparseJacobianReverse`` .

String
======
You can set any Ipopt string option using a line with the following syntax:

   ``String`` *name* *value*

Here *name* is any valid Ipopt string option
and *value* is its setting.

Numeric
=======
You can set any Ipopt numeric option using a line with the following syntax:

   ``Numeric`` *name* *value*

Here *name* is any valid Ipopt numeric option
and *value* is its setting.

Integer
=======
You can set any Ipopt integer option using a line with the following syntax:

   ``Integer`` *name* *value*

Here *name* is any valid Ipopt integer option
and *value* is its setting.

xi
**
The argument *xi* has prototype

   ``const`` *Vector* & *xi*

and its size is equal to *nx* .
It specifies the initial point where Ipopt starts the optimization process.

xl
**
The argument *xl* has prototype

   ``const`` *Vector* & *xl*

and its size is equal to *nx* .
It specifies the lower limits for the argument in the optimization problem.

xu
**
The argument *xu* has prototype

   ``const`` *Vector* & *xu*

and its size is equal to *nx* .
It specifies the upper limits for the argument in the optimization problem.

gl
**
The argument *gl* has prototype

   ``const`` *Vector* & *gl*

and its size is equal to *ng* .
It specifies the lower limits for the constraints in the optimization problem.

gu
**
The argument *gu* has prototype

   ``const`` *Vector* & *gu*

and its size is equal to *ng* .
It specifies the upper limits for the constraints in the optimization problem.

fg_eval
*******
The argument *fg_eval* has prototype

   *FG_eval* *fg_eval*

where the class *FG_eval* is unspecified except for the fact that
it supports the syntax

| |tab| *FG_eval* :: ``ADvector``
| |tab| *fg_eval* ( *fg* , *x* )

The type *ADvector*
and the arguments to *fg* , *x* have the following meaning:

ADvector
========
The type *FG_eval* :: ``ADvector`` must be a :ref:`SimpleVector-name` class with
:ref:`elements of type<SimpleVector@Elements of Specified Type>`
``AD<double>`` .

x
=
The *fg_eval* argument *x* has prototype

   ``const`` *ADvector* & *x*

where *nx* = *x* . ``size`` () .

fg
==
The *fg_eval* argument *fg* has prototype

   *ADvector* & *fg*

where 1 + *ng* = *fg* . ``size`` () .
The input value of the elements of *fg* does not matter.
Upon return from *fg_eval* ,

   ``fg`` [0] =

:math:`f (x)`

and   for :math:`i = 0, \ldots , ng-1`,

   ``fg`` [1 + ``i`` ] =

:math:`g_i (x)`

solution
********
The argument *solution* has prototype

   ``ipopt::solve_result<`` *Dvector* >& *solution*

After the optimization process is completed, *solution* contains
the following information:

status
======
The *status* field of *solution* has prototype

   ``ipopt::solve_result<`` *Dvector* >:: ``status_type`` *solution* . ``status``

It is the final Ipopt status for the optimizer.
Here is a list of the possible values for the status:

.. list-table::
   :widths: auto

   * - *status*
     - Meaning
   * - not_defined
     - The optimizer did not return a final status for this problem.
   * - unknown
     - The status returned by the optimizer is not defined in the Ipopt
       documentation for ``finalize_solution`` .
   * - success
     - Algorithm terminated successfully at a point satisfying the convergence
       tolerances (see Ipopt options).
   * - maxiter_exceeded
     - The maximum number of iterations was exceeded (see Ipopt options).
   * - stop_at_tiny_step
     - Algorithm terminated because progress was very slow.
   * - stop_at_acceptable_point
     - Algorithm stopped at a point that was converged,
       not to the 'desired' tolerances, but to 'acceptable' tolerances
       (see Ipopt options).
   * - local_infeasibility
     - Algorithm converged to a non-feasible point
       (problem may have no solution).
   * - user_requested_stop
     - This return value should not happen.
   * - diverging_iterates
     - It the iterates are diverging.
   * - restoration_failure
     - Restoration phase failed, algorithm doesn't know how to proceed.
   * - error_in_step_computation
     - An unrecoverable error occurred while Ipopt tried to
       compute the search direction.
   * - invalid_number_detected
     - Algorithm received an invalid number (such as ``nan`` or ``inf`` )
       from the users function *fg_info* . ``eval`` or from the CppAD evaluations
       of its derivatives
       (see the Ipopt option ``check_derivatives_for_naninf`` ).
   * - internal_error
     - An unknown Ipopt internal error occurred.
       Contact the Ipopt authors through the mailing list.

x
=
The ``x`` field of *solution* has prototype

   *Vector* *solution* . ``x``

and its size is equal to *nx* .
It is the final :math:`x` value for the optimizer.

zl
==
The ``zl`` field of *solution* has prototype

   *Vector* *solution* . ``zl``

and its size is equal to *nx* .
It is the final Lagrange multipliers for the
lower bounds on :math:`x`.

zu
==
The ``zu`` field of *solution* has prototype

   *Vector* *solution* . ``zu``

and its size is equal to *nx* .
It is the final Lagrange multipliers for the
upper bounds on :math:`x`.

g
=
The ``g`` field of *solution* has prototype

   *Vector* *solution* . ``g``

and its size is equal to *ng* .
It is the final value for the constraint function :math:`g(x)`.

lambda
======
The ``lambda`` field of *solution* has prototype

   *Vector* > *solution* . ``lambda``

and its size is equal to *ng* .
It is the final value for the
Lagrange multipliers corresponding to the constraint function.

obj_value
=========
The ``obj_value`` field of *solution* has prototype

   ``double`` *solution* . ``obj_value``

It is the final value of the objective function :math:`f(x)`.
{xrst_toc_hidden
   example/ipopt_solve/get_started.cpp
   example/ipopt_solve/retape.cpp
   example/ipopt_solve/ode_inverse.cpp
}
Example
*******
All the examples return true if it succeeds and false otherwise.

get_started
===========
The file
:ref:`example/ipopt_solve/get_started.cpp<ipopt_solve_get_started.cpp-name>`
is an example and test of ``ipopt::solve``
taken from the Ipopt manual.

retape
======
The file
:ref:`example/ipopt_solve/retape.cpp<ipopt_solve_retape.cpp-name>`
demonstrates when it is necessary to specify
:ref:`ipopt_solve@options@Retape` as true.

ode_inverse
===========
The file
:ref:`example/ipopt_solve/ode_inverse.cpp<ipopt_solve_ode_inverse.cpp-name>`
demonstrates using Ipopt to solve for parameters in an ODE model.

{xrst_end ipopt_solve}
