Introduction

Running MATLAB on HPC's cluster nodes is similar to running any other serial job. Make sure you've read the tutorial for C programs first, to understand the basics. We will not demonstrate any parallel code here, so reading just the serial section is okay for now. A basic introduction to running MATLAB in the computer labs at UMBC is available on the CIRC webpage here.

For more information about the software, see the MATLAB website.

Performing Calculations on the Cluster Nodes

Let's try to run this sample MATLAB program, given below

% Generate two 100x100 matrices with random contents:
A=rand(100);
B=rand(100);

% Multiply the two matrices:
AB=A*B;

% Calculate the sum of the contents:
sumAB=sum(AB(:));

% Save the AB and sumAB variables to the Matlab save file out.mat:
save out.mat AB sumAB;

Download: ../code-2010/matrixmultiply-matlab/matrixmultiply.m

As always, we will need a batch script too

#!/bin/bash
#SBATCH --job-name=matrixmultiply
#SBATCH --output=slurm.out
#SBATCH --error=slurm.err
#SBATCH --partition=develop

matlab -nodisplay -r "matrixmultiply, exit"

Download: ../code-2010/matrixmultiply-matlab/run.slurm

Note that by using the serial queue, we've requested a single core of one node for our job. This will help to yield the best throughput of MATLAB jobs on the cluster. See the technical report HPCF-2009-1 (Sharma & Gobbert) on the publications page for more details. We can run our batch script in the usual way

[araim1@tara-fe1 matrixmultiply-matlab]$ sbatch run.slurm
sbatch: Submitted batch job 2621
[araim1@tara-fe1 matrixmultiply-matlab]$

After your job completes, you should see an out.mat MATLAB save file in your directory. Later on, if you want to get the data out of that file, you can use the the load command in MATLAB:

>> load out.mat

which will load in the AB and sumAB variables that you saved using your save command. Also in your directory, there should also be slurm.out and slurm.err files. The slurm.err file should be empty and the slurm.out file should contain something like this

[araim1@tara-fe1 matrixmultiply-matlab]$ cat slurm.out
                            < M A T L A B (R) >
                  Copyright 1984-2008 The MathWorks, Inc.
                         Version 7.6.0.324 (R2008a)
                             February 10, 2008


  To get started, type one of these: helpwin, helpdesk, or demo.
  For product information, visit www.mathworks.com.

[araim1@tara-fe1 matrixmultiply-matlab]$

You should be able to use any of the usual non-graphical MATLAB functionality if you follow the directions in this section. If you want to generate graphics in your MATLAB jobs, continue to the next section.

Generating Plots on the Cluster Nodes

As with all cluster jobs, you will need a batch script in order to run MATLAB

#!/bin/bash
#SBATCH --job-name=plotsine
#SBATCH --output=slurm.out
#SBATCH --error=slurm.err
#SBATCH --partition=develop

matlab -nodisplay -r "plotsine, exit"

Download: ../code-2010/plotsine-matlab/run.slurm

Now you'll need the plotsine.m file that the script tries to run

zero_to_2pi=linspace(0,2*pi,1000);
them_sine=sin(zero_to_2pi);

plot(zero_to_2pi,them_sine);
print -dpng sine.png
print -deps sine.eps
print -djpeg sine.jpeg

Download: ../code-2010/plotsine-matlab/plotsine.m

Now submit the batch script and wait for it to finish. After it finishes, you should see the following files

[araim1@tara-fe1 plotsine-matlab]$ ls
run.slurm      plotsine.m  sine.eps        sine.jpeg     
sine.png       slurm.err   slurm.out
[araim1@tara-fe1 plotsine-matlab]$

The sine.eps, sine.jpeg and sine.png files contain a plot of sin(x) from x=0..2*pi. The files are encapsulated postscript (.eps), joint photographic experts group (.jpeg) and portable network graphics files (.png), respectively. The slurm.err file should be empty and the slurm.out file should contain the same text as in the previous section. The three images you made should look something like this

PNG sine plot

The encapsulated postscript file (sine.eps) will be in greyscale since I used -deps instead of -depsc. Here are links to the three output files if you want to download them

Checking memory in Matlab programs

On the How to check memory usage page, we discuss various ways of monitoring memory usage, including logging it directly from your C code. In Matlab, there doesn't seem to be a built-in way to do this (not in the Linux version at least). But with a small amount of work, we can add the capability ourselves.

First grab the following C files, which are also used in How to check memory usage

The following C code is written in a specific form which Matlab can interface to. It will call the get_memory_usage_kb function defined in the C files above. The code retrieves the VmRSS and VmSize quantities for the current process (see How to check memory usage for more information), and returns them as a pair to Matlab.

#include <sys/types.h>
#include <unistd.h>
#include "mex.h"
#include "memory.h"

void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[])
{
    int* data;
    long vmrss;
    long vmsize;

    if (nrhs > 0)
    {
        mexErrMsgTxt("Too many input arguments.");
    }

    get_memory_usage_kb(&vmrss, &vmsize);

    plhs[0] = mxCreateNumericMatrix(1, 1, mxUINT32_CLASS, mxREAL);
    data = mxGetData(plhs[0]);
    data[0] = vmrss;

    plhs[1] = mxCreateNumericMatrix(1, 1, mxUINT32_CLASS, mxREAL);
    data = mxGetData(plhs[1]);
    data[0] = vmsize;
}

Download: ../code-2010/check_memory-matlab/getmemusage.c

To compile this code, we need to use the Matlab MEX compiler. This is already installed on the cluster. We can use it as follows to compile our code. If the compilation succeeds, the file getmemusage.mexa64 is created.

[araim1@tara-fe1 check_memory-matlab]$ mex getmemusage.c memory.c
[araim1@tara-fe1 check_memory-matlab]$ ls
getmemusage.c  getmemusage.mexa64  memory.c  memory.h
[araim1@tara-fe1 check_memory-matlab]$

Now we can start up Matlab and call our new getmemusage function just like any usual function

[araim1@tara-fe1 check_memory-matlab]$ matlab -nodisplay

                                                   < M A T L A B (R) >
                                         Copyright 1984-2009 The MathWorks, Inc.
                                       Version 7.9.0.529 (R2009b) 64-bit (glnxa64)
                                                     August 12, 2009

 
  To get started, type one of these: helpwin, helpdesk, or demo.
  For product information, visit www.mathworks.com.
 
>> [vmrss, vmsize] = getmemusage

vmrss =

      101140


vmsize =

      933132
>> A = rand(5000, 5000);
>> [vmrss, vmsize] = getmemusage 

vmrss =

      298572


vmsize =

     1128448

>>

Note that this approach has a few limitations. It can only keep track of memory used in the current process. Matlab may invoke external processes for some tasks, whose memory usage will not be counted by this method.