# source:branches/parallel/Ipopt/contrib/AsNMPC/doc/usage.tex@1887

Last change on this file since 1887 was 1887, checked in by andreasw, 3 years ago

synchronized with trunk rev 1886; fixed bug in Matrix-vector product for parallel matrix

File size: 7.8 KB
Line
1\documentclass[a4paper]{article}
2\usepackage{listings} \lstset{numbers=left, numberstyle=\tiny, numbersep=5pt} \lstset{language=Perl}
3
4\begin{document}
5\section{Introduction}
6The advanced step NMPC code compiles into a library that holds the code for the Schur complement computation, and an executable which holds an interface to AMPL. This document describes the usage of the asNMPC code using the C++ and the AMPL interface.
7
8\section{AMPL Interface}
9Since many models are written in AMPL, this interface makes it very easy to apply any of the capabilities of the AsNMPC code to your existing models. The usage of the different tools using this AMPL interface is described below.
11Given a discretized DAE model of an optimal control problem in AMPL, applying the advanced step algorithm is very easy. Suppose a model
12\begin{equation}
13  \label{discretized_OCP_asnmpc}
14  \begin{array}{cc}
15    \min\limits_z& \phi(z)\\
16    s.t.& c(z) = 0\\
17    & z_0-w_0 = 0\\
18    & z\geq 0
19  \end{array}
20\end{equation}
21Not that for the asNMPC formulation, there need to be explicitly defined variables $z_0$ for the initial values (whereas usually, these are just parameters). To define the values for these new variables, additional initial value constraints $z_0-w_0=0$ have to be added. Given this formulation, only four suffixes need to be set to initialize the asNMPC problem:
22\begin{description}
23\item[nmpc\_state\_0] This suffix has to be set for the initial variables $z_0$. The suffixes have to be set to values from 1 to length($z_0$). This enumeration is crucial.
24\item[nmpc\_state\_1] This suffix has to be set for the discretized variables at timestep $t$ corresponding to the inital variables $z_0$. They have to be indexed the same way as nmpc\_state\_0.
25\item[nmpc\_state\_value\_1] This suffix holds the perturbed values for the variables at timestep $t$. It has to be set for the same variables as nmpc\_state\_1.
26\item[nmpc\_init\_constr] This suffix has to be set for the inital value constraints $z_0 - w_0=0$. If a constraint is an initial value constraint, set this suffix to 1 (no indexing is necessary).
27\end{description}
28If you have set these suffixes, the only thing missing is to enable the asNMPC algorithm by setting the solver option
29\begin{verbatim}
30option ipopt_options 'run_nmpc yes';
31\end{verbatim}
32This option can alternatively be set in the ipopt.opt file.
33
34To make sure that the initial value constraints are not eliminated by AMPL, the presolve feature should be turned off as well:
35\begin{verbatim}
36option presolve 0;
37\end{verbatim}
38
39After the algorithm has completed successfully, the solution is stored in the following AMPL suffixes:
40\begin{description}
41\item[nmpc\_sol\_state\_1] This suffix is set for the variables and the constraints. It holds the variable and constraint multiplier values computed in the advanced step algorithm
42\item[nmpc\_sol\_state\_1\_z\_L] This suffix holds the advanced step bound multipliers for the lower bounds on the variables.
43\item[nmpc\_sol\_state\_1\_z\_U] ... the same for the upper bounds.
44\end{description}
45
46An example implementation of the above is provided in the directory
47\begin{verbatim}
48examples/hicks_ampl
49\end{verbatim}
50There, the asNMPC code is applied to the reactor model described in \cite{Hicks1971}.
51
52The AMPL interface as described above only works for simulations, where the future measurement is known beforehand. Using the AMPL model definiton with an outside measurement device is generally possible. If you intend on using this feature in a real-time environment, please contact the author.
53\subsection{Parametric Sensitivity}
54The parametric sensitivity feature uses the same suffixes as the asNMPC algorithm. The parameters need to be defined as variables and set using the initial value constraints described above. The only difference in the parametric case is that the suffixes nmpc\_state\_0 and nmpc\_state\_1 are not set for different variables, but both for the parameters.
55
56A small example of the parametric sensitivity feature is located in the directory
57\begin{verbatim}
58examples/parametric_ampl
59\end{verbatim}
60\subsection{Reduced Hessian}
61The reduced hessian feature is even easier to use. The critical problem is to decide which variables will be free variables at the optimal solution. The free variables have to be marked by setting the suffix
62\begin{verbatim}
63red_hessian
64\end{verbatim}
65to $1..n$, where $n$ is the number of free variables. The columns of the inverse reduced hessian, which will be printed, is determined by the ordering of these indices. The algorithm is enabled by setting the solver option
66\begin{verbatim}
67option ipopt_options 'compute_red_hessian yes';
68\end{verbatim}
69
70An example of the reduced hessian calculation can be found in
71\begin{verbatim}
72examples/red_hess_ampl
73\end{verbatim}
74\section{C++ Interface}
75The C++ interface is very simple to apply to an existing {\tt Ipopt::TNLP} implementation. With the member function {\tt TNLP::::get\_var\_con\_metadata}, Ipopt provides a feature very similar to that of AMPL suffixes.
76
77The procedure of making a TNLP class capable to be used with the asNMPC code follows the same lines as in AMPL. First, the parameters / initial values have to be introduced as variables. Then, the initial value equations need to be added to the constraints, and the jacobian computation has to be adjusted accordingly. Finally, the suffixes have to be set the same way they would in AMPL as described above, using the member function {\tt TNLP::::get\_var\_con\_metadata}. This is illustrated in the examples {\tt examples/redhess\_cpp} and {\tt examples/parametric\_cpp}
78\section{Options}
79There are several new options that can be set in the {\tt ipopt.opt} file, that determine the behavior of the asNMPC code. The most important options are the ones that turn the execution of the additional post-optimal code on and off. These options are
80\begin{verbatim}
81run_nmpc yes
82\end{verbatim}
83for the advanced step and parametric sensitivity computation, and
84\begin{verbatim}
85compute_red_hessian yes
86\end{verbatim}
87for the reduced hessian computation.
88
89Further options for the advanced step code are
90\begin{description}
91\item[select\_step] This option determines which formula is used to compute the advanced step. The options are \texttt{advanced} for the full advanced step with Schur complement and multiplier correction, \texttt{sensitivity} for the Schur step without multiplier correction, \texttt{ift} for the fast backsolve without Schur complement computation, but with multiplier correction, and finally \texttt{iftsensitivity} the same as \texttt{ift}, but without multiplier correction. For parametric problems, the options \texttt{sensitivity} and \texttt{iftsensitivity} should be used, whereas for advanced step problems, the options \texttt{advanced} and \texttt{ift} are more suitable.
92\item[n\_nmpc\_steps] In general, the advanced step is designed to accomodate an arbitrary number of advanced steps. Right now, however, this value has to be set to either 0 or 1.
93\item[nmpc\_boundcheck] If set to \texttt{yes}, this option turns on the bound correction algorithm within the advanced step.
94\item[nmpc\_bound\_eps] This option sets the value by which the bounds are to be relaxed in the boundcheck mode.
95\item[nmpc\_max\_pdpert] For certain problems, IPOPT uses inertia correction of the primal dual matrix to achieve better convergence properties. This inertia correction changes the matrix and renders it useless for the use with AsNMPC. This option sets an upper bound, which the inertia correction may have. If any of the inertia correction values is above this bound, the AsNMPC algorithm is aborted.
96\item[rh\_eigendecomp] If this option is set to yes, the reduced hessian code will compute the eigenvalue decomposition of the reduced hessian matrix.
97\end{description}
98\bibliographystyle{plain}
99\bibliography{asnmpc}
100\end{document}
Note: See TracBrowser for help on using the repository browser.