# Changes between Version 9 and Version 10 of MatlabInterface

Ignore:
Timestamp:
Sep 19, 2008 2:31:36 PM (5 years ago)
Comment:

--

Unmodified
Removed
Modified
• ## MatlabInterface

 v9 #!html

How to install and use the MATLAB interface for IPOPT

How to install the MATLAB interface for IPOPT

Peter Carbonetto
Department of Computer Science
University of British Columbia

IPOPT is a software package for solving nonlinear objectives subject to nonlinear constraints. It uses primal-dual interior point methodology. Importantly, it is open source. What is described here is an interface to the IPOPT optimization engine, specially designed so it can be easily used in the MATLAB programming environment.

Let's start this tutorial by installing the MATLAB interface.

Installation

with large, sparse matrices on 64-bit platforms with MATLAB version 7.3 or greater.

Tutorial by example

Let's go through four examples which demonstrate the principal features of the MATLAB interface to IPOPT. For additional information, you can always type help ipopt in the MATLAB prompt. The tutorial exampels are all located in the directory Ipopt/contrib/MatlabInterface/examples.

Example 1

First, let's look at the Hock & Schittkowski test problem #51.1 It is an optimization problem with 5 variables, no inequality constraints and 3 equality constraints. There is a MATLAB script examplehs051.m which runs the limited-memory BFGS (Broyden-Fletcher-Goldfarb-Shanno) algorithm with the starting point [2.5 0.5 2 -1 0.5] and obtains the solution [1 1 1 1 1]. The line in the script which executes the IPOPT solver is

@computeConstraints,@computeJacobian,'',[],'',[],...
'jac_c_constant','yes','hessian_approximation',...

The first input is the initial point. The second and third inputs specify the lower and upper bounds on the variables. Since there are no such bounds, we set the entries of these two vectors to -Inf and +Inf. The fourth and fifth inputs specify the lower and upper bounds on the 3 constraint functions. The next five inputs specify the function handles to the required callback routines. We've written the callback routines as subfunctions in the same M-file. Since we are using a limited-memory approximation to the Hessian, we don't need to know the values of the second-order partial derivatives, so we set the Hessian callback routine to the empty string. The rest of the input arguments set some options for the solver, as detailed in the IPOPT documentation.

If you examine the functions computeObjective and computeGradient, you will see that computing the objective function and gradient vector is relatively straightforward. The function computeConstraints returns a vector of length equal to the number of constraint functions. The callback function computeJacobian returns an M x N sparse matrix, where M is the number of constraint functions and N is the number of variables. It is important to always return a sparse matrix, even if there is no computational advantage in doing so. Otherwise, MATLAB will report an error.

Example 2

Let's move to the second example, examplehs038.m. It demonstrates the use of IPOPT on an optimization problem with 4 variables and no constraints other than simple bound constraints. This time, we've implemented a callback routine for evaluating the Hessian. The Hessian callback function takes as input the current value of the variables x, the factor in front of the objective term sigma, an the values of the constraint multipliers lambda (which in this case is empty). If the last input is true, then the callback routine must return a sparse matrix that has zeros in locations where the second-order derivative at that location will ALWAYS be zero. The return value H must always be a lower triangular matrix (type help tril). As explained in the IPOPT documentation, the Hessian matrix is symmetric so the information contained in the upper triangular part is redundant.

This example also demonstrates the use an iterative callback function, which can be useful for displaying the status of the solver. This is specified by the twelfth input. The function callback takes as input the current iteration t, the current value of the objective f, and the current point x.

Example 3

The third slightly more complicated example script is examplehs071.m, which is the same as the problem explored in the IPOPT documentation (Hock and Schittkowski test problem #71). It is worth taking a peek at the functions computeHessian and computeJacobian. In the Hessian callback function, we make use of the input lambda. Since the Hessian is dense, its structure is returned with the line

H = sparse(tril(ones(n)))

where n is the number of variables. The Jacobian is dense, so we can return its structure in a single line:

J = sparse(ones(m,n))

where m is the number of constraint functions.

This example also differs from previous ones because the initial values for the Lagrange multipliers are specified in MATLAB. We need to input three sets of multipliers to IPOPT: the Lagrange multipliers corresponding to the lower bounds on the optimization variables, the multipliers corresponding to the uppwer bounds on the variables, and the multipliers associated with the constraint functions. To specify these three sets of Lagrange multipliers, we fill in three fields in the multipliers struct as follows:

multipliers.zl     = [1 1 1 1];
multipliers.zu     = [1 1 1 1];
multipliers.lambda = [1 1];

Note that this optimization problem has 4 variables and 2 constraints.

In this example script, we have also chosen to output the the values of the Lagrange multipliers that compose the dual portion of the final primal-dual solution. When I ran this script, I obtained final values of approximately

multipliers.zl     = [1 0 0 0];
multipliers.zu     = [0 0 0 0];
multipliers.lambda = [-0.55 0.16];

The third output in the call to IPOPT is the number of iterations IPOPT takes to converge to the stationary point within the specified tolerance.

Example 4

The last example is the script examplelauritzen.m in the subdirectory bayesnet. It is vastly more complicated than the other three. It pertains to research in inference in probabilistic models in artificial intelligence. This script demonstrates the problem of inferring the most probable states of random variables given a Bayesian network.2 In this case, the model represents the interaction between causes (e.g. smoking) and diseases (e.g. lung cancer). We are given a patient that is a smoker, has tested positive for some X-ray, and has recently visited Asia. In many ways this is a silly and highly overused example, but it suits our needs here because it demonstrates how to treat inference as an optimization problem, and how to solve this optimization problem using IPOPT. This code should NOT be used to solve large inference problems because it is not particularly efficient.

The call to IPOPT is buried in the file bopt.m. It is

[qR qS] = ipopt({qR qS},{repmat(eps,nqr,1) repmat(eps,nqs,1)},...
{ repmat(inf,nqr,1) repmat(inf,nqs,1) },...
[ ones(1,nr) ones(1,ns) zeros(1,nc) ],...
[ ones(1,nr) ones(1,ns) zeros(1,nc) ],...
@computeJGConstraints',@computeJGJacobian',...
@computeJGHessian',{ K C f Rv Rf Sv Sf NS d },'',...
...

As you can see, it is rather complicated! The first input, as usual, is the starting point. (The variables actually represent probability estimates.) Notice that we are passing a cell array, and each entry of the cell array is a matrix. Likewise, the bound constraints are specified as cell arrays. This is permitted as long as the starting point and the bound constraints have the same structure. If not, the MATLAB will report an error. (Note that the lower bounds on the variables are set to floating-point precision. Type help eps. In this way, we ensure that the logarithm of a variable never evaluates to zero.)

This cell array syntax is useful when your program has several different types of variables. These sets of variables are then passed as separate input arguments to the MATLAB callback functions. For instance, qR and qS are passed as separate arguments to the objective callback function in the M-file computeJGObjective.m.  The entries of the cell array are also treated as separate outputs from the gradient callback function (see the M-file computeJGGradient.m), and from the main call to ipopt.

In this example, the constraint functions are all linear, so they have no impact on the value of the Hessian. In fact, the Hessian is a diagonal matrix (but not positive definite). The Jacobian can be extremely large, but it is also very sparse; the number of entries is a multiple of the number of variables.

This example also demonstrates the use of auxiliary data. In bopt.m, notice that the input after computeJGHessian is a cell array. This cell array is passed as input to every MATLAB callback routine.

The tutorial is over!

Notes on implementation of the MATLAB interface

(see above).

Footnotes

1 For further information, see: Willi Hock and Klaus Schittkowski. (1981) Test Examples for Nonlinear Programming Codes. Lecture Notes in Economics and Mathematical Systems Vol. 187, Springer-Verlag.

2 If you want to learn more about junction graphs for approximate inference, and a special case of this is called the junction tree algorithm. Recommended reading includes:

• Aji and McEliece (2001). The generalized distributive law and free energy minimization. Proceedings of the 39th Allerton Conference.
• Yedidia, Freeman and Weiss (2005). Constructing free-energy approximations and generalized belief propagation algorithms. IEEE Transactions on Information Theory 51(7).

}}} }}}