Throughout this tutorial, we'll be assuming you have some sort of UNIX-based operating system, such as Mac OS X, Solaris or Linux. We can't help you if you have a Windows operating system, but we'll presume you have enough experience with Windows to figure out how to modify these steps for your setup, if necessary. (If you are using Windows, we highly recommend that you check out the gnumex project website before continuing.) Of course, you'll need to have a version of MATLAB installed o n your computer (hopefully a more recent version), and that you are relatively familiar with the MATLAB programming language (if not, it is a very simple language and you could learn it in a few hours). This software package has been tested on MATLAB versions 7.2 and 7.3. 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.

Install compilers. The first thing you need to do is install a C++ compiler and a Fortran 77 compiler. Now, you might already have these installed. However, you may not be able to use these installed compilers because you must use the precise compilers supported by MATLAB (yes, it's a pain). 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 (and the "mex" command will tell you which compiler versions are legal). In order to find out which compiler is supported by your version of MATLAB, run the mex program provided in your MATLAB installation or consult this webpage.

Configure MATLAB. Once you've installed the appropriate compilers, set up and configure MATLAB to build MEX files. This is explained quite nicely here.

Install IPOPT. The MATLAB interface adds several complicating matters to the standard IPOPT installation procedure. Before you continue, please familiarize yourself with the standard procedure. What follows are the steps followed on a typical Linux machine. First, download the IPOPT source files and the third-party source code (BLAS, LAPACK, HSL, etc.).

MATLAB demands that you compile the code with certain flags, such as -fPIC and -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 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.

Once you have all the necessary source code, call the IPOPT configure script. On a Linux machine with MATLAB 7.3 installed, the call should 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"          \
       ADD_FFLAGS="-fPIC -fexceptions"

We 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, we ran the fconfigure 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 make install 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 the prefix variable above.

What we haven't yet done is compile the code for the MATLAB interface. We'll do this next.

Modify the Makefile and build the MEX file. Go to into the subdirectory Ipopt/contrib/MatlabInterface/src and open the file called Makefile with your favourite text editor. We need to change this file a little bit so that it coincides with your MATLAB setup. You will find that most of the variables, such as CXX and CXXFLAGS, have been automatically (and hopefully, correctly) set according to the flags specified during your initial call to configure script. However, you may need to modify MATLAB_HOME and MEXSUFFIX, 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 make all 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.

Finally. If the installation procedure was successful, you will end up with a MEX file. On a Linux machine, the MEX file will be called 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 type

  addpath sourcedir

in the MATLAB command prompt, where sourcedir is the location of the MEX file you created. It is basically the full pathname that ends in Ipopt/contrib/MatlabInterface. 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).

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.