You are here

Running MATLAB on WestGrid Systems with Donated Licenses

Introduction

Until the fall of 2009, WestGrid had not purchased MATLAB, but, relied on the academic licenses at the partner institutions. However, those licenses restrict use of MATLAB to machines hosted at a researcher's particular institution. Since that time, WestGrid has purchased a consortium license for the MATLAB Distributed Computing Server that allows broader access to MATLAB. In February 2012, SFU acquired a site license that also allows SFU-based researchers access to MATLAB and the Distributed Computing Server on WestGrid machines hosted at SFU.

The notes below relate to the previous installations of MATLAB, not to the Distributed Computing Server. See the main MATLAB page for information on how to submit jobs to the Distributed Computing Server.

Using MATLAB in Batch Mode

MATLAB may be run in either an unattended (batch) or an interactive mode. The instructions given here are primarily for batch job submission. For advice on interactive usage, please contact support@westgrid.ca.

Users are expected to be generally familiar with MATLAB capabilities, including use of the MATLAB compiler, mcc.

To use MATLAB in batch mode, prepare a file of MATLAB commands (a so-called "M-file"), with a quit statement at the end.

For example, suppose the following commands (to approximate a Fourier expansion of a sawtooth function and save a plot of the result to a PostScript file) are placed in a file called cosplot.m:

% MATLAB M-file example to approximate a sawtooth
% with a truncated Fourier expansion.
nterms=5;
fourbypi=4.0/pi;
np=100;
y(1:np)=pi/2.0;
x(1:np)=linspace(-2.0*pi,2*pi,np);

for k=1:nterms
twokm=2*k-1;
y=y-fourbypi*cos(twokm*x)/twokm^2;
end;

%(The following commands for generating graphics output work
% with MATLAB 7 on glacier but produce empty plots with MATLAB 6
% on some other systems.)
plot(x,y);
print -dpsc matlab_test_plot.ps;
quit;

To run MATLAB interactively on Glacier (UBC researchers only), with the above M-file as input, we could use:

/global/software/matlab/bin/matlab < cosplot.m

However, like other jobs on WestGrid systems, if one is doing more than small debugging runs, MATLAB jobs should be submitted for batch scheduling. This is done by embedding the MATLAB command line in a script which is then submitting using the qsub command. Details of scheduling and job management are explained elsewhere, but, simple examples of job submission are shown in the following sections

Using MATLAB in Batch Mode on Glacier (UBC researchers only)

Note: The Glacier cluster is being retired, so, these notes are here only for historical reference. As mentioned above, WestGrid has not purchased MATLAB licenses. The MATLAB licenses for jobs on Glacier are provided courtesy of the University of British Columbia, out of the license pool available to the entire UBC community. A total of 20 general MATLAB licenses have been made available for WestGrid Glacier cluster users. The number of MATLAB toolbox licenses is not currently restricted in that way. Please note that MATLAB is available on Glacier only for UBC researchers.

In order to manage the licenses effectively, a MATLAB job script (example shown below) should specify how many licenses are required for both MATLAB and the MATLAB Toolboxes. Jobs that request more than the allowed number of licenses will be cancelled without notice. To indicate that a single MATLAB license is required, add the following line to the batch job script:

#PBS -W x=GRES:MATLAB

Here GRES is specifying a Moab resource manager extension for generic resources (GRES).

If more than one MATLAB license is required, specify the number after a plus sign. For example, to advise that 2 licenses are needed, use:

#PBS -W x=GRES:MATLAB+2

Requests for Toolbox licenses are handled in a similar manner, listing the Toolbox name or names, separating them by commas and using a numerical suffix to indicate the number required. For example:

#PBS -W x=GRES:MATLAB+3,Image_Toolbox+2

Note the line "#PBS -W x=GRES..." is not needed for compiled MATLAB programs that do not require access to the license manager at run time. Also, as of this writing, this directive cannot be used in conjunction with the quality of service flag,-W x="QOS:debug", which is normally available for requesting processors reserved for short test jobs.

To run a batch job on Glacier, submit a script similar to matlab.pbs, shown below, to the default queue using qsub:

qsub -l walltime=12:00:00 matlab.pbs

Modify the m-file name, cosplot.m in the example, to reference your own input file of MATLAB commands.

#!/bin/bash
#PBS -S /bin/bash
#PBS -W x=GRES:MATLAB

# PBS script for MATLAB batch job, DSP 2005-06-01,2006-02-03,2006-11-24
# If this file is "matlab.pbs", submit with "qsub matlab.pbs"

# Check on some basics:
echo "Running on host: " `hostname`
echo "Changing to directory from which PBS script was submitted."
cd $PBS_O_WORKDIR
echo "Current working directory is now: " `pwd`
echo "Starting MATLAB at `date`"

# Let cosplot.m be a file of MATLAB commands.
# Be sure to include a "quit;" as the last line of the file.
# Run MATLAB with this command file:

/global/software/matlab/bin/matlab -nodisplay -nojvm -nodesktop -nosplash < cosplot.m

echo "MATLAB run completed at `date`"

The Distributed Computing Toolbox was formerly available on Glacier for doing parallel computations in MATLAB, although facility has now been moved to Orcinus. Example job scripts are available on Glacier in /global/software/matlab/job_examples.

Using the MATLAB compiler

To use the MATLAB compiler to compile a MATLAB function m-file, cosplot2.m, use the mcc command with a -m argument:

mcc -m cosplot2.m

Please note that the m-file must contain a function statement - script m-files cannot be used directly with the MATLAB compiler. See documentation for the compiler at the Mathworks web site. Here is an example function m-file (which also illustrates that the function m-files can take arguments):

function cosplot2(nterms,postscript_output)
% MATLAB M-file example to approximate a sawtooth
% with a truncated Fourier expansion.
fourbypi=4.0/pi;
np=100;
y(1:np)=pi/2.0;
x(1:np)=linspace(-2.0*pi,2*pi,np);

for k=1:nterms
twokm=2*k-1;
y=y-fourbypi*cos(twokm*x)/twokm^2;
end;

%(The following commands for generating graphics output work
% with MATLAB 7 on glacier but produce empty plots with MATLAB 6
% on some other systems.)
plot(x,y);
print('-depsc',postscript_output);
quit;
end

Following is an example of a batch job submission script showing how to run an mcc-compiled program. Note that the #PBS -W x=GRES:MATLAB line used when running MATLAB itself is not used for the compiled version, as a MATLAB license is not needed at run time in the latter case.

#!/bin/bash
#PBS -S /bin/bash
# PBS batch job script to run an mcc-compiled MATLAB program, DSP 2007-11-05
# If this file is "matlab.pbs", submit with "qsub matlab.pbs"
# Check on some basics:

echo "Running on host: " `hostname`
echo "Changing to directory from which PBS script was submitted."
cd $PBS_O_WORKDIR
echo "Current working directory is now: " `pwd`

echo "Starting run at `date`"
# Let cosplot2.m be a MATLAB function m-file, compiled to cosplot2 .
# Run cosplot2 with:
cosplot2 3 cosplot_3.eps
echo "Run completed at `date`"

If you encounter an error message indicating that "app-defaults file cannot be found in any of the default places", this can be corrected by setting the XAPPLRESDIR environment variable to include the directory /global/software/matlab/X11/app-defaults.

Using MATLAB on Bugaboo (SFU researchers only)

Researchers who are based at SFU may run MATLAB jobs on Bugaboo using the University's site license. Access to all the MATLAB toolboxes is provided. Up to 32 processors per user are available.

Note the line #PBS -W x=GRES... shown in the Glacier batch job example is not needed on Bugaboo.

Using MATLAB on Grex (U of M researchers only)

Researchers who are based at the University of Manitoba can use the University's site license for MATLAB. Type

module load uofm/matlab

to place the MATLAB executables in your command path.

Using MATLAB on Jasper and Hungabee (U of A researchers only)

Researchers who are based at the University of Alberta can run MATLAB on Jasper. Type

module load uofa/matlab/<release number>

to place the MATLAB executables in your command path. For example:

module load uofa/matlab/R2013a

Type module avail to see a list of available MATLAB releases.

Following is a sample MATLAB script for running on Jasper:

#!/bin/bash
#PBS -S /bin/bash
#PBS -l nodes=1:ppn=1
#PBS -l walltime=24:00:00
#PBS -m bea
#PBS -M yourEmail@yourEmailAddress
cd $PBS_O_WORKDIR
module load uofa/matlab/R2013a
matlab -nodisplay -singleCompThread -r myScript -logfile matlab.log

2015-12-15 - Fixed various formatting errors.