Subsections


Compiling and Installing the MATLAB interface

based on documentation by Peter Carbonetto13, Tony Kelman14, and Ray Zimmerman


The MATLAB interface to IPOPT uses the mex interface of MATLAB. It 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.

NOTE: The MATLAB interface does not support MATLAB 8.3 (aka, R2014a), as it has not been adapted to MATLAB changes in the buildsystem for MEX files.

First, note that some binaries of IPOPT mex files are available for download at http://www.coin-or.org/download/binary/Ipopt. Further, the OPTI Toolbox (http://www.i2c2.aut.ac.nz/Wiki/OPTI) comes with a precompiled MATLAB interface for IPOPT on Windows.

Setting up mex

To build the interface by yourself, you will need to have MATLAB installed on your system and have it configured to build mex files, see http://www.mathworks.com/support/tech-notes/1600/1605.html for detail on how to set this up.

Ipopt 3.11 has added Makefile options to automate fixes for commonly-encountered issues with building the MATLAB interface. On Mac OS X or Windows, the file mexopts.sh (mexopts.bat on Windows) will need to be modified. This is performed automatically by calling make mexopts in the $IPOPTDIR/build/Ipopt/contrib/MatlabInterface/src directory. No changes will be made if you already have a mexopts.sh file in that directory. If you need to make these modifications manually, follow the steps below.

For Mac OS X, the following procedure has been reported: First, one executes a command like

/Applications/MATLAB_R2012.app/bin/mex -setup
This creates a mexopts.sh file in the  /.matlab/R2010 directory. Copy that file to the directory $IPOPTDIR/build/Ipopt/contrib/MatlabInterface/src and modify it as follows.

On Windows, if you are using the GNU compilers via MinGW, then you will need to use the gnumex project. First, execute the script ./get.Gnumex from the $IPOPTDIR/Ipopt/contrib/MatlabInterface directory. Then, after configuring IPOPT, go to $IPOPTDIR/build/contrib/MatlabInterface/src and execute make gnumex. This will start an instance of MATLAB and open the gnumex tool. Check that the options are filled out appropriately for your MinGW installation, click ``Make options file," then close this new instance of MATLAB after gnumex has created mexopts.bat.

Calling make mexopts will automatically make the necessary changes to this new mexopts.bat file. If you would like to do so manually, the changes are as follows.

Adjusting configuration and build of IPOPT

The configure script of IPOPT attempts to automatically locate the directory where MATLAB is installed by querying the location of the matlab executable. You can also manually specify the MATLAB home directory when calling the configure script with the flag -with-matlab-home. You can determine this home directory by the command matlabroot within MATLAB.

In practice, it has been found easier to install and use the MATLAB interface by disabling compilation of the shared libraries, and use only static libraries instead. However, these static libraries need to be built in a way that allow using them in a shared library, i.e., they need to build with position-independent code. This is achieved with the configure script flags

  --disable-shared --with-pic
On Mac OS X, it has been reported that additionally the following flags for configure should be used:
  ADD_CFLAGS="-fno-common -fexceptions -no-cpp-precomp"
  ADD_CXXFLAGS="-fno-common -fexceptions -no-cpp-precomp"
  ADD_FFLAGS="-fexceptions -fbackslash"

With IPOPT 3.11, a site script for configure has been added to the MATLAB interface. This script takes care of setting configure options in a way that is appropriate for building an IPOPT mex file that is useable via MATLAB. Therefore, instead of setting configure options as described in the previous section, it should be sufficient to create a directory $IPOPTDIR/build/share, copy the site file $IPOPTDIR/contrib/MatlabInterface/MatlabInterface.site to that directory, and rename it to config.site before running configure. Alternatively, you can set an environment variable CONFIG_SITE that points to the site file.

This site script sets the configure flags (if not specified by the user) -disable-shared -with-pic -with-blas=BUILD -with-lapack=BUILD. The first two flags are discussed above. We also specify that the reference versions of BLAS and LAPACK should be used by default because of a commonly observed issue on 64-bit Linux systems. If IPOPT configure finds BLAS and/or LAPACK libraries already installed then it will use them. However, MATLAB includes its own versions of BLAS and LAPACK, which on 64-bit systems are incompatible with the expected interface used by IPOPT and the BLAS and LAPACK packages available in many Linux distributions. If the IPOPT mex file is compiled in such a way that the BLAS and LAPACK libraries are dynamically linked as shared libraries (as found in installed Linux packages), those library dependencies will be overridden by MATLAB's incompatible versions. This can be avoided by statically linking BLAS and LAPACK into the IPOPT mex file, which the above combination of configure flags will do. Note, that this issue does not appear to affect Mac OS X versions of MATLAB, so if you would like to use the Apple optimized BLAS and LAPACK libraries you can override these settings and specify -with-blas='-framework vecLib' -with-lapack='-framework vecLib'.

The site script also tests whether the compilers on your system are capable of statically linking the standard C++ and Fortran libraries into a shared library. This is possible with GCC versions 4.5.0 or newer on Mac OS X or Windows, 4.7.3 or newer (when GCC itself is built -with-pic) on Linux. If this is the case, then the site script will set appropriate configure flags and options in the MATLAB interface Makefile to statically link all standard libraries into the IPOPT mex file. This should allow a single mex file to work with a variety of versions of MATLAB, and on computers that do not have the same compiler versions installed. If this static linking of standard libraries causes any issues, you can disable it with the configure flag -disable-matlab-static.

Building the MATLAB interface

After configuring, building, and installing IPOPT itself, it is time to build the MATLAB interface. For that, IPOPT's configure has setup a directory $IPOPTDIR/build/contrib/MatlabInterface/src which contains a Makefile. You may 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. For example, on Mac OS X, it has been reported that all duplicates of strings like -L/usr/lib/gcc/i686-apple-darwin11/4.2.1/../../.. should be removed from the LIBS line.

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 should have ended up with a mex file. The mex file will be called ipopt.$MEXEXT, where $MEXEXT is mexglx for 32-bit Linux, mexa64 for 64-bit Linux, mexw32 for 32-bit Windows, etc.

Making MATLAB aware of the mex file

In order to use the mex file 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).

Additional notes

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.

As MATLAB (version R2008a or newer) includes its own HSL MA57 library, IPOPT's configure can be setup to enable using this library in IPOPT's MA57 solver interface. To enable this, one should specify the configure option -enable-matlab-ma57. Note, that using this option is not advisable if one also provides the source for MA57 via ThirdParty/HSL.

Troubleshooting

The installation procedure described above 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

Remedy: 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. -with-pic) when you ran the configure script at the very beginning.


Problem: MATLAB fails to link to IPOPT shared library

Remedy: 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

Remedy: 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).



Footnotes

... Carbonetto13
University of British Columbia
... Kelman14
University of California, Berkeley