CppAD: A C++ Algorithmic Differentiation Package 20110419
cppad_ipopt_nlp.hpp
Go to the documentation of this file.
00001 /* $Id$ */
00002 # ifndef CPPAD_IPOPT_NLP_INCLUDED
00003 # define CPPAD_IPOPT_NLP_INCLUDED
00004 /* --------------------------------------------------------------------------
00005 CppAD: C++ Algorithmic Differentiation: Copyright (C) 2003-10 Bradley M. Bell
00006 
00007 CppAD is distributed under multiple licenses. This distribution is under
00008 the terms of the 
00009                     Common Public License Version 1.0.
00010 
00011 A copy of this license is included in the COPYING file of this distribution.
00012 Please visit http://www.coin-or.org/CppAD/ for information on other licenses.
00013 -------------------------------------------------------------------------- */
00014 /*
00015 $begin cppad_ipopt_nlp$$
00016 $spell
00017         cppad
00018         bool
00019         doesn't
00020         nan
00021         inf
00022         naninf
00023         std
00024         maxiter
00025         infeasibility
00026         obj
00027         const
00028         optimizer
00029         cppad_ipopt_nlp.hpp
00030         fg_info.eval
00031         retape
00032         CppAD
00033         
00034 $$
00035 $section Nonlinear Programming Using the CppAD Interface to Ipopt$$
00036 
00037 $index nonlinear, programming CppAD$$
00038 $index programming, nonlinear$$
00039 $index CppAD, nonlinear programming$$
00040 $index Ipopt, AD$$
00041 $index AD, Ipopt$$
00042 
00043 $head Syntax$$
00044 $codei%# include "cppad_ipopt_nlp.hpp"
00045 %$$
00046 $codei%# cppad_ipopt_solution %solution%;
00047 %$$
00048 $codei%cppad_ipopt_nlp %cppad_nlp%(
00049         %n%, %m%, %x_i%, %x_l%, %x_u%, %g_l%, %g_u%, &%fg_info%, &%solution%
00050 )%$$
00051 
00052 $head Purpose$$
00053 The class $code cppad_ipopt_nlp$$ is used to solve nonlinear programming
00054 problems of the form
00055 $latex \[
00056 \begin{array}{rll}
00057 {\rm minimize}      & f(x) 
00058 \\
00059 {\rm subject \; to} & g^l \leq g(x) \leq g^u
00060 \\
00061                     & x^l  \leq x   \leq x^u
00062 \end{array}
00063 \] $$
00064 This is done using 
00065 $href%
00066         https://www.coin-or.org/projects/Ipopt%
00067         Ipopt
00068 %$$
00069 optimizer and 
00070 $href%
00071         http://www.coin-or.org/CppAD/%
00072         CppAD
00073 %$$
00074 Algorithmic Differentiation package.
00075 
00076 $head fg(x)$$
00077 The function $latex fg : \R^n \rightarrow \R^{m+1}$$ is defined by
00078 $latex \[
00079 \begin{array}{rcl}
00080         fg_0 (x)     & = & f(x)         \\
00081         fg_1 (x)     & = & g_0 (x)      \\
00082                      & \vdots &         \\
00083         fg_m (x)     & = & g_{m-1} (x)
00084         \end{array}
00085 \] $$
00086 
00087 $subhead Index Vector$$
00088 We define an $italic index vector$$ as a vector of non-negative integers
00089 for which none of the values are equal; i.e.,
00090 it is both a vector and a set.
00091 If $latex I$$ is an index vector $latex |I|$$ is used to denote the
00092 number of elements in $latex I$$ and $latex \| I \|$$ is used
00093 to denote the value of the maximum element in $latex I$$.
00094 
00095 $subhead Projection$$
00096 Given an index vector $latex J$$ and a positive integer $latex n$$
00097 where $latex n > \| J \|$$, we use $latex J \otimes n $$ for
00098 the mapping $latex ( J \otimes n ) : \R^n \rightarrow \R^{|J|}$$ defined by
00099 $latex \[
00100         [ J \otimes n ] (x)_j = x_{J(j)}
00101 \] $$
00102 for $latex j = 0 , \ldots |J| - 1$$.
00103 
00104 $subhead Injection$$
00105 Given an index vector $latex I$$ and a positive integer $latex m$$
00106 where $latex m > \| I \|$$, we use $latex m \otimes I$$ for
00107 the mapping $latex ( m \otimes I ): \R^{|I|} \rightarrow \R^m$$ defined by
00108 $latex \[
00109 [ m \otimes I ] (y)_i = \left\{ \begin{array}{ll}
00110 y_k & {\rm if} \; i = I(k) \; {\rm for \; some} \; 
00111         k \in \{ 0 , \cdots, |I|-1 \} 
00112 \\
00113 0   & {\rm otherwise}
00114 \end{array} \right.
00115 \] $$
00116 
00117 $subhead Representation$$
00118 In many applications, each of the component functions of $latex fg(x)$$
00119 only depend on a few of the components of $latex x$$.
00120 In this case, expressing $latex fg(x)$$ in terms of simpler functions
00121 with fewer arguments can greatly reduce the amount of work required
00122 to compute its derivatives.
00123 $pre
00124 
00125 $$
00126 We use the functions
00127 $latex r_k : \R^{q(k)} \rightarrow \R^{p(k)}$$ 
00128 for $latex k = 0 , \ldots , K$$ to express our
00129 representation of $latex fg(x)$$ in terms of simpler functions
00130 as follows
00131 $latex \[
00132 fg(x) = \sum_{k=0}^{K-1} \; \sum_{\ell=0}^{L(k) - 1} 
00133 [ (m+1) \otimes I_{k,\ell} ] \; \circ
00134          \; r_k \; \circ \; [ J_{k,\ell} \otimes n ] \; (x)
00135 \] $$
00136 where $latex \circ$$ represents function composition,
00137 for $latex k = 0 , \ldots , K - 1$$, and $latex \ell = 0 , \ldots , L(k)$$,
00138 $latex I_{k,\ell}$$ and  $latex J_{k,\ell}$$ are index vectors with
00139 $latex | J_{k,\ell} | = q(k)$$, 
00140 $latex \| J_{k,\ell} \| < n$$,
00141 $latex | I_{k,\ell} | = p(k)$$, and
00142 $latex \| I_{k,\ell} \| \leq m$$. 
00143 
00144 $head Simple Representation$$
00145 In the simple representation,
00146 $latex r_0 (x) = fg(x)$$,
00147 $latex K = 1$$,
00148 $latex q(0) = n$$,
00149 $latex p(0) = m+1$$,
00150 $latex L(0) = 1$$,
00151 $latex I_{0,0} = (0 , \ldots , m)$$,
00152 and $latex J_{0,0} = (0 , \ldots , n-1)$$.
00153 
00154 $head SizeVector$$
00155 The type $codei SizeVector$$ is defined by the 
00156 $codei cppad_ipopt_nlp.hpp$$ include file to be a 
00157 $cref/SimpleVector/$$ class with elements of type
00158 $code size_t$$.
00159 
00160 $head NumberVector$$
00161 The type $codei NumberVector$$ is defined by the 
00162 $codei cppad_ipopt_nlp.hpp$$ include file to be a 
00163 $cref/SimpleVector/$$ class with elements of type
00164 $code Ipopt::Number$$.
00165 
00166 $head ADNumber$$
00167 The type $codei ADNumber$$ is defined by the 
00168 $codei cppad_ipopt_nlp.hpp$$ include file to be a 
00169 an AD type that can be used to compute derivatives.
00170 
00171 $head ADVector$$
00172 The type $codei ADVector$$ is defined by the 
00173 $codei cppad_ipopt_nlp.hpp$$ include file to be a 
00174 $cref/SimpleVector/$$ class with elements of type
00175 $code ADNumber$$. 
00176 
00177 $head n$$
00178 The argument $icode n$$ has prototype
00179 $codei%
00180         size_t %n%
00181 %$$
00182 It specifies the dimension of the argument space; 
00183 i.e., $latex x \in \R^n$$.
00184 
00185 $head m$$
00186 The argument $icode m$$ has prototype
00187 $codei%
00188         size_t %m%
00189 %$$
00190 It specifies the dimension of the range space for $latex g$$; 
00191 i.e., $latex g : \R^n \rightarrow \R^m$$.
00192 
00193 $head x_i$$
00194 The argument $icode x_i$$ has prototype
00195 $codei%
00196         const NumberVector& %x_i%
00197 %$$
00198 and its size is equal to $latex n$$.
00199 It specifies the initial point where Ipopt starts the optimization process.
00200 
00201 $head x_l$$
00202 The argument $icode x_l$$ has prototype
00203 $codei%
00204         const NumberVector& %x_l%
00205 %$$
00206 and its size is equal to $latex n$$.
00207 It specifies the lower limits for the argument in the optimization problem;
00208 i.e., $latex x^l$$.
00209 
00210 $head x_u$$
00211 The argument $icode x_u$$ has prototype
00212 $codei%
00213         const NumberVector& %x_u%
00214 %$$
00215 and its size is equal to $latex n$$.
00216 It specifies the upper limits for the argument in the optimization problem;
00217 i.e., $latex x^u$$.
00218 
00219 $head g_l$$
00220 The argument $icode g_l$$ has prototype
00221 $codei%
00222         const NumberVector& %g_l%
00223 %$$
00224 and its size is equal to $latex m$$.
00225 It specifies the lower limits for the constraints in the optimization problem;
00226 i.e., $latex g^l$$.
00227 
00228 $head g_u$$
00229 The argument $icode g_u$$ has prototype
00230 $codei%
00231         const NumberVector& %g_u%
00232 %$$
00233 and its size is equal to $latex n$$.
00234 It specifies the upper limits for the constraints in the optimization problem;
00235 i.e., $latex g^u$$.
00236 
00237 $head fg_info$$
00238 The argument $icode fg_info$$ has prototype
00239 $codei%
00240         %FG_info fg_info%
00241 %$$
00242 where the class $icode FG_info$$ is derived from the 
00243 base class $code cppad_ipopt_fg_info$$.
00244 Certain virtual member functions of $icode fg_info$$ are used to 
00245 compute the value of $latex fg(x)$$.
00246 The specifications for these member functions are given below:
00247 
00248 $subhead fg_info.number_functions$$
00249 This member function has prototype
00250 $codei%
00251         virtual size_t cppad_ipopt_fg_info::number_functions(void)
00252 %$$
00253 If $icode K$$ has type $code size_t$$, the syntax
00254 $codei%
00255         %K% = %fg_info%.number_functions()
00256 %$$
00257 sets $icode K$$ to the number of functions used in the
00258 representation of $latex fg(x)$$; i.e., $latex K$$ in
00259 the $cref/representation/cppad_ipopt_nlp/fg(x)/Representation/$$ above.
00260 $pre
00261 
00262 $$
00263 The $code cppad_ipopt_fg_info$$ implementation of this function
00264 corresponds to the simple representation mentioned above; i.e.
00265 $icode%K% = 1%$$.
00266 
00267 $subhead fg_info.eval_r$$
00268 This member function has the prototype
00269 $codei%
00270 virtual ADVector cppad_ipopt_fg_info::eval_r(size_t %k%, const ADVector& %u%) = 0;
00271 %$$
00272 Thus it is a pure virtual function and must be defined in the 
00273 derived class $icode FG_info$$.
00274 $pre
00275 
00276 $$
00277 This function computes the value of $latex r_k (u)$$
00278 used in the $cref/representation/cppad_ipopt_nlp/fg(x)/Representation/$$
00279 for $latex fg(x)$$.
00280 If $icode k$$ in $latex \{0 , \ldots , K-1 \}$$ has type $code size_t$$,
00281 $icode u$$ is an $code ADVector$$ of size $icode q(k)$$ 
00282 and $icode r$$ is an $code ADVector$$ of size $icode p(k)$$
00283 the syntax
00284 $codei%
00285         %r% = %fg_info%.eval_r(%k%, %u%)
00286 %$$
00287 set $icode r$$ to the vector $latex r_k (u)$$.
00288 
00289 $subhead fg_info.retape$$
00290 This member function has the prototype
00291 $codei%
00292         virtual bool cppad_ipopt_fg_info::retape(size_t %k%)
00293 %$$
00294 If $icode k$$ in $latex \{0 , \ldots , K-1 \}$$ has type $code size_t$$,
00295 and $icode retape$$ has type $code bool$$,
00296 the syntax
00297 $codei%
00298         %retape% = %fg_info%.retape(%k%)
00299 %$$
00300 sets $icode retape$$ to true or false.
00301 If $icode retape$$ is true, 
00302 $code cppad_ipopt_nlp$$ will retape the operation sequence 
00303 corresponding to $latex r_k (u)$$ for
00304 every value of $icode u$$. 
00305 An $code cppad_ipopt_nlp$$ object
00306 should use much less memory and run faster if $icode retape$$ is false.
00307 You can test both the true and false cases to make sure 
00308 the operation sequence does not depend on $icode u$$.
00309 $pre
00310 
00311 $$
00312 The $code cppad_ipopt_fg_info$$ implementation of this function
00313 sets $icode retape$$ to true 
00314 (while slower it is also safer to always retape).
00315 
00316 $subhead fg_info.domain_size$$
00317 This member function has prototype
00318 $codei%
00319         virtual size_t cppad_ipopt_fg_info::domain_size(size_t %k%)
00320 %$$
00321 If $icode k$$ in $latex \{0 , \ldots , K-1 \}$$ has type $code size_t$$,
00322 and $icode q$$ has type $code size_t$$, the syntax
00323 $codei%
00324         %q% = %fg_info%.domain_size(%k%)
00325 %$$
00326 sets $icode q$$ to the dimension of the domain space for $latex r_k (u)$$;
00327 i.e., $latex q(k)$$ in
00328 the $cref/representation/cppad_ipopt_nlp/fg(x)/Representation/$$ above.
00329 
00330 $pre
00331 
00332 $$
00333 The $code cppad_ipopt_h_base$$ implementation of this function
00334 corresponds to the simple representation mentioned above; i.e.,
00335 $latex q = n$$.
00336 
00337 $subhead fg_info.range_size$$
00338 This member function has prototype
00339 $codei%
00340         virtual size_t cppad_ipopt_fg_info::range_size(size_t %k%)
00341 %$$
00342 If $icode k$$ in $latex \{0 , \ldots , K-1 \}$$ has type $code size_t$$,
00343 and $icode p$$ has type $code size_t$$, the syntax
00344 $codei%
00345         %p% = %fg_info%.range_size(%k%)
00346 %$$
00347 sets $icode p$$ to the dimension of the range space for $latex r_k (u)$$;
00348 i.e., $latex p(k)$$ in
00349 the $cref/representation/cppad_ipopt_nlp/fg(x)/Representation/$$ above.
00350 $pre
00351 
00352 $$
00353 The $code cppad_ipopt_h_base$$ implementation of this function
00354 corresponds to the simple representation mentioned above; i.e.,
00355 $latex p = m+1$$.
00356 
00357 $subhead fg_info.number_terms$$
00358 This member function has prototype
00359 $codei%
00360         virtual size_t cppad_ipopt_fg_info::number_terms(size_t %k%)
00361 %$$
00362 If $icode k$$ in $latex \{0 , \ldots , K-1 \}$$ has type $code size_t$$,
00363 and $icode L$$ has type $code size_t$$, the syntax
00364 $codei%
00365         %L% = %fg_info%.number_terms(%k%)
00366 %$$
00367 sets $icode L$$ to the number of terms in representation
00368 for this value of $icode k$$;
00369 i.e., $latex L(k)$$ in
00370 the $cref/representation/cppad_ipopt_nlp/fg(x)/Representation/$$ above.
00371 $pre
00372 
00373 $$
00374 The $code cppad_ipopt_h_base$$ implementation of this function
00375 corresponds to the simple representation mentioned above; i.e.,
00376 $latex L = 1$$.
00377 
00378 $subhead fg_info.index$$
00379 This member function has prototype
00380 $codei%
00381         virtual void cppad_ipopt_fg_info::index(
00382                 size_t %k%, size_t %ell%, SizeVector& %I%, SizeVector& %J%
00383         )
00384 %$$ 
00385 The argument 
00386 $icode% 
00387         k
00388 %$$
00389 has type $codei size_t$$
00390 and is a value between zero and $latex K-1$$ inclusive.
00391 The argument 
00392 $icode% 
00393         ell
00394 %$$
00395 has type $codei size_t$$
00396 and is a value between zero and $latex L(k)-1$$ inclusive.
00397 The argument 
00398 $icode%
00399         I
00400 %$$ is a $cref/SimpleVector/$$ with elements
00401 of type $code size_t$$ and size greater than or equal to $latex p(k)$$.
00402 The input value of the elements of $icode I$$ does not matter.
00403 The output value of
00404 the first $latex p(k)$$ elements of $icode I$$ 
00405 must be the corresponding elements of $latex I_{k,ell}$$ 
00406 in the $cref/representation/cppad_ipopt_nlp/fg(x)/Representation/$$ above.
00407 The argument 
00408 $icode%
00409         J
00410 %$$ is a $cref/SimpleVector/$$ with elements
00411 of type $code size_t$$ and size greater than or equal to $latex q(k)$$.
00412 The input value of the elements of $icode J$$ does not matter.
00413 The output value of 
00414 the first $latex q(k)$$ elements of $icode J$$ 
00415 must be the corresponding elements of $latex J_{k,ell}$$ 
00416 in the $cref/representation/cppad_ipopt_nlp/fg(x)/Representation/$$ above.
00417 $pre
00418 
00419 $$
00420 The $code cppad_ipopt_h_base$$ implementation of this function
00421 corresponds to the simple representation mentioned above; i.e.,
00422 for $latex i = 0 , \ldots , m$$,
00423 $icode%I%[%i%] = %i%$$,
00424 and  for $latex j = 0 , \ldots , n-1$$,
00425 $icode%J%[%j%] = %j%$$.
00426 
00427 $head solution$$
00428 After the optimization process is completed, $icode solution$$ contains
00429 the following information:
00430 
00431 $subhead status$$
00432 The $icode status$$ field of $icode solution$$ has prototype
00433 $codei%
00434         cppad_ipopt_solution::solution_status %solution%.status
00435 %$$
00436 It is the final Ipopt status for the optimizer. 
00437 Here is a list of the possible values for the status:
00438 
00439 $table
00440 $icode status$$ $cnext Meaning
00441 $rnext
00442 not_defined $cnext
00443 The optimizer did not return a final status to this $code cppad_ipopt_nlp$$
00444 object.
00445 $rnext
00446 unknown $cnext
00447 The status returned by the optimizer is not defined in the Ipopt
00448 documentation for $code finalize_solution$$.
00449 $rnext
00450 success $cnext
00451 Algorithm terminated successfully at a point satisfying the convergence 
00452 tolerances (see Ipopt options).
00453 $rnext
00454 maxiter_exceeded $cnext
00455 The maximum number of iterations was exceeded (see Ipopt options).
00456 $rnext
00457 stop_at_tiny_step $cnext
00458 Algorithm terminated because progress was very slow.
00459 $rnext
00460 stop_at_acceptable_point $cnext
00461 Algorithm stopped at a point that was converged, 
00462 not to the 'desired' tolerances, but to 'acceptable' tolerances 
00463 (see Ipopt options).
00464 $rnext
00465 local_infeasibility $cnext
00466 Algorithm converged to a non-feasible point
00467 (problem may have no solution).
00468 $rnext
00469 user_requested_stop $cnext
00470 This return value should not happen.
00471 $rnext
00472 diverging_iterates $cnext
00473 It the iterates are diverging.
00474 $rnext
00475 restoration_failure $cnext
00476 Restoration phase failed, algorithm doesn't know how to proceed.
00477 $rnext
00478 error_in_step_computation $cnext
00479 An unrecoverable error occurred while Ipopt tried to 
00480 compute the search direction.
00481 $rnext
00482 invalid_number_detected $cnext
00483 Algorithm received an invalid number (such as $code nan$$ or $code inf$$) 
00484 from the users function $icode%fg_info%.eval%$$ or from the CppAD evaluations
00485 of its derivatives
00486 (see the Ipopt option $code check_derivatives_for_naninf$$).
00487 $rnext
00488 internal_error $cnext
00489 An unknown Ipopt internal error occurred.
00490 Contact the Ipopt authors through the mailing list.
00491 $tend
00492 
00493 $subhead x$$
00494 The $code x$$ field of $icode solution$$ has prototype
00495 $codei%
00496         NumberVector %solution%.x
00497 %$$
00498 and its size is equal to $latex n$$.
00499 It is the final $latex x$$ value for the optimizer.
00500 
00501 $subhead z_l$$
00502 The $code z_l$$ field of $icode solution$$ has prototype
00503 $codei%
00504         NumberVector %solution%.z_l
00505 %$$
00506 and its size is equal to $latex n$$.
00507 It is the final Lagrange multipliers for the 
00508 lower bounds on $latex x$$.
00509 
00510 $subhead z_u$$
00511 The $code z_u$$ field of $icode solution$$ has prototype
00512 $codei%
00513         NumberVector %solution%.z_u
00514 %$$
00515 and its size is equal to $latex n$$.
00516 It is the final Lagrange multipliers for the 
00517 upper bounds on $latex x$$.
00518 
00519 $subhead g$$
00520 The $code g$$ field of $icode solution$$ has prototype
00521 $codei%
00522         NumberVector %solution%.g
00523 %$$
00524 and its size is equal to $latex m$$.
00525 It is the final value for the constraint function $latex g(x)$$.
00526 
00527 $subhead lambda$$
00528 The $code lambda$$ field of $icode solution$$ has prototype
00529 $codei%
00530         NumberVector %solution%.lambda
00531 %$$
00532 and its size is equal to $latex m$$.
00533 It is the final value for the 
00534 Lagrange multipliers corresponding to the constraint function.
00535 
00536 $subhead obj_value$$
00537 The $code obj_value$$ field of $icode solution$$ has prototype
00538 $codei%
00539         Number %solution%.obj_value
00540 %$$
00541 It is the final value of the objective function $latex f(x)$$.
00542 
00543 
00544 $children%
00545         cppad_ipopt/example/example_windows.bat%
00546         cppad_ipopt/example/get_started.cpp%
00547         cppad_ipopt/example/ode1.omh%
00548         cppad_ipopt/speed/ode_speed.cpp
00549 %$$
00550 
00551 $head Visual Studio$$
00552 If you are using Visual Studio, see the special
00553 $cref/cppad_ipopt_windows/$$ instructions.
00554 
00555 $head Example$$
00556 The file 
00557 $cref/ipopt_get_started.cpp/$$ is an example and test of 
00558 $code cppad_ipopt_nlp$$  that uses the 
00559 $cref/simple representation/cppad_ipopt_nlp/Simple Representation/$$.
00560 It returns true if it succeeds and false otherwise.
00561 The section $cref/cppad_ipopt_ode/$$ discusses an example that
00562 uses a more complex representation.
00563 
00564 $head Wish List$$
00565 This is a list of possible future improvements to 
00566 $code cppad_ipopt_nlp$$ that would require changed to the user interface:
00567 $list number$$
00568 The routine $codei%fg_info.eval_r(%k%, %u%)%$$ should also support 
00569 $codei NumberVector$$ for the type of the argument $code u$$
00570 (this would certainly be more efficient when 
00571 $codei%fg_info.retape(%k%)%$$ is true and $latex L(k) > 1$$).
00572 It could be an option for the user to provide this as well as
00573 the necessary $code ADVector$$ definition.
00574 $lnext
00575 There should a $cref/Discrete/$$ routine that the user can call
00576 to determine the value of $latex \ell$$ during the evaluation of
00577 $codei%fg_info.eval_r(%k%, %u%)%$$.
00578 This way data, which does not affect the derivative values,
00579 can be included in the function recording and evaluation.
00580 $lend
00581 
00582 $end
00583 -----------------------------------------------------------------------------
00584 */
00585 # include <cppad/cppad.hpp>
00586 # include <coin/IpIpoptApplication.hpp>
00587 # include <coin/IpTNLP.hpp>
00588 
00589 /*!
00590 \file cppad_ipopt_nlp.hpp
00591 \brief CppAD interface to Ipopt
00592 */
00593 
00594 
00595 /// A scalar value used to record operation sequence.
00596 typedef CppAD::AD<Ipopt::Number>       ADNumber;
00597 /// A simple vector of values used to record operation sequence
00598 typedef CppAD::vector<ADNumber>        ADVector;
00599 /// A simple vector of size_t values.
00600 typedef CppAD::vector<size_t>          SizeVector;
00601 /// A simple vector of values used by Ipopt
00602 typedef CppAD::vector<Ipopt::Number>   NumberVector;
00603 
00604 /*!
00605 Abstract base class user derives from to define the funcitons in the problem.
00606 */
00607 class cppad_ipopt_fg_info
00608 {
00609         /// allow cppad_ipopt_nlp class complete access to this class
00610         friend class cppad_ipopt_nlp;
00611 private:
00612         /// domain space dimension for the functions f(x), g(x)
00613         size_t n_;
00614         /// range space dimension for the function g(x)
00615         size_t m_;
00616         /// the cppad_ipopt_nlp constructor uses this method to set n_
00617         void set_n(size_t n)
00618         {       n_ = n; }
00619         /// the cppad_ipopt_nlp constructor uses this method to set m_
00620         void set_m(size_t m)
00621         {       m_ = m; }
00622 
00623 public:
00624         /// destructor virtual so user derived class destructor gets called
00625         virtual ~cppad_ipopt_fg_info(void)
00626         { }
00627         /// number_functions; i.e. K (simple representation uses 1)
00628         virtual size_t number_functions(void)
00629         {       return 1; }
00630         /// function that evaluates the users representation for f(x) and
00631         /// and g(x) is pure virtual so user must define it in derived class
00632         virtual ADVector eval_r(size_t k, const ADVector& u) = 0;
00633         /// should the function r_k (u) be retaped when ever the arguemnt
00634         /// u changes (default is true which is safe but slow)
00635         virtual bool retape(size_t k)
00636         {       return true; }
00637         /// domain_size q[k] for r_k (u) (simple representation uses n)
00638         virtual size_t domain_size(size_t k)
00639         {       return n_; }
00640         /// range_size p[k] for r_k (u) (simple representation uses m+1)
00641         virtual size_t range_size(size_t k)
00642         {       return m_ + 1; }
00643         /// number_terms that use r_k (u) (simple represenation uses 1)
00644         virtual size_t number_terms(size_t k)
00645         {       return 1; }
00646         /// return the index vectors I_{k,ell} and J_{k,ell}
00647         /// (simple representation uses I[i] = i and J[j] = j)
00648         virtual void index(size_t k, size_t ell, SizeVector& I, SizeVector& J)
00649         {       assert( I.size() >= m_ + 1 );
00650                 assert( J.size() >= n_ );
00651                 for(size_t i = 0; i <= m_; i++)
00652                         I[i] = i;
00653                 for(size_t j = 0; j < n_; j++)
00654                         J[j] = j;
00655         }
00656 };
00657 
00658 /*!
00659 Class that contains information about the problem solution
00660 
00661 \section Nonlinear_Programming_Problem Nonlinear Programming Problem
00662 We are give smooth functions 
00663 \f$ f : {\bf R}^n \rightarrow {\bf R} \f$
00664 and
00665 \f$ g : {\bf R}^n \rightarrow {\bf R}^m \f$
00666 and wish to solve the problem
00667 \f[
00668 \begin{array}{rcl}
00669 {\rm minimize} & f(x) & {\rm w.r.t.} \; x \in {\bf R}^n
00670 \\
00671 {\rm subject \; to} & g^l \leq g(x) \leq g^u 
00672 \\
00673 & x^l \leq x \leq x^u
00674 \end{array}
00675 \f]
00676 
00677 
00678 \section Users_Representation Users Representation
00679 The functions 
00680 \f$ f : {\bf R}^n \rightarrow {\bf R} \f$ and
00681 \f$ g : {\bf R}^n \rightarrow {\bf R}^m \f$ are defined by
00682 \f[
00683 \left( \begin{array}{c} f(x) \\ g(x) \end{array} \right)
00684 =
00685 \sum_{k=0}^{K-1} \; \sum_{\ell=0}^{L(k) - 1} 
00686 [ (m+1) \otimes I_{k,\ell} ] \; \circ
00687          \; r_k \; \circ \; [ J_{k,\ell} \otimes n ] \; (x)
00688 \f]
00689 where for \f$ k = 0 , \ldots , K-1\f$,
00690 \f$ r_k : {\bf R}^{q(k)} \rightarrow {\bf R}^{p(k)} \f$.
00691 
00692 \section Evaluation_Methods Evaluation Methods
00693 The set of evaluation methods for this class is
00694 \verbatim
00695         { eval_f, eval_grad_f, eval_g, eval_jac_g, eval_h }
00696 \endverbatim
00697 Note that the \c bool return flag for the evaluations methods 
00698 does not appear in the Ipopt documentation.
00699 Looking at the code, it seems to be a flag telling Ipopt to abort
00700 when the flag is false.
00701 
00702 */
00703 class cppad_ipopt_solution 
00704 {
00705 public:
00706         /// possible values for he solution status
00707         enum solution_status {
00708                 not_defined,
00709                 success,
00710                 maxiter_exceeded,
00711                 stop_at_tiny_step,
00712                 stop_at_acceptable_point,
00713                 local_infeasibility,
00714                 user_requested_stop,
00715                 feasible_point_found,
00716                 diverging_iterates,
00717                 restoration_failure,
00718                 error_in_step_computation,
00719                 invalid_number_detected,
00720                 too_few_degrees_of_freedom,
00721                 internal_error,
00722                 unknown
00723         }  status;
00724         /// the approximation solution
00725         NumberVector      x;
00726         /// Lagrange multipliers corresponding to lower bounds on x
00727         NumberVector      z_l;
00728         /// Lagrange multipliers corresponding to upper bounds on x
00729         NumberVector      z_u;
00730         /// value of g(x)
00731         NumberVector      g;
00732         /// Lagrange multipliers correspondiing constraints on g(x)
00733         NumberVector      lambda;
00734         /// value of f(x)
00735         Ipopt::Number     obj_value;
00736         /// constructor initializes solution status as not yet defined
00737         cppad_ipopt_solution(void)
00738         {       status = not_defined; }
00739 };
00740 
00741 /*! 
00742 Class connects Ipopt to CppAD for derivative and sparsity pattern calculations.
00743 */
00744 class cppad_ipopt_nlp : public Ipopt::TNLP
00745 {
00746 private:
00747         /// A Scalar value used by Ipopt
00748         typedef Ipopt::Number                         Number;
00749         /// An index value used by Ipopt 
00750         typedef Ipopt::Index                          Index;
00751         /// Indexing style used in Ipopt sparsity structure 
00752         typedef Ipopt::TNLP::IndexStyleEnum           IndexStyleEnum;
00753         /// A simple vector of boolean values
00754         typedef CppAD::vectorBool                     BoolVector;
00755         /// A simple vector of AD function objects
00756         typedef CppAD::vector< CppAD::ADFun<Number> > ADFunVector;
00757         /// A simple vector of simple vectors of boolean values
00758         typedef CppAD::vector<BoolVector>             BoolVectorVector;
00759         /// A mapping that is dense in i, sparse in j, and maps (i, j)
00760         /// to the corresponding sparsity index in Ipopt.
00761         typedef CppAD::vector< std::map<size_t,size_t> > IndexMap;
00762 
00763         // ------------------------------------------------------------------
00764         // Values directly passed in to constuctor
00765         // ------------------------------------------------------------------
00766         /// dimension of the domain space for f(x) and g(x)
00767         /// (passed to ctor)
00768         const size_t                    n_;
00769         /// dimension of the range space for g(x)
00770         /// (passed to ctor)
00771         const size_t                    m_;
00772         /// dimension of the range space for g(x)
00773         /// (passed to ctor)
00774         const NumberVector              x_i_;
00775         /// lower limit for x 
00776         /// (size n_), (passed to ctor)
00777         const NumberVector              x_l_;
00778         /// upper limit for x 
00779         /// (size n_) (passed to ctor)
00780         const NumberVector              x_u_;
00781         /// lower limit for g(x)
00782         /// (size m_) (passed to ctor)
00783         const NumberVector              g_l_;
00784         /// upper limit for g(x)
00785         /// (size m_) (passed to ctor)
00786         const NumberVector              g_u_;
00787         /// pointer to base class version of derived class object used to get 
00788         /// information about the user's representation for f(x) and g(x)
00789         /// (passed to ctor)
00790         cppad_ipopt_fg_info* const      fg_info_;
00791         /// pointer to object where final results are stored
00792         /// (passed to ctor)
00793         cppad_ipopt_solution* const     solution_;
00794 
00795         // ------------------------------------------------------------------
00796         // Effectively const values determined during constructor using calls 
00797         // to fg_info:
00798         // ------------------------------------------------------------------
00799         /// The value of \f$ K \f$ in the representation.
00800         /// (effectively const)
00801         size_t                 K_;
00802         /// Does operation sequence for \f$ r_k (u) \f$ depend on \f$ u \f$.
00803         /// (size K_) (effectively const)
00804         BoolVector             retape_;
00805         /// <tt>q_[k]</tt> is the domain space dimension for \f$ r_k (u) \f$
00806         /// (size K_) (effectively const)
00807         SizeVector             q_;
00808         /// <tt>p_[k]</tt> is the range space dimension for \f$ r_k (u) \f$
00809         /// (size K_) (effectively const)
00810         SizeVector             p_;
00811         /// <tt>L_[k]</tt> is number of times \f$ r_k (u) \f$ appears in
00812         /// the representation summation
00813         /// (size K_) (effectively const)
00814         SizeVector             L_; 
00815         // -------------------------------------------------------------------
00816         // Other effectively const values determined by the constructor:
00817         // -------------------------------------------------------------------
00818         /*!
00819         CppAD sparsity patterns for \f$ \{ r_k^{(1)} (u) \} \f$ (set by ctor).
00820 
00821         For <tt>k = 0 , ... , K_-1, pattern_jac_r_[k]</tt> 
00822         is a CppAD sparsity pattern for the Jacobian of \f$ r_k (u) \f$ 
00823         and as such it has size <tt>p_[k]*q_[k]</tt>.
00824         (effectively const)
00825         */
00826         BoolVectorVector                 pattern_jac_r_;
00827 
00828         /*!
00829         CppAD sparsity patterns for \f$ \{ r_k^{(2)} (u) \} \f$ (set by ctor).
00830 
00831         For <tt>k = 0 , ... , K_-1, pattern_jac_r_[k]</tt> 
00832         is a CppAD sparsity pattern for the Hessian of 
00833         \f[
00834                 R(u) = \sum_{i=0}^{p[k]-1}  r_k (u)_i
00835         \f]
00836         and as such it has size <tt>q_[k]*q_[k]</tt>.
00837         (effectively const)
00838         */
00839         BoolVectorVector                 pattern_hes_r_;
00840 
00841         /// number non-zero is Ipopt sparsity structor for Jacobian of g(x)
00842         /// (effectively const)
00843         size_t                           nnz_jac_g_;
00844         /// row indices in Ipopt sparsity structor for Jacobian of g(x)
00845         /// (effectively const)
00846         SizeVector                       iRow_jac_g_;
00847         /// column indices in Ipopt sparsity structor for Jacobian of g(x)
00848         /// (effectively const)
00849         SizeVector                       jCol_jac_g_;
00850 
00851         /// number non-zero is Ipopt sparsity structor for Hessian of Lagragian
00852         /// (effectively const)
00853         size_t                           nnz_h_lag_;
00854         /// row indices in Ipopt sparsity structor for Hessian of Lagragian
00855         /// (effectively const)
00856         SizeVector                       iRow_h_lag_;
00857         /// column indices in Ipopt sparsity structor for Hessian of Lagragian
00858         /// (effectively const)
00859         SizeVector                       jCol_h_lag_;
00860 
00861         /*!
00862         Mapping from (i, j) in Jacobian of g(x) to Ipopt sparsity structure
00863 
00864         For <tt>i = 0 , ... , m_-1, index_jac_g_[i]</tt>
00865         is a standard map from column index values \c j to the corresponding
00866         index in the Ipopt sparsity structure for the Jacobian of g(x). 
00867         */ 
00868         IndexMap                         index_jac_g_;
00869 
00870         /*!
00871         Mapping from (i, j) in Hessian of fg(x) to Ipopt sparsity structure
00872 
00873         For <tt>i = 0 , ... , n_-1, index_hes_fg_[i]</tt>
00874         is a standard map from column index values \c j to the corresponding
00875         index in the Ipopt sparsity structure for the Hessian of the Lagragian.
00876         */ 
00877         IndexMap                         index_hes_fg_;
00878         // -----------------------------------------------------------------
00879         // Values that are changed by routine other than the constructor:
00880         // -----------------------------------------------------------------
00881 
00882         /// For <tt>k = 0 , ... , K_-1, r_fun_[k]</tt> 
00883         /// is a the CppAD function object corresponding to \f$ r_k (u) \f$.
00884         ADFunVector                      r_fun_;
00885         /*!
00886         Is r_fun[k] OK for current x.
00887  
00888         For <tt>k = 0 , ... , K_-1, tape_ok_[k]</tt> 
00889         is true if current operations sequence in <tt>r_fun_[k]</tt> 
00890         OK for this value of \f$ x \f$. 
00891         Note that \f$ u = [ J_{k,\ell} \otimes n ] (x) \f$ may depend on the
00892         value of \f$ \ell \f$.
00893         */
00894         BoolVector             tape_ok_;
00895 
00896         /// work space of size equal maximum of <tt>q[k]</tt> w.r.t \c k.
00897         SizeVector             J_;
00898         /// work space of size equal maximum of <tt>p[k]</tt> w.r.t \c k.
00899         SizeVector             I_; 
00900         // ------------------------------------------------------------
00901         // Private Methods
00902         // ------------------------------------------------------------
00903         /// block the default constructor from use
00904         cppad_ipopt_nlp(const cppad_ipopt_nlp&);
00905         /// blocks the assignment operator from use
00906         cppad_ipopt_nlp& operator=(const cppad_ipopt_nlp&);
00907 public:
00908         // ----------------------------------------------------------------
00909         // See cppad_ipopt_nlp.hpp for doxygen documentation of these methods
00910         // ----------------------------------------------------------------
00911 
00912         /// only constructor for cppad_ipopot_nlp
00913         cppad_ipopt_nlp(
00914                 size_t n                         , 
00915                 size_t m                         ,
00916                 const NumberVector    &x_i       ,
00917                 const NumberVector    &x_l       ,
00918                 const NumberVector    &x_u       ,
00919                 const NumberVector    &g_l       ,
00920                 const NumberVector    &g_u       ,
00921                 cppad_ipopt_fg_info*   fg_info   ,
00922                 cppad_ipopt_solution*  solution
00923         );
00924 
00925         // use virtual so that derived class destructor gets called.
00926         virtual ~cppad_ipopt_nlp();
00927 
00928         // return info about the nlp
00929         virtual bool get_nlp_info(
00930                 Index&          n           , 
00931                 Index&          m           , 
00932                 Index&          nnz_jac_g   ,
00933                 Index&          nnz_h_lag   , 
00934                 IndexStyleEnum& index_style
00935         );
00936 
00937         // return bounds for my problem 
00938         virtual bool get_bounds_info(
00939                 Index           n   , 
00940                 Number*         x_l , 
00941                 Number*         x_u ,
00942                 Index           m   , 
00943                 Number*         g_l , 
00944                 Number*         g_u   
00945         );
00946 
00947         // return the starting point for the algorithm 
00948         virtual bool get_starting_point(
00949                 Index          n            , 
00950                 bool           init_x       , 
00951                 Number*        x            ,
00952                 bool           init_z       , 
00953                 Number*        z_L          , 
00954                 Number*        z_U          ,
00955                 Index          m            ,
00956                 bool           init_lambda  ,
00957                 Number*        lambda
00958         );
00959 
00960         // return the objective value 
00961         virtual bool eval_f(
00962                 Index          n           , 
00963                 const Number*  x           , 
00964                 bool           new_x       , 
00965                 Number&        obj_value
00966         );
00967 
00968         // Method to return the gradient of the objective 
00969         virtual bool eval_grad_f(
00970                 Index          n           , 
00971                 const Number*  x           , 
00972                 bool           new_x       , 
00973                 Number*        grad_f
00974         );
00975 
00976         // return the constraint residuals
00977         virtual bool eval_g(
00978                 Index          n           , 
00979                 const Number*  x           , 
00980                 bool           new_x       , 
00981                 Index          m           , 
00982                 Number*        g
00983         );
00984 
00985         // Method to return:
00986         // 1) The structure of the jacobian (if "values" is NULL)
00987         // 2) The values of the jacobian (if "values" is not NULL)
00988         virtual bool eval_jac_g(
00989                 Index          n           , 
00990                 const Number*  x           , 
00991                 bool           new_x       ,
00992                 Index          m           , 
00993                 Index          nele_jac    , 
00994                 Index*         iRow        , 
00995                 Index*         jCol        ,
00996                 Number*        values
00997         );
00998 
00999         // Method to return:
01000         //  1) structure of hessian of the lagrangian (if "values" is NULL)
01001         //  2) values of hessian of the lagrangian (if "values" is not NULL)
01002         virtual bool eval_h(
01003                 Index          n           , 
01004                 const Number*  x           , 
01005                 bool           new_x       ,
01006                 Number         obj_factor  , 
01007                 Index          m           , 
01008                 const Number*  lambda      ,
01009                 bool           new_lambda  , 
01010                 Index          nele_hess   , 
01011                 Index*         iRow        ,
01012                 Index*         jCol        , 
01013                 Number*        values
01014         );
01015 
01016         // called when the algorithm is completed so the TNLP can 
01017         // store/write the solution 
01018         virtual void finalize_solution(
01019                 Ipopt::SolverReturn       status      ,
01020                 Index                      n          , 
01021                 const Number*              x          , 
01022                 const Number*              z_L        , 
01023                 const Number*              z_U        ,
01024                 Index                      m          , 
01025                 const Number*              g          , 
01026                 const Number*              lambda     ,
01027                 Number                     obj_value  ,
01028                 const Ipopt::IpoptData*           ip_data    ,
01029                 Ipopt::IpoptCalculatedQuantities* ip_cq
01030         );
01031 
01032         virtual bool intermediate_callback(
01033                 Ipopt::AlgorithmMode              mode,
01034                 Index                             iter, 
01035                 Number                            obj_value,
01036                 Number                            inf_pr, 
01037                 Number                            inf_du,
01038                 Number                            mu, 
01039                 Number                            d_norm,
01040                 Number                            regularization_size,
01041                 Number                            alpha_du, 
01042                 Number                            alpha_pr,
01043                 Index                             ls_trials,
01044                 const Ipopt::IpoptData*           ip_data,
01045                 Ipopt::IpoptCalculatedQuantities* ip_cq
01046         );
01047 
01048 };
01049 
01050 
01051 
01052 # endif