Compiling MATLAB under MATLAB R14

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, tools have been created within the community (FrameL frgetvect,
Matapps Channel,chanstruct,chanvector) which can read
frame file data and find it with the LDR databases on the LSC Grid computers.

MATLAB Compiler 4

The new release of MATLAB (called both MATLAB 7 and Release 14) comes
with a new Compiler 4.0.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.0.1 is already installed on 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.

Setting up for compiling

If you are going to use the LHO Linux development machine, you need to use a grid-enabled SSH
to login to it.  Please see the pre-BootCamp web page for this.

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 ldas-pcdev1 do the following
at the command line
/usr/local/matlab/bin/mbuild -setup.
Choose the default option.

This creates a file mbuildopts.sh in a .matlab/R14 sub-directory of your home
directory.

2) Get updated versions of FrameL functions

The current FrameL version in Ligotools (v6r12) is not fully compatible with the newly-released
MATLAB compiler.  Specifically, you need to get new frgetvect.mexglx and frgetvect.m
files using these links,

Add these two files to directory ~/matlab (which holds the startup.m file)

3) Fix your startup.m file

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.
Also, you need to make sure the modified FrameL files are ahead
of the Ligotools path.

We wrap the addpath commands with a conditional and add
~/matlab to our MATLAB path.  Here is an example startup.m for
the LHO Linux machine.

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 ldas-pcdev1.ligo-wa.caltech.edu, add the following to your .bash_profile
# MATLAB setup
export MATLAB_ROOT=/usr/local/matlab7
LD_LIBRARY_PATH = ${MATLAB_ROOT}/bin/glnx86:
    ${MATLAB_ROOT}/sys/os/glnx86:
    ${MATLAB_ROOT}/sys/os/glnx86:
    ${MATLAB_ROOT}/sys/java/jre/glnx86/jre1.4.2/lib/i386/client:
    ${MATLAB_ROOT}/sys/java/jre/glnx86/jre1.4.2/lib/i386:
    ${MATLAB_ROOT}/sys/opengl/lib/glnx86:${LD_LIBRARY_PATH}
export LD_LIBRARY_PATH

export XAPPLRESDIR=${MATLAB_ROOT}/X11/app-defaults

I have provided an example .bash_profile .

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

Create the sample executable

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.

3) Test the application

Here we exit MATLAB, and run the application from the command line
>> quit
[thorne@ldas-pcdev1 mat_test]$ ./magicsquare 4
Warning: Unable to open display , MATLAB is starting without a display.
  You will not be able to display graphics on the screen.
Warning: No window system found.  Java option 'MWT' ignored.

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].

Keith Thorne
Last modified: Fri Aug 20 2004 12:45PM PDT