Using MATLAB on HPC

The following is meant to be a brief guide to running MATLAB jobs on HPC. For more information on running jobs, please see the New User Guide or Running a Job on HPC using Slurm.

MATLAB Paths

MATLAB uses a search path to locate files. You can explicitly set the search path using the MATLABPATH environment variable in your Slurm or environment setup script with a line like the following:

export MATLABPATH=/home/rcf-proj/tt/ttrojan/matlab:$MATLABPATH

Within a script, use path to display MATLAB’s search path, and addpath() to add a new location to the search path.

>> path  
>> addpath('/home/rcf-proj/tt/ttrojan/matlab')  
>> path

See the What Is the MATLAB Search Path? and Set the MATLABPATH Environment Variable pages on the Mathworks website for more information about MATLAB’s search path.

Running MATLAB Interactively

It is a good idea to test your MATLAB program on an “interactive” compute node, before submitting a batch (remote) job. The following will request a compute node with 8 cpus, each with 2GB of memory, for 1 hour and, when the resource is allocated, log you into the node.

[ttrojan@hpc-login3]$ salloc --ntasks=8 --mem-per-cpu=2g --time=1:00:00
salloc: Pending job allocation 2377051
salloc: job 2377051 queued and waiting for resources
salloc: job 2377051 has been allocated resources
salloc: Granted job allocation 2377051
salloc: Waiting for resource configuration
salloc: Nodes hpc3676 are ready for job
---------- Begin SLURM Prolog ----------
Job ID:        2377051
Username:      ttrojan
Accountname:   lc_hpcc
Name:          sh
Partition:     quick
Nodelist:      hpc3676
TasksPerNode:  8
CPUsPerTask:   Default[1]
TMPDIR:        /tmp/2377051.quick
SCRATCHDIR:    /staging/scratch/2377051
Cluster:       uschpc
HSDA Account:  false
---------- 2018-12-12 17:59:36 ---------
[ttrojan@hpc3676]$ 

Once you are on a compute node, select the version of MATLAB you wish to run from /usr/usc/matlab. Now load, or “source” the setup script for your selected version to configure your current environment to find and use that version of MATLAB.

$ source /usr/usc/matlab/R2018a/setup.sh

Note: This assumes you are running in a bash shell. For a (t)csh shell, source setup.csh.

To test an example, create a test file, hello.m and add the following lines:

disp('Hello Tommy!')
exit

You can use the option –nodisplay to suppress the graphical interface. Batch jobs run remotely with no GUI. Note: You cannot suppress the copyright.

$ matlab -nodisplay -r hello

        < M A T L A B (R) >
Copyright 1984-2018 The MathWorks, Inc.
R2018a (9.4.0.813654) 64-bit (glnxa64)
        February 23, 2018
              : 
Hello Tommy!

Alternatively, you can run your program within MATLAB.

[ttrojan@hpc-login3]$ matlab -nodisplay
        < M A T L A B (R) >
Copyright 1984-2018 The MathWorks, Inc.
R2018a (9.4.0.813654) 64-bit (glnxa64)
        February 23, 2018
              : 
# If code in same directory where MATLAB was invoked
>> hello
Hello Tommy!

# If not, add its path to MATLAB's search path
>> addpath('/home/rcf-proj/tt/ttrojan/matlab/hello')
Hello Tommy!

Running MATLAB Remotely

When you have tested your MATLAB program and are ready to run it remotely, i.e., in batch mode, you will create a new text file, called a job script, where you will specify the compute resources and commands needed to run your job. The following job script, myjob.slurm, will request 16 cpus on a single compute node, each with 2GB of memory, for 4 hours, and will then set up MATLAB R2018a and run myprogram.m.

#!/bin/bash
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=16
#SBATCH --mem-per-cpu=2GB
#SBATCH --time=4:00:00
#SBATCH --export=none #Ensures job gets a fresh login environment

source /usr/usc/matlab/R2018a/setup.sh
matlab -nodisplay -r hello

You can now submit your job for remote processing using Slurm’s sbatch jobscript command.

[ttrojan@hpc-login3 matlab]$ sbatch example_matlab.slurm
Submitted batch job 1131075

To check on the status of your job use the command squeue -u username. If you are on a head node, you can use the HPC squeue wrapper myqueue.

$ squeue -u ttrojan
JOBID PARTITION     NAME     USER ST       TIME  NODES NODELIST(REASON)
1131095     quick example_matlab     ttrojan PD       0:00      2 (Resources)

$ myqueue
JOBID    USER  ACCOUNT  PARTITION  NAME             TASKS  CPUS_PER_TASK  MIN_MEMORY  START_TIME           TIME  TIME_LIMIT  STATE    NODELIST(REASON)
1131075  ttrojan  lc_tt1  quick      example_matlab  16     1              1G          2018-07-02T11:14:46  1:49  30:00       RUNNING  hpc1046

By default, all output sent to the console, including error messages and print statements, is directed to a file named “slurm-%j.out”, where the “%j” is replaced with the job ID number. The file will be generated on the first node of the job allocation.

Any files created by the MATLAB program itself will be created as specified by the program.

Running MATLAB Graphically

MATLAB can be run graphically, as you would run it on your personal computer. You must log in to a head node with X11 Forwarding enabled.

ssh -X username@hpc-login.usc.edu

To run MATLAB graphically, type the following. The ‘&’ runs the program in the background.

$ source /usr/usc/matlab/R2018a/setup.sh
$ matlab &

MATLAB Licenses

USC has a university-wide license for MATLAB that includes the Linux versions maintained by USC in /usr/usc/matlab. Additionally, HPC licenses MATLAB’s Parallel Computing Toolbox and MATLAB Distributed Computing Server for running single and multi node parallel jobs.

The following command displays the number of MATLAB licenses that are in use:

$ /usr/usc/matlab/R2016a/etc/glnxa64/lmutil lmstat -a -c /usr/usc/matlab/R2016a/licenses/network.lic | grep MATLAB
Users of MATLAB:  (Total of 10000 licenses issued;  Total of 16 licenses in use)
  "MATLAB" v39, vendor: MLM, expiry: 30-jan-2019
Users of MATLAB_Distrib_Comp_Engine:  (Total of 1000 licenses issued;  Total of 376 licenses in use)
  "MATLAB_Distrib_Comp_Engine" v39, vendor: MLM, expiry: 01-jan-0000


You can search for the MATLAB distributed computing licenses that are checked out to you:

$ /usr/usc/matlab/R2016a/etc/glnxa64/lmutil lmstat -a -c /usr/usc/matlab/R2016a/licenses/network.lic | grep -e MATLAB -e Distrib_Comp -e ttrojan
Users of MATLAB:  (Total of 10000 licenses issued;  Total of 14 licenses in use)
  "MATLAB" v39, vendor: MLM, expiry: 30-jan-2019
    ttrojan hpc3613 /dev/tty (v36) (hpc-licenses/28518 121423), start Thu 12/20 16:09
Users of Distrib_Computing_Toolbox:  (Total of 10000 licenses issued;  Total of 12 licenses in use)
  "Distrib_Computing_Toolbox" v39, vendor: MLM, expiry: 30-jan-2019
    ttrojan hpc3613 /dev/tty (v36) (hpc-licenses/28518 91467), start Thu 12/20 16:09
Users of MATLAB_Distrib_Comp_Engine:  (Total of 1000 licenses issued;  Total of 346 licenses in use)
  "MATLAB_Distrib_Comp_Engine" v39, vendor: MLM, expiry: 01-jan-0000
    ttrojan hpc3617 /dev/tty (v36) (hpc-licenses/28518 3926), start Thu 12/20 10:02
    ttrojan hpc3617 /dev/tty (v36) (hpc-licenses/28518 121423), start Thu 12/20 16:09
    ttrojan hpc3615 /dev/tty (v36) (hpc-licenses/28518 61352), start Thu 12/20 10:03
    ttrojan hpc3615 /dev/tty (v36) (hpc-licenses/28518 91467), start Thu 12/20 16:09

Debugging

There are options for debugging MATLAB. See the matlab (Linux) page on the Mathworks website.

Getting Help

For additional information on MATLAB, please visit the Mathworks help website. For any questions related specifically to using Parallel MATLAB on HPC, send an email to hpc@usc.edu.