-------------------------------------------------- lines 8-391 of file: include/cppad/ipopt/solve.hpp -------------------------------------------------- {xrst_begin ipopt_solve} {xrst_spell bvector doesn fg gl gu maxiter naninf ng nx rll xl zl zu } Use Ipopt to Solve a Nonlinear Programming Problem ################################################## Syntax ****** | # ``include `` | ``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 `_ 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` ``bool`` . Dvector ******* The type *DVector* must be a :ref:`SimpleVector-name` class with :ref:`elements of 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` 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` ``AD`` . 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` is an example and test of ``ipopt::solve`` taken from the Ipopt manual. retape ====== The file :ref:`example/ipopt_solve/retape.cpp` 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` demonstrates using Ipopt to solve for parameters in an ODE model. {xrst_end ipopt_solve}