You are here

MATLAB

Table of Contents

Introduction

MATLAB is a general-purpose high-level programming package for numerical work such as linear algebra, signal processing and other calculations involving matrices or vectors of data. Visualization tools are also included for presentation of results. The basic MATLAB package is extended through add-on components including SIMULINK, and the Image Processing, Optimization, Neural Network, Signal Processing, Spline and Wavelet Toolboxes.

Please note that how MATLAB can be used on WestGrid systems depends strongly on licensing, as described in the next section.

Ways to run MATLAB - License considerations

There are three methods of accessing MATLAB on WestGrid systems, as determined by the type of licensing (license-free standalone applications, donated academic licenses and WestGrid Distributed Computing Server license).

For users with access to a MATLAB compiler license, either their own or provided by their institutions, on a machine with an architecture and system similar to a target WestGrid machine, it may be possible to create a standalone application from their code using the MATLAB compiler. The application can then be run on a WestGrid system without using any licenses at run time.

On most WestGrid systems there is a "normal" MATLAB distribution, which is run using donated academic licenses from individual institutions. Often this is provided only to access the MATLAB compiler to produce standalone applications. Under the terms of those licenses MATLAB jobs can be run by researchers from SFU only on Bugaboo, University of Alberta researchers only on Jasper, UBC researchers only on Glacier and Orcinus, University of Calgary researchers only on the Breezy, Lattice or Parallel, University of Manitoba researchers only on Grex and UVic researchers only on Hermes and Nestor.

However, in late 2009, WestGrid purchased a new 64-worker "consortium" license for the MATLAB Distributed Computing Server. The consortium license allows researchers from Canadian academic institutions who have licensed the Parallel Computing Toolbox (or have access to it through a local server) to submit jobs to a WestGrid cluster, even if it is not located at their home institution. In March 2013 the number of licensed workers was increased to 160. Orcinus is the only WestGrid cluster on which the Distributed Computing Server workers run under the consortium license. The separate SFU site license allows for Distributed Computing Server jobs to be run on Bugaboo.

The notes below relate to creating and running standalone applications. Instructions for using the Distributed Computing Server license are given here. Instructions for using MATLAB under the donated academic licenses are given on a separate page.

Standalone Applications

If you (or your institution) own a MATLAB compiler license running on a Linux machine with an architecture similar to a WestGrid compute node you may be able to create a standalone application from your code. Such an application may then be run as a serial (or in some cases, a single-node parallel) job on an appropriate WestGrid system without using any licenses at run time. Two cases in which this approach may be useful are when there is a need to run many copies of the code simultaneously and when you need access to machines with a large amount of memory (such as Breezy, which has 256 GB per compute node). Note that the degree to which explicit parallel processing commands, such as matlabpool, are supported by the MATLAB compiler depends on the compiler version.  Try to use the most recent compiler available.

For several WestGrid institutions, there are local machines on which the MATLAB compiler is available to researchers from the corresponding institution. For example, University of Calgary researchers may use MATLAB on the WestGrid Lattice cluster to create applications that can then be deployed to other WestGrid clusters, such as Hermes or Breezy. In a similar manner, SFU researchers may use the compiler on Bugaboo, UBC researchers may use Orcinus, etc. Please contact support@westgrid.ca to discuss your particular situation.

Creating a standalone application

The MATLAB mcc command is used to compile source code (.m files) into a standalone excecutable. There are a couple of important considerations to keep in mind when creating an executable that can be run in the WestGrid batch-oriented environment. One is that there is no graphical display attached to your session and the other is that the number of threads used by the standalone application has to be controlled.

For example, with code mycode.m a source directory src, with the compiled files being written to a directory called deploy, the following mcc command line (at the Linux shell prompt) could be used:

mkdir deploy
cd src
mcc -R -nodisplay \
-R -nojvm \
-R -singleCompThread \
-m -v -w enable \
-d ../deploy \
mycode.m

Note the option -singleCompThread has been included in order to limit the executable to just one computational thread.  Depending on your application, you may not want to disable the Java Virtual Machine.  In that case, do not include the -R -nojvm.

In the deploy directory, an executable mycode will be created along with a script run_mycode.sh. These two files should be copied to the target machine where the code is to be run.

Running a standalone application

After the standalone executable mycode and corresponding script run_mycode.sh have been transferred to a directory on the target system (such as Hermes or Breezy) on which they will be run, a batch job script needs to be created in the same directory. Here is an example batch job script.

#!/bin/bash
#PBS -S /bin/bash

# Choose the MCR directory according to the compiler version used
MCR=/global/software/matlab/mcr/v714

echo "Running on host: `hostname`"
cd $PBS_O_WORKDIR
echo "Current working directory is `pwd`"

echo "Starting run at: `date`"
./run_mycode.sh $MCR
echo "Job finished at: `date`"

The job is then submitted as any ordinary WestGrid batch job with the qsub command. See the Running Jobs page for more information. If the above script is called matlab.pbs, it could be submitted using:

qsub -l walltime=72:00:00,mem=6gb matlab.pbs

The specified walltime and total memory (mem) limits should be adjusted to appropriate values for your particular run.

An important part of the above script is the location of the MATLAB Compiler Runtime (MCR) directory. This directory contains files necessary for the standalone application to run. The version of the MCR files specified (v714 in the example, which corresponds to MATLAB R2010b) must match the version of MATLAB used to compile the code.

A complete list of the MATLAB distributions and the corresponding compiler and MCR versions is given on the Mathworks web site. The most recent versions are listed below, along with the corresponding installation directory to which the MCR variable should be set in the example script. Not all systems have all versions installed, so, check the /global/software/matlab/mcr directory on the system you are proposing to use (except Bugaboo, where the files are in /usr/local/matlab-mcr). If the MCR version you need has not been installed please write to support@westgrid.ca to request that it be installed, or use a different version of MATLAB for your compilation.

MATLAB Release Compiler Version MCR Version MCR directory*
R2009b 4.11 7.11 /global/software/matlab/mcr/v711
R2009bSP1 4.12 7.12 Not installed
R2010a 4.13 7.13 /global/software/matlab/mcr/v713
R2010b 4.14 7.14 /global/software/matlab/mcr/v714
R2011a 4.15 7.15 /global/software/matlab/mcr/v715
R2011b 4.16 7.16 /global/software/matlab/mcr/v716
R2012a 4.17 7.17 /global/software/matlab/mcr/v717
R2012b 4.18 8.0 /global/software/matlab/mcr/v80
R2013a 4.18.1 8.1 /global/software/matlab/mcr/v81
R2013b 5.0 8.2 /global/software/matlab/mcr/v82
R2014a 5.1 8.3 /global/software/matlab/mcr/v83

 

* Please note that the MCR directories on Bugaboo are located under /usr/local/matlab-mcr instead of /global/software/matlab/mcr.

Passing arguments to a standalone application

In most programs there are a number of input data values that determine the specific calculation to be performed. In order to avoid recompiling your code for each change of these key input parameters, you can pass one or more arguments to the main function (as will be illustrated in the next section on reading parameters from a file). The arguments to be passed to the code are appended to the line in your batch job script that runs your compiled code. In the example given here, a single file name, params.in, is passed as an argument to the standalone application. The idea is that multiple parameters can be specified in this parameter file, rather than parsing multiple command-line arguments. Here is an example batch job script example.

Caution: the command line arguments are interpreted as text by the compiled program, even if they appear to be numbers. So, you may need to use a str2num function call to convert character strings to numerical values.

#!/bin/bash
#PBS -S /bin/bash

# Choose the MCR directory according to the compiler version used
MCR=/global/software/matlab/mcr/v714

echo "Running on host: `hostname`"
cd $PBS_O_WORKDIR
echo "Current working directory is `pwd`"

echo "Starting run at: `date`"
./run_mycode.sh $MCR params.in
echo "Job finished at: `date`"

 

Reading parameters from a file

To complete the example in the previous section of passing a parameter file name, params.in, as an argument to a compiled MATLAB code, here we illustrate one possible way of structuring the parameter file and using the parameters that are read.  The main program used in the example will call the MATLAB built-in function bench, which runs a series of numerical and graphical tests (although the graphical part will not be meaningful here). The bench function itself takes an argument, the number of repetitions of the set of tests to run.

For the parameter file format, we assume a fairly general form that is a subset of MATLAB syntax, in which a variable is assigned a value, followed by a semicolon and an optional comment.  Extra lines not matching this format are generally ignored, although the parsing logic doesn't correctly handle all cases.  In particular there should be no spaces between the variable name and the equal sign when assigning values. In the file, params.in, one could have:

# A comment line that will be ignored.
% Another line that will be ignored.
nreps=3;  % Number of repetitions of the bench command to execute.
output_file=bench_output; % Output file name
b=42; % Another variable

Here is a program that reads the params.in file, using the nreps parameter to control the number of calculations to perform.

function bench_ppn_test(command_line_arg)

% Pass a single parameter file name as the command line argument
% Assume the file name does not contain any spaces.

% Run the MATLAB bench command the number of times, nreps, specified
% in the parameter file.

% 2014-01-21, 2014-02-06 DSP

message=['Command line string: ',command_line_arg];
disp(message)

% Parse the command line for the argument

params_file=sscanf(command_line_arg,'%s')

message=['Parameters file name: ',params_file];
disp(message)

% Assign a default value to the number of repetitions

nreps=1;

% Read the parameters file to see if the default nreps should be
% over-ridden.

fid = fopen(params_file);

line=fgetl(fid);
while ischar(line)
% Ignore lines that do not have an equal sign.
equal_index=strfind(line,'=');
if isempty(equal_index)
else
% Take variable name to be the text to the left of the equal sign.
name=strtrim(sscanf(line(1:equal_index-1),'%s'));

% Find semicolon
semicolon_index=strfind(line,';');
if isempty(semicolon_index)
disp('Semicolon missing from line:');
disp(line);
else
value=line(equal_index+1:semicolon_index-1);

% Make sure that eval doesn't change the type of numeric variables.
% Note that if(eval( ['exist ' name])) can't be used directly.
% http://www.mathworks.com/help/matlab/matlab_prog/variables-in-nested-and-anonymous-functions.html

eval( ['exist ' name ';']);
if (ans)
disp('Assigning new value for variable:')
if (isa(eval(name), 'numeric'))
eval([name ' = str2num(value)'])
end
else
disp('Initializing variable:')
eval([name ' = value'])
end
end
end
line=fgetl(fid);
end

fclose(fid);
disp('Finished reading parameters file');

message=['Setting number of bench repetitions to ',num2str(nreps)];
disp(message)

% Find the number of cores assigned to the job

coresenv=str2num(getenv('PBS_NUM_PPN'))
if(isempty(coresenv))
coresenv=1
end

% Set number of computational threads to coresenv
% Note Mathworks warns that the maxNumCompThreads function will
% be removed in future versions of MATLAB.

default_cores = maxNumCompThreads(coresenv)

% Calling bench with argument nreps read from the parameters file.

tic
bench(nreps)
toc

quit;

 

For More Information

Updated:
2014-01-16 - Mostly just cosmetic changes.
2014-02-04 - Added R2013b line to MATLAB compiler table.
2014-02-06 - Added example of reading parameters from a file and passing the parameter file name as an argument to a compiled MATLAB program.
2014-04-11 - Added R2014a line to MATLAB compiler table.