IPOPT Call the IPOPT constrained, nonlinear solver.
The basic function call is
[x, info] = IPOPT(x0,funcs,options)
The first input is either a matrix or a cell array of matrices. It
declares the starting point for the solver.
CALLBACK FUNCTIONS
The second input must be struct containing function handles for various
MATLAB routines. For more information on using functions and function
handles in MATLAB, type HELP FUNCTION and HELP FUNCTION_HANDLE in the
MATLAB prompt.
funcs.objective (required)
Calculates the objective function at the current point. It takes one
point, the current iterate x. For example, the definition of the
objective function for the Hock & Schittkowski (H&S) test problem #71
(with 4 optimization variables) would be
function f = objective (x)
f = x(1)*x(4)*sum(x(1:3)) + x(3);
funcs.gradient (required)
Computes the gradient of the objective at the current point. It takes
one input, the current iterate x. For H&S test problem #71, the
definition of the gradient callback would be
function g = gradient (x)
g = [ x(1)*x(4) + x(4)*sum(x(1:3))
x(1)*x(4)
x(1)*x(4) + 1
x(1)*sum(x(1:3)) ];
funcs.constraints (optional)
This function is only required if there are constraints on your
variables. It evaluates the constraint functions at the current
point. It takes one input, x. The return value is a vector of length
equal to the number of constraints (it must be of the same length as
options.cl and options.cu). For H&S test problem #71, the
callback definition would be
function c = constraints (x)
c = [ prod(x); sum(x.^2) ];
funcs.jacobian (optional)
This function is only required if there are constraints on your
variables. Evaluates the Jacobian of the constraints at the current
point. It takes one input, x. The output must always be an M x N
sparse matrix, where M is the number of constraints and N is the
number of variables. Type HELP SPARSE for more information on
constructing sparse matrices in MATLAB. The definition of the
callback function for H&S test problem #71 would be
function J = jacobian (x)
sparse([ prod(x)./x; 2*x ]);
Notice that the return value is a sparse matrix.
funcs.jacobianstructure (optional)
This function is only required if there are constraints on your
variables. It takes no inputs. The return value is a sparse
matrix whereby an entry is nonzero if and only if the Jacobian of
the constraints is nonzero at ANY point. The callback function for
the H&S test problem #71 simply returns a 2 x 4 matrix of ones in
the sparse matrix format:
function J = jacobianstructure()
J = sparse(ones(2,4));
funcs.hessian (optional)
Evaluates the Hessian of the Lagrangian at the current point. It
must be specified unless you choose to use the limited-memory
quasi-Newton approximation to the Hessian (see below).
The callback function has three inputs: the current point (x), a
scalar factor on the objective (sigma), and the Lagrange multipliers
(lambda), a vector of length equal to the number of constraints. The
function should compute
sigma*H + lambda(1)*G1 + ... + lambda(M)*GM
where M is the number of constraints, H is the Hessian of the
objective and the G's are the Hessians of the constraint
functions. The output must always be an N x N sparse, lower triangular
matrix, where N is the number of variables. In other words, if X is
the output value, then X must be the same as TRIL(X).
Here is an implementation of the Hessian callback routine for the
H&S test problem #71:
function H = hessian (x, sigma, lambda)
H = sigma*[ 2*x(4) 0 0 0;
x(4) 0 0 0;
x(4) 0 0 0;
2*x(1)+x(2)+x(3) x(1) x(1) 0 ];
H = H + lambda(1)*[ 0 0 0 0;
x(3)*x(4) 0 0 0;
x(2)*x(4) x(1)*x(4) 0 0;
x(2)*x(3) x(1)*x(3) x(1)*x(2) 0 ];
H = sparse(H + lambda(2)*diag([2 2 2 2]));
funcs.hessianstructure (optional)
This function serves the same purpose as funcs.jacobianstructure, but
for the Hessian matrix. Again, it is not needed if you are using the
limited-memory quasi-Newton approximation to the Hessian. It takes no
inputs, and must return a sparse, lower triangular matrix. For H&S
test problem #71, the MATLAB callback routine is fairly
straightforward:
function H = hessianstructure()
H = sparse(tril(ones(4)));
funcs.iterfunc (optional)
An additional callback routine that is called once per algorithm
iteration. It takes three inputs: the first is the current iteration
of the algorithm, the second is the current value of the objective,
and the third is a structure containing fields x, inf_pr, inf_du, mu,
d_norm, regularization_size, alpha_du, alpha_pr, and ls_trials. This
function should always return true unless you want IPOPT to terminate
prematurely for whatever reason. If you would like to use the third
input to iterfunc along with auxdata functionality, you will need to
modify the appropriate section of ipopt_auxdata.m.
OPTIONS
The options are passed through the third input. What follows is a
description of the fields you may optionally specify.
options.lb
Specify lower bounds on the variables. It must have the same number
of elements as x0. Set an entry to -Inf to specify no lower bound.
options.ub
Specify upper bounds on the variables. It must have the same number
of elements as x0. Set an entry to Inf to specify no upper bound.
options.cl, options.cu
Set lower and upper bounds on the constraints. Each should be a
vector of length equal to the number of constraints. As before, a
bound is removed by setting the entry to -Inf or +Inf. An equality
constraint is achieved by setting cl(i) = cu(i).
options.auxdata
Optionally, one may choose to pass additional auxiliary data to the
MATLAB callback routines listed above through the function call. For
instance, the objective callback function now takes two inputs, x and
auxdata. The auxiliary data may not change through the course of the
IPOPT optimization. The auxiliary data keep the same values as they
possessed in the initial call. If you need variables that change over
time, you may want to consider global variables (type HELP
GLOBAL). See the lasso.m file in the examples subdirectory for an
illustration of how the auxiliary data is passed to the various
callback functions. Starting with Ipopt version 3.11, you must call
ipopt_auxdata(x0,funcs,options) to use auxdata functionality.
options.zl, options.zu, options.lambda
These fields specify the initial value for the Lagrange multipliers,
which is especially useful for "warm starting" the interior-point
solver. They specify the Lagrange multipliers corresponding to the
lower bounds on the variables, upper bounds on the variables, and
constraints, respectively.
options.ipopt
Finally, you may also change the settings of IPOPT through this
field. For instance, to turn off the IPOPT output, use the
limited-memory BFGS approximation to the Hessian, and turn on the
derivative checker, do the following:
options.ipopt.print_level = 0;
options.ipopt.hessian_approximation = 'limited-memory';
options.ipopt.derivative_test = 'first-order';
For more details, see the documentation on the IPOPT website.
OUTPUTS
If the solver successfully converges to a stationary point or terminated
without an unrecoverable error, the function IPOPT outputs the candidate
solution x. In all other cases, an error is thrown. It also outputs some
additional information:
info.zl, info.zu, info.lambda
The value of the Lagrange multipliers at the solution. See the
"options" for more information on the Lagrange multipliers.
info.status
Upon termination, this field will take on one of these following
values (for a more up-to-date listing, see the IpReturnCodes.h header
file in the IPOPT C++ source directory):
0 solved
1 solved to acceptable level
2 infeasible problem detected
3 search direction becomes too small
4 diverging iterates
5 user requested stop
-1 maximum number of iterations exceeded
-2 restoration phase failed
-3 error in step computation
-10 not enough degrees of freedom
-11 invalid problem definition
-12 invalid option
-13 invalid number detected
-100 unrecoverable exception
-101 non-IPOPT exception thrown
-102 insufficient memory
-199 internal error
info.iter, info.cpu
Number of iterations and CPU time (in seconds) taken by the Ipopt run
Finally, for more information, please consult the following webpages:
http://www.cs.ubc.ca/~pcarbo/ipopt-for-matlab
http://projects.coin-or.org/Ipopt
Copyright (C) 2008 Peter Carbonetto. All Rights Reserved.
This code is published under the Eclipse Public License.
Author: Peter Carbonetto
Dept. of Computer Science
University of British Columbia
September 19, 2008
Downloaded binaries from http://www.coin-or.org/download/binary/Ipopt/I
popt-3.11.8-linux64mac64win32win64-matlabmexfiles.zip on 3/22/20160001 % IPOPT Call the IPOPT constrained, nonlinear solver. 0002 % The basic function call is 0003 % 0004 % [x, info] = IPOPT(x0,funcs,options) 0005 % 0006 % The first input is either a matrix or a cell array of matrices. It 0007 % declares the starting point for the solver. 0008 % 0009 % CALLBACK FUNCTIONS 0010 % 0011 % The second input must be struct containing function handles for various 0012 % MATLAB routines. For more information on using functions and function 0013 % handles in MATLAB, type HELP FUNCTION and HELP FUNCTION_HANDLE in the 0014 % MATLAB prompt. 0015 % 0016 % funcs.objective (required) 0017 % 0018 % Calculates the objective function at the current point. It takes one 0019 % point, the current iterate x. For example, the definition of the 0020 % objective function for the Hock & Schittkowski (H&S) test problem #71 0021 % (with 4 optimization variables) would be 0022 % 0023 % function f = objective (x) 0024 % f = x(1)*x(4)*sum(x(1:3)) + x(3); 0025 % 0026 % funcs.gradient (required) 0027 % 0028 % Computes the gradient of the objective at the current point. It takes 0029 % one input, the current iterate x. For H&S test problem #71, the 0030 % definition of the gradient callback would be 0031 % 0032 % function g = gradient (x) 0033 % g = [ x(1)*x(4) + x(4)*sum(x(1:3)) 0034 % x(1)*x(4) 0035 % x(1)*x(4) + 1 0036 % x(1)*sum(x(1:3)) ]; 0037 % 0038 % funcs.constraints (optional) 0039 % 0040 % This function is only required if there are constraints on your 0041 % variables. It evaluates the constraint functions at the current 0042 % point. It takes one input, x. The return value is a vector of length 0043 % equal to the number of constraints (it must be of the same length as 0044 % options.cl and options.cu). For H&S test problem #71, the 0045 % callback definition would be 0046 % 0047 % function c = constraints (x) 0048 % c = [ prod(x); sum(x.^2) ]; 0049 % 0050 % funcs.jacobian (optional) 0051 % 0052 % This function is only required if there are constraints on your 0053 % variables. Evaluates the Jacobian of the constraints at the current 0054 % point. It takes one input, x. The output must always be an M x N 0055 % sparse matrix, where M is the number of constraints and N is the 0056 % number of variables. Type HELP SPARSE for more information on 0057 % constructing sparse matrices in MATLAB. The definition of the 0058 % callback function for H&S test problem #71 would be 0059 % 0060 % function J = jacobian (x) 0061 % sparse([ prod(x)./x; 2*x ]); 0062 % 0063 % Notice that the return value is a sparse matrix. 0064 % 0065 % funcs.jacobianstructure (optional) 0066 % 0067 % This function is only required if there are constraints on your 0068 % variables. It takes no inputs. The return value is a sparse 0069 % matrix whereby an entry is nonzero if and only if the Jacobian of 0070 % the constraints is nonzero at ANY point. The callback function for 0071 % the H&S test problem #71 simply returns a 2 x 4 matrix of ones in 0072 % the sparse matrix format: 0073 % 0074 % function J = jacobianstructure() 0075 % J = sparse(ones(2,4)); 0076 % 0077 % funcs.hessian (optional) 0078 % 0079 % Evaluates the Hessian of the Lagrangian at the current point. It 0080 % must be specified unless you choose to use the limited-memory 0081 % quasi-Newton approximation to the Hessian (see below). 0082 % 0083 % The callback function has three inputs: the current point (x), a 0084 % scalar factor on the objective (sigma), and the Lagrange multipliers 0085 % (lambda), a vector of length equal to the number of constraints. The 0086 % function should compute 0087 % 0088 % sigma*H + lambda(1)*G1 + ... + lambda(M)*GM 0089 % 0090 % where M is the number of constraints, H is the Hessian of the 0091 % objective and the G's are the Hessians of the constraint 0092 % functions. The output must always be an N x N sparse, lower triangular 0093 % matrix, where N is the number of variables. In other words, if X is 0094 % the output value, then X must be the same as TRIL(X). 0095 % 0096 % Here is an implementation of the Hessian callback routine for the 0097 % H&S test problem #71: 0098 % 0099 % function H = hessian (x, sigma, lambda) 0100 % H = sigma*[ 2*x(4) 0 0 0; 0101 % x(4) 0 0 0; 0102 % x(4) 0 0 0; 0103 % 2*x(1)+x(2)+x(3) x(1) x(1) 0 ]; 0104 % H = H + lambda(1)*[ 0 0 0 0; 0105 % x(3)*x(4) 0 0 0; 0106 % x(2)*x(4) x(1)*x(4) 0 0; 0107 % x(2)*x(3) x(1)*x(3) x(1)*x(2) 0 ]; 0108 % H = sparse(H + lambda(2)*diag([2 2 2 2])); 0109 % 0110 % funcs.hessianstructure (optional) 0111 % 0112 % This function serves the same purpose as funcs.jacobianstructure, but 0113 % for the Hessian matrix. Again, it is not needed if you are using the 0114 % limited-memory quasi-Newton approximation to the Hessian. It takes no 0115 % inputs, and must return a sparse, lower triangular matrix. For H&S 0116 % test problem #71, the MATLAB callback routine is fairly 0117 % straightforward: 0118 % 0119 % function H = hessianstructure() 0120 % H = sparse(tril(ones(4))); 0121 % 0122 % funcs.iterfunc (optional) 0123 % 0124 % An additional callback routine that is called once per algorithm 0125 % iteration. It takes three inputs: the first is the current iteration 0126 % of the algorithm, the second is the current value of the objective, 0127 % and the third is a structure containing fields x, inf_pr, inf_du, mu, 0128 % d_norm, regularization_size, alpha_du, alpha_pr, and ls_trials. This 0129 % function should always return true unless you want IPOPT to terminate 0130 % prematurely for whatever reason. If you would like to use the third 0131 % input to iterfunc along with auxdata functionality, you will need to 0132 % modify the appropriate section of ipopt_auxdata.m. 0133 % 0134 % OPTIONS 0135 % 0136 % The options are passed through the third input. What follows is a 0137 % description of the fields you may optionally specify. 0138 % 0139 % options.lb 0140 % 0141 % Specify lower bounds on the variables. It must have the same number 0142 % of elements as x0. Set an entry to -Inf to specify no lower bound. 0143 % 0144 % options.ub 0145 % 0146 % Specify upper bounds on the variables. It must have the same number 0147 % of elements as x0. Set an entry to Inf to specify no upper bound. 0148 % 0149 % options.cl, options.cu 0150 % 0151 % Set lower and upper bounds on the constraints. Each should be a 0152 % vector of length equal to the number of constraints. As before, a 0153 % bound is removed by setting the entry to -Inf or +Inf. An equality 0154 % constraint is achieved by setting cl(i) = cu(i). 0155 % 0156 % options.auxdata 0157 % 0158 % Optionally, one may choose to pass additional auxiliary data to the 0159 % MATLAB callback routines listed above through the function call. For 0160 % instance, the objective callback function now takes two inputs, x and 0161 % auxdata. The auxiliary data may not change through the course of the 0162 % IPOPT optimization. The auxiliary data keep the same values as they 0163 % possessed in the initial call. If you need variables that change over 0164 % time, you may want to consider global variables (type HELP 0165 % GLOBAL). See the lasso.m file in the examples subdirectory for an 0166 % illustration of how the auxiliary data is passed to the various 0167 % callback functions. Starting with Ipopt version 3.11, you must call 0168 % ipopt_auxdata(x0,funcs,options) to use auxdata functionality. 0169 % 0170 % options.zl, options.zu, options.lambda 0171 % 0172 % These fields specify the initial value for the Lagrange multipliers, 0173 % which is especially useful for "warm starting" the interior-point 0174 % solver. They specify the Lagrange multipliers corresponding to the 0175 % lower bounds on the variables, upper bounds on the variables, and 0176 % constraints, respectively. 0177 % 0178 % options.ipopt 0179 % 0180 % Finally, you may also change the settings of IPOPT through this 0181 % field. For instance, to turn off the IPOPT output, use the 0182 % limited-memory BFGS approximation to the Hessian, and turn on the 0183 % derivative checker, do the following: 0184 % 0185 % options.ipopt.print_level = 0; 0186 % options.ipopt.hessian_approximation = 'limited-memory'; 0187 % options.ipopt.derivative_test = 'first-order'; 0188 % 0189 % For more details, see the documentation on the IPOPT website. 0190 % 0191 % OUTPUTS 0192 % 0193 % If the solver successfully converges to a stationary point or terminated 0194 % without an unrecoverable error, the function IPOPT outputs the candidate 0195 % solution x. In all other cases, an error is thrown. It also outputs some 0196 % additional information: 0197 % 0198 % info.zl, info.zu, info.lambda 0199 % 0200 % The value of the Lagrange multipliers at the solution. See the 0201 % "options" for more information on the Lagrange multipliers. 0202 % 0203 % info.status 0204 % 0205 % Upon termination, this field will take on one of these following 0206 % values (for a more up-to-date listing, see the IpReturnCodes.h header 0207 % file in the IPOPT C++ source directory): 0208 % 0209 % 0 solved 0210 % 1 solved to acceptable level 0211 % 2 infeasible problem detected 0212 % 3 search direction becomes too small 0213 % 4 diverging iterates 0214 % 5 user requested stop 0215 % 0216 % -1 maximum number of iterations exceeded 0217 % -2 restoration phase failed 0218 % -3 error in step computation 0219 % -10 not enough degrees of freedom 0220 % -11 invalid problem definition 0221 % -12 invalid option 0222 % -13 invalid number detected 0223 % 0224 % -100 unrecoverable exception 0225 % -101 non-IPOPT exception thrown 0226 % -102 insufficient memory 0227 % -199 internal error 0228 % 0229 % info.iter, info.cpu 0230 % 0231 % Number of iterations and CPU time (in seconds) taken by the Ipopt run 0232 % 0233 % Finally, for more information, please consult the following webpages: 0234 % 0235 % http://www.cs.ubc.ca/~pcarbo/ipopt-for-matlab 0236 % http://projects.coin-or.org/Ipopt 0237 % 0238 % Copyright (C) 2008 Peter Carbonetto. All Rights Reserved. 0239 % This code is published under the Eclipse Public License. 0240 % 0241 % Author: Peter Carbonetto 0242 % Dept. of Computer Science 0243 % University of British Columbia 0244 % September 19, 2008 0245 % 0246 % Downloaded binaries from http://www.coin-or.org/download/binary/Ipopt/I 0247 % popt-3.11.8-linux64mac64win32win64-matlabmexfiles.zip on 3/22/2016