Changeset 483


Ignore:
Timestamp:
Aug 24, 2005 9:58:21 AM (14 years ago)
Author:
andreasw
Message:

a number of additions and changes (in particular, C and Fortran interface
description - installation descriptions etc)

File:
1 edited

Legend:

Unmodified
Added
Removed
  • branches/dev/Docs/documentation.tex

    r478 r483  
    11%% Copyright (C) 2005, Carnegie Mellon University and others.
    22%%
    3 %% The first version of this files was contributed to the Ipopt project
     3%% The first version of this file was contributed to the Ipopt project
    44%% on Aug 1, 2005, by Yoshiaki Kawajiri
    55%%                    Department of Chemical Engineering
    66%%                    Carnegie Mellon University
    77%%                    Pittsburgh, PA 15213
     8%%
     9%% Since then, the content of this file has been updated significantly by
     10%%     Carl Laird and Andreas Waechter        IBM
    811%%
    912\documentclass[letter,10pt]{article}
     
    1518\renewcommand{\baselinestretch}{1.1}
    1619\usepackage{amsfonts}
     20\usepackage{amsmath}
    1721
    1822\newcommand{\RR}{{\mathbb{R}}}
     23\newcommand{\Ipopt}{{\sc Ipopt}}
    1924
    2025
    2126\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:\\
     28A 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}}
    3036
    3137%\date{\today}
     
    3541
    3642\section{Overview}
    37 Ipopt (\underline{I}nterior \underline{P}oint \underline{Opt}imizer) is an open
    38 source software package for large-scale 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,
     44pronounced ``I--P--Opt'') is an open source software package for
     45large-scale nonlinear optimization. It can be used to solve general
     46nonlinear programming problems of the form
     47%\begin{subequations}\label{NLP}
    4048\begin{eqnarray}
    41 \min_{x} &&f(x) \label{obj} \\
     49\min_{x\in\RR^n} &&f(x) \label{eq:obj} \\
    4250\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}
    4452\end{eqnarray}
     53%\end{subequations}
    4554where $x \in \RR^n$ are the optimization variables (possibly with
    4655lower and upper bounds, $x^L\in(\RR\cup\{-\infty\})^n$ and
     
    4857objective function, and $g:\RR^n\longrightarrow \RR^m$ are the general
    4958nonlinear constraints.  The functions $f(x)$ and $g(x)$ can be linear
    50 or nonlinear and convex or non-convex (but are assumed to be twice
     59or nonlinear and convex or non-convex (but should be twice
    5160continuously differentiable). The constraints, $g(x)$, have lower and
    5261upper bounds, $g^L\in(\RR\cup\{-\infty\})^n$ and
    5362$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 COIN-OR\cite{COINORWeb} under the
    61 open-source 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.coin-or.org/mailman/listinfo/coin-ipopt}). 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
     63form $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
     67aims to find a local solution of (\ref{eq:obj}-\ref{eq:bounds}).  The mathematical details
     68of the algorithm can be found in several publications
     69\cite{NocWaeWal:adaptive,WaechterPhD,WaeBie:IpoptImpl,WaeBie05:filterglobal,WaeBie05:filterlocal}.
     70
     71The \Ipopt\ package is available from COIN-OR
     72(\texttt{www.coin-or.org}) under the CPL (Common Public
     73License) open-source license and includes the source code for \Ipopt.
     74In order to build \Ipopt, some third party components are required
     75(see Section~\ref{ExternalCode}).
     76
     77If desired, the \Ipopt\ distribution generates an executable for the
     78modeling environments AMPL. As well, you can link your problem
     79statement with \Ipopt\ using interfaces for Fortran, C, or C++.
     80\Ipopt\ can be used with most Linux/Unix environments, and on Windows
     81using Visual Studio .NET or Cygwin.  The purpose of this document is
     82to demonstrate how to solve problems using \Ipopt. This includes
     83installation and compilation of \Ipopt\ for use with AMPL as well as
     84linking with your own code.
     85
     86More information might be found on the \Ipopt\ home page at
     87\texttt{http://projects.coin-or.org/Ipopt}.  General questions related
     88to \Ipopt\ should be addressed to \Ipopt\ mailing list\footnote{\tt
     89  http://list.coin-or.org/mailman/listinfo/coin-ipopt}. You might
     90want to look at the archives before posting a question.
     91
     92\section{History of \Ipopt}
     93The original \Ipopt\ (Fortran version) was a product of the dissertation
     94research of Andreas W\"achter \cite{WaechterPhD}, under Lorenz
    7795T. Biegler at the Chemical Engineering Department at Carnegie Mellon
    7896University. The code was made open source and distributed by the
    79 COIN-OR initiative, which is now a non-profit corporation.  Ipopt has
     97COIN-OR initiative, which is now a non-profit corporation.  \Ipopt\ has
    8098been actively developed under COIN-OR since 2002.
    8199
    82100To continue natural extension of the code and allow easy addition of
    83101new features, IBM Research decided to invest in an open source
    84 re-write of Ipopt in C++.  The new C++ version of the Ipopt
    85 optimization code (Ipopt 3.0 and beyond) is currently developed at IBM
     102re-write of \Ipopt\ in C++.  The new C++ version of the \Ipopt\
     103optimization code (\Ipopt\ 3.0 and beyond) is currently developed at IBM
    86104Research and remains part of the COIN-OR initiative. Future
    87105development on the Fortran version will cease with the exception of
    88106occasional bug fix releases.
    89107
    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 COIN-OR 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:
     108This document is a guide to using \Ipopt\ 3.0 (the new C++ version of \Ipopt).
     109
     110\section{Installing \Ipopt}\label{Installing}
     111
     112The following sections describe the installation procedures on
     113UNIX/Linux systems.  For installation instructions on Windows
     114see Section~\ref{WindowsInstall}.
     115
     116\subsection{Getting the \Ipopt\ Code}
     117\Ipopt\ is available from the COIN-OR subversion repository. You can
     118either download the code using \texttt{svn} (the
     119\textit{subversion}\footnote{see
     120  \texttt{http://subversion.tigris.org/}} client similar to CVS) or
     121simply retrieve a tarball (compressed archive file).  While the
     122tarball is an easy method to retrieve the code, using the
     123\textit{subversion} system allows users the benefits of the version
     124control system, including easy updates and revision control.
     125
     126\subsubsection{Getting the \Ipopt\ code via subversion}
     127
     128Of course, the \textit{subversion} client must be installed on your
     129system if you want to obtain the code this way (the executable it
     130called \texttt{svn}).  Information about \textit{subversion} and how
     131to download it can be found at \texttt{http://subversion.tigris.org/}.\\
     132
     133To obtain the \Ipopt\ source code via subversion, follow the steps
     134below:
    105135\begin{enumerate}
    106136\item{Create a directory to store the code}\\
     
    109139prompt, do not type {\tt \$}, only the text following it.
    110140\item{Download the code to the new directory}\\
    111 {\tt \$ cd Ipopt; svn co https://www.coin-or.org/svn/ipopt-devel/trunk}
     141{\tt \$ cd Ipopt\\
     142\$ svn co https://www.coin-or.org/svn/Ipopt/trunk}
     143\item Change into the root directory of the \Ipopt\ distribution\\
     144{\tt \$ cd trunk}
    112145\end{enumerate}
    113146
    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
     147In the following, ``\texttt{\$IPOPTDIR}'' will refer to the directory in
     148which you are right now (output of \texttt{pwd}).
     149
     150\subsubsection{Getting the \Ipopt\ code as tarball}
     151
     152To use the tarball, follow the steps below:
     153\begin{enumerate}
     154\item Download the latest tarball from
     155\texttt{http://www.coin-or.org/Tarballs}.  The file you should look
     156for has the form \texttt{ipopt-3.x.x.tar.gz} (where
     157``\texttt{3.x.x.}'' is the version number).  Put this file in a
     158directory under which you want to put the \Ipopt\ installation.
     159\item Issue the following commands to unpack the archive file: \\
     160\texttt{\$ gunzip ipopt-3.x.x.tar.gz} \\
     161\texttt{\$ tar xvf ipopt-3.x.x.tar} \\
     162Note the {\tt \$} indicates the command line
     163prompt, do not type {\tt \$}, only the text following it.
     164\item Change into the root directory of the \Ipopt\ distribution\\
     165{\tt \$ cd ipopt-3.x.x}
     166\end{enumerate}
     167
     168In the following, ``\texttt{\$IPOPTDIR}'' will refer to the directory in
     169which 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
     173distribution, namely ASL (the Ampl Solver Library), BLAS, and some
     174sparse linear algebra routines from the Harwell Subroutine Library.
     175
     176Note that you only need to obtain the ASL if you intend to use \Ipopt\
    120177from AMPL.  It is not required if you want to specify yout
    121178optimization problem in a programming language (C++, C, or Fortran).
     
    125182system, retrieving ASL, and BLAS is straightforward using scripts
    126183included with the ipopt distribution. These scripts download the
    127 required files from the Netlib Repository (http://www.netlib.org).\\
     184required files from the Netlib Repository (\texttt{www.netlib.org}).\\
    128185
    129186\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}\\
    132191
    133192\noindent
    134193If 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 alternative
     194the \texttt{INSTALL.*} files in the \texttt{\$IPOPTDIR/Extern/blas}
     195and \texttt{\$IPOPTDIR/Extern/ASL} directories for alternative
    137196instructions.
    138197
     
    144203third party code.
    145204\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.
    163223\end{enumerate}
    164224
    165225
    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
     230basic steps that should work on most systems.  For special
     231compilations and some for troubleshooting see
     232Appendix~\ref{ExpertInstall} and consult the \Ipopt\ webpage before
     233sending a message to the mailing list.
    169234\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 \\
    178250{\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 ?...?
    186268\end{enumerate}
    187269
    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
     272There are two ways to install \Ipopt\ on Windows systems.  The first
     273option, described in ection~\ref{CygwinInstall}, is to use Cygwin (see
     274\texttt{www.cygwin.com}), which offers a UNIX-like environment
     275on Windows and in which the installation procedure described earlier
     276in this section can be used.  The \Ipopt\ distribution also includes
     277projects files for the Microsoft Visual Studio (see
     278Section~\ref{VisualStudioInstall}).
     279
     280\subsubsection{Installation with Cygwin}\label{CygwinInstall}
     281
     282Cygwin is a Linux-like environment for Windows; if you don't know what
     283it is you might want to have a look at the Cygwin homepage,
     284\texttt{www.cygwin.com}.
     285
     286It is possible to build the \Ipopt\ AMPL solver executable in Cygwin
     287for general use in Windows.  You can also hook up \Ipopt\ to your own
     288program 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  non-cygwin compilers, but this is not (yet?) supported.}.
     291
     292If you want to compile \Ipopt\ under Cygwin, you first have to install
     293Cygwin in your Windows system.  This is pretty straight forward; you
     294simply download the ``setup'' program from
     295\texttt{www.cygwin.com} and start it.
     296
     297Then you do the following steps (assuming here that you don't have any
     298complications with firewall settings etc - in that case you might have
     299to 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 pre-chosen.  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 gcc-core
     321  \item gcc-g77
     322  \item gcc-g++
     323  \item gcc-mingw
     324  \item gcc-mingw-core
     325  \item gcc-mingw-g77
     326  \item gcc-mingw-g++
     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
     364The \Ipopt\ distribution includes project files that can be used to
     365compile the \Ipopt\ library and a Fortran and C++ example within the
     366Microsoft Visual Studio.  The project files have been created with
     367Microsoft Visual C++ .NET 2003 Standard, and the Intel Visual Fortran
     368Compiler 8.
     369
     370In order to use those project files, download the \Ipopt\ source code,
     371as well as the required third party code (put it into the Extern/blas
     372and Extern/HSL directories---ASL is not required for the Fortran and C
     373examples). Then open the solution file\\
     374
     375\texttt{\$IPOPTDIR$\backslash$Windows$\backslash$VisualStudio\_dotNET$\backslash$Ipopt$\backslash$Ipopt.sln}\\
     376
     377Note: Since the project files were created only with the Standard
     378edition of the C++ compiler, code optimization might be disabled; for
     379fast 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
     384applications, and there are a number of ways to interface with \Ipopt\
    191385that allow specific data structures and linear solver
    192386techniques. Nevertheless, the authors have included a standard
    193387representation that should meet the needs of most users.
    194388
    195 This tutorial will discuss four interfaces to Ipopt, namely the AMPL
     389This tutorial will discuss four interfaces to \Ipopt, namely the AMPL
    196390modeling language interface, and the C, C++, and Fortran code
    197391interfaces.  AMPL is a 3rd party modeling language tool that allows
     
    204398
    205399We will illustrate how to use each of the four interfaces using an
    206 example problem, number 71 from the Hock-Schittkowsky 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,
     400example problem, number 71 from the Hock-Schittkowsky 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}
     409with the starting point
    214410\begin{equation}
    215 x {=} (1, 5, 5, 1) \label{ex_startpt}
     411x {=} (1, 5, 5, 1) \label{eq:ex_startpt}
    216412\end{equation}
    217 and the optimal solution,
     413and the optimal solution
    218414\[
    219415x^\star {=} (1.00000000, 4.74299963, 3.82114998, 1.37940829). \nonumber
    220416\]
    221417
    222 \section{Tutorial Example: Using the AMPL interface}
     418\subsection{Using the AMPL interface}
    223419Interfacing through the AMPL interface is by far the easiest way to
    224 solve a problem with Ipopt. The user must simply formulate the problem
     420solve a problem with \Ipopt. The user must simply formulate the problem
    225421in AMPL syntax, and solve the problem through the AMPL environment.
    226422There are drawbacks, however. AMPL is a 3rd party package and, as
    227423such, must be appropriately licensed (a free, student version for
    228424limited problem size is available from the AMPL website,
    229 www.ampl.com). Furthermore, the AMPL environment may be prohibitive
     425\texttt{www.ampl.com}). Furthermore, the AMPL environment may be prohibitive
    230426for very large problems. Nevertheless, formulating the problem in AMPL
    231427is straightforward and even for large problems, it is often used as a
     
    234430This tutorial is not intended as a guide to formulating models in
    235431AMPL. 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
     434The problem presented in equations
     435(\ref{eq:ex_obj})--(\ref{eq:ex_startpt}) can be solved with \Ipopt\ with
     436the AMPL model file given in Figure~\ref{fig:HS71}.
     437
     438\begin{figure}
     439  \centering
     440\begin{footnotesize}
    241441\begin{verbatim}
    242442# tell ampl to use the ipopt executable as a solver
     
    257457# specify the constraints
    258458s.t.
    259        
    260459        inequality:
    261460                x1 * x2 * x3 * x4 >= 25;
     
    279478display x4;
    280479\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
     486The line, ``{\tt option solver ipopt;}'' tells AMPL to use \Ipopt\ as
     487the solver. The \Ipopt\ executable (installed in
     488Section~\ref{sec.comp_and_inst}) must be in the path for AMPL to find
     489it. The remaining lines specify the problem in AMPL format. The
     490problem can now be solved by starting AMPL and loading the mod file:
    287491\begin{verbatim}
    288492$ ampl
     
    293497\end{verbatim}
    294498%$
    295 The problem will be solved using Ipopt and the solution will be
     499The problem will be solved using \Ipopt\ and the solution will be
    296500displayed.
    297501
    298502At this point, AMPL users may wish to skip the sections about
    299503interfacing with code, but should read Section \ref{sec.options}
    300 concerning Ipopt options, and Section \ref{sec.ipopt_output} which
    301 explains the output displayed by ipopt.
    302 
    303 \section{Tutorial Example: Interfacing with Ipopt through code}
    304 In order to solve a problem, Ipopt needs more information than just
     504concerning \Ipopt\ options, and Section \ref{sec.ipopt_output} which
     505explains the output displayed by \Ipopt.
     506
     507\subsection{Interfacing with \Ipopt\ through code}
     508In order to solve a problem, \Ipopt\ needs more information than just
    305509the problem definition (for example, the derivative information). If
    306510you are using a modeling language like AMPL, the extra information is
    307 provided by the modeling tool and the Ipopt interface. When
    308 interfacing with Ipopt through your own code, however, you must
     511provided by the modeling tool and the \Ipopt\ interface. When
     512interfacing with \Ipopt\ through your own code, however, you must
    309513provide this additional information.
    310514
    311515\begin{figure}
    312 \caption{Information Required By Ipopt}
    313516\begin{enumerate}
    314         \item Problem dimensions \label{it.prob_dim}
    315                 \begin{itemize}
    316                         \item number of variables
    317                         \item number of constraints
    318                 \end{itemize}
    319         \item Problem bounds
    320                 \begin{itemize}
    321                         \item variable bounds
    322                         \item constraint bounds
    323                 \end{itemize}
    324         \item Initial starting point
    325                 \begin{itemize}
    326                         \item Initial values for the primal $x$ variables
    327                         \item Initial values for the multipliers (only
    328                           required for a warm start option)
    329                 \end{itemize}
    330         \item Problem Structure \label{it.prob_struct}
    331                 \begin{itemize}
    332                 \item number of nonzeros in the Jacobian of the constraints
    333                 \item number of nonzeros in the Hessian of the Lagrangian
    334                 \item Structure of the Jacobian of the constraints
    335                 \item Structure of the Hessian of the Lagrangian
    336                 \end{itemize}
    337         \item Evaluation of Problem Functions \label{it.prob_eval} \\
    338         Information evaluated using a given point
    339         ($x_k, \lambda_k, \sigma_f$ coming from Ipopt)
    340                 \begin{itemize}
    341                         \item Objective function, $f(x_k)$
    342                         \item Gradient of the objective $\nabla f(x_k)$
    343                         \item Constraint residuals, $g(x_k)$
    344                         \item Jacobian of the constraints, $\nabla g(x_k)$
    345                         \item Hessian of the Lagrangian,
    346                         $\sigma_f \nabla^2 f(x_k) + \sum_{i=1}^m\lambda_i\nabla^2 g_i(x_k)$
    347                 \end{itemize}
     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}
    348551\end{enumerate}
     552\caption{Information Required By \Ipopt}
    349553\label{fig.required_info}
    350554\end{figure}
    351 \vspace{0.1in}
    352 The information required by Ipopt is shown in Figure
     555%\vspace{0.1in}
     556The information required by \Ipopt\ is shown in Figure
    353557\ref{fig.required_info}. The problem dimensions and bounds are
    354558straightforward and come solely from the problem definition. The
    355559initial starting point is used by the algorithm when it begins
    356 iterating to solve the problem. If Ipopt has difficulty converging, or
     560iterating to solve the problem. If \Ipopt\ has difficulty converging, or
    357561if it converges to a locally infeasible point, adjusting the starting
    358562point may help.
    359563
    360 Providing the problem structure is a bit more involved. Ipopt is a
     564Providing the problem structure is a bit more involved. \Ipopt\ is a
    361565nonlinear programming solver that is designed for solving large scale,
    362 sparse problems. While Ipopt can be customized for a variety of matrix
    363 formats, a triplet format is used for the standard interfaces in this
     566sparse problems. While \Ipopt\ can be customized for a variety of matrix
     567formats, the triplet format is used for the standard interfaces in this
    364568tutorial. For an overview of the triplet format for sparse matrices,
    365 see Appendix \ref{app.triplet}. Before solving the problem, Ipopt
     569see Appendix~\ref{app.triplet}. Before solving the problem, \Ipopt\
    366570needs to know the number of nonzeros and the structure (row and column
    367571indices of each of the nonzeros) of the Jacobian and the Hessian. Once
     
    371575nonzero at the starting point.
    372576
    373 As Ipopt iterates, it will need the values for the items in
     577As \Ipopt\ iterates, it will need the values for the items in
    374578(\ref{it.prob_eval}) evaluated at particular points. Before we can
    375579begin coding the interface, however, we need to work out the details
    376580of these equations symbolically for example problem
    377 (\ref{ex_obj}-\ref{ex_bounds}).
    378 
    379 The gradient of the objective is given by
     581(\ref{eq:ex_obj}-\ref{eq:ex_bounds}).
     582
     583The gradient of the objective $f(x)$ is given by
    380584\begin{equation}
    381585\left[
     
    389593\end{equation}
    390594the Jacobian of
    391 the constraints is,
     595the constraints $g(x)$ is,
    392596\begin{equation}
    393597\left[
     
    401605We need to determine the Hessian of the Lagrangian.  The Lagrangian is
    402606given 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 Ipopt can ask for the Hessian of the objective or the
     607technically, $ \nabla^2 f(x_k) + \sum_{i=1}^m\lambda_i\nabla^2 g_i(x_k)$.
     608However, so that \Ipopt\ can ask for the Hessian of the objective or the
    405609constraints independently if required, we introduce a factor
    406610($\sigma_f$) in front of the objective term. The value for $\sigma_f$
    407611is generally $1$, although it may include scaling factors or even be
    408 set to zero to retrieve the Hessian of the constraints alone.
     612set to zero to retrieve the Hessians of the constraints alone.
    409613
    410614For our implementation then, the symbolic form of the Hessian of the
    411 Lagrangian (with the $\sigma_f$ parameter) is,
     615Lagrangian
     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,
    412620%\begin{eqnarray}
    413621%{\cal L}(x,\lambda) &{=}& f(x) + c(x)^T \lambda \nonumber \\
     
    448656\right]
    449657\end{equation}
    450 where the first term comes from the Hessian of the objective function, and the
    451 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.
     658where the first term comes from the Hessian of the objective function,
     659and the second and third term from the Hessian of (\ref{eq:ex_ineq})
     660and (\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.
    455663
    456664%C =============================================================================
     
    471679%C
    472680%C =============================================================================
    473 
    474 The remainder of this section of the tutorial will lead you through
     681\vspace{\baselineskip}
     682
     683The remaining sections of the tutorial will lead you through
    475684the coding required to solve example problem
    476 (\ref{ex_obj}-\ref{ex_bounds}) using, first C++, then C, and finally
     685(\ref{eq:ex_obj})--(\ref{eq:ex_bounds}) using, first C++, then C, and finally
    477686Fortran. Completed versions of these examples can be found in {\tt
    478 Ipopt/trunk/Examples} under {\tt hs071\_cpp}, {\tt hs071\_c}, {\tt
     687\$IPOPTDIR/Examples} under {\tt hs071\_cpp}, {\tt hs071\_c}, {\tt
    479688hs071\_f}.
    480689
    481690As a user, you are responsible for coding two sections of the program
    482 that solves a problem using Ipopt: the executable ({\tt main}) and the
    483 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.
     691that solves a problem using \Ipopt: the main executable (e.g., {\tt
     692  main}) and the problem representation.  Typically, you will write an
     693executable that prepares the problem, and then passes control over to
     694\Ipopt\ through an {\tt Optimize} or {\tt Solve} call. In this call,
     695you will give \Ipopt\ everything that it requires to call back to your
     696code whenever it needs functions evaluated (like the objective, the
     697Jacobian, etc.).  In each of the three sections that follow (C++, C,
     698and Fortran), we will first discuss how to code the problem
     699representation, and then how to code the executable.
    491700
    492701\subsection{The C++ Interface}
     
    494703language, however, we will lead you through each step of the
    495704implementation. 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.
     705that inherits off of the pure virtual base class, {\tt TNLP} ({\tt
     706  IpTNLP.hpp}). For the executable (the {\tt main} function) we will
     707make the call to \Ipopt\ through the {\tt IpoptApplication} class
     708({\tt IpIpoptApplication.hpp}). In addition, we will also be using the
     709SmartPtr class ({\tt IpSmartPtr.hpp}) which implements a reference
     710counting pointer that takes care of memory management (object
     711deletion) for you.
     712
     713After ``\texttt{make install}'' (see Section~\ref{sec.comp_and_inst}),
     714the 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}).
    503717
    504718\subsubsection{Coding the Problem Representation}\label{sec.cpp_problem}
     
    506720by coding the {\tt HS071\_NLP} class, a specific implementation of the
    507721{\tt TNLP} base class. In the executable, we will create an instance
    508 of the {\tt HS071\_NLP} class and give this class to Ipopt so it can
     722of the {\tt HS071\_NLP} class and give this class to \Ipopt\ so it can
    509723evaluate the problem functions through the {\tt TNLP} interface. If
    510724you 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 MyExample and
     725the completed example in the {\tt Example/hs071\_cpp} directory.
     726
     727Start by creating a new directory under Examples, called {\tt MyExample} and
    514728create the files {\tt hs071\_nlp.hpp} and {\tt hs071\_nlp.cpp}. In
    515729{\tt hs071\_nlp.hpp}, include {\tt IpTNLP.hpp} (the base class), tell
    516 the compiler that we are using the Ipopt namespace, and create the
     730the compiler that we are using the \Ipopt\ namespace, and create the
    517731declaration of the {\tt HS071\_NLP} class, inheriting off of {\tt
    518732  TNLP}. Have a look at the {\tt TNLP} class in {\tt IpTNLP.hpp}; you
     
    521735{\tt HS071\_NLP.cpp} using the descriptions given below. In {\tt
    522736  hs071\_nlp.cpp}, first include the header file for your class and
    523 tell the compiler that you are using the Ipopt namespace. A full
     737tell the compiler that you are using the \Ipopt\ namespace. A full
    524738version of these files can be found in the {\tt Examples/hs071\_cpp}
    525739directory.
    526740
    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}
     743virtual bool get_nlp_info(Index& n, Index& m, Index& nnz_jac_g,
     744                          Index& nnz_h_lag, IndexStyleEnum& index_style)
     745\end{verbatim}
     746Give \Ipopt\ the information about the size of the problem (and hence,
    531747the size of the arrays that it needs to allocate).
    532748\begin{itemize}
     
    536752\item {\tt nnz\_h\_lag}: (out), the number of nonzero entries in the Hessian.
    537753\item {\tt index\_style}: (out), the style used for row/col entries in the sparse matrix
    538 format (C\_STYLE: 0-based, FORTRAN\_STYLE: 1-based).
     754format ({\tt C\_STYLE}: 0-based, {\tt FORTRAN\_STYLE}: 1-based).
    539755\end{itemize}
    540 Ipopt uses this information when allocating the arrays that
     756\Ipopt\ uses this information when allocating the arrays that
    541757it will later ask you to fill with values. Be careful in this method
    542758since incorrect values will cause memory bugs which may be very
     
    552768entire problem.
    553769
     770\begin{footnotesize}
    554771\begin{verbatim}
    555772bool HS071_NLP::get_nlp_info(Index& n, Index& m, Index& nnz_jac_g,
     
    575792}
    576793\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}
     798virtual bool get_bounds_info(Index n, Number* x_l, Number* x_u,
     799                             Index m, Number* g_l, Number* g_u)
     800\end{verbatim}
     801Give \Ipopt\ the value of the bounds on the variables and constraints.
    582802\begin{itemize}
    583803\item {\tt n}: (in), the number of variables in the problem (dimension of {\tt x}).
     
    592812lower bound to a value less than or equal to the value of the option
    593813{\tt nlp\_lower\_bound\_inf} (data member of {\tt TNLP}) will cause
    594 Ipopt to assume no lower bound. Likewise, specifying the upper bound
     814\Ipopt\ to assume no lower bound. Likewise, specifying the upper bound
    595815above or equal to the value of the option {\tt nlp\_upper\_bound\_inf}
    596 will cause Ipopt to assume no upper bound.  These options, {\tt
     816will cause \Ipopt\ to assume no upper bound.  These options, {\tt
    597817  nlp\_lower\_bound\_inf} and {\tt nlp\_upper\_bound\_inf}, are set to
    598818$-10^{19}$ and $10^{19}$ respectively, by default, but may be modified
     
    603823the upper bound to some number greater than $10^{19}$. The second
    604824constraint is an equality constraint and we set both bounds to
    605 $40$. Ipopt recognizes this as an equality constraint and does not
     825$40$. \Ipopt\ recognizes this as an equality constraint and does not
    606826treat it as two inequalities.
    607827
     828\begin{footnotesize}
    608829\begin{verbatim}
    609830bool 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)
    611832{
    612833  // here, the n and m we gave IPOPT in get_nlp_info are passed back to us.
     
    640861}
    641862\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}
     867virtual 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}
     871Give \Ipopt\ the starting point before it begins iterating.
    648872\begin{itemize}
    649873\item {\tt n}: (in), the number of variables in the problem (dimension of {\tt x}).
     
    665889
    666890Depending on the options that have been set,
    667 Ipopt may or may not require bounds for the primal variables $x$, the
     891\Ipopt\ may or may not require bounds for the primal variables $x$, the
    668892bound multipliers $z$, and the equality multipliers $\lambda$. The
    669893boolean flags {\tt init\_x},{\tt init\_z}, and {\tt init\_lambda} tell
     
    677901them.
    678902
     903\begin{footnotesize}
    679904\begin{verbatim}
    680905bool 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)
    684909{
    685910  // Here, we assume we only have starting values for x, if you code
     
    699924}
    700925\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}
     930virtual bool eval_f(Index n, const Number* x,
     931                    bool new_x, Number& obj_value)
     932\end{verbatim}
    705933Return the value of the objective function as calculated using {\tt x}.
    706934\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)$).
    712943\end{itemize}
    713944
     
    715946any of the evaluation methods used the same $x$ values. This can be
    716947helpful when users have efficient implementations that calculate
    717 multiple outputs at once. Ipopt internally caches results from the
     948multiple outputs at once. \Ipopt\ internally caches results from the
    718949{\tt TNLP} and generally, this flag can be ignored.
    719950
     
    724955For our example, we ignore the {\tt new\_x} flag and calculate the objective.
    725956
     957\begin{footnotesize}
    726958\begin{verbatim}
    727959bool HS071_NLP::eval_f(Index n, const Number* x, bool new_x, Number& obj_value)
     
    734966}
    735967\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}
     972virtual bool eval_grad_f(Index n, const Number* x, bool new_x,
     973                         Number* grad_f)
     974\end{verbatim}
     975Return the gradient of the objective to \Ipopt, as calculated by the values in {\tt x}.
    741976\begin{itemize}
    742977\item {\tt n}: (in), the number of variables in the problem (dimension of {\tt x}).
     
    755990any of the evaluation methods used the same $x$ values. This can be
    756991helpful when users have efficient implementations that caclulate
    757 multiple outputs at once. Ipopt internally caches results from the
     992multiple outputs at once. \Ipopt\ internally caches results from the
    758993{\tt TNLP} and generally, this flag can be ignored.
    759994
     
    764999In our example, we ignore the {\tt new\_x} flag and calculate the
    7651000values for the gradient of the objective.
     1001\begin{footnotesize}
    7661002\begin{verbatim}
    7671003bool HS071_NLP::eval_grad_f(Index n, const Number* x, bool new_x, Number* grad_f)
     
    7771013}
    7781014\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}
     1019virtual bool eval_g(Index n, const Number* x,
     1020                    bool new_x, Index m, Number* g)}
     1021\end{verbatim}
     1022Give \Ipopt\ the value of the constraints as calculated by the values in {\tt x}.
    7851023\begin{itemize}
    7861024\item {\tt n}: (in), the number of variables in the problem (dimension of {\tt x}).
     
    7981036any of the evaluation methods used the same $x$ values. This can be
    7991037helpful when users have efficient implementations that calculate
    800 multiple outputs at once. Ipopt internally caches results from the
     1038multiple outputs at once. \Ipopt\ internally caches results from the
    8011039{\tt TNLP} and generally, this flag can be ignored.
    8021040
     
    8071045In our example, we ignore the {\tt new\_x} flag and calculate the
    8081046values for the gradient of the objective.
     1047\begin{footnotesize}
    8091048\begin{verbatim}
    8101049bool HS071_NLP::eval_g(Index n, const Number* x, bool new_x, Index m, Number* g)
     
    8191058}
    8201059\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}
     1064virtual 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}
    8261068Return either the structure of the Jacobian of the constraints, or the values for the
    8271069Jacobian of the constraints as calculated by the values in {\tt x}.
     
    8441086the sparse matrix format used in this method.
    8451087
    846 If the {\tt iRow} and {\tt jCol} arguments are not NULL, then Ipopt
     1088If the {\tt iRow} and {\tt jCol} arguments are not NULL, then \Ipopt
    8471089wants you to fill in the structure of the Jacobian (the row and column
    8481090indices only). At this time, the {\tt x} argument and the {\tt values}
     
    8501092
    8511093If the {\tt x} argument and the {\tt values} argument are not NULL,
    852 then Ipopt wants you to fill in the values of the Jacobian as
     1094then \Ipopt\ wants you to fill in the values of the Jacobian as
    8531095calculated from the array {\tt x} (using the same order as you used
    8541096when specifying the structure). At this time, the {\tt iRow} and {\tt
     
    8581100any of the evaluation methods used the same $x$ values. This can be
    8591101helpful when users have efficient implementations that caclulate
    860 multiple outputs at once. Ipopt internally caches results from the
     1102multiple outputs at once. \Ipopt\ internally caches results from the
    8611103{\tt TNLP} and generally, this flag can be ignored.
    8621104
     
    8681110specify it using the sparse format.
    8691111
     1112\begin{footnotesize}
    8701113\begin{verbatim}
    8711114bool 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)
    8741117{
    8751118  if (values == NULL) {
     
    9031146}
    9041147\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}
     1152virtual 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}
    9101157Return the structure of the Hessian of the Lagrangian or the values of the
    9111158Hessian of the Lagrangian as calculated by the values in {\tt obj\_factor},
     
    9311178\end{itemize}
    9321179
    933 If the {\tt iRow} and {\tt jCol} arguments are not NULL, then Ipopt
     1180If the {\tt iRow} and {\tt jCol} arguments are not NULL, then \Ipopt
    9341181wants you to fill in the structure of the Hessian (the row and column
    9351182indices only). In this case, the {\tt x}, {\tt lambda}, and {\tt
     
    9371184
    9381185If the {\tt x}, {\tt lambda}, and {\tt values} arrays are not NULL,
    939 then Ipopt wants you to fill in the values of the Hessian as
     1186then \Ipopt\ wants you to fill in the values of the Hessian as
    9401187calculated using {\tt x} and {\tt lambda} (using the same order as you
    9411188used when specifying the structure). In this case, the {\tt iRow} and
     
    9451192false if the last call to any of the evaluation methods used the same
    9461193values. This can be helpful when users have efficient implementations
    947 that caclulate multiple outputs at once. Ipopt internally caches
     1194that caclulate multiple outputs at once. \Ipopt\ internally caches
    9481195results from the {\tt TNLP} and generally, this flag can be ignored.
    9491196
     
    9551202sparse matrix format. Because the Hessian is symmetric, we only need to
    9561203specify the lower left corner.
     1204\begin{footnotesize}
    9571205\begin{verbatim}
    9581206bool 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)
    9621210{
    9631211  if (values == NULL) {
     
    10201268}
    10211269\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}
     1274virtual 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}
    10271279This is the only method that is not mentioned in Figure
    1028 \ref{fig.required_info}. This method is called by Ipopt after the
     1280\ref{fig.required_info}. This method is called by \Ipopt\ after the
    10291281algorithm has finished (successfully or even with most errors).
    10301282\begin{itemize}
     
    10461298        failed to find a more feasible point.
    10471299        \item {\tt INTERNAL\_ERROR}: An unknown internal error occurred. Please
    1048         contact the Ipopt Authors through the mailing list.
     1300        contact the \Ipopt\ Authors through the mailing list.
    10491301        \end{itemize}
    10501302\item {\tt n}: (in), the number of variables in the problem (dimension of {\tt x}).
     
    10651317the screen.
    10661318
     1319\begin{footnotesize}
    10671320\begin{verbatim}
    10681321void 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)
    10721325{
    10731326  // here is where we would store the solution to variables, or write to a file, etc
     
    10921345}
    10931346\end{verbatim}
     1347\end{footnotesize}
    10941348
    10951349This is all that is required for our {\tt HS071\_NLP} class and
    10961350the coding of the problem representation.
    10971351 
    1098 \subsubsection{Coding the Executable (main)}
     1352\subsubsection{Coding the Executable (\texttt{main})}
    10991353Now 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 Ipopt
     1354we need to code the main function that will call \Ipopt\ and ask \Ipopt\
    11011355to find a solution.
    11021356
    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}.
     1357Here, we must create an instance of our problem ({\tt HS071\_NLP}),
     1358create an instance of the \Ipopt\ solver (\texttt{IpoptApplication}),
     1359and ask the solver to find a solution. We always use the
     1360\texttt{SmartPtr} template class instead of raw C++ pointers when
     1361creating and passing \Ipopt\ objects. To find out more information
     1362about smart pointers and the {\tt SmartPtr} implementation used in
     1363\Ipopt, see Appendix \ref{app.smart_ptr}.
    11091364
    11101365Create the file {\tt MyExample.cpp} in the MyExample directory.
    11111366Include {\tt HS071\_NLP.hpp} and {\tt IpIpoptApplication.hpp}, tell
    1112 the compiler to use the Ipopt namespace, and implement the {\tt main}
    1113 function.
     1367the compiler to use the {\tt Ipopt} namespace, and implement the {\tt
     1368  main} function.
     1369\begin{footnotesize}
    11141370\begin{verbatim}
    11151371#include "IpIpoptApplication.hpp"
     
    11491405}
    11501406\end{verbatim}
     1407\end{footnotesize}
    11511408
    11521409The 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
     1413to its progress to the console, and return the {\tt SolverReturn}
     1414status.
    11571415
    11581416\subsubsection{Compiling and Testing the Example}
    11591417Our next task is to compile and test the code. If you are familiar
    11601418with 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,
     1419code, including the \Ipopt\ library {\tt libipopt.a} (and other
     1420necessary libraries).  If you are using Linux/UNIX, then a sample
     1421makefile exists already that was created by configure. Copy {\tt
     1422  Examples/hs071\_cpp/Makefile} into your {\tt MyExample} directory.
     1423This makefile was created for the {\tt hs071\_cpp} code, but it can be
     1424easily modified for your example problem. Edit the file, making the
     1425following changes,
    11671426
    11681427\begin{itemize}
     
    11771436{\tt \$ ./my\_example}
    11781437and you should see output resembling the following,
     1438\begin{footnotesize}
    11791439\begin{verbatim}
    11801440Total number of variables............................:        4
     
    12431503*** The problem solved!
    12441504\end{verbatim}
     1505\end{footnotesize}
    12451506
    12461507This 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,
    12481509Section \ref{sec.jnlst} to learn about adjusting the output produced
    1249 from Ipopt through the use of the Journalist, and Section
     1510from \Ipopt\ through the use of the Journalist, and Section
    12501511\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}.
     1512customize the behavior of \Ipopt.
     1513
     1514\subsection{The C Interface}\label{sec.cinterface}
     1515The 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
     1520reading this section, it will be helpful to have a look at this file.
     1521
     1522In order to solve an optimization problem with the C interface, one
     1523has 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.}
     1526with the function {\tt CreateIpoptProblem}, which lateron has to be
     1527passed to the {\tt IpoptSolve} function.
     1528
     1529The {\tt IpoptProblem} created by {\tt CreateIpoptProblem} contains
     1530the problem dimensions, the variable and constraint bounds, and the
     1531function pointers for callbacks that will be used to evaluate the NLP
     1532problem functions and their derivatives (see also the discussion of
     1533the C++ methods {\tt get\_nlp\_info} and {\tt get\_bounds\_info} in
     1534Section~\ref{sec.cpp_problem} for information about the arguments of
     1535{\tt CreateIpoptProblem}).
     1536
     1537The 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 one-to-one to the
     1540arguments for the C++ methods discussed in
     1541Section~\ref{sec.cpp_problem}; for example, for the meaning of $\tt
     1542n$, $\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
     1544functions should return {\tt TRUE}, unless there was a problem doing
     1545the requested function/derivative evaluation at the given point {\tt
     1546  x}.
     1547
     1548Note the additional argument of type {\tt UserDataPtr} in the callback
     1549functions.  This pointer argument is available for you to communicate
     1550information between the main program that calls {\tt IpoptSolve} and
     1551any of the callback functions.  This pointer is simply passed
     1552unmodified by \Ipopt\ amoung those functions.  For example, you can
     1553use this to pass constants that define the optimization problem and
     1554are computed before the optimization in the main C program to the
     1555callback functions.
     1556
     1557After an {\tt IpoptProblem} has been created, you can set algorithmic
     1558options for \Ipopt\ (see Section~\ref{sec.options}) using the {\tt
     1559  AddIpopt*Option} functions.  Finally, the \Ipopt\ algorithm is
     1560called with {\tt IpoptSolve}, giving \Ipopt\ the {\tt IpoptProblem},
     1561the starting point, and arrays to store the solution values (primal
     1562and dual variables), if desired.  Finally, after everything is done,
     1563you should call {\tt FreeIpoptProblem} to release internal memory that
     1564is still allocated inside \Ipopt.
     1565
     1566In 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
     1568interface.  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
     1584In order to implement the example problem on your own, create a new
     1585directory {\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
     1589implementations for the five callback functions.  Have a look at the
     1590C++ 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
     1593prototypes, but are implemented almost identically to the C++ code.
     1594See the completed example in {\tt Examples/hs071\_c/hs071\_c.c} if you
     1595are not sure how to do this.
    12831596
    12841597We 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
     1600variable and constraint bounds, and the function pointers to the
     1601callback routines. The {\tt IpoptSolve} function requires the {\tt
     1602  IpoptProblem}, the starting point, and allocated arrays for the
     1603solution.  The {\tt main} function from the example is shown next, and
     1604discussed below.
     1605
     1606%in Figure~\ref{fig:cexample-main}.
     1607%\begin{figure}
     1608%  \centering
     1609\begin{footnotesize}
    12911610\begin{verbatim}
    12921611int main()
     
    13011620  enum ApplicationReturnStatus status; /* Solve return code */
    13021621  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 */
    13031626  Number obj;                          /* objective value */
    13041627  Index i;                             /* generic counter */
    13051628 
     1629  /* set the number of variables and allocate space for the bounds */
    13061630  n=4;
    13071631  x_L = (Number*)malloc(sizeof(Number)*n);
    13081632  x_U = (Number*)malloc(sizeof(Number)*n);
     1633  /* set the values for the variable bounds */
    13091634  for (i=0; i<n; i++) {
    13101635    x_L[i] = 1.0;
     
    13121637  }
    13131638
     1639  /* set the number of constraints and allocate space for the bounds */
    13141640  m=2;
    13151641  g_L = (Number*)malloc(sizeof(Number)*m);
    13161642  g_U = (Number*)malloc(sizeof(Number)*m);
     1643  /* set the values of the constraint bounds */
    13171644  g_L[0] = 25; g_U[0] = 2e19;
    13181645  g_L[1] = 40; g_U[1] = 40;
    13191646
     1647  /* create the IpoptProblem */
    13201648  nlp = CreateIpoptProblem(n, x_L, x_U, m, g_L, g_U, 8, 10, 0,
    13211649                           &eval_f, &eval_g, &eval_grad_f,
    13221650                           &eval_jac_g, &eval_h);
    13231651 
    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", 1e-9);
     1661  AddIpoptStrOption(nlp, "mu_strategy", "adaptive");
     1662
     1663  /* allocate space for the initial point and set the values */
    13251664  x = (Number*)malloc(sizeof(Number)*n);
    13261665  x[0] = 1.0;
     
    13291668  x[3] = 1.0;
    13301669
    1331   AddIpoptNumOption(nlp, "tol", 1e-9);
    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  }
    13351694 
     1695  /* free allocated memory */
    13361696  FreeIpoptProblem(nlp);
    1337   free(x_L);
    1338   free(x_U);
    1339   free(g_L);
    1340   free(g_U);
    13411697  free(x);
     1698  free(mult_x_L);
     1699  free(mult_x_U);
    13421700
    13431701  return 0;
    13441702}
    13451703\end{verbatim}
     1704\end{footnotesize}
     1705%  \caption{{\tt main} function for C example}
     1706%  \label{fig:cexample-main}
     1707%\end{figure}
     1708
    13461709Here, we declare all the necessary variables and set the dimensions of
    13471710the problem.  The problem has 4 variables, so we set {\tt n} and
    13481711allocate 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
     1713program). We then set the values for the variable bounds.
     1714
     1715The problem has 2 constraints, so we set {\tt m} and allocate space
     1716for 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
     1722through \Ipopt\ options.  The second constraint is an equality, so we
     1723set both the upper and the lower bound to 40.
    13601724
    13611725We next create an instance of the {\tt IpoptProblem} by calling {\tt
    13621726CreateIpoptProblem}, giving it the problem dimensions and the variable
    13631727and 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 the
     1728nele\_hess} are the number of elements in Jacobian and the Hessian,
     1729respectively. See Appendix~\ref{app.triplet} for a description of the
    13661730sparse matrix format. The {\tt index\_style} argument specifies whether
    13671731we want to use C style indexing for the row and column indices of the
    13681732matrices or Fortran style indexing. Here, we set it to {\tt 0} to
    13691733indicate C style.  We also include the references to each of our
    1370 callback functions. Ipopt can use these function pointers to ask for
     1734callback functions. \Ipopt\ uses these function pointers to ask for
    13711735evaluation of the NLP when required.
    13721736
    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.
     1737After freeing the bound arrays that are no longer required, the next
     1738two lines illustrate how you can change the value of options through
     1739the interface.  \Ipopt\ options can also be changed by creating a {\tt
     1740PARAMS.DAT} file (see Section~\ref{sec.options}). We next allocate
     1741space for the initial point and set the values as given in the problem
     1742definition.
     1743
     1744The call to {\tt IpoptSolve} can provide us with information about the
     1745solution, but most of this is optional. Here, we want values for the
     1746bound multipliers at the solution and we allocate space for these.
    13811747
    13821748We can now make the call to {\tt IpoptSolve} and find the solution of
    13831749the problem. We pass in the {\tt IpoptProblem}, the starting point
    1384 {\tt x} (Ipopt will use this variable to return the solution as
    1385 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}, Ipopt will
     1750{\tt x} (\Ipopt\ will use this array to return the solution as well).
     1751The next 5 arguments are pointers so \Ipopt\ can fill in values at the
     1752solution.  If these pointers are set to {\tt NULL}, \Ipopt\ will
    13871753ignore that entry.  For example, here, we do not want the constraint
    13881754residuals at the solution or the equality multipliers, so we set those
    13891755entries to {\tt NULL}. We do want the value of the objective, and the
    13901756multipliers 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
     1758to you in the callback functions.
     1759
     1760The return code is an ApplicationReturnStatus enumeration, see the
     1761header file {\tt ReturnCodes\_inc.h} which is installed along {\tt
     1762  IpStdCInterface.h} in the \Ipopt\ include directory.
     1763
     1764After the problem has solved, we check the status and print the
     1765solution if successful. Finally, we free the {\tt IpoptProblem} and
     1766the remaining memory, and return from {\tt main}.
     1767
     1768\subsection{The Fortran Interface}
     1769
     1770The Fortran interface is essentially a wrapper of the C interface
     1771discussed in Section~\ref{sec.cinterface}.  The way to hook up \Ipopt\
     1772in a Fortran program is very similar to how it is done for the C
     1773interface, and the functions of the Fortran interface correspond
     1774one-to-one to the those of the C interface, including their arguments.
     1775You 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
     1779The 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 64-bit 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 user-provided 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
    13991809
    14001810\section{Ipopt Options}\label{sec.options}
     
    14021812algorithm.  Options are all identified by a string name and their
    14031813values can be of one of three types, Number (real), Integer, or
    1404 string. Number options are used for things like tolerances, integer
     1814String. Number options are used for things like tolerances, integer
    14051815options are used for things like maximum number of iterations, and
    14061816string options are used for setting algorithm details, like the NLP
     
    14311841how this is done.
    14321842
    1433 A subset of Ipopt options are available through AMPL. To set options
     1843A subset of \Ipopt\ options are available through AMPL. To set options
    14341844through AMPL, use the internal AMPL command {\tt options}.  For
    14351845example, \\
     
    14371847max\_iter=500''} \\
    14381848is a valid options command in AMPL. The most common
    1439 options are referenced in Appendix \ref{app.options_ref}. These are also
     1849options are referenced in Appendix~\ref{app.options_ref}. These are also
    14401850the options that are available through AMPL using the {\tt options}
    14411851command. To specify other options when using AMPL, you can always
     
    14561866as a course project for \textit{47852 Open Source Software for
    14571867Optimization}, taught by Prof. Fran\c cois Margot at Tepper School of
    1458 Business, Carnegie Mellon University. The authors of Ipopt greatly
     1868Business, Carnegie Mellon University. The authors of \Ipopt\ greatly
    14591869thank Yoshi for his efforts.
    14601870
    1461 \begin{thebibliography}{99}
    1462 \bibitem{COINORWeb}
    1463 http://www.coin-or.org
    1464 \bibitem{AndreasPaper}
    1465 W\"achter, A. and Biegler, L.T.:''On the Implementation of a Primal-Dual
    1466         Interior Point Filter Line Search Algorithm for Large-Scale
    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 Large-Scale 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}
    14771879
    14781880
    14791881\appendix
    14801882\section{Triplet Format for Sparse Matrices}\label{app.triplet}
    1481 Ipopt was designed for optimizing large sparse nonlinear programs.
     1883\Ipopt\ was designed for optimizing large sparse nonlinear programs.
    14821884Because 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.
    14831885Consider the matrix,
     
    15091911  sparse representation grows linearly in the number of nonzeros.}
    15101912
    1511 In triplet format used in these Ipopt interfaces, the row and column
     1913In triplet format used in these \Ipopt\ interfaces, the row and column
    15121914numbers are 1-based {\bf have table for both 0- and 1-based}, and the
    15131915above matrix is represented by
     
    15541956
    15551957It is very important to use SmartPtr's instead of raw pointers when
    1556 passing objects to Ipopt. Internally, Ipopt uses smart pointers for
     1958passing objects to \Ipopt. Internally, \Ipopt\ uses smart pointers for
    15571959referencing objects. If you use a raw pointer in your executable, the
    1558 object's counter will NOT get incremented. Then, when Ipopt uses smart
     1960object's counter will NOT get incremented. Then, when \Ipopt\ uses smart
    15591961pointers inside its own code, the counter will get
    1560 incremented. However, before Ipopt returns control to your code, it
     1962incremented. However, before \Ipopt\ returns control to your code, it
    15611963will decrement as many times as it incremented and the counter will
    1562 return to zero. Therefore, Ipopt will delete the object. When control
     1964return to zero. Therefore, \Ipopt\ will delete the object. When control
    15631965returns to you, you now have a raw pointer that points to a deleted
    15641966object.
     
    15661968This might sound difficult to anyone not familiar with the use of
    15671969smart pointers, but just follow one simple rule; always use a SmartPtr
    1568 when creating or passing an Ipopt object.
     1970when creating or passing an \Ipopt\ object.
    15691971
    15701972\section{Options Reference} \label{app.options_ref}
     
    18022204   get a more accurate solution to the linear system
    18032205\end{verbatim}
     2206
     2207\subsection{Detailed Installation Information}\label{ExpertInstall}
     2208
     2209
     2210
    18042211\end{document}
Note: See TracChangeset for help on using the changeset viewer.