NOTE: The information on this page refers to Ipopt version 3.10. For uptodate information on how to build the Ipopt/MATLAB interface, see the Ipopt documentation
How to install and use the MATLAB interface for IPOPT
Department of Computer Science
University of British Columbia
Throughout this tutorial, I'll be assuming you have some sort of UNIX-based operating system such as Mac OS X, Solaris or Linux. I'm afraid these instructions do not directly apply to the Windows operating system. Hopefully you have enough experience with Windows to figure out how to modify these steps for your setup. (There is a detailed step-by-step guide for Windows including 64-bit platforms and a documentation of the Matlab Interface itself. If you are using Windows, you may also have a look at the gnumex project website before continuing. In addition, some detailed instruction steps for compilation of the Matlab interface (for 32 bit Matlab) under Windows 7 have been compiled by Ipopt users and are available here and here.)
Naturally, you'll need to have a version of MATLAB installed on your computer. This software package has been tested on MATLAB versions 7.2 through 7.7. It might very well work on earlier versions of MATLAB, but there is also a good chance that it will not. It is unlikely that the software will run with versions prior to MATLAB 6.5.
1. Install supported compilers
The first thing you need to do is install a C++ compiler and a Fortran 77 compiler. It is crucial that you use the precise compilers supported by MATLAB. For instance, on my Linux machine I have MATLAB version 7.3, so the people at MathWorks tell me that I need to have the GNU Compiler Collection (GCC) version 3.4.5. If you use the incorrect version of GCC, you will likely encounter linking errors. The mex command will tell you which compiler versions are legal.
2. Configure MATLAB
Once you've installed the appropriate compilers, set up and configure MATLAB to build MEX files. This is explained quite nicely here.
3. Install IPOPT
To install IPOPT, follow the standard IPOPT installation procedure with a few small changes.
Usually, MATLAB demands that you compile the code with certain flags,
-fexceptions on Linux. The
first flag tells the compiler to generate position-independent code,
and the second flag enables exception handling. Usually these flags
coincide with your MEX options file. You can figure out which flags are
used on your system by running the mex compiler with the
-v flag on a simple example source file (Hello
World is your friend). See this
MathWorks technical support webpage for more information on the
MEX options file.
IPOPT attempts to automatically locate the directory where MATLAB is
installed by querying the location of the mex executable. You can
also manually specify the MATLAB home directory when calling the configure
script with the flag
In practice, you might find that it is easier to install and use the
MATLAB interface by disabling compilation of the shared libraries, and use
only static libraries instead. This is achieved with the configure script
On a Linux machine with MATLAB 7.3 installed, the call to the IPOPT configure script will look something like
./configure --prefix=$HOME/ipopt/install \
CXX=g++-3.4.5 CC=gcc-3.4.5 F77=g77-3.4.5 \
ADD_CXXFLAGS="-fPIC -fexceptions" \
ADD_CFLAGS="-fPIC -fexceptions" \
I also installed the MATLAB interface to IPOPT on an Apple computer running Mac OS X 10.3.9 and MATLAB 7.2. For this machine, I ran the configure script with the following command:
./configure --prefix=$HOME/ipopt/install \
ADD_CFLAGS="-fno-common -fexceptions -no-cpp-precomp -fPIC" \
ADD_CXXFLAGS="-fno-common -fexceptions -no-cpp-precomp -fPIC" \
ADD_FFLAGS="-x f77-cpp-input -fPIC -fno-common" \
FLIBS="-lg2c -lfrtbegin -lSystem" \
F77=g77 CC=gcc CXX=g++
After this, follow the standard installation steps: type
make, wait a few minutes, then
in the UNIX command line. This compiles all the source code into a
single library and places it in the install directory as specified by
prefix variable above.
What we haven't yet done is compile the code for the MATLAB interface. We'll do this next.
4. Modify the Makefile and build the MEX file
Go to into the
Ipopt/contrib/MatlabInterface/src and open
the file called
Makefile with your favourite text
editor. You need to edit this file a little bit to suit for your system
setup. You will find that most of the variables such
CXXFLAGS have been automatically
(and hopefully, correctly) set according to the flags specified during
your initial call to
However, you may
need to modify
MEX as explained in the comments of the Makefile.
On one of our Linux
machines, we had set these Makefile variables to
MATLAB_HOME = /cs/local/generic/lib/pkg/matlab-7.3/bin/matlab
MEXSUFFIX = mexglx
Once you think you've set up the Makefile properly, type
install in the same directory as the Makefile. If you didn't get
any errors, then you're pretty much all set to go!
There's a great possibility you will encounter problems with the installation instructions we have just described here. I'm afraid some resourcefulness will be required on your part, as the installation will be slightly different for each person. Please consult the troubleshooting section on this webpage, and the archives of the IPOPT mailing list. If you can't find the answer at either of these locations, try sending an email to the IPOPT mailing list.
5. Final steps
If the installation procedure was successful, you
will end up with a MEX file. On a Linux machine, the MEX file will be
ipopt.mexglx. In order to use it in MATLAB, you
need to tell MATLAB where to find it. The best way to do this is to
in the MATLAB command prompt, where
sourcedir is the
location of the MEX file you created. (For more information, type
addpath in MATLAB. You
can also achieve the same thing by modifying the
MATLABPATH environment variable in the UNIX command line,
using either the
export command (in Bash shell), or the
setenv command (in C-shell).
Using the MATLAB interface
There are several illustrative examples provided in the
Ipopt/contrib/MatlabInterface/examples directory. The best way
to understand how to use the interface is to carefully go over these
For more information, type
help ipopt in the MATLAB
A note on 64-bit platforms
Starting with version 7.3, MATLAB can handle 64-bit addressing, and the authors of MATLAB have modified the implementation of sparse matrices to reflect this change. However, the row and column indices in the sparse matrix are converted to signed integers, and this could potentially cause problems when dealing with large, sparse matrices on 64-bit platforms with MATLAB version 7.3 or greater.
Troubleshooting and known issues
The installation procedure I've described does involve a certain amount of expertise on the part of the user. If you are encountering problems, it is highly recommended that you follow the standard installation of IPOPT first, and then test the installation by running some examples, either in C++ or in AMPL.
What follows are a list of common errors encountered, along with a suggested remedy.
PROBLEM: compilation is successful, but MATLAB crashes
Even if you
didn't get any errors during compilation, there's still a possibility
that you didn't link the MEX file properly. In this case, executing
IPOPT in MATLAB will cause MATLAB to crash. This is a common problem,
and usually arises because you did not choose the proper compiler or
set the proper compilation flags (e.g.
-fPIC) when you
configure script at the very beginning.
PROBLEM: MATLAB fails to link to IPOPT shared library
encounter this problem if you try to execute one of the examples in
MATLAB, and MATLAB complains that it cannot find the IPOPT shared
library. The installation script has been set up so that the MEX file
you are calling knows where to look for the IPOPT shared library.
However, if you moved the library then you will run into a problem.
One way to fix this problem is to modify the
variable in the MATLAB interface Makefile (see above) so that the
correct path of the IPOPT library is specified. Alternatively, you
could modify the
environment variable so that the location of the IPOPT library is
included in the path. If none of this is familiar to you, you might
want to do a web search to find out more.
PROBLEM: "mwIndex" is not defined
You may get a
compilation error that says something to the effect that mwIndex is
not defined. This error will surface on a version of MATLAB prior to
7.3. The solution is to add the flag
CXXFLAGS variable in the MATLAB interface Makefile
Notes on implementation of the MATLAB interface
I won't bore you with all the details of the implementation. I would, however, like to briefly point out a few of them. Most of the issues of interest surround the representation of sparse matrices.
The MATLAB interface will necessarily be slower than the standard C++ interface to IPOPT. That's because MATLAB dynamically allocates new memory for all the outputs passed back from a function. Thus, for large problems each iteration of IPOPT will involve the dynamic allocation and deallocation of large amounts of memory.
Sparse matrices. The greatest challenge was most definitely the conversion of sparse matrices from MATLAB to IPOPT. Sparse matrices are used to represent the Jacobian of the constraint functions and the Hessian of the Lagrangian function. There is a very nice document by Gilbert, Moler and Schreiber that discusses the design and implementation of sparse matrices in the MATLAB environment. The problem is that IPOPT assumes a static sparse matrix structure, but in MATLAB there is no way to ensure that the size of the matrix (the number of non-zero elements) does not change over time; if an entry of a sparse matrix is set to zero, then the arrays are automatically adjusted so that no storage is expended for that entry. This may seem like a highly inefficient way to implement sparse matrices, and indeed it is. However, Gilbert, Moler and Schreiber emphasize efficient matrix-level operations over efficient element-level operations.
We can legitimately make the following assumption: the non-zero
entries of a sparse matrix passed back from MATLAB are a
SparseMatrixStructure keeps track of the
structure of a sparse MATLAB matrix. It does not store the values of
the non-zero entries. I use it for the Jacobian of the constraints
and the Hessian of the Lagrangian. Even though these two matrices are
fundamentally different (one is square and lower triangular, the other
is rectangular), we can treat their structures in the same way.
The principal functions of interest in class
copyElems. The function
converts the MATLAB sparse matrix format into the equivalent IPOPT
format. The function
copyElems copies the entries from
one sparse matrix to another when one sparse matrix has a different
structure than the other. Obviously, for the copy operation to be
plausible, the set of non-zero entries of the destination matrix must
be a superset of the non-zero entries of the source matrix. Due to
efficiency concerns, no checks are made to ensure that this is
satisfied; it is up to the user to ensure that a sparse matrix passed
back to IPOPT never has a non-zero entry that was not declared
returnStructureOnly = true. In my
implementation, I have gone through great pains to ensure: 1. that the
copy function only makes one pass through the entries of the sparse
matrix, and 2. that there are no if statements inside the for loops,
which can severely impinge on the speed of the copy operation.
Nov 7, 2011 Ipopt on Mac OS X contains detailed Mac OS X build notes, including Matlab interface, by Ray Zimmerman (rz10@…).Oct 3, 2012 In a Sept 14, 2012 post to the mailing list, Tony Kelman discusses changes to streamline the build process and links to some binaries that are available for download.