Changeset 483
 Timestamp:
 Aug 24, 2005 9:58:21 AM (14 years ago)
 File:

 1 edited
Legend:
 Unmodified
 Added
 Removed

branches/dev/Docs/documentation.tex
r478 r483 1 1 %% Copyright (C) 2005, Carnegie Mellon University and others. 2 2 %% 3 %% The first version of this file swas contributed to the Ipopt project3 %% The first version of this file was contributed to the Ipopt project 4 4 %% on Aug 1, 2005, by Yoshiaki Kawajiri 5 5 %% Department of Chemical Engineering 6 6 %% Carnegie Mellon University 7 7 %% Pittsburgh, PA 15213 8 %% 9 %% Since then, the content of this file has been updated significantly by 10 %% Carl Laird and Andreas Waechter IBM 8 11 %% 9 12 \documentclass[letter,10pt]{article} … … 15 18 \renewcommand{\baselinestretch}{1.1} 16 19 \usepackage{amsfonts} 20 \usepackage{amsmath} 17 21 18 22 \newcommand{\RR}{{\mathbb{R}}} 23 \newcommand{\Ipopt}{{\sc Ipopt}} 19 24 20 25 21 26 \begin{document} 22 \title{Introduction to Ipopt:\\ 23 A tutorial for downloading, installing, and using Ipopt.} 24 25 \author{Yoshiaki 26 Kawajiri\footnote{Department of Chemical Engineering, Carnegie Mellon 27 University, Pittsburgh, PA, 15213, Email: kawajiri@cmu.edu}, Carl 28 D. Laird\footnote{Department of Chemical Engineering, Carnegie Mellon 29 University, Pittsburgh, PA, 15213, Email: kawajiri@cmu.edu}} 27 \title{Introduction to \Ipopt:\\ 28 A tutorial for downloading, installing, and using \Ipopt.} 29 30 \author{Yoshiaki Kawajiri\footnote{Department of Chemical Engineering, 31 Carnegie Mellon University, Pittsburgh, PA 15213, USA}, Carl D. 32 Laird\footnote{Department of Chemical Engineering, Carnegie Mellon 33 University, Pittsburgh, PA 15213, USA}, Andreas 34 W\"achter\footnote{Department of Mathematical Sciences, IBM 35 T.J.~Watson Research Center, Yorktown Heights, NY 10598, USA}} 30 36 31 37 %\date{\today} … … 35 41 36 42 \section{Overview} 37 Ipopt (\underline{I}nterior \underline{P}oint \underline{Opt}imizer) is an open 38 source software package for largescale nonlinear optimization. It can 39 be used to solve general nonlinear programming problems of the form 43 \Ipopt\ (\underline{I}nterior \underline{P}oint \underline{Opt}imizer, 44 pronounced ``IPOpt'') is an open source software package for 45 largescale nonlinear optimization. It can be used to solve general 46 nonlinear programming problems of the form 47 %\begin{subequations}\label{NLP} 40 48 \begin{eqnarray} 41 \min_{x } &&f(x) \label{obj} \\49 \min_{x\in\RR^n} &&f(x) \label{eq:obj} \\ 42 50 \mbox{s.t.} \; &&g^L \leq g(x) \leq g^U \\ 43 &&x^L \leq x \leq x^U, \label{ bounds}51 &&x^L \leq x \leq x^U, \label{eq:bounds} 44 52 \end{eqnarray} 53 %\end{subequations} 45 54 where $x \in \RR^n$ are the optimization variables (possibly with 46 55 lower and upper bounds, $x^L\in(\RR\cup\{\infty\})^n$ and … … 48 57 objective function, and $g:\RR^n\longrightarrow \RR^m$ are the general 49 58 nonlinear constraints. The functions $f(x)$ and $g(x)$ can be linear 50 or nonlinear and convex or nonconvex (but are assumed tobe twice59 or nonlinear and convex or nonconvex (but should be twice 51 60 continuously differentiable). The constraints, $g(x)$, have lower and 52 61 upper bounds, $g^L\in(\RR\cup\{\infty\})^n$ and 53 62 $g^U\in(\RR\cup\{+\infty\})^m$. Note that equality constraints of the 54 form $g_i(x)=\bar g_i$ can be specified by setting $g^L_{i}=g^U_{i}=\bar g_i$. 55 56 Ipopt implements an interior point line search filter method. The 57 mathematical details of the algorithm can be found in the reports 58 \cite{AndreasPaper} \cite{AndreasThesis}. 59 60 The Ipopt package is available from COINOR\cite{COINORWeb} under the 61 opensource CPL license and includes the complete source code for 62 Ipopt. The Ipopt distribution generates an executable for different 63 modeling environments, including AMPL. As well, you can link your 64 problem statement with Ipopt using interfaces for Fortran, C, or 65 C++. Ipopt can be used with most Linux/Unix environments, and on 66 Windows using Visual Studio .NET or Cygwin. The purpose of this 67 document is to demonstrate how to solve problems using Ipopt. This 68 includes installation and compilation of Ipopt for use with AMPL as 69 well as linking with your own code. General questions related to Ipopt 70 should be addressed to Ipopt mailing list ({\tt 71 http://list.coinor.org/mailman/listinfo/coinipopt}). You might want 72 to look at the archives before posting a question. 73 74 \section{History of Ipopt} 75 The original Ipopt (Fortran version) was a product of the dissertation 76 research of Andreas W\"achter \cite{AndreasThesis}, under Lorenz 63 form $g_i(x)=\bar g_i$ can be specified by setting 64 $g^L_{i}=g^U_{i}=\bar g_i$. 65 66 \Ipopt\ implements an interior point line search filter method that 67 aims to find a local solution of (\ref{eq:obj}\ref{eq:bounds}). The mathematical details 68 of the algorithm can be found in several publications 69 \cite{NocWaeWal:adaptive,WaechterPhD,WaeBie:IpoptImpl,WaeBie05:filterglobal,WaeBie05:filterlocal}. 70 71 The \Ipopt\ package is available from COINOR 72 (\texttt{www.coinor.org}) under the CPL (Common Public 73 License) opensource license and includes the source code for \Ipopt. 74 In order to build \Ipopt, some third party components are required 75 (see Section~\ref{ExternalCode}). 76 77 If desired, the \Ipopt\ distribution generates an executable for the 78 modeling environments AMPL. As well, you can link your problem 79 statement with \Ipopt\ using interfaces for Fortran, C, or C++. 80 \Ipopt\ can be used with most Linux/Unix environments, and on Windows 81 using Visual Studio .NET or Cygwin. The purpose of this document is 82 to demonstrate how to solve problems using \Ipopt. This includes 83 installation and compilation of \Ipopt\ for use with AMPL as well as 84 linking with your own code. 85 86 More information might be found on the \Ipopt\ home page at 87 \texttt{http://projects.coinor.org/Ipopt}. General questions related 88 to \Ipopt\ should be addressed to \Ipopt\ mailing list\footnote{\tt 89 http://list.coinor.org/mailman/listinfo/coinipopt}. You might 90 want to look at the archives before posting a question. 91 92 \section{History of \Ipopt} 93 The original \Ipopt\ (Fortran version) was a product of the dissertation 94 research of Andreas W\"achter \cite{WaechterPhD}, under Lorenz 77 95 T. Biegler at the Chemical Engineering Department at Carnegie Mellon 78 96 University. The code was made open source and distributed by the 79 COINOR initiative, which is now a nonprofit corporation. Ipopthas97 COINOR initiative, which is now a nonprofit corporation. \Ipopt\ has 80 98 been actively developed under COINOR since 2002. 81 99 82 100 To continue natural extension of the code and allow easy addition of 83 101 new features, IBM Research decided to invest in an open source 84 rewrite of Ipopt in C++. The new C++ version of the Ipopt85 optimization code ( Ipopt3.0 and beyond) is currently developed at IBM102 rewrite of \Ipopt\ in C++. The new C++ version of the \Ipopt\ 103 optimization code (\Ipopt\ 3.0 and beyond) is currently developed at IBM 86 104 Research and remains part of the COINOR initiative. Future 87 105 development on the Fortran version will cease with the exception of 88 106 occasional bug fix releases. 89 107 90 This document is a guide to using Ipopt 3.0 (the new C++ version of Ipopt). 91 92 %\section{Interfacing to Ipopt} 93 94 \section{Getting the Code} 95 Ipopt is available from the COINOR subversion repository. You can 96 either download the code using svn (the subversion client similar to 97 cvs) or simply retrieve the tarball (at the writing of this document, 98 the tarballs were not available, therefore, directions only include 99 use of svn). While the tarball is an easy method to retrieve the 100 code, using the subversion system allows users the benefits of the 101 version control system, including easy updates and revision 102 control. 103 104 To use subversion, follow the steps below: 108 This document is a guide to using \Ipopt\ 3.0 (the new C++ version of \Ipopt). 109 110 \section{Installing \Ipopt}\label{Installing} 111 112 The following sections describe the installation procedures on 113 UNIX/Linux systems. For installation instructions on Windows 114 see Section~\ref{WindowsInstall}. 115 116 \subsection{Getting the \Ipopt\ Code} 117 \Ipopt\ is available from the COINOR subversion repository. You can 118 either download the code using \texttt{svn} (the 119 \textit{subversion}\footnote{see 120 \texttt{http://subversion.tigris.org/}} client similar to CVS) or 121 simply retrieve a tarball (compressed archive file). While the 122 tarball is an easy method to retrieve the code, using the 123 \textit{subversion} system allows users the benefits of the version 124 control system, including easy updates and revision control. 125 126 \subsubsection{Getting the \Ipopt\ code via subversion} 127 128 Of course, the \textit{subversion} client must be installed on your 129 system if you want to obtain the code this way (the executable it 130 called \texttt{svn}). Information about \textit{subversion} and how 131 to download it can be found at \texttt{http://subversion.tigris.org/}.\\ 132 133 To obtain the \Ipopt\ source code via subversion, follow the steps 134 below: 105 135 \begin{enumerate} 106 136 \item{Create a directory to store the code}\\ … … 109 139 prompt, do not type {\tt \$}, only the text following it. 110 140 \item{Download the code to the new directory}\\ 111 {\tt \$ cd Ipopt; svn co https://www.coinor.org/svn/ipoptdevel/trunk} 141 {\tt \$ cd Ipopt\\ 142 \$ svn co https://www.coinor.org/svn/Ipopt/trunk} 143 \item Change into the root directory of the \Ipopt\ distribution\\ 144 {\tt \$ cd trunk} 112 145 \end{enumerate} 113 146 114 \subsection{Download External Code} 115 Ipopt uses a few external packages that are not included in the 116 distribution, namely ASL (the Ampl Solver Library), BLAS, and 117 some routines from the Harwell Subroutine Library. 118 119 Note that you only need to obtain the ASL if you intend to use Ipopt 147 In the following, ``\texttt{\$IPOPTDIR}'' will refer to the directory in 148 which you are right now (output of \texttt{pwd}). 149 150 \subsubsection{Getting the \Ipopt\ code as tarball} 151 152 To use the tarball, follow the steps below: 153 \begin{enumerate} 154 \item Download the latest tarball from 155 \texttt{http://www.coinor.org/Tarballs}. The file you should look 156 for has the form \texttt{ipopt3.x.x.tar.gz} (where 157 ``\texttt{3.x.x.}'' is the version number). Put this file in a 158 directory under which you want to put the \Ipopt\ installation. 159 \item Issue the following commands to unpack the archive file: \\ 160 \texttt{\$ gunzip ipopt3.x.x.tar.gz} \\ 161 \texttt{\$ tar xvf ipopt3.x.x.tar} \\ 162 Note the {\tt \$} indicates the command line 163 prompt, do not type {\tt \$}, only the text following it. 164 \item Change into the root directory of the \Ipopt\ distribution\\ 165 {\tt \$ cd ipopt3.x.x} 166 \end{enumerate} 167 168 In the following, ``\texttt{\$IPOPTDIR}'' will refer to the directory in 169 which you are right now (output of \texttt{pwd}). 170 171 \subsection{Download External Code}\label{ExternalCode} 172 \Ipopt\ uses a few external packages that are not included in the 173 distribution, namely ASL (the Ampl Solver Library), BLAS, and some 174 sparse linear algebra routines from the Harwell Subroutine Library. 175 176 Note that you only need to obtain the ASL if you intend to use \Ipopt\ 120 177 from AMPL. It is not required if you want to specify yout 121 178 optimization problem in a programming language (C++, C, or Fortran). … … 125 182 system, retrieving ASL, and BLAS is straightforward using scripts 126 183 included with the ipopt distribution. These scripts download the 127 required files from the Netlib Repository ( http://www.netlib.org).\\184 required files from the Netlib Repository (\texttt{www.netlib.org}).\\ 128 185 129 186 \noindent 130 {\tt \$ cd trunk/ipopt/Extern/blas; ./get.blas}\\ 131 {\tt \$ cd ../ASL; ./get.asl}\\ 187 {\tt \$ cd \$IPOPTDIR/Extern/blas}\\ 188 {\tt \$ ./get.blas}\\ 189 {\tt \$ cd ../ASL}\\ 190 {\tt \$ ./get.asl}\\ 132 191 133 192 \noindent 134 193 If you don't have \texttt{wget} installed on your system, please read 135 the \texttt{INSTALL.*} files in the \texttt{ trunk/ipopt/Extern/blas}136 and \texttt{ trunk/ipopt/Extern/ASL} directories for alternative194 the \texttt{INSTALL.*} files in the \texttt{\$IPOPTDIR/Extern/blas} 195 and \texttt{\$IPOPTDIR/Extern/ASL} directories for alternative 137 196 instructions. 138 197 … … 144 203 third party code. 145 204 \begin{enumerate} 146 \item{Go to {\tt http://hsl.rl.ac.uk/archive/hslarchive.html}} 147 \item{Follow the instruction on the website, and submit the registration form.} 148 \item{Go to \textit{HSL Archive Programs}, and find the package list.} 149 \item{In your browser window, click on \textit{MA27}.} 150 \item{Make sure that \textit{Double precision:} is checked. 151 Click \textit{Download package (comments removed)}} 152 \item{Save the file as {\tt ma27ad.f} in {\tt ipopt/trunk/Extern/HSL/}}\\ 153 Note: Some browsers append a file extension ({\tt .txt}) when you save 154 the file, so you may have to rename it. 155 \item{Go back to the package list using the back button of your browser.} 156 \item{In your browser window, click on \textit{MC19}.} 157 \item{Make sure \textit{Double precision:} is checked. Click 158 \textit{Download package (comments removed)}} 159 \item{Save the file as {\tt mc19ad.f} in {\tt 160 ipopt/trunk/Extern/HSL/}}\\ 161 Note: Some browsers append a file extension ({\tt .txt}) when you save 162 the file, so you may have to rename it. 205 \item Go to {\tt http://hsl.rl.ac.uk/archive/hslarchive.html} 206 \item Follow the instruction on the website, read the license, and 207 submit the registration form. 208 \item Go to \textit{HSL Archive Programs}, and find the package list. 209 \item In your browser window, click on \textit{MA27}. 210 \item Make sure that \textit{Double precision:} is checked. 211 Click \textit{Download package (comments removed)} 212 \item Save the file as {\tt ma27ad.f} in {\tt \$IPOPTDIR/Extern/HSL/}\\ 213 Note: Some browsers append a file extension ({\tt .txt}) when you save 214 the file, so you may have to rename it. 215 \item Go back to the package list using the back button of your browser. 216 \item In your browser window, click on \textit{MC19}. 217 \item Make sure \textit{Double precision:} is checked. Click 218 \textit{Download package (comments removed)} 219 \item Save the file as {\tt mc19ad.f} in {\tt 220 \$IPOPTDIR/Extern/HSL/}\\ 221 Note: Some browsers append a file extension ({\tt .txt}) when you save 222 the file, so you may have to rename it. 163 223 \end{enumerate} 164 224 165 225 166 \section{Compiling and Installing Ipopt} \label{sec.comp_and_inst} 167 Ipopt can be easily compiled and installed with the usual {\tt configure}, 168 {\tt make}, {\tt make install} commands. 226 \subsection{Compiling and Installing \Ipopt} \label{sec.comp_and_inst} 227 228 \Ipopt\ can be easily compiled and installed with the usual {\tt 229 configure}, {\tt make}, {\tt make install} commands. Below are the 230 basic steps that should work on most systems. For special 231 compilations and some for troubleshooting see 232 Appendix~\ref{ExpertInstall} and consult the \Ipopt\ webpage before 233 sending a message to the mailing list. 169 234 \begin{enumerate} 170 \item{Go to the main directory of Ipopt:\\ 171 {\tt \$ cd; cd ipopt/trunk}} 172 \item{Run the configure script}\\ 173 {\tt \$ ./configure}\\ 174 The default configure (without any options) is 175 sufficient for most users. If you want to see the configure options, 176 run {\tt ./configure help}. 177 \item{Build the code}\\ 235 \item Go to the main directory of \Ipopt:\\ 236 {\tt \$ cd \$IPOPTDIR} 237 \item Run the configure script\\ 238 {\tt \$ ./configure} 239 240 If the last output line of the script reads ``\texttt{configure: 241 Configuration successful}'' then everything worked fine. 242 Otherwise, look at the screen output, have a look at the 243 \texttt{config.log} output file and/or consult 244 Appendix~\ref{ExpertInstall}. 245 246 The default configure (without any options) is sufficient for most 247 users. If you want to see the configure options, consult 248 Appendix~\ref{ExpertInstall}. 249 \item Build the code \\ 178 250 {\tt \$ make} 179 \item{Install Ipopt}\\ 180 {\tt \$ make install}\\ 181 This installs the the ipopt library and 182 necessary header files to ?...? 183 \item{Test the installation}\\ 184 {\tt \$ make test}\\ 185 This should ?...? 251 \item Install \Ipopt \\ 252 {\tt \$ make install}\\ 253 This installs 254 \begin{itemize} 255 \item the \Ipopt\ AMPL solver executable (if ASL source was 256 downloaded) in \texttt{\$IPOPTDIR/bin}, 257 \item the \Ipopt\ library (\texttt{libipopt.a}) in 258 \texttt{\$IPOPTDIR/lib}, 259 \item and the necessary header files in 260 \texttt{\$IPOPTDIR/include/ipopt}. 261 \end{itemize} 262 You can change the default installation directory (here 263 \texttt{\$IPOPTDIR}) to something else (such as \texttt{/usr/local}) 264 by using the \texttt{prefix} switch for \texttt{configure}. 265 %\item Test the installation \\ 266 % {\tt \$ make test}\\ 267 % This should ?...? 186 268 \end{enumerate} 187 269 188 \section{Interfacing your NLP to Ipopt: A tutorial example.} 189 Ipopt has been designed to be flexible for a wide variety of 190 applications, and there are a number of ways to interface with Ipopt 270 \subsection{Installation on Windows}\label{WindowsInstall} 271 272 There are two ways to install \Ipopt\ on Windows systems. The first 273 option, described in ection~\ref{CygwinInstall}, is to use Cygwin (see 274 \texttt{www.cygwin.com}), which offers a UNIXlike environment 275 on Windows and in which the installation procedure described earlier 276 in this section can be used. The \Ipopt\ distribution also includes 277 projects files for the Microsoft Visual Studio (see 278 Section~\ref{VisualStudioInstall}). 279 280 \subsubsection{Installation with Cygwin}\label{CygwinInstall} 281 282 Cygwin is a Linuxlike environment for Windows; if you don't know what 283 it is you might want to have a look at the Cygwin homepage, 284 \texttt{www.cygwin.com}. 285 286 It is possible to build the \Ipopt\ AMPL solver executable in Cygwin 287 for general use in Windows. You can also hook up \Ipopt\ to your own 288 program if you compile it in the Cygwin environment\footnote{It might 289 also be possible to build an \Ipopt\ DLL that can be used from 290 noncygwin compilers, but this is not (yet?) supported.}. 291 292 If you want to compile \Ipopt\ under Cygwin, you first have to install 293 Cygwin in your Windows system. This is pretty straight forward; you 294 simply download the ``setup'' program from 295 \texttt{www.cygwin.com} and start it. 296 297 Then you do the following steps (assuming here that you don't have any 298 complications with firewall settings etc  in that case you might have 299 to choose some connection settings differently): 300 301 \begin{enumerate} 302 \item Click next 303 \item Select ``install from the internet'' (default) and click next 304 \item Select a directory where Cygwin is to be installed (you can 305 leave the default) and choose all other things to your liking, then 306 click next 307 \item Select a temp dir for Cygwin setup to store some files (if you 308 put it on your desktop you will later remember to delete it) 309 \item Select ``direct connection'' (default) and click next 310 \item Select some mirror site that seems close by to you and click next 311 \item OK, now comes the complicated part:\\ 312 You need to select the packages that you want to have installed. By 313 default, there are already selections, but the compilers are usually 314 not prechosen. You need to make sure that you select the GNU 315 compilers (for Fortran, C, and C++  together with the MinGW 316 options), the GNU Make, and Subversion. For this, click on the "Devel" 317 branch (which opens a subtree) and select: 318 \begin{itemize} 319 \item gcc 320 \item gcccore 321 \item gccg77 322 \item gccg++ 323 \item gccmingw 324 \item gccmingwcore 325 \item gccmingwg77 326 \item gccmingwg++ 327 \item make 328 \item subversion 329 \end{itemize} 330 331 Then, in the ``Web'' branch, please select ``wget'' (which will make 332 the installation of third party dependencies for \Ipopt\ easier) 333 334 This will automatically also select some other packages. 335 \item Then you click on next, and Cygwin will be installed (follow the 336 rest of the instructions and choose everything else to your liking). 337 At a later point you can easily add/remove packages with the setup 338 program. 339 340 \item Now that you have Cygwin, you can open a Cygwin window, which is 341 like a UNIX shell window. 342 343 \item Now you just follow the instructions in the beginning of 344 Sections~\ref{Installing}: You download the \Ipopt\ code into 345 your Cygwin home directory (from the Windows explorer that is 346 usually something like 347 \texttt{C:$\backslash$Cygwin$\backslash$home$\backslash$your\_user\_name}). 348 After that you obtain the third party code (like on Linux/UNIX), 349 type 350 351 \texttt{./configure CXX=g++ CC=gcc F77=g77} 352 353 and 354 355 \texttt{make install} 356 357 in the correct directories, and hopefully that will work. The 358 \Ipopt\ AMPL solver executable will be in the subdirectory 359 \texttt{bin} (called ``\texttt{ipopt.exe}''). 360 \end{enumerate} 361 362 \subsubsection{Using the Visual Studio}\label{VisualStudioInstall} 363 364 The \Ipopt\ distribution includes project files that can be used to 365 compile the \Ipopt\ library and a Fortran and C++ example within the 366 Microsoft Visual Studio. The project files have been created with 367 Microsoft Visual C++ .NET 2003 Standard, and the Intel Visual Fortran 368 Compiler 8. 369 370 In order to use those project files, download the \Ipopt\ source code, 371 as well as the required third party code (put it into the Extern/blas 372 and Extern/HSL directoriesASL is not required for the Fortran and C 373 examples). Then open the solution file\\ 374 375 \texttt{\$IPOPTDIR$\backslash$Windows$\backslash$VisualStudio\_dotNET$\backslash$Ipopt$\backslash$Ipopt.sln}\\ 376 377 Note: Since the project files were created only with the Standard 378 edition of the C++ compiler, code optimization might be disabled; for 379 fast performance make sure you enable code optimization. 380 381 \section{Interfacing your NLP to \Ipopt: A tutorial example.} 382 383 \Ipopt\ has been designed to be flexible for a wide variety of 384 applications, and there are a number of ways to interface with \Ipopt\ 191 385 that allow specific data structures and linear solver 192 386 techniques. Nevertheless, the authors have included a standard 193 387 representation that should meet the needs of most users. 194 388 195 This tutorial will discuss four interfaces to Ipopt, namely the AMPL389 This tutorial will discuss four interfaces to \Ipopt, namely the AMPL 196 390 modeling language interface, and the C, C++, and Fortran code 197 391 interfaces. AMPL is a 3rd party modeling language tool that allows … … 204 398 205 399 We will illustrate how to use each of the four interfaces using an 206 example problem, number 71 from the HockSchittkowsky test suite, 207 \begin{eqnarray} 208 \min_{x \in \Re^4} &x_1 x_4 (x_1 + x_2 + x_3) + x_3 \label{ex_obj} \\ 209 \mbox{s.t.} \; &x_1 x_2 x_3 x_4 \ge 25 \label{ex_ineq} \\ 210 &x_1^2 + x_2^2 + x_3^2 + x_4^2 = 40 \label{ex_equ} \\ 211 &1 \leq x_1, x_2, x_3, x_4 \leq 5, \label{ex_bounds} 212 \end{eqnarray} 213 with the starting point, 400 example problem, number 71 from the HockSchittkowsky test suite \cite{HS}, 401 %\begin{subequations}\label{HS71} 402 \begin{eqnarray} 403 \min_{x \in \Re^4} &x_1 x_4 (x_1 + x_2 + x_3) + x_3 \label{eq:ex_obj} \\ 404 \mbox{s.t.} \; &x_1 x_2 x_3 x_4 \ge 25 \label{eq:ex_ineq} \\ 405 &x_1^2 + x_2^2 + x_3^2 + x_4^2 = 40 \label{eq:ex_equ} \\ 406 &1 \leq x_1, x_2, x_3, x_4 \leq 5, \label{eq:ex_bounds} 407 \end{eqnarray} 408 %\end{subequations} 409 with the starting point 214 410 \begin{equation} 215 x {=} (1, 5, 5, 1) \label{e x_startpt}411 x {=} (1, 5, 5, 1) \label{eq:ex_startpt} 216 412 \end{equation} 217 and the optimal solution ,413 and the optimal solution 218 414 \[ 219 415 x^\star {=} (1.00000000, 4.74299963, 3.82114998, 1.37940829). \nonumber 220 416 \] 221 417 222 \s ection{Tutorial Example:Using the AMPL interface}418 \subsection{Using the AMPL interface} 223 419 Interfacing through the AMPL interface is by far the easiest way to 224 solve a problem with Ipopt. The user must simply formulate the problem420 solve a problem with \Ipopt. The user must simply formulate the problem 225 421 in AMPL syntax, and solve the problem through the AMPL environment. 226 422 There are drawbacks, however. AMPL is a 3rd party package and, as 227 423 such, must be appropriately licensed (a free, student version for 228 424 limited problem size is available from the AMPL website, 229 www.ampl.com). Furthermore, the AMPL environment may be prohibitive425 \texttt{www.ampl.com}). Furthermore, the AMPL environment may be prohibitive 230 426 for very large problems. Nevertheless, formulating the problem in AMPL 231 427 is straightforward and even for large problems, it is often used as a … … 234 430 This tutorial is not intended as a guide to formulating models in 235 431 AMPL. If you are not already familiar with AMPL, please consult 236 \cite{AMPL_REFERENCE}. 237 238 The problem presented in equations (\ref{ex_obj}\ref{ex_startpt}) can 239 be solved with Ipopt with the following AMPL mod file. 240 \subsubsection{hs071\_ampl.mod} 432 \cite{FouGayKer:AMPLbook}. 433 434 The problem presented in equations 435 (\ref{eq:ex_obj})(\ref{eq:ex_startpt}) can be solved with \Ipopt\ with 436 the AMPL model file given in Figure~\ref{fig:HS71}. 437 438 \begin{figure} 439 \centering 440 \begin{footnotesize} 241 441 \begin{verbatim} 242 442 # tell ampl to use the ipopt executable as a solver … … 257 457 # specify the constraints 258 458 s.t. 259 260 459 inequality: 261 460 x1 * x2 * x3 * x4 >= 25; … … 279 478 display x4; 280 479 \end{verbatim} 281 282 The line, "{\tt option solver ipopt;}" tells ampl to use ipopt as the 283 solver. The ipopt executable (installed in Section 284 {\ref{sec.comp_and_inst}) must be in the path for AMPL to find it. The 285 remaining lines specify the problem in AMPL format. The problem can 286 now be solved by starting ampl and loading the mod file. 480 \end{footnotesize} 481 482 \caption{AMPL model file hs071\_ampl.mod} 483 \label{fig:HS71} 484 \end{figure} 485 486 The line, ``{\tt option solver ipopt;}'' tells AMPL to use \Ipopt\ as 487 the solver. The \Ipopt\ executable (installed in 488 Section~\ref{sec.comp_and_inst}) must be in the path for AMPL to find 489 it. The remaining lines specify the problem in AMPL format. The 490 problem can now be solved by starting AMPL and loading the mod file: 287 491 \begin{verbatim} 288 492 $ ampl … … 293 497 \end{verbatim} 294 498 %$ 295 The problem will be solved using Ipoptand the solution will be499 The problem will be solved using \Ipopt\ and the solution will be 296 500 displayed. 297 501 298 502 At this point, AMPL users may wish to skip the sections about 299 503 interfacing with code, but should read Section \ref{sec.options} 300 concerning Ipoptoptions, and Section \ref{sec.ipopt_output} which301 explains the output displayed by ipopt.302 303 \s ection{Tutorial Example: Interfacing with Ipoptthrough code}304 In order to solve a problem, Ipoptneeds more information than just504 concerning \Ipopt\ options, and Section \ref{sec.ipopt_output} which 505 explains the output displayed by \Ipopt. 506 507 \subsection{Interfacing with \Ipopt\ through code} 508 In order to solve a problem, \Ipopt\ needs more information than just 305 509 the problem definition (for example, the derivative information). If 306 510 you are using a modeling language like AMPL, the extra information is 307 provided by the modeling tool and the Ipoptinterface. When308 interfacing with Ipoptthrough your own code, however, you must511 provided by the modeling tool and the \Ipopt\ interface. When 512 interfacing with \Ipopt\ through your own code, however, you must 309 513 provide this additional information. 310 514 311 515 \begin{figure} 312 \caption{Information Required By Ipopt}313 516 \begin{enumerate} 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 Information evaluated using a given point339 ($x_k, \lambda_k, \sigma_f$ coming fromIpopt)340 341 342 343 344 345 346 347 517 \item Problem dimensions \label{it.prob_dim} 518 \begin{itemize} 519 \item number of variables 520 \item number of constraints 521 \end{itemize} 522 \item Problem bounds 523 \begin{itemize} 524 \item variable bounds 525 \item constraint bounds 526 \end{itemize} 527 \item Initial starting point 528 \begin{itemize} 529 \item Initial values for the primal $x$ variables 530 \item Initial values for the multipliers (only 531 required for a warm start option) 532 \end{itemize} 533 \item Problem Structure \label{it.prob_struct} 534 \begin{itemize} 535 \item number of nonzeros in the Jacobian of the constraints 536 \item number of nonzeros in the Hessian of the Lagrangian 537 \item Structure of the Jacobian of the constraints 538 \item Structure of the Hessian of the Lagrangian 539 \end{itemize} 540 \item Evaluation of Problem Functions \label{it.prob_eval} \\ 541 Information evaluated using a given point ($x_k, 542 \lambda_k, \sigma_f$ coming from \Ipopt) 543 \begin{itemize} 544 \item Objective function, $f(x_k)$ 545 \item Gradient of the objective $\nabla f(x_k)$ 546 \item Constraint residuals, $g(x_k)$ 547 \item Jacobian of the constraints, $\nabla g(x_k)$ 548 \item Hessian of the Lagrangian, 549 $\sigma_f \nabla^2 f(x_k) + \sum_{i=1}^m\lambda_i\nabla^2 g_i(x_k)$ 550 \end{itemize} 348 551 \end{enumerate} 552 \caption{Information Required By \Ipopt} 349 553 \label{fig.required_info} 350 554 \end{figure} 351 \vspace{0.1in}352 The information required by Ipoptis shown in Figure555 %\vspace{0.1in} 556 The information required by \Ipopt\ is shown in Figure 353 557 \ref{fig.required_info}. The problem dimensions and bounds are 354 558 straightforward and come solely from the problem definition. The 355 559 initial starting point is used by the algorithm when it begins 356 iterating to solve the problem. If Ipopthas difficulty converging, or560 iterating to solve the problem. If \Ipopt\ has difficulty converging, or 357 561 if it converges to a locally infeasible point, adjusting the starting 358 562 point may help. 359 563 360 Providing the problem structure is a bit more involved. Ipoptis a564 Providing the problem structure is a bit more involved. \Ipopt\ is a 361 565 nonlinear programming solver that is designed for solving large scale, 362 sparse problems. While Ipoptcan be customized for a variety of matrix363 formats, atriplet format is used for the standard interfaces in this566 sparse problems. While \Ipopt\ can be customized for a variety of matrix 567 formats, the triplet format is used for the standard interfaces in this 364 568 tutorial. For an overview of the triplet format for sparse matrices, 365 see Appendix \ref{app.triplet}. Before solving the problem, Ipopt569 see Appendix~\ref{app.triplet}. Before solving the problem, \Ipopt\ 366 570 needs to know the number of nonzeros and the structure (row and column 367 571 indices of each of the nonzeros) of the Jacobian and the Hessian. Once … … 371 575 nonzero at the starting point. 372 576 373 As Ipoptiterates, it will need the values for the items in577 As \Ipopt\ iterates, it will need the values for the items in 374 578 (\ref{it.prob_eval}) evaluated at particular points. Before we can 375 579 begin coding the interface, however, we need to work out the details 376 580 of these equations symbolically for example problem 377 (\ref{e x_obj}\ref{ex_bounds}).378 379 The gradient of the objective is given by581 (\ref{eq:ex_obj}\ref{eq:ex_bounds}). 582 583 The gradient of the objective $f(x)$ is given by 380 584 \begin{equation} 381 585 \left[ … … 389 593 \end{equation} 390 594 the Jacobian of 391 the constraints is,595 the constraints $g(x)$ is, 392 596 \begin{equation} 393 597 \left[ … … 401 605 We need to determine the Hessian of the Lagrangian. The Lagrangian is 402 606 given by $f(x) + g(x)^T \lambda$ and the Hessian of the Lagrangian is 403 technically, $ \nabla^2 f(x_k) + sum_{i=1}^m\lambda_i\nabla^2 g_i(x_k)$,404 however, so that Ipoptcan ask for the Hessian of the objective or the607 technically, $ \nabla^2 f(x_k) + \sum_{i=1}^m\lambda_i\nabla^2 g_i(x_k)$. 608 However, so that \Ipopt\ can ask for the Hessian of the objective or the 405 609 constraints independently if required, we introduce a factor 406 610 ($\sigma_f$) in front of the objective term. The value for $\sigma_f$ 407 611 is generally $1$, although it may include scaling factors or even be 408 set to zero to retrieve the Hessian of the constraints alone.612 set to zero to retrieve the Hessians of the constraints alone. 409 613 410 614 For our implementation then, the symbolic form of the Hessian of the 411 Lagrangian (with the $\sigma_f$ parameter) is, 615 Lagrangian 616 \[ 617 \sigma_f \nabla^2 f(x_k) + \sum_{i=1}^m\lambda_i\nabla^2 g_i(x_k) 618 \] 619 (with the $\sigma_f$ parameter) is, 412 620 %\begin{eqnarray} 413 621 %{\cal L}(x,\lambda) &{=}& f(x) + c(x)^T \lambda \nonumber \\ … … 448 656 \right] 449 657 \end{equation} 450 where the first term comes from the Hessian of the objective function, and the451 second and third term from the Hessian of (\ref{ex_ineq}) and (\ref{ex_equ})452 respectively. Therefore, the dual variables $\lambda_1$ and $\lambda_2$ 453 are then the multipliers for constraints (\ref{ex_ineq}) and (\ref{ex_equ}) 454 respectively.658 where the first term comes from the Hessian of the objective function, 659 and the second and third term from the Hessian of (\ref{eq:ex_ineq}) 660 and (\ref{eq:ex_equ}) respectively. Therefore, the dual variables 661 $\lambda_1$ and $\lambda_2$ are then the multipliers for constraints 662 (\ref{eq:ex_ineq}) and (\ref{eq:ex_equ}) respectively. 455 663 456 664 %C ============================================================================= … … 471 679 %C 472 680 %C ============================================================================= 473 474 The remainder of this section of the tutorial will lead you through 681 \vspace{\baselineskip} 682 683 The remaining sections of the tutorial will lead you through 475 684 the coding required to solve example problem 476 (\ref{e x_obj}\ref{ex_bounds}) using, first C++, then C, and finally685 (\ref{eq:ex_obj})(\ref{eq:ex_bounds}) using, first C++, then C, and finally 477 686 Fortran. Completed versions of these examples can be found in {\tt 478 Ipopt/trunk/Examples} under {\tt hs071\_cpp}, {\tt hs071\_c}, {\tt687 \$IPOPTDIR/Examples} under {\tt hs071\_cpp}, {\tt hs071\_c}, {\tt 479 688 hs071\_f}. 480 689 481 690 As a user, you are responsible for coding two sections of the program 482 that solves a problem using Ipopt: the executable ({\tt main}) and the483 problem representation. Generally, you will write an executable that 484 prepares the problem, and then passes control over to Ipopt through an 485 {\tt Optimize} call. In this {\tt Optimize} call, you will give Ipopt 486 everything that it requires to call back to your code whenever it 487 needs functions evaluated (like the objective, the Jacobian, etc.). 488 In each of the three sections that follow (C++, C, and Fortran), we 489 will first discuss how to code the problem representation, and then 490 how to code the executable.691 that solves a problem using \Ipopt: the main executable (e.g., {\tt 692 main}) and the problem representation. Typically, you will write an 693 executable that prepares the problem, and then passes control over to 694 \Ipopt\ through an {\tt Optimize} or {\tt Solve} call. In this call, 695 you will give \Ipopt\ everything that it requires to call back to your 696 code whenever it needs functions evaluated (like the objective, the 697 Jacobian, etc.). In each of the three sections that follow (C++, C, 698 and Fortran), we will first discuss how to code the problem 699 representation, and then how to code the executable. 491 700 492 701 \subsection{The C++ Interface} … … 494 703 language, however, we will lead you through each step of the 495 704 implementation. For the problem representation, we will create a class 496 that inherits off of the pure virtual base class, {\tt TNLP} 497 ({\tt IpTNLP.hpp}). For the executable (the {\tt main} function) we will 498 make the call to Ipopt through the IpoptApplication class 499 (IpIpoptApplication.hpp). In addition, we will also be using the 500 SmartPtr class ({\tt IpSmartPtr.hpp}) which implements a reference counting 501 pointer that takes care of memory management (object deletion) for 502 you. 705 that inherits off of the pure virtual base class, {\tt TNLP} ({\tt 706 IpTNLP.hpp}). For the executable (the {\tt main} function) we will 707 make the call to \Ipopt\ through the {\tt IpoptApplication} class 708 ({\tt IpIpoptApplication.hpp}). In addition, we will also be using the 709 SmartPtr class ({\tt IpSmartPtr.hpp}) which implements a reference 710 counting pointer that takes care of memory management (object 711 deletion) for you. 712 713 After ``\texttt{make install}'' (see Section~\ref{sec.comp_and_inst}), 714 the header files are installed in \texttt{\$IPOPTDIR/include/ipopt} 715 (or in \texttt{\$PREFIX/include/ipopt} if the switch 716 \texttt{prefix=\$PREFIX} was used for {\tt configure}). 503 717 504 718 \subsubsection{Coding the Problem Representation}\label{sec.cpp_problem} … … 506 720 by coding the {\tt HS071\_NLP} class, a specific implementation of the 507 721 {\tt TNLP} base class. In the executable, we will create an instance 508 of the {\tt HS071\_NLP} class and give this class to Ipoptso it can722 of the {\tt HS071\_NLP} class and give this class to \Ipopt\ so it can 509 723 evaluate the problem functions through the {\tt TNLP} interface. If 510 724 you have any difficulty as the implementation proceeds, have a look at 511 the completed example in the {\tt hs071\_cpp} directory.512 513 Start by creating a new directory under Examples, called MyExampleand725 the completed example in the {\tt Example/hs071\_cpp} directory. 726 727 Start by creating a new directory under Examples, called {\tt MyExample} and 514 728 create the files {\tt hs071\_nlp.hpp} and {\tt hs071\_nlp.cpp}. In 515 729 {\tt hs071\_nlp.hpp}, include {\tt IpTNLP.hpp} (the base class), tell 516 the compiler that we are using the Ipoptnamespace, and create the730 the compiler that we are using the \Ipopt\ namespace, and create the 517 731 declaration of the {\tt HS071\_NLP} class, inheriting off of {\tt 518 732 TNLP}. Have a look at the {\tt TNLP} class in {\tt IpTNLP.hpp}; you … … 521 735 {\tt HS071\_NLP.cpp} using the descriptions given below. In {\tt 522 736 hs071\_nlp.cpp}, first include the header file for your class and 523 tell the compiler that you are using the Ipoptnamespace. A full737 tell the compiler that you are using the \Ipopt\ namespace. A full 524 738 version of these files can be found in the {\tt Examples/hs071\_cpp} 525 739 directory. 526 740 527 \paragraph{virtual bool get\_nlp\_info(Index\& n, Index\& m, Index\& nnz\_jac\_g, \\ 528 Index\& nnz\_h\_lag, IndexStyleEnum\& index\_style)} 529 $\;$ \\ 530 Give Ipopt the information about the size of the problem (and hence, 741 \paragraph{Method {\texttt{get\_nlp\_info}}} with Prototype 742 \begin{verbatim} 743 virtual bool get_nlp_info(Index& n, Index& m, Index& nnz_jac_g, 744 Index& nnz_h_lag, IndexStyleEnum& index_style) 745 \end{verbatim} 746 Give \Ipopt\ the information about the size of the problem (and hence, 531 747 the size of the arrays that it needs to allocate). 532 748 \begin{itemize} … … 536 752 \item {\tt nnz\_h\_lag}: (out), the number of nonzero entries in the Hessian. 537 753 \item {\tt index\_style}: (out), the style used for row/col entries in the sparse matrix 538 format ( C\_STYLE: 0based, FORTRAN\_STYLE: 1based).754 format ({\tt C\_STYLE}: 0based, {\tt FORTRAN\_STYLE}: 1based). 539 755 \end{itemize} 540 Ipoptuses this information when allocating the arrays that756 \Ipopt\ uses this information when allocating the arrays that 541 757 it will later ask you to fill with values. Be careful in this method 542 758 since incorrect values will cause memory bugs which may be very … … 552 768 entire problem. 553 769 770 \begin{footnotesize} 554 771 \begin{verbatim} 555 772 bool HS071_NLP::get_nlp_info(Index& n, Index& m, Index& nnz_jac_g, … … 575 792 } 576 793 \end{verbatim} 577 578 \paragraph{virtual bool get\_bounds\_info(Index n, Number* x\_l, Number* x\_u, \\ 579 Index m, Number* g\_l, Number* g\_u)} 580 $\;$ \\ 581 Give Ipopt the value of the bounds on the variables and constraints. 794 \end{footnotesize} 795 796 \paragraph{Method {\texttt{get\_bounds\_info}}} with Prototype 797 \begin{verbatim} 798 virtual bool get_bounds_info(Index n, Number* x_l, Number* x_u, 799 Index m, Number* g_l, Number* g_u) 800 \end{verbatim} 801 Give \Ipopt\ the value of the bounds on the variables and constraints. 582 802 \begin{itemize} 583 803 \item {\tt n}: (in), the number of variables in the problem (dimension of {\tt x}). … … 592 812 lower bound to a value less than or equal to the value of the option 593 813 {\tt nlp\_lower\_bound\_inf} (data member of {\tt TNLP}) will cause 594 Ipoptto assume no lower bound. Likewise, specifying the upper bound814 \Ipopt\ to assume no lower bound. Likewise, specifying the upper bound 595 815 above or equal to the value of the option {\tt nlp\_upper\_bound\_inf} 596 will cause Ipoptto assume no upper bound. These options, {\tt816 will cause \Ipopt\ to assume no upper bound. These options, {\tt 597 817 nlp\_lower\_bound\_inf} and {\tt nlp\_upper\_bound\_inf}, are set to 598 818 $10^{19}$ and $10^{19}$ respectively, by default, but may be modified … … 603 823 the upper bound to some number greater than $10^{19}$. The second 604 824 constraint is an equality constraint and we set both bounds to 605 $40$. Ipoptrecognizes this as an equality constraint and does not825 $40$. \Ipopt\ recognizes this as an equality constraint and does not 606 826 treat it as two inequalities. 607 827 828 \begin{footnotesize} 608 829 \begin{verbatim} 609 830 bool HS071_NLP::get_bounds_info(Index n, Number* x_l, Number* x_u, 610 Index m, Number* g_l, Number* g_u)831 Index m, Number* g_l, Number* g_u) 611 832 { 612 833 // here, the n and m we gave IPOPT in get_nlp_info are passed back to us. … … 640 861 } 641 862 \end{verbatim} 642 643 \paragraph{virtual bool get\_starting\_point(Index n, bool init\_x, Number* x, \\ 644 bool init\_z, Number* z\_L, Number* z\_U, Index m, 645 bool init\_lambda, Number* lambda)} 646 $\;$ \\ 647 Give Ipopt the starting point before it begins iterating. 863 \end{footnotesize} 864 865 \paragraph{Method {\texttt{get\_starting\_point}}} with Prototype 866 \begin{verbatim} 867 virtual bool get_starting_point(Index n, bool init_x, Number* x, 868 bool init_z, Number* z_L, Number* z_U, 869 Index m, bool init_lambda, Number* lambda) 870 \end{verbatim} 871 Give \Ipopt\ the starting point before it begins iterating. 648 872 \begin{itemize} 649 873 \item {\tt n}: (in), the number of variables in the problem (dimension of {\tt x}). … … 665 889 666 890 Depending on the options that have been set, 667 Ipoptmay or may not require bounds for the primal variables $x$, the891 \Ipopt\ may or may not require bounds for the primal variables $x$, the 668 892 bound multipliers $z$, and the equality multipliers $\lambda$. The 669 893 boolean flags {\tt init\_x},{\tt init\_z}, and {\tt init\_lambda} tell … … 677 901 them. 678 902 903 \begin{footnotesize} 679 904 \begin{verbatim} 680 905 bool HS071_NLP::get_starting_point(Index n, bool init_x, Number* x, 681 bool init_z, Number* z_L, Number* z_U,682 Index m, bool init_lambda,683 Number* lambda)906 bool init_z, Number* z_L, Number* z_U, 907 Index m, bool init_lambda, 908 Number* lambda) 684 909 { 685 910 // Here, we assume we only have starting values for x, if you code … … 699 924 } 700 925 \end{verbatim} 701 702 \paragraph{virtual bool eval\_f(Index n, const Number* x, 703 bool new\_x, Number\& obj\_value)} 704 $\;$ \\ 926 \end{footnotesize} 927 928 \paragraph{Method {\texttt{eval\_f}}} with Prototype 929 \begin{verbatim} 930 virtual bool eval_f(Index n, const Number* x, 931 bool new_x, Number& obj_value) 932 \end{verbatim} 705 933 Return the value of the objective function as calculated using {\tt x}. 706 934 \begin{itemize} 707 \item {\tt n}: (in), the number of variables in the problem (dimension of {\tt x}). 708 \item {\tt x}: (in), the current values for the primal variables, {\tt x}. 709 \item {\tt new\_x}: (in), false if any evaluation method was previously called 710 with the same values in {\tt x}, true otherwise. 711 \item {\tt obj\_value}: (out) the value of the objective function ($f(x)$). 935 \item {\tt n}: (in), the number of variables in the problem (dimension 936 of {\tt x}). 937 \item {\tt x}: (in), the current values for the primal variables, {\tt 938 x}. 939 \item {\tt new\_x}: (in), false if any evaluation method was 940 previously called with the same values in {\tt x}, true otherwise. 941 \item {\tt obj\_value}: (out) the value of the objective function 942 ($f(x)$). 712 943 \end{itemize} 713 944 … … 715 946 any of the evaluation methods used the same $x$ values. This can be 716 947 helpful when users have efficient implementations that calculate 717 multiple outputs at once. Ipoptinternally caches results from the948 multiple outputs at once. \Ipopt\ internally caches results from the 718 949 {\tt TNLP} and generally, this flag can be ignored. 719 950 … … 724 955 For our example, we ignore the {\tt new\_x} flag and calculate the objective. 725 956 957 \begin{footnotesize} 726 958 \begin{verbatim} 727 959 bool HS071_NLP::eval_f(Index n, const Number* x, bool new_x, Number& obj_value) … … 734 966 } 735 967 \end{verbatim} 736 737 \paragraph{virtual bool eval\_grad\_f(Index n, const Number* x, bool new\_x, 738 Number* grad\_f)} 739 $\;$ \\ 740 Return the gradient of the objective to Ipopt, as calculated by the values in {\tt x}. 968 \end{footnotesize} 969 970 \paragraph{Method {\texttt{eval\_grad\_f}}} with Prototype 971 \begin{verbatim} 972 virtual bool eval_grad_f(Index n, const Number* x, bool new_x, 973 Number* grad_f) 974 \end{verbatim} 975 Return the gradient of the objective to \Ipopt, as calculated by the values in {\tt x}. 741 976 \begin{itemize} 742 977 \item {\tt n}: (in), the number of variables in the problem (dimension of {\tt x}). … … 755 990 any of the evaluation methods used the same $x$ values. This can be 756 991 helpful when users have efficient implementations that caclulate 757 multiple outputs at once. Ipoptinternally caches results from the992 multiple outputs at once. \Ipopt\ internally caches results from the 758 993 {\tt TNLP} and generally, this flag can be ignored. 759 994 … … 764 999 In our example, we ignore the {\tt new\_x} flag and calculate the 765 1000 values for the gradient of the objective. 1001 \begin{footnotesize} 766 1002 \begin{verbatim} 767 1003 bool HS071_NLP::eval_grad_f(Index n, const Number* x, bool new_x, Number* grad_f) … … 777 1013 } 778 1014 \end{verbatim} 779 780 781 \paragraph{virtual bool eval\_g(Index n, const Number* x, 782 bool new\_x, Index m, Number* g)} 783 $\;$ \\ 784 Give Ipopt the value of the constraints as calculated by the values in {\tt x}. 1015 \end{footnotesize} 1016 1017 \paragraph{Method {\texttt{eval\_g}}} with Prototype 1018 \begin{verbatim} 1019 virtual bool eval_g(Index n, const Number* x, 1020 bool new_x, Index m, Number* g)} 1021 \end{verbatim} 1022 Give \Ipopt\ the value of the constraints as calculated by the values in {\tt x}. 785 1023 \begin{itemize} 786 1024 \item {\tt n}: (in), the number of variables in the problem (dimension of {\tt x}). … … 798 1036 any of the evaluation methods used the same $x$ values. This can be 799 1037 helpful when users have efficient implementations that calculate 800 multiple outputs at once. Ipoptinternally caches results from the1038 multiple outputs at once. \Ipopt\ internally caches results from the 801 1039 {\tt TNLP} and generally, this flag can be ignored. 802 1040 … … 807 1045 In our example, we ignore the {\tt new\_x} flag and calculate the 808 1046 values for the gradient of the objective. 1047 \begin{footnotesize} 809 1048 \begin{verbatim} 810 1049 bool HS071_NLP::eval_g(Index n, const Number* x, bool new_x, Index m, Number* g) … … 819 1058 } 820 1059 \end{verbatim} 821 822 \paragraph{virtual bool eval\_jac\_g(Index n, const Number* x, bool new\_x, \\ 823 Index m, Index nele\_jac, Index* iRow, 824 Index *jCol, Number* values)} 825 $\;$ \\ 1060 \end{footnotesize} 1061 1062 \paragraph{Method {\texttt{eval\_jac\_g}}} with Prototype 1063 \begin{verbatim} 1064 virtual bool eval_jac_g(Index n, const Number* x, bool new_x, 1065 Index m, Index nele_jac, Index* iRow, 1066 Index *jCol, Number* values) 1067 \end{verbatim} 826 1068 Return either the structure of the Jacobian of the constraints, or the values for the 827 1069 Jacobian of the constraints as calculated by the values in {\tt x}. … … 844 1086 the sparse matrix format used in this method. 845 1087 846 If the {\tt iRow} and {\tt jCol} arguments are not NULL, then Ipopt1088 If the {\tt iRow} and {\tt jCol} arguments are not NULL, then \Ipopt 847 1089 wants you to fill in the structure of the Jacobian (the row and column 848 1090 indices only). At this time, the {\tt x} argument and the {\tt values} … … 850 1092 851 1093 If the {\tt x} argument and the {\tt values} argument are not NULL, 852 then Ipoptwants you to fill in the values of the Jacobian as1094 then \Ipopt\ wants you to fill in the values of the Jacobian as 853 1095 calculated from the array {\tt x} (using the same order as you used 854 1096 when specifying the structure). At this time, the {\tt iRow} and {\tt … … 858 1100 any of the evaluation methods used the same $x$ values. This can be 859 1101 helpful when users have efficient implementations that caclulate 860 multiple outputs at once. Ipoptinternally caches results from the1102 multiple outputs at once. \Ipopt\ internally caches results from the 861 1103 {\tt TNLP} and generally, this flag can be ignored. 862 1104 … … 868 1110 specify it using the sparse format. 869 1111 1112 \begin{footnotesize} 870 1113 \begin{verbatim} 871 1114 bool HS071_NLP::eval_jac_g(Index n, const Number* x, bool new_x, 872 Index m, Index nele_jac, Index* iRow, Index *jCol,873 Number* values)1115 Index m, Index nele_jac, Index* iRow, Index *jCol, 1116 Number* values) 874 1117 { 875 1118 if (values == NULL) { … … 903 1146 } 904 1147 \end{verbatim} 905 906 \paragraph{virtual bool eval\_h(Index n, const Number* x, bool new\_x,\\ 907 Number obj\_factor, Index m, const Number* lambda, bool new\_lambda,\\ 908 Index nele\_hess, Index* iRow, Index* jCol, Number* values)} 909 $\;$ \\ 1148 \end{footnotesize} 1149 1150 \paragraph{Method {\texttt{eval\_h}}} with Prototype 1151 \begin{verbatim} 1152 virtual bool eval_h(Index n, const Number* x, bool new_x, 1153 Number obj_factor, Index m, const Number* lambda, 1154 bool new_lambda, Index nele_hess, Index* iRow, 1155 Index* jCol, Number* values) 1156 \end{verbatim} 910 1157 Return the structure of the Hessian of the Lagrangian or the values of the 911 1158 Hessian of the Lagrangian as calculated by the values in {\tt obj\_factor}, … … 931 1178 \end{itemize} 932 1179 933 If the {\tt iRow} and {\tt jCol} arguments are not NULL, then Ipopt1180 If the {\tt iRow} and {\tt jCol} arguments are not NULL, then \Ipopt 934 1181 wants you to fill in the structure of the Hessian (the row and column 935 1182 indices only). In this case, the {\tt x}, {\tt lambda}, and {\tt … … 937 1184 938 1185 If the {\tt x}, {\tt lambda}, and {\tt values} arrays are not NULL, 939 then Ipoptwants you to fill in the values of the Hessian as1186 then \Ipopt\ wants you to fill in the values of the Hessian as 940 1187 calculated using {\tt x} and {\tt lambda} (using the same order as you 941 1188 used when specifying the structure). In this case, the {\tt iRow} and … … 945 1192 false if the last call to any of the evaluation methods used the same 946 1193 values. This can be helpful when users have efficient implementations 947 that caclulate multiple outputs at once. Ipoptinternally caches1194 that caclulate multiple outputs at once. \Ipopt\ internally caches 948 1195 results from the {\tt TNLP} and generally, this flag can be ignored. 949 1196 … … 955 1202 sparse matrix format. Because the Hessian is symmetric, we only need to 956 1203 specify the lower left corner. 1204 \begin{footnotesize} 957 1205 \begin{verbatim} 958 1206 bool HS071_NLP::eval_h(Index n, const Number* x, bool new_x, 959 Number obj_factor, Index m, const Number* lambda,960 bool new_lambda, Index nele_hess, Index* iRow,961 Index* jCol, Number* values)1207 Number obj_factor, Index m, const Number* lambda, 1208 bool new_lambda, Index nele_hess, Index* iRow, 1209 Index* jCol, Number* values) 962 1210 { 963 1211 if (values == NULL) { … … 1020 1268 } 1021 1269 \end{verbatim} 1022 1023 \paragraph{virtual void finalize\_solution(SolverReturn status,\\ 1024 Index n, const Number* x, const Number* z\_L, const Number* z\_U, \\ 1025 Index m, const Number* g, const Number* lambda, Number obj\_value)} 1026 $\;$ \\ 1270 \end{footnotesize} 1271 1272 \paragraph{Method \texttt{finalize\_solution}} with Prototype 1273 \begin{verbatim} 1274 virtual void finalize_solution(SolverReturn status, Index n, 1275 const Number* x, const Number* z_L, 1276 const Number* z_U, Index m, const Number* g, 1277 const Number* lambda, Number obj_value) 1278 \end{verbatim} 1027 1279 This is the only method that is not mentioned in Figure 1028 \ref{fig.required_info}. This method is called by Ipoptafter the1280 \ref{fig.required_info}. This method is called by \Ipopt\ after the 1029 1281 algorithm has finished (successfully or even with most errors). 1030 1282 \begin{itemize} … … 1046 1298 failed to find a more feasible point. 1047 1299 \item {\tt INTERNAL\_ERROR}: An unknown internal error occurred. Please 1048 contact the IpoptAuthors through the mailing list.1300 contact the \Ipopt\ Authors through the mailing list. 1049 1301 \end{itemize} 1050 1302 \item {\tt n}: (in), the number of variables in the problem (dimension of {\tt x}). … … 1065 1317 the screen. 1066 1318 1319 \begin{footnotesize} 1067 1320 \begin{verbatim} 1068 1321 void HS071_NLP::finalize_solution(SolverReturn status, 1069 Index n, const Number* x, const Number* z_L, const Number* z_U,1070 Index m, const Number* g, const Number* lambda,1071 Number obj_value)1322 Index n, const Number* x, const Number* z_L, 1323 const Number* z_U, Index m, const Number* g, 1324 const Number* lambda, Number obj_value) 1072 1325 { 1073 1326 // here is where we would store the solution to variables, or write to a file, etc … … 1092 1345 } 1093 1346 \end{verbatim} 1347 \end{footnotesize} 1094 1348 1095 1349 This is all that is required for our {\tt HS071\_NLP} class and 1096 1350 the coding of the problem representation. 1097 1351 1098 \subsubsection{Coding the Executable ( main)}1352 \subsubsection{Coding the Executable (\texttt{main})} 1099 1353 Now that we have a problem representation, the {\tt HS071\_NLP} class, 1100 we need to code the main function that will call Ipopt and ask Ipopt1354 we need to code the main function that will call \Ipopt\ and ask \Ipopt\ 1101 1355 to find a solution. 1102 1356 1103 Here, we must create an instance of our problem ({\tt HS071\_NLP}), create an 1104 instance of the ipopt solver (IpoptApplication), and ask the solver to 1105 find a solution. We always use the SmartPtr template class instead of 1106 raw C++ pointers when creating and passing Ipopt objects. To find out 1107 more information about smart pointers and the SmartPtr implementation 1108 used in Ipopt, see Appendix \ref{app.smart_ptr}. 1357 Here, we must create an instance of our problem ({\tt HS071\_NLP}), 1358 create an instance of the \Ipopt\ solver (\texttt{IpoptApplication}), 1359 and ask the solver to find a solution. We always use the 1360 \texttt{SmartPtr} template class instead of raw C++ pointers when 1361 creating and passing \Ipopt\ objects. To find out more information 1362 about smart pointers and the {\tt SmartPtr} implementation used in 1363 \Ipopt, see Appendix \ref{app.smart_ptr}. 1109 1364 1110 1365 Create the file {\tt MyExample.cpp} in the MyExample directory. 1111 1366 Include {\tt HS071\_NLP.hpp} and {\tt IpIpoptApplication.hpp}, tell 1112 the compiler to use the Ipopt namespace, and implement the {\tt main} 1113 function. 1367 the compiler to use the {\tt Ipopt} namespace, and implement the {\tt 1368 main} function. 1369 \begin{footnotesize} 1114 1370 \begin{verbatim} 1115 1371 #include "IpIpoptApplication.hpp" … … 1149 1405 } 1150 1406 \end{verbatim} 1407 \end{footnotesize} 1151 1408 1152 1409 The first line of code in {\tt main} creates an instance of {\tt 1153 HS071\_NLP}. We then create an instance of the ipopt solver, 1154 IpoptApplication. The call to {\tt app>OptimizeTNLP(...)} will run 1155 Ipopt and try to solve the problem. By default, Ipopt will write to 1156 its progress to the console, and return the {\tt SolverReturn} status. 1410 HS071\_NLP}. We then create an instance of the \Ipopt\ solver, {\tt 1411 IpoptApplication}. The call to {\tt app>OptimizeTNLP(...)} will run 1412 \Ipopt\ and try to solve the problem. By default, \Ipopt\ will write 1413 to its progress to the console, and return the {\tt SolverReturn} 1414 status. 1157 1415 1158 1416 \subsubsection{Compiling and Testing the Example} 1159 1417 Our next task is to compile and test the code. If you are familiar 1160 1418 with the compiler and linker used on your system, you can build the 1161 code, including the ipopt library (and other necessary libraries). If 1162 you are using Linux/UNIX, then a sample makefile exists already that was 1163 created by configure. Copy {\tt Examples/hs071\_cpp/Makefile} into 1164 your {\tt MyExample} directory. This makefile was created for the 1165 hs071\_cpp code, but it can be easily modified for your example 1166 problem. Edit the file, making the following changes, 1419 code, including the \Ipopt\ library {\tt libipopt.a} (and other 1420 necessary libraries). If you are using Linux/UNIX, then a sample 1421 makefile exists already that was created by configure. Copy {\tt 1422 Examples/hs071\_cpp/Makefile} into your {\tt MyExample} directory. 1423 This makefile was created for the {\tt hs071\_cpp} code, but it can be 1424 easily modified for your example problem. Edit the file, making the 1425 following changes, 1167 1426 1168 1427 \begin{itemize} … … 1177 1436 {\tt \$ ./my\_example} 1178 1437 and you should see output resembling the following, 1438 \begin{footnotesize} 1179 1439 \begin{verbatim} 1180 1440 Total number of variables............................: 4 … … 1243 1503 *** The problem solved! 1244 1504 \end{verbatim} 1505 \end{footnotesize} 1245 1506 1246 1507 This completes the basic C++ tutorial, but see Section 1247 \ref{sec.output} which explains the standard console output of Ipopt,1508 \ref{sec.output} which explains the standard console output of \Ipopt, 1248 1509 Section \ref{sec.jnlst} to learn about adjusting the output produced 1249 from Ipoptthrough the use of the Journalist, and Section1510 from \Ipopt\ through the use of the Journalist, and Section 1250 1511 \ref{sec.options} for information about the use of options to 1251 customize the behavior of Ipopt. 1252 1253 \subsection{The C Interface} 1254 Have a look at {\tt IpStdCInterface.h} to see the declarations for the 1255 C interface. For the C++ interface, all problem information is 1256 provided through the NLP class. In the C interface, we instead create 1257 an IpoptProblem (C structure) and pass that structure to the 1258 IpoptSolve call. 1259 1260 The IpoptProblem structure contains the problem dimensions, the variable 1261 and constraint bounds, and the function pointers for callbacks that 1262 will be used to evaluate the NLP. 1263 We then make the call to IpoptSolve, giving Ipopt the IpoptProblem structure, 1264 the starting point, and arrays to store the solution values, if desired. 1265 1266 A completed version of this example can be found in {\tt 1267 Examples/hs071\_c}. We first create the necessary callback functions 1268 for evaluating the NLP. We require callbacks to evaluate the 1269 objective value, constraints, gradient of the objective, Jacobian of 1270 the constraints, and the Hessian of the Lagrangian. These callbacks 1271 are implemented using function pointers (see {\tt IpStdCInterface.h}). 1272 Have a look at the documentation for {\tt eval\_f}, {\tt eval\_g}, {\tt 1273 eval\_grad\_f}, {\tt eval\_jac\_g}, and {\tt eval\_h} in Section 1274 \ref{sec.cpp_problem}. The C implementations will have different 1275 prototypes, but will be implemented almost identically to the C++ 1276 code. 1277 1278 Create a new directory {\tt MyCExample} and create a new file, {\tt 1279 hs071\_c.c}. Here, include the interface header file {\tt 1280 IpStdCInterface.h}, along with {\tt malloc.h} and {\tt assert.h}. Add 1281 the prototypes and implementations for the five callback functions. 1282 See the completed example in {\tt Examples/hs071\_c/hs071\_c.c}. 1512 customize the behavior of \Ipopt. 1513 1514 \subsection{The C Interface}\label{sec.cinterface} 1515 The C interface for \Ipopt\ is declared in the header file {\tt 1516 IpStdCInterface.h}, which is found in\\ 1517 \texttt{\$IPOPTDIR/include/ipopt} (or in 1518 \texttt{\$PREFIX/include/ipopt} if the switch 1519 \texttt{prefix=\$PREFIX} was used for {\tt configure}); while 1520 reading this section, it will be helpful to have a look at this file. 1521 1522 In order to solve an optimization problem with the C interface, one 1523 has to create an {\tt IpoptProblem}\footnote{{\tt IpoptProblem} is a 1524 pointer to a C structure; you should not access this structure 1525 directly, only through the functions provided in the C interface.} 1526 with the function {\tt CreateIpoptProblem}, which lateron has to be 1527 passed to the {\tt IpoptSolve} function. 1528 1529 The {\tt IpoptProblem} created by {\tt CreateIpoptProblem} contains 1530 the problem dimensions, the variable and constraint bounds, and the 1531 function pointers for callbacks that will be used to evaluate the NLP 1532 problem functions and their derivatives (see also the discussion of 1533 the C++ methods {\tt get\_nlp\_info} and {\tt get\_bounds\_info} in 1534 Section~\ref{sec.cpp_problem} for information about the arguments of 1535 {\tt CreateIpoptProblem}). 1536 1537 The prototypes for the callback functions, {\tt Eval\_F\_CB}, {\tt 1538 Eval\_Grad\_F\_CB}, etc., are defined in the header file {\tt 1539 IpStdCInterface.h}. Their arguments correspond onetoone to the 1540 arguments for the C++ methods discussed in 1541 Section~\ref{sec.cpp_problem}; for example, for the meaning of $\tt 1542 n$, $\tt x$, $\tt new\_x$, $\tt obj\_value$ in the declaration of {\tt 1543 Eval\_F\_CB} see the discussion of ``{\tt eval\_f}''. The callback 1544 functions should return {\tt TRUE}, unless there was a problem doing 1545 the requested function/derivative evaluation at the given point {\tt 1546 x}. 1547 1548 Note the additional argument of type {\tt UserDataPtr} in the callback 1549 functions. This pointer argument is available for you to communicate 1550 information between the main program that calls {\tt IpoptSolve} and 1551 any of the callback functions. This pointer is simply passed 1552 unmodified by \Ipopt\ amoung those functions. For example, you can 1553 use this to pass constants that define the optimization problem and 1554 are computed before the optimization in the main C program to the 1555 callback functions. 1556 1557 After an {\tt IpoptProblem} has been created, you can set algorithmic 1558 options for \Ipopt\ (see Section~\ref{sec.options}) using the {\tt 1559 AddIpopt*Option} functions. Finally, the \Ipopt\ algorithm is 1560 called with {\tt IpoptSolve}, giving \Ipopt\ the {\tt IpoptProblem}, 1561 the starting point, and arrays to store the solution values (primal 1562 and dual variables), if desired. Finally, after everything is done, 1563 you should call {\tt FreeIpoptProblem} to release internal memory that 1564 is still allocated inside \Ipopt. 1565 1566 In the remainder of this section we discuss how the example problem 1567 (\ref{eq:ex_obj})(\ref{eq:ex_bounds}) can be solved using the C 1568 interface. A completed version of this example can be found in {\tt 1569 Examples/hs071\_c}. 1570 1571 % We first create the necessary callback 1572 % functions for evaluating the NLP. As just discussed, the \Ipopt\ C 1573 % interface required callbacks to evaluate the objective value, 1574 % constraints, gradient of the objective, Jacobian of the constraints, 1575 % and the Hessian of the Lagrangian. These callbacks are implemented 1576 % using function pointers. Have a look at the C++ implementation for 1577 % {\tt eval\_f}, {\tt eval\_g}, {\tt eval\_grad\_f}, {\tt eval\_jac\_g}, 1578 % and {\tt eval\_h} in Section \ref{sec.cpp_problem}. The C 1579 % implementations have somewhat different prototypes, but are 1580 % implemented almost identically to the C++ code. 1581 1582 \vspace{\baselineskip} 1583 1584 In order to implement the example problem on your own, create a new 1585 directory {\tt MyCExample} and create a new file, {\tt 1586 hs071\_c.c}. Here, include the interface header file {\tt 1587 IpStdCInterface.h}, along with other necessary header files, such as 1588 {\tt stdlib.h} and {\tt assert.h}. Add the prototypes and 1589 implementations for the five callback functions. Have a look at the 1590 C++ implementation for {\tt eval\_f}, {\tt eval\_g}, {\tt 1591 eval\_grad\_f}, {\tt eval\_jac\_g}, and {\tt eval\_h} in Section 1592 \ref{sec.cpp_problem}. The C implementations have somewhat different 1593 prototypes, but are implemented almost identically to the C++ code. 1594 See the completed example in {\tt Examples/hs071\_c/hs071\_c.c} if you 1595 are not sure how to do this. 1283 1596 1284 1597 We now need to implement the {\tt main} function, create the {\tt 1285 IpoptProblem}, and call {\tt IpoptSolve}. The {\tt CreateIpoptProblem} 1286 function requires the problem dimensions, the variable and constraint 1287 bounds, and the function pointers to the callback routines. The {\tt 1288 IpoptSolve} function requires the {\tt IpoptProblem}, the starting 1289 point, and allocated arrays for the solution. The {\tt main} function 1290 from the example is shown below. 1598 IpoptProblem}, set options, and call {\tt IpoptSolve}. The {\tt 1599 CreateIpoptProblem} function requires the problem dimensions, the 1600 variable and constraint bounds, and the function pointers to the 1601 callback routines. The {\tt IpoptSolve} function requires the {\tt 1602 IpoptProblem}, the starting point, and allocated arrays for the 1603 solution. The {\tt main} function from the example is shown next, and 1604 discussed below. 1605 1606 %in Figure~\ref{fig:cexamplemain}. 1607 %\begin{figure} 1608 % \centering 1609 \begin{footnotesize} 1291 1610 \begin{verbatim} 1292 1611 int main() … … 1301 1620 enum ApplicationReturnStatus status; /* Solve return code */ 1302 1621 Number* x = NULL; /* starting point and solution vector */ 1622 Number* mult_x_L = NULL; /* lower bound multipliers 1623 at the solution */ 1624 Number* mult_x_U = NULL; /* upper bound multipliers 1625 at the solution */ 1303 1626 Number obj; /* objective value */ 1304 1627 Index i; /* generic counter */ 1305 1628 1629 /* set the number of variables and allocate space for the bounds */ 1306 1630 n=4; 1307 1631 x_L = (Number*)malloc(sizeof(Number)*n); 1308 1632 x_U = (Number*)malloc(sizeof(Number)*n); 1633 /* set the values for the variable bounds */ 1309 1634 for (i=0; i<n; i++) { 1310 1635 x_L[i] = 1.0; … … 1312 1637 } 1313 1638 1639 /* set the number of constraints and allocate space for the bounds */ 1314 1640 m=2; 1315 1641 g_L = (Number*)malloc(sizeof(Number)*m); 1316 1642 g_U = (Number*)malloc(sizeof(Number)*m); 1643 /* set the values of the constraint bounds */ 1317 1644 g_L[0] = 25; g_U[0] = 2e19; 1318 1645 g_L[1] = 40; g_U[1] = 40; 1319 1646 1647 /* create the IpoptProblem */ 1320 1648 nlp = CreateIpoptProblem(n, x_L, x_U, m, g_L, g_U, 8, 10, 0, 1321 1649 &eval_f, &eval_g, &eval_grad_f, 1322 1650 &eval_jac_g, &eval_h); 1323 1651 1324 1652 /* We can free the memory now  the values for the bounds have been 1653 copied internally in CreateIpoptProblem */ 1654 free(x_L); 1655 free(x_U); 1656 free(g_L); 1657 free(g_U); 1658 1659 /* set some options */ 1660 AddIpoptNumOption(nlp, "tol", 1e9); 1661 AddIpoptStrOption(nlp, "mu_strategy", "adaptive"); 1662 1663 /* allocate space for the initial point and set the values */ 1325 1664 x = (Number*)malloc(sizeof(Number)*n); 1326 1665 x[0] = 1.0; … … 1329 1668 x[3] = 1.0; 1330 1669 1331 AddIpoptNumOption(nlp, "tol", 1e9); 1332 AddIpoptStrOption(nlp, "mu_strategy", "adaptive"); 1333 1334 status = IpoptSolve(nlp, x, NULL, &obj, NULL, NULL, NULL, NULL); 1670 /* allocate space to store the bound multipliers at the solution */ 1671 mult_x_L = (Number*)malloc(sizeof(Number)*n); 1672 mult_x_U = (Number*)malloc(sizeof(Number)*n); 1673 1674 /* solve the problem */ 1675 status = IpoptSolve(nlp, x, NULL, &obj, NULL, mult_x_L, mult_x_U, NULL); 1676 1677 if (status == Solve_Succeeded) { 1678 printf("\n\nSolution of the primal variables, x\n"); 1679 for (i=0; i<n; i++) { 1680 printf("x[%d] = %e\n", i, x[i]); 1681 } 1682 1683 printf("\n\nSolution of the bound multipliers, z_L and z_U\n"); 1684 for (i=0; i<n; i++) { 1685 printf("z_L[%d] = %e\n", i, mult_x_L[i]); 1686 } 1687 for (i=0; i<n; i++) { 1688 printf("z_U[%d] = %e\n", i, mult_x_U[i]); 1689 } 1690 1691 printf("\n\nObjective value\n"); 1692 printf("f(x*) = %e\n", obj); 1693 } 1335 1694 1695 /* free allocated memory */ 1336 1696 FreeIpoptProblem(nlp); 1337 free(x_L);1338 free(x_U);1339 free(g_L);1340 free(g_U);1341 1697 free(x); 1698 free(mult_x_L); 1699 free(mult_x_U); 1342 1700 1343 1701 return 0; 1344 1702 } 1345 1703 \end{verbatim} 1704 \end{footnotesize} 1705 % \caption{{\tt main} function for C example} 1706 % \label{fig:cexamplemain} 1707 %\end{figure} 1708 1346 1709 Here, we declare all the necessary variables and set the dimensions of 1347 1710 the problem. The problem has 4 variables, so we set {\tt n} and 1348 1711 allocate space for the variable bounds (don't forget to call {\tt 1349 free} for each of your {\tt malloc} calls). We then set the values for 1350 the variable bounds. 1351 1352 The problem has 2 constraints, so we set {\tt m} 1353 and allocate space for the constraint bounds. The first constraint has 1354 a lower bound of $25$ and no upper bound. Here we set the upper bound 1355 to \texttt{2e19}. Ipopt interprets any number greater than \texttt{nlp\_upper\_bound\_inf} 1356 as infinity. The default value of \texttt{nlp\_upper\_bound\_inf} and 1357 \texttt{nlp\_lower\_bound\_inf} is \texttt{1e19} and can be changed through ipopt options. 1358 The second constraint is an equality, so we set both the upper and the 1359 lower bound to $40$. 1712 free} for each of your {\tt malloc} calls before the end of the 1713 program). We then set the values for the variable bounds. 1714 1715 The problem has 2 constraints, so we set {\tt m} and allocate space 1716 for the constraint bounds. The first constraint has a lower bound of 1717 $25$ and no upper bound. Here we set the upper bound to 1718 \texttt{2e19}. \Ipopt\ interprets any number greater than 1719 \texttt{nlp\_upper\_bound\_inf} as infinity. The default value of 1720 \texttt{nlp\_lower\_bound\_inf} and \texttt{nlp\_upper\_bound\_inf} is 1721 \texttt{1e19} and \texttt{1e19}, respectively, and can be changed 1722 through \Ipopt\ options. The second constraint is an equality, so we 1723 set both the upper and the lower bound to 40. 1360 1724 1361 1725 We next create an instance of the {\tt IpoptProblem} by calling {\tt 1362 1726 CreateIpoptProblem}, giving it the problem dimensions and the variable 1363 1727 and constraint bounds. The arguments {\tt nele\_jac} and {\tt 1364 nele\_hess} are the number of elements in Jacobian and the Hessian 1365 respectively. See appendix\ref{app.triplet} for a description of the1728 nele\_hess} are the number of elements in Jacobian and the Hessian, 1729 respectively. See Appendix~\ref{app.triplet} for a description of the 1366 1730 sparse matrix format. The {\tt index\_style} argument specifies whether 1367 1731 we want to use C style indexing for the row and column indices of the 1368 1732 matrices or Fortran style indexing. Here, we set it to {\tt 0} to 1369 1733 indicate C style. We also include the references to each of our 1370 callback functions. Ipopt can usethese function pointers to ask for1734 callback functions. \Ipopt\ uses these function pointers to ask for 1371 1735 evaluation of the NLP when required. 1372 1736 1373 The next two lines illustrate how you can change the value of options 1374 through the interface. Ipopt Options can also be changed by creating 1375 a PARAMS.DAT file. We next allocate space for the initial point and 1376 set the values as given in the problem definition. 1377 1378 The call to {\tt IpoptSolve} can provide us with information about the solution, 1379 but most of this is optional. Here, we want values for the bound multipliers at 1380 the solution and we allocate space for these. 1737 After freeing the bound arrays that are no longer required, the next 1738 two lines illustrate how you can change the value of options through 1739 the interface. \Ipopt\ options can also be changed by creating a {\tt 1740 PARAMS.DAT} file (see Section~\ref{sec.options}). We next allocate 1741 space for the initial point and set the values as given in the problem 1742 definition. 1743 1744 The call to {\tt IpoptSolve} can provide us with information about the 1745 solution, but most of this is optional. Here, we want values for the 1746 bound multipliers at the solution and we allocate space for these. 1381 1747 1382 1748 We can now make the call to {\tt IpoptSolve} and find the solution of 1383 1749 the problem. We pass in the {\tt IpoptProblem}, the starting point 1384 {\tt x} ( Ipopt will use this variable to return the solution as1385 well). The next 5 arguments are pointers so Ipopt can fill in values 1386 at the solution. If these pointers are set to {\tt NULL}, Ipoptwill1750 {\tt x} (\Ipopt\ will use this array to return the solution as well). 1751 The next 5 arguments are pointers so \Ipopt\ can fill in values at the 1752 solution. If these pointers are set to {\tt NULL}, \Ipopt\ will 1387 1753 ignore that entry. For example, here, we do not want the constraint 1388 1754 residuals at the solution or the equality multipliers, so we set those 1389 1755 entries to {\tt NULL}. We do want the value of the objective, and the 1390 1756 multipliers for the variable bounds. The last argument is a {\tt 1391 void*} for user data. Any pointer you give here will also be passed to 1392 you in the callback functions. 1393 1394 The return code is an ApplicationReturnStatus enumeration, see {\tt 1395 Interfaces/ReturnCodes\_inc.h}. 1396 1397 After the problem has solved, we check the status and print the solution if 1398 successful. Finally, we free the memory and return from {\tt main}. 1757 void*} for user data. Any pointer you give here will also be passed 1758 to you in the callback functions. 1759 1760 The return code is an ApplicationReturnStatus enumeration, see the 1761 header file {\tt ReturnCodes\_inc.h} which is installed along {\tt 1762 IpStdCInterface.h} in the \Ipopt\ include directory. 1763 1764 After the problem has solved, we check the status and print the 1765 solution if successful. Finally, we free the {\tt IpoptProblem} and 1766 the remaining memory, and return from {\tt main}. 1767 1768 \subsection{The Fortran Interface} 1769 1770 The Fortran interface is essentially a wrapper of the C interface 1771 discussed in Section~\ref{sec.cinterface}. The way to hook up \Ipopt\ 1772 in a Fortran program is very similar to how it is done for the C 1773 interface, and the functions of the Fortran interface correspond 1774 onetoone to the those of the C interface, including their arguments. 1775 You can find an implementation of the example problem 1776 (\ref{eq:ex_obj})(\ref{eq:ex_bounds}) in {\tt 1777 \$IPOPTDIR/Examples/hs071\_f}. 1778 1779 The only special things to consider are: 1780 \begin{itemize} 1781 \item The return value of the function {\tt IPCREATE} is of an {\tt 1782 INTEGER} type that must be large enough to capture a pointer 1783 on the particular machine. This means, that you have to declare 1784 the ``handle'' for the IpoptProblem as {\tt INTEGER*8} if your 1785 program is compiled in 64bit mode. All other {\tt INTEGER}type 1786 variables must be of the regular type. 1787 \item For the call of {\tt IPSOLVE} (which is the function that is to 1788 be called to run \Ipopt), all arrays, including those for the dual 1789 variables, must be given (in contrast to the C interface). The 1790 return value {\tt IERR} of this function indicates the outcome of 1791 the optimization (see the include file {\tt IpReturnCodes.inc} in 1792 the \Ipopt\ include directory. 1793 \item The return {\tt IERR} value of the remaining functions is zero, 1794 unless there was a problem during execution of the function call. 1795 \item The callback functions ({\tt EV\_*} in the example) include the 1796 arguments {\tt IDAT} and {\tt DAT}, which are {\tt INTEGER} and {\tt 1797 DOUBLE PRECISION} arrays that are passed unmodified between the 1798 main program calling {\tt IPSOLVE} and the evaluation subroutines 1799 {\tt EV\_*} (similarly to {\tt UserDataPtr} arguments in the C 1800 interface). Those can be used to pass ``private'' data between 1801 the userprovided Fortran subroutines. 1802 1803 The last argument of the {\tt EV\_*} subroutines, {\tt IERR}, is to 1804 be set to 0 by the users on return, unless there was a problem 1805 during the evaluation of the optimnization problem 1806 function/derivative for the given point {\tt X}. 1807 \end{itemize} 1808 1399 1809 1400 1810 \section{Ipopt Options}\label{sec.options} … … 1402 1812 algorithm. Options are all identified by a string name and their 1403 1813 values can be of one of three types, Number (real), Integer, or 1404 string. Number options are used for things like tolerances, integer1814 String. Number options are used for things like tolerances, integer 1405 1815 options are used for things like maximum number of iterations, and 1406 1816 string options are used for setting algorithm details, like the NLP … … 1431 1841 how this is done. 1432 1842 1433 A subset of Ipoptoptions are available through AMPL. To set options1843 A subset of \Ipopt\ options are available through AMPL. To set options 1434 1844 through AMPL, use the internal AMPL command {\tt options}. For 1435 1845 example, \\ … … 1437 1847 max\_iter=500''} \\ 1438 1848 is a valid options command in AMPL. The most common 1439 options are referenced in Appendix 1849 options are referenced in Appendix~\ref{app.options_ref}. These are also 1440 1850 the options that are available through AMPL using the {\tt options} 1441 1851 command. To specify other options when using AMPL, you can always … … 1456 1866 as a course project for \textit{47852 Open Source Software for 1457 1867 Optimization}, taught by Prof. Fran\c cois Margot at Tepper School of 1458 Business, Carnegie Mellon University. The authors of Ipoptgreatly1868 Business, Carnegie Mellon University. The authors of \Ipopt\ greatly 1459 1869 thank Yoshi for his efforts. 1460 1870 1461 \begin{thebibliography}{99} 1462 \bibitem{COINORWeb} 1463 http://www.coinor.org 1464 \bibitem{AndreasPaper} 1465 W\"achter, A. and Biegler, L.T.:''On the Implementation of a PrimalDual 1466 Interior Point Filter Line Search Algorithm for LargeScale 1467 Nonlinear Programming'', Research Report, IBM T. J. Watson 1468 Research Center, Yorktown, USA (2004) 1469 \bibitem{AndreasThesis} 1470 W\"achter, A.:''An Interior Point Algorithm for LargeScale Nonlinear 1471 Optimization with Applications in Process Engineering'', 1472 Ph.D. Thesis, Carnegie Mellon University, Pittsburgh, USA (2002) 1473 \bibitem{MargotClassText} 1474 Margot, F.: Course material for \textit{47852 Open Source Software for 1475 Optimization}, Carnegie Mellon University (2005) 1476 \end{thebibliography} 1871 1872 \bibliographystyle{plain} 1873 \bibliography{/home/andreasw/tex/andreas} 1874 1875 %\bibitem{MargotClassText} 1876 %Margot, F.: Course material for \textit{47852 Open Source Software for 1877 % Optimization}, Carnegie Mellon University (2005) 1878 %\end{thebibliography} 1477 1879 1478 1880 1479 1881 \appendix 1480 1882 \section{Triplet Format for Sparse Matrices}\label{app.triplet} 1481 Ipoptwas designed for optimizing large sparse nonlinear programs.1883 \Ipopt\ was designed for optimizing large sparse nonlinear programs. 1482 1884 Because of problem sparsity, the required matrices (like the Jacobian or Hessian) are not stored as traditional dense matrices, but rather in a sparse matrix format. For the tutorials in this document, we use the triplet format. 1483 1885 Consider the matrix, … … 1509 1911 sparse representation grows linearly in the number of nonzeros.} 1510 1912 1511 In triplet format used in these Ipoptinterfaces, the row and column1913 In triplet format used in these \Ipopt\ interfaces, the row and column 1512 1914 numbers are 1based {\bf have table for both 0 and 1based}, and the 1513 1915 above matrix is represented by … … 1554 1956 1555 1957 It is very important to use SmartPtr's instead of raw pointers when 1556 passing objects to Ipopt. Internally, Ipoptuses smart pointers for1958 passing objects to \Ipopt. Internally, \Ipopt\ uses smart pointers for 1557 1959 referencing objects. If you use a raw pointer in your executable, the 1558 object's counter will NOT get incremented. Then, when Ipoptuses smart1960 object's counter will NOT get incremented. Then, when \Ipopt\ uses smart 1559 1961 pointers inside its own code, the counter will get 1560 incremented. However, before Ipoptreturns control to your code, it1962 incremented. However, before \Ipopt\ returns control to your code, it 1561 1963 will decrement as many times as it incremented and the counter will 1562 return to zero. Therefore, Ipoptwill delete the object. When control1964 return to zero. Therefore, \Ipopt\ will delete the object. When control 1563 1965 returns to you, you now have a raw pointer that points to a deleted 1564 1966 object. … … 1566 1968 This might sound difficult to anyone not familiar with the use of 1567 1969 smart pointers, but just follow one simple rule; always use a SmartPtr 1568 when creating or passing an Ipoptobject.1970 when creating or passing an \Ipopt\ object. 1569 1971 1570 1972 \section{Options Reference} \label{app.options_ref} … … 1802 2204 get a more accurate solution to the linear system 1803 2205 \end{verbatim} 2206 2207 \subsection{Detailed Installation Information}\label{ExpertInstall} 2208 2209 2210 1804 2211 \end{document}
Note: See TracChangeset
for help on using the changeset viewer.