MATLAB at WestGrid
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.
Until recently, WestGrid had not purchased MATLAB, but, relied on the academic licenses of the Universities of Calgary, Alberta and British Columbia. As such, MATLAB jobs could be run by researchers from Calgary only on the Terminus cluster hosted at Calgary, U. of Alberta researchers only on machines at the U of A and UBC researchers only on the UBC machines. However, in late 2009, WestGrid purchased a new 64-worker "consortium" license for the MATLAB Distributed Computing Server, which will overcome the restrictions with the old licensing arrangement. The new license will allow researchers who have licensed the Parallel Computing Toolbox to submit jobs to a WestGrid cluster, even if it is not located at their home institution.
If you own a Parallel Computing Toolbox license and would like to participate in testing the Distributed Computing Server, please contact WestGrid technical support.
The notes below relate to the previous installations of MATLAB, not to the Distributed Computing Server. Instructions for the latter software will be added as testing is completed.
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:
% 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 lattice and nexus.)
plot(x,y);
print -dpsc matlab_test_plot.ps;
quit;
To run MATLAB interactively on Nexus, with the above M-file as input, we could use:
/usr/local/bin/matlab < cosplot.m
On glacier, you can run MATLAB with:
/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 Nexus
Please note that MATLAB is available on Nexus only for U. of Alberta researchers. Even so, such researchers may be better off applying to use a more recent version of MATLAB on a non-WestGrid cluster at the U of A. (See http://www.ualberta.ca/AICT/RESEARCH/LinuxClusters/ and http://www.ualberta.ca/AICT/RESEARCH/Software/MATLAB.numstats.site.html).
Most of the WestGrid SGI computers at the University of Alberta are intended for parallel jobs. Nexus and Helios are ones on which serial jobs may be run. To access these machines, log in to nexus.westgrid.ca.
Use the following command to submit the script, matlab.pbs, to the nexus queue.
where matlab.pbs is shown below. Modify the m-file name, cosplot.m in the example, to reference your own input file of MATLAB commands.
#PBS -S /usr/bin/bash
# PBS script for MATLAB batch job, DSP 2004-12-06
# If this file is "matlab.pbs", submit with "qsub matlab.pbs"
# Check on some basics:
echo "Running on host: " `/usr/bsd/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:
/usr/local/bin/matlab -nojvm -nodesktop -nosplash < cosplot.m
echo "MATLAB run completed at `date`"
Using MATLAB in Batch Mode on Glacier
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. However, Non-UBC researchers who can compile binary-compatible standalone applications using their own MATLAB compiler licenses may run such applications without licensing restrictions.
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:
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:
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:
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:
Modify the m-file name, cosplot.m in the example, to reference your own input file of MATLAB commands.
#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 Distibuted Computing Toolbox is available on Glacier for doing parallel computations in MATLAB, although this is at an early stage of development. 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:
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):
% 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 lattice and nexus.)
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.
#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.
Updated 2010-01-07.
