Prev

Next

Index-> contents reference index search external

Up-> CppAD cppad_ipopt_nlp

CppAD-> Install Introduction AD ADFun multi_thread library cppad_ipopt_nlp Example preprocessor Appendix

cppad_ipopt_nlp-> cppad_ipopt_windows ipopt_get_started.cpp cppad_ipopt_ode ipopt_ode_speed.cpp

Headings-> Syntax Purpose cppad_ipopt namespace ipopt_library_paths fg(x) ---..Index Vector ---..Projection ---..Injection ---..Representation Simple Representation SizeVector NumberVector ADNumber ADVector n m x_i x_l x_u g_l g_u fg_info ---..fg_info.number_functions ---..fg_info.eval_r ---..fg_info.retape ---..fg_info.domain_size ---..fg_info.range_size ---..fg_info.number_terms ---..fg_info.index solution ---..status ---..x ---..z_l ---..z_u ---..g ---..lambda ---..obj_value Visual Studio Example Wish List

Nonlinear Programming Using the CppAD Interface to Ipopt
Syntax
# include "cppad_ipopt_nlp.hpp"
cppad_ipopt_solution solution;
cppad_ipopt_nlp cppad_nlp(
     n, m, x_i, x_l, x_u, g_l, g_u, &fg_info, &solution
)
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:ipopt_library_paths

Purpose
The class cppad_ipopt_nlp is used to solve nonlinear programming problems of the form $$\begin{array}{cc}\hfill \mathrm{minimize}& \mathit{f}(\mathit{x})\hfill \\ \hfill \mathrm{subject}\mathrm{to}& {\mathit{g}}^{\mathit{l}}\le \mathit{g}(\mathit{x})\le {\mathit{g}}^{\mathit{u}}\hfill \\ \hfill & {\mathit{x}}^{\mathit{l}}\le \mathit{x}\le {\mathit{x}}^{\mathit{u}}\hfill \end{array}$$ This is done using Ipopt optimizer and CppAD Algorithmic Differentiation package.

cppad_ipopt namespace
All of the declarations for these routines are in the cppad_ipopt namespace (not the CppAD namespace). For example; SizeVector below actually denotes the type cppad_ipopt::SizeVector.

ipopt_library_paths
If you are linking to a shared version of the Ipopt library, you may have to add some paths the LD_LIBRARY_PATH shell variable using the export command in the syntax above. For example, perhaps
     ipopt_library_paths=IpoptDir/lib/coin:IpoptDir/lib/coin/ThirdParty
see IpoptDir .

fg(x)
The function $\mathit{fg}:{\mathbf{R}}^{\mathit{n}}\to {\mathbf{R}}^{\mathit{m}+1}$ is defined by $$\begin{array}{ccc}\hfill {\mathit{fg}}_0(\mathit{x})& \hfill =\hfill & \mathit{f}(\mathit{x})\hfill \\ \hfill {\mathit{fg}}_1(\mathit{x})& \hfill =\hfill & {\mathit{g}}_0(\mathit{x})\hfill \\ \hfill & \hfill ⋮\hfill & \hfill \\ \hfill {\mathit{fg}}_{\mathit{m}}(\mathit{x})& \hfill =\hfill & {\mathit{g}}_{\mathit{m}-1}(\mathit{x})\hfill \end{array}$$
Index Vector
We define an index vector as a vector of non-negative integers for which none of the values are equal; i.e., it is both a vector and a set. If $\mathit{I}$ is an index vector $|\mathit{I}|$ is used to denote the number of elements in $\mathit{I}$ and $\Vert \mathit{I}\Vert$ is used to denote the value of the maximum element in $\mathit{I}$ .

Projection
Given an index vector $\mathit{J}$ and a positive integer $\mathit{n}$ where $\mathit{n}>\Vert \mathit{J}\Vert$ , we use $\mathit{J}\otimes \mathit{n}$ for the mapping $(\mathit{J}\otimes \mathit{n}):{\mathbf{R}}^{\mathit{n}}\to {\mathbf{R}}^{|\mathit{J}|}$ defined by $$[\mathit{J}\otimes \mathit{n}](\mathit{x}{)}_{\mathit{j}}={\mathit{x}}_{\mathit{J}(\mathit{j})}$$ for $\mathit{j}=0,\dots |\mathit{J}|-1$ .

Injection
Given an index vector $\mathit{I}$ and a positive integer $\mathit{m}$ where $\mathit{m}>\Vert \mathit{I}\Vert$ , we use $\mathit{m}\otimes \mathit{I}$ for the mapping $(\mathit{m}\otimes \mathit{I}):{\mathbf{R}}^{|\mathit{I}|}\to {\mathbf{R}}^{\mathit{m}}$ defined by $$[\mathit{m}\otimes \mathit{I}](\mathit{y}{)}_{\mathit{i}}=\{\begin{array}{cc}{\mathit{y}}_{\mathit{k}}\hfill & \mathrm{if}\mathit{i}=\mathit{I}(\mathit{k})\mathrm{for}\mathrm{some}\mathit{k}\in \{0,\cdots ,|\mathit{I}|-1\}\hfill \\ 0\hfill & \mathrm{otherwise}\hfill \end{array}$$
Representation
In many applications, each of the component functions of $\mathit{fg}(\mathit{x})$ only depend on a few of the components of $\mathit{x}$ . In this case, expressing $\mathit{fg}(\mathit{x})$ in terms of simpler functions with fewer arguments can greatly reduce the amount of work required to compute its derivatives.

We use the functions ${\mathit{r}}_{\mathit{k}}:{\mathbf{R}}^{\mathit{q}(\mathit{k})}\to {\mathbf{R}}^{\mathit{p}(\mathit{k})}$ for $\mathit{k}=0,\dots ,\mathit{K}$ to express our representation of $\mathit{fg}(\mathit{x})$ in terms of simpler functions as follows $$\mathit{fg}(\mathit{x})=\sum _{\mathit{k}=0}^{\mathit{K}-1}\sum _{\ell =0}^{\mathit{L}(\mathit{k})-1}[(\mathit{m}+1)\otimes {\mathit{I}}_{\mathit{k},\ell }]\circ {\mathit{r}}_{\mathit{k}}\circ [{\mathit{J}}_{\mathit{k},\ell }\otimes \mathit{n}](\mathit{x})$$ where $\circ$ represents function composition, for $\mathit{k}=0,\dots ,\mathit{K}-1$ , and $\ell =0,\dots ,\mathit{L}(\mathit{k})$ , ${\mathit{I}}_{\mathit{k},\ell }$ and ${\mathit{J}}_{\mathit{k},\ell }$ are index vectors with $|{\mathit{J}}_{\mathit{k},\ell }|=\mathit{q}(\mathit{k})$ , $\Vert {\mathit{J}}_{\mathit{k},\ell }\Vert <\mathit{n}$ , $|{\mathit{I}}_{\mathit{k},\ell }|=\mathit{p}(\mathit{k})$ , and $\Vert {\mathit{I}}_{\mathit{k},\ell }\Vert \le \mathit{m}$ .

Simple Representation
In the simple representation, ${\mathit{r}}_0(\mathit{x})=\mathit{fg}(\mathit{x})$ , $\mathit{K}=1$ , $\mathit{q}(0)=\mathit{n}$ , $\mathit{p}(0)=\mathit{m}+1$ , $\mathit{L}(0)=1$ , ${\mathit{I}}_{0,0}=(0,\dots ,\mathit{m})$ , and ${\mathit{J}}_{0,0}=(0,\dots ,\mathit{n}-1)$ .

SizeVector
The type SizeVector is defined by the cppad_ipopt_nlp.hpp include file to be a SimpleVector class with elements of type size_t.

NumberVector
The type NumberVector is defined by the cppad_ipopt_nlp.hpp include file to be a SimpleVector class with elements of type Ipopt::Number.

ADNumber
The type ADNumber is defined by the cppad_ipopt_nlp.hpp include file to be a an AD type that can be used to compute derivatives.

ADVector
The type ADVector is defined by the cppad_ipopt_nlp.hpp include file to be a SimpleVector class with elements of type ADNumber.

n
The argument n has prototype
     size_t n
It specifies the dimension of the argument space; i.e., $\mathit{x}\in {\mathbf{R}}^{\mathit{n}}$ .

m
The argument m has prototype
     size_t m
It specifies the dimension of the range space for $\mathit{g}$ ; i.e., $\mathit{g}:{\mathbf{R}}^{\mathit{n}}\to {\mathbf{R}}^{\mathit{m}}$ .

x_i
The argument x_i has prototype
     const NumberVector& x_i
and its size is equal to $\mathit{n}$ . It specifies the initial point where Ipopt starts the optimization process.

x_l
The argument x_l has prototype
     const NumberVector& x_l
and its size is equal to $\mathit{n}$ . It specifies the lower limits for the argument in the optimization problem; i.e., ${\mathit{x}}^{\mathit{l}}$ .

x_u
The argument x_u has prototype
     const NumberVector& x_u
and its size is equal to $\mathit{n}$ . It specifies the upper limits for the argument in the optimization problem; i.e., ${\mathit{x}}^{\mathit{u}}$ .

g_l
The argument g_l has prototype
     const NumberVector& g_l
and its size is equal to $\mathit{m}$ . It specifies the lower limits for the constraints in the optimization problem; i.e., ${\mathit{g}}^{\mathit{l}}$ .

g_u
The argument g_u has prototype
     const NumberVector& g_u
and its size is equal to $\mathit{n}$ . It specifies the upper limits for the constraints in the optimization problem; i.e., ${\mathit{g}}^{\mathit{u}}$ .

fg_info
The argument fg_info has prototype
     FG_info fg_info
where the class FG_info is derived from the base class cppad_ipopt_fg_info. Certain virtual member functions of fg_info are used to compute the value of $\mathit{fg}(\mathit{x})$ . The specifications for these member functions are given below:

fg_info.number_functions
This member function has prototype
     virtual size_t cppad_ipopt_fg_info::number_functions(void)
If K has type size_t, the syntax
     K = fg_info.number_functions()
sets K to the number of functions used in the representation of $\mathit{fg}(\mathit{x})$ ; i.e., $\mathit{K}$ in the representation above.

The cppad_ipopt_fg_info implementation of this function corresponds to the simple representation mentioned above; i.e. K = 1 .

fg_info.eval_r
This member function has the prototype
virtual ADVector cppad_ipopt_fg_info::eval_r(size_t k, const ADVector& u) = 0;
Thus it is a pure virtual function and must be defined in the derived class FG_info .

This function computes the value of ${\mathit{r}}_{\mathit{k}}(\mathit{u})$ used in the representation for $\mathit{fg}(\mathit{x})$ . If k in $\{0,\dots ,\mathit{K}-1\}$ has type size_t, u is an ADVector of size q(k) and r is an ADVector of size p(k) the syntax
     r = fg_info.eval_r(k, u)
set r to the vector ${\mathit{r}}_{\mathit{k}}(\mathit{u})$ .

fg_info.retape
This member function has the prototype
     virtual bool cppad_ipopt_fg_info::retape(size_t k)
If k in $\{0,\dots ,\mathit{K}-1\}$ has type size_t, and retape has type bool, the syntax
        retape = fg_info.retape(k)
sets retape to true or false. If retape is true, cppad_ipopt_nlp will retape the operation sequence corresponding to ${\mathit{r}}_{\mathit{k}}(\mathit{u})$ for every value of u . An cppad_ipopt_nlp object should use much less memory and run faster if retape is false. You can test both the true and false cases to make sure the operation sequence does not depend on u .

The cppad_ipopt_fg_info implementation of this function sets retape to true (while slower it is also safer to always retape).

fg_info.domain_size
This member function has prototype
     virtual size_t cppad_ipopt_fg_info::domain_size(size_t k)
If k in $\{0,\dots ,\mathit{K}-1\}$ has type size_t, and q has type size_t, the syntax
     q = fg_info.domain_size(k)
sets q to the dimension of the domain space for ${\mathit{r}}_{\mathit{k}}(\mathit{u})$ ; i.e., $\mathit{q}(\mathit{k})$ in the representation above.

The cppad_ipopt_h_base implementation of this function corresponds to the simple representation mentioned above; i.e., $\mathit{q}=\mathit{n}$ .

fg_info.range_size
This member function has prototype
     virtual size_t cppad_ipopt_fg_info::range_size(size_t k)
If k in $\{0,\dots ,\mathit{K}-1\}$ has type size_t, and p has type size_t, the syntax
     p = fg_info.range_size(k)
sets p to the dimension of the range space for ${\mathit{r}}_{\mathit{k}}(\mathit{u})$ ; i.e., $\mathit{p}(\mathit{k})$ in the representation above.

The cppad_ipopt_h_base implementation of this function corresponds to the simple representation mentioned above; i.e., $\mathit{p}=\mathit{m}+1$ .

fg_info.number_terms
This member function has prototype
     virtual size_t cppad_ipopt_fg_info::number_terms(size_t k)
If k in $\{0,\dots ,\mathit{K}-1\}$ has type size_t, and L has type size_t, the syntax
     L = fg_info.number_terms(k)
sets L to the number of terms in representation for this value of k ; i.e., $\mathit{L}(\mathit{k})$ in the representation above.

The cppad_ipopt_h_base implementation of this function corresponds to the simple representation mentioned above; i.e., $\mathit{L}=1$ .

fg_info.index
This member function has prototype
     virtual void cppad_ipopt_fg_info::index(
          size_t k, size_t ell, SizeVector& I, SizeVector& J
     )
The argument  
     k
has type size_t and is a value between zero and $\mathit{K}-1$ inclusive. The argument  
     ell
has type size_t and is a value between zero and $\mathit{L}(\mathit{k})-1$ inclusive. The argument
     I
is a SimpleVector with elements of type size_t and size greater than or equal to $\mathit{p}(\mathit{k})$ . The input value of the elements of I does not matter. The output value of the first $\mathit{p}(\mathit{k})$ elements of I must be the corresponding elements of ${\mathit{I}}_{\mathit{k},\mathit{ell}}$ in the representation above. The argument
     J
is a SimpleVector with elements of type size_t and size greater than or equal to $\mathit{q}(\mathit{k})$ . The input value of the elements of J does not matter. The output value of the first $\mathit{q}(\mathit{k})$ elements of J must be the corresponding elements of ${\mathit{J}}_{\mathit{k},\mathit{ell}}$ in the representation above.

The cppad_ipopt_h_base implementation of this function corresponds to the simple representation mentioned above; i.e., for $\mathit{i}=0,\dots ,\mathit{m}$ , I[i] = i , and for $\mathit{j}=0,\dots ,\mathit{n}-1$ , J[j] = j .

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

status
The status field of solution has prototype
     cppad_ipopt_solution::solution_status solution.status
It is the final Ipopt status for the optimizer. Here is a list of the possible values for the status:

status	Meaning
not_defined	The optimizer did not return a final status to this cppad_ipopt_nlp object.
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
     NumberVector solution.x
and its size is equal to $\mathit{n}$ . It is the final $\mathit{x}$ value for the optimizer.

z_l
The z_l field of solution has prototype
     NumberVector solution.z_l
and its size is equal to $\mathit{n}$ . It is the final Lagrange multipliers for the lower bounds on $\mathit{x}$ .

z_u
The z_u field of solution has prototype
     NumberVector solution.z_u
and its size is equal to $\mathit{n}$ . It is the final Lagrange multipliers for the upper bounds on $\mathit{x}$ .

g
The g field of solution has prototype
     NumberVector solution.g
and its size is equal to $\mathit{m}$ . It is the final value for the constraint function $\mathit{g}(\mathit{x})$ .

lambda
The lambda field of solution has prototype
     NumberVector solution.lambda
and its size is equal to $\mathit{m}$ . It is the final value for the Lagrange multipliers corresponding to the constraint function.

obj_value
The obj_value field of solution has prototype
     Number solution.obj_value
It is the final value of the objective function $\mathit{f}(\mathit{x})$ .

Visual Studio
If you are using Visual Studio, see the special cppad_ipopt_windows instructions.

Example
The file ipopt_get_started.cpp is an example and test of cppad_ipopt_nlp that uses the simple representation . It returns true if it succeeds and false otherwise. The section cppad_ipopt_ode discusses an example that uses a more complex representation.

Wish List
This is a list of possible future improvements to cppad_ipopt_nlp that would require changed to the user interface:

1. The routine fg_info.eval_r(k, u) should also support NumberVector for the type of the argument u (this would certainly be more efficient when fg_info.retape(k) is true and $\mathit{L}(\mathit{k})>1$ ). It could be an option for the user to provide this as well as the necessary ADVector definition.
2. There should a Discrete routine that the user can call to determine the value of $\ell$ during the evaluation of fg_info.eval_r(k, u) . This way data, which does not affect the derivative values, can be included in the function recording and evaluation.

---

Input File: cppad_ipopt/src/cppad_ipopt_nlp.hpp