Hoffman2:Compiling MATLAB

Back to all things Hoffman2

Running the MATLAB GUI is not always desirable. If you already know that your code works and no visuals or user interaction are needed, then using the MATLAB GUI is unnecessary and adds extra work for the computer. Instead, it may be better to compile your MATLAB code into an executable that can be submitted as a job on Hoffman2.

Furthermore, if you need to run the same MATLAB script on multiple subjects and would like to do so in parallel, you will find that you can't simply open up multiple instances of MATLAB on Hoffman2. This is because each user is only allotted one MATLAB license. To parallelize your processing, it would be better to compile your MATLAB script and submit a job for each subject using the compiled code. Compiled code does not require a MATLAB license in order to run.

Compiling

There is a handy tool, mcc, which can take a MATLAB .m file and compile it into an executable that can be run outside of MATLAB. It is expensive to buy, but luckily Hoffman2 has already done the purchasing for you.

Remember that to use mcc, you need an open MATLAB license. If you are running MATLAB already and open up a new Hoffman2 session intending to compile something with mcc, know that you will see errors and compilation will fail because you are already using your one allotted MATLAB license.

We have two example MATLAB scripts:

/u/home/FMRI/apps/examples/mcc/subfunctions/exampleSubfunction.m

This function can take any number of arguments and the text it prints out is based on the type of variables it receives. It is kept in a separate directory from the exampleMatlabScript.m file to illustrate how to work with dependent files in different parts of the filesystem.

function exampleSubfunction(varargin)

fprintf('This is a MATLAB function that takes input arguments.\n');

for i=1:length(varargin)
    if( ~isempty(varargin{i}) )
        switch class(varargin{i})
            case 'double'
                fprintf('Argument #%d\t -- %s -- is a double\n', i, varargin{i});
            case 'char'
                fprintf('Argument #%d\t -- %s -- is a char\n', i, varargin{i});
            otherwise
                fprintf('Argument #%d\t -- is an unknown\n', i);
        end
    else
        fprintf('Argument #%d\t -- is empty\n', i);
    end
end
end

/u/home/FMRI/apps/examples/mcc/exampleMatlabScript.m

Makes use of the exampleSubfunction() function.

function matlabScript(varargin)

fprintf('Passing numbers to the subfunction...\n');
subfunction(1, 2, 3);

fprintf('Passing characters to the subfunction...\n');
subfunction('a', 'b', 'c');

fprintf('Passing whatever arguments you gave me on to the subfunction...\n');
for i=1:length(varargin)
    subfunction(varargin{i});
end

end

To compile this example script, first check out an interactive node because this can be a computational intensive process. Then run the following commands

$ mkdir ~/mccExample
$ cd ~/mccExample
$ mcc -m /u/home/FMRI/apps/examples/mcc/exampleMatlabScript.m -R -singleCompThread -I /u/home/FMRI/apps/examples/mcc/

The output will probably start with

Ifconfig uses the ioctl access method to get the full address information, which limits hardware addresses to 8 bytes.
Because Infiniband address has 20 bytes, only the first 8 bytes are displayed correctly.
Ifconfig is obsolete! For replacement check ip.

which can be ignored and will be followed by any other messages related to the compiling, or error messages if something went wrong.

Testing

Now that you've compiled your code, you should test it to make sure it works before submitting 100,000 jobs using it.

1. Check out an interactive node
2. Execute

   $ module load matlab

   so that the computing node knows how to speak MATLAB

3. Then change to the directory where the compiled code is

   $ cd ~/mccExample

4. And run your compiled code

   $ ./exampleMatlabScript 

   Feel free to add any arguments to your function call, e.g.

   $ ./exampleMatlabScript ARG1 2 3 4

   to see how the output changes.

Submitting

You've compiled code and tested that it works. Time to submit it as a job. ATS has a tool for this (similar to job.q) called matexe.q.

Known Issues

• The official mcc documentation cites a -a flag for including a directory and all of its subdirectories recursively. We haven't found this flag to work very effectively and strongly suggest you use -I to explicitly name all the directories that have .m files your code depends on.
• Compiling EEGLAB has thus far failed on Hoffman2. Compiling SPM5 or SPM8 may fail similarly. If you figure out how to do this, let us know.
• You cannot compile something while you have another MATLAB session open. Each Hoffman2 user is allotted one MATLAB license at a time, and mcc requires a license to run.

External Links

• How to pass variables to compiled MATLAB code