MATLAB interface for IPOPT: installation and usage

# How to install and use the MATLAB interface for IPOPT Peter Carbonetto Department of Computer Science University of British Columbia ## Installation 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. (If you are using Windows, I highly recommend that you check out the gnumex project website before continuing.) 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, 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 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 `--with-matlab-home`. 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 flag `-disable-shared`. 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"          \
           ADD_FFLAGS="-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 `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. ### 4. 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. You need to edit this file a little bit to suit for your system 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`, `MEXSUFFIX` and `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 `make 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 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. (For more information, type `help 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 examples. For more information, type `help ipopt` in the MATLAB prompt. ## 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 ran the `configure` script at the very beginning. ### PROBLEM: MATLAB fails to link to IPOPT shared library You might 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 `LDFLAGS` variable in the MATLAB interface Makefile (see above) so that the correct path of the IPOPT library is specified. Alternatively, you could modify the `LD_LIBRARY_PATH` 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 `-DMWINDEXISINT` to the `CXXFLAGS` variable in the MATLAB interface Makefile (see above).