Compiling_MATLAB_with_Release_14

Compiling MATLAB under MATLAB R14 SP1

Here are the steps for MATLAB compilation
Why create MATLAB executables?
Setup for MATLAB compilation
Testing your MATLAB compiler setup
Setup MCR on Grid computer

Why compile MATLAB into executables?

MATLAB has become quite popular for interactively analyzing data and doing time-series analysis within the LSC. It would be even better if one could then use the same programs and functions to do large-scale batch processing, instead of having to translate into a different language! (It would certainly eliminate an extra code walkthrough review)

But you can! MATLAB now has a compiler which can be used to make stand-alone executables which have been run on LSC Grid computers for the S2 data analaysis (Burst Group r-statistic, BlockNormal, Stochastic Group).

While you do need to purchase a MATLAB Compiler license to build the executables, you can then freely distribute the executable and the MATLAB Component Runtime (MCR) to as many computers as you want! No licenses, no limits.

Recently, the Matapps software directory has been created in LSCSoft to house MATLAB applications developed by the LSC community.

MATLAB Compiler 4.1

The new release of MATLAB (called both MATLAB 7.1 and Release 14 SP1) comes with a new Compiler 4.1. The documentation for the compiler is available online from Mathworks.

This uses the MATLAB Component Runtime (MCR) which allows the use of nearly every function in the MATLAB libraries in a stand-alone executable. This means that compilable variants of MATLAB functions (required for MATLAB 6) are no longer needed! In particular, MATLAB classes and objects can be used.

Unfortunately, because the MCR runs M-files instead of compiling an executable, compiled code is no faster than interactive code.

The MCR requires a different method for distributing executables. This is most important when exporting stand-alone programs to the LSC Grid computers

Getting the MATLAB Compiler

It is important to compile MATLAB programs on the same operating system type where the executables will be run. As the LSC Grid utilities all use Linux at present, you need to run the compiler on a Linux system. The MATLAB Compiler 4.1 is already installed on the Penn State Gravity cluster (gravity.psu.edu) and the LHO Linux development node (ldas-pcdev1.ligo-wa.caltech.edu).

The license can be purchased for an existing MATLAB installation from MathWorks. The cost for an academic license for the compiler is ~ $200.

Setup for MATLAB compilation under R14Sp1

The instructions which follow are detailed for the Penn State Gravity cluster (for compilation) and Pleaides cluster (for grid processing). It should be similar on other systems.

Note that Compiler 4.1 has corrected problems with the initial compiler release. This has simplified the installation and setup from Compiler 4.0.

1) Create build options file

As detailed in the Mathworks documentation, after installing the compiler each user should make a build options script (mbuildopts.sh). On PSU Gravity cluster, do the following at the command line:

/usr/local/matlab-r14sp1/bin/mbuild -setup

Choose the default option.

This creates a file mbuildopts.sh in a .matlab/R14 sub-directory of your home directory. Here is a log file of the mbuild process.

2) Modify the build options file

There is still an error in the options script which needs to be fixed. It involves adding gcc_s as a library.
1) Open mbuildopts.sh in an editor
2) On or about line 88, add -lgcc_s to the CLIBS line for 'gcc' under 'glnx86' as below:

#----------------------------------------------------------------------------
            ;;
        glnx86)
#----------------------------------------------------------------------------
            RPATH="-Wl,--rpath-link,$TMW_ROOT/bin/$Arch"
#           gcc -v
#           gcc version 3.2.3
            CC='gcc'
            CFLAGS="$MFLAGS -ansi -D_GNU_SOURCE -pthread -fexceptions"
            CLIBS="$RPATH $MLIBS -lm -lstdc++ -lgcc_s"

3) Save the modified mbuildopts.sh

There is also a reference mbuildopts.sh file with the gcc_s change .

3) Fix your startup.m file to running executables

When testing a stand-alone build, you need to make sure it sees the local encrypted m-files instead of ones from your CVS sandbox. We wrap any addpath commands (which let us see the CVS sandbox files) with a conditional to prevent their use when running an executable. The syntax of the startup.m file should be:

if((str2num(version('-release')) < 14) || ~isdeployed)
   addpath commands
   ...
end

Here is an example startup.m for the Gravity cluster and the psurg CVS.

The startup.m file should be in your ~/matlab directory.

4) Add MATLAB run-time to your path

To test the stand-alone executables on the machine you have MATLAB installed on, you need to have the MATLAB Component Runtime in your dynamic library path. This is detailed in on page 5-4 of the Compiler manual.

On the Gravity cluster add the following to your .cshrc

setenv MATLAB_ROOT /usr/local/matlab-r14sp1
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/bin/glnx86:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/os/glnx86:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnx86/jre1.4.2/lib/i386/client:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/java/jre/glnx86/jre1.4.2/lib/i386:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MATLAB_ROOT}/sys/opengl/lib/glnx86:${LD_LIBRARY_PATH}
setenv XAPPLRESDIR ${MATLAB_ROOT}/X11/app-defaults
unsetenv MATLAB

I have provided an example .cshrc_fragment which handles a non-existent LD_LIBRARY_PATH and checks if MATLAB was already added to it.

** NOTE: Do NOT define an environment variable named "MATLAB" under MATLAB R14. This will screw up the compiler in quite subtle ways.

Testing your compiler setup

We will now follow the stand-alone application example (page 5-3 of the Compiler manual).

1) Get the magicsquare.m sample code

This is located in <matlabroot>/extern/examples/compiler, but I have also made it available following this magicsquare.m link.

Create a directory (~/mat_test) and copy the file to it.

2) Build the application

Here we start up MATLAB and invoke the mcc compiler. Use the following at the command prompt
$

cd ~/mat_test
matlab -nodisplay
>>mcc -mv magicsquare.m

This will create the following files
magicsquare --> the executable
magicsquare_main.c --> 'main' wrapper
magicsquare_mcc_component_data.c
magicsquare.ctf --> encoded matlab files
magicsquare_mcr --> directory of m-files for application

When the compilation is progressing, a long blow-by-blow listing is shown because we added the -v option (for verbose). Once things work, you can skip this option. Here is a copy of the compilation log.

Warning: when you first run the executable it will unpack the .ctf file into an _mcr directory. Having this (or any _mcr) directory in your matlab path may cause problems when trying to compile! This is probably your problem if you get an error:

Error: File: dirname Line: 1 Column: 25

in which case, you will want to check the verbose listing to see what _mcr directory is in your path.

3) Test the application

Here we exit MATLAB, and run the application from the command line:

>>
quit
[thorne@auriga]$ ./magicsquare 4 

ans =
 
    16     2     3    13
     5    11    10     8
     9     7     6    12
     4    14    15     1

Handling function inputs on the command line

Any function inputs are passed as command line arguments. One difficulty is that numbers are passed as doubles within MATLAB, but as text strings when entered at the command line. A way to handle this is shown in the example code

function magicsquare(n)
%MAGICSQUARE generates a magic square matrix of the size specified
% by the input parameter n.

% Copyright 2003 The MathWorks, Inc.
if (ischar(n))
  n=str2num(n);
end
magic(n)

The ischar(n) test checks that if text is encountered for a numeric input, it is converted from a string to a numeric equivalent. This will even work for MATLAB constructs like [1:5].

Setup MCR on Grid computer

To run MATLAB executables on a machine without MATLAB installed, we need to install the MATLAB Component Runtime (MCR) files on that computer. This includes most LSC Grid computers.

1) Check if this is already setup

Often, the Grid computer sys-admin has already installed this. If that is the case, obtain the location of the MCR installation from them and jump to step 4)

2) Get MCR Installer file (MCRInstaller.zip)

This can be created using the buildmcr command within MATLAB. Because the user may not be allowed to write into the default MATLAB directory, we have it create that file locally. Use the following at the MATLAB prompt

% buildmcr('.');
This will take some time. A copy of the installer is stored on the Gravity cluster at ~s3/no-backup/Matlab_MCR/v71.

3) Transfer and install on Grid computer

If it doesn't exist, create a MCR sub-directory on Pleiades off your home directory using gsh.pl

[thorne@auriga ~]$ gsh.pl
gsh version: $Id: gsh.pl,v 1.12 2004/02/10 22:15:16 mcnabb Exp $
time left for grid-proxy: 131:18:51 (5.5 days)
ligo-grid.aset.psu.edu:/usr18/home/ux001007/> mkdir MCR

2) Copy the MCRInstaller.zip for v7.1 to your home directory on Pleiades

ligo-grid.aset.psu.edu:/usr18/home/ux001007/ put MCRInstaller.zip

3) Unzip the MCR Installer on Pleiades using unzip and then exit gsh.pl

ligo-grid.aset.psu.edu:/usr18/home/ux001007/> unzip MCRInstaller.zip -d MCR
ligo-grid.aset.psu.edu:/usr18/home/ux001007/> quit

** this creates a v71 sub-directory under the MCR directory

4) Put script with MCR in LD_LIBRARY_PATH on Grid computer

To use MCR on the Grid computer, the MCR needs to be added to the LD_LIBRARY_PATH.
This is similar to the setup above, but for MCR directories. Here it is for csh:

setenv MCR_ROOT ${HOME}/MCR/v71
setenv LD_LIBRARY_PATH ${MCR_ROOT}/runtime/glnx86:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MCR_ROOT}/bin/glnx86:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MCR_ROOT}/sys/os/glnx86:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MCR_ROOT}/sys/java/jre/glnx86/jre1.4.2/lib/i386/client:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MCR_ROOT}/sys/java/jre/glnx86/jre1.4.2/lib/i386:${LD_LIBRARY_PATH}
setenv LD_LIBRARY_PATH ${MCR_ROOT}/sys/opengl/lib/glnx86:${LD_LIBRARY_PATH}
setenv XAPPLRESDIR ${MCR_ROOT}/X11/app-defaults

There is a sample csh file (MCRSetup_v71.csh) available to use as well. Transfer this file to the Grid computer (using gsh.pl)

ligo-grid.aset.psu.edu:/usr18/home/ux001007/> put MCRSetup_v71.csh

Then add the following either to your .cshrc on the Grid computer or to each executable script submitted via condor:

source MCRSetup_v71.csh

Finally, you must move both the compiled executable and the .ctf file to the Grid computer and make sure they are in your path (the .ctf file can be put in your LD_LIBRARY_PATH or your PATH)

Keith Thorne

Last modified: Thur Oct 14 2004 4:30 PM EDT