MATLAB

MATLAB is an integrated technical computing environment from theMathworks that combines array-based numeric computation, advanced graphics and visualization, and a high-level programming language. Separately licensed toolboxes provide additional domain-specific functionality.

The Mathworks provides MATLAB examples and tutorials for all experience levels here

Using MATLAB on Rivanna

You must always set up your environment in order to use MATLAB.  To load the most recent installed version run

module load matlab

You can work in the MATLAB desktop on the Rivanna frontends; we recommend FastX for this application.  However, the time and memory that a job can use on the frontends are limited, so for longer jobs you should submit your job to compute nodes through SLURM.

Submitting an Interactive Job

If you wish to run a longer job under the control of the Desktop, you will need to submit an interactive job.  This submits a job to the queueing system as usual, but rather than starting your program on the assigned compute node, an interactive job starts a shell in which you can run whatever you wish.  In order to transmit the display properly you must first issue the command

ssh -Y localhost

Then run the local command ijob

ijob -c 1 -A mygroup

For more information about ijob see its documentation.

Submitting a Batch Job

Once your program is debugged, we recommend running in batch mode when possible.  This runs the job in the background on a compute node.  Write a script similar to the following:

#!/bin/bash
#SBATCH -N 1   #Number of nodes
#SBATCH -n 1   #Number of cores
#SBATCH -t 01:00:00
#SBATCH -o output_filename
#SBATCH -p standard 
#SBATCH -A mygroup

module load matlab
matlab -nojmv -nodisplay -nosplash -singleCompThread -r "Mymain(myvar1s);exit"

The options -nojmv and -nodisplay suppress the Desktop and any attempt to run a graphical display.  The -singleCompThread option is to ensure that all MATLAB built-in functions use only one thread.  Some MATLAB functions are capable of running on multiple cores, but may not do so very efficiently.  To use them in multicore mode you must request the appropriate number of cores, but you will be charged SUs for all cores whether they are used effectively or not.  Unless you are sure you can use the cores effectively it's generally best to restrict your job to one core.

The ;exit is very important to ensure that the job terminates when the computation is done.

Compiling Your MATLAB Code

The number of licenses for MATLAB is limited; this is especially true for some of the specialty toolkits.  If you compile your code, you can run it without requiring any licenses.  This helps both you (since you will not need to worry about whether a license is available) and other users (by keeping licenses free). 

The first requirement is that all your code must be in functions; none can be a script.  If you have a master script, turn it into a function called, for example, main.m.  Suppose your other functions are in files myfirst.m and mysecond.m.  Then, after loading the matlab module, run

mcc -m main myfirst mysecond

This produces an executable called main. You then run main as a standalone executable in your SLURM script.

When you are running many jobs from a compiled code, they will share a location to cache libraries and other data, which by default is .mcrCache in your top-level home directory.  Since all your jobs are trying to use the same files, corruption can occur.  We recommend that you separate your cache locations for each job.  This can be accomplished by adding to your SLURM script the line

export MCR_CACHE_ROOT=/scratch/$USER/$SLURM_JOB_ID

Running MATLAB in Parallel on Rivanna

If you have a job that can be structured to run across multiple cores, you can greatly speed up the time to your results.  There are two ways to run in parallel in MATLAB. The Parallel Computing Toolkit allows you to distribute for loops over multiple cores using parfor.  Here is an example of a parallel loop

tic;
parfor i=1:nloop
    a(i)=FunctionTakesLongTime();
    end
time=toc

The full example can be downloaded below.

To run your parallel matlab code using a SLURM script, you can use a script similar to the following

#!/bin/bash

#SBATCH -p standard
#SBATCH -A hpc_build
#SBATCH --time=12:00:00
#SBATCH --output=parforTest1.out
#SBATCH --error=parforTest.err
#SBATCH --nodes=1                #Number of nodes
#SBATCH --ntasks-per-node=20     #Number of cores per node

# Load Matlab environment
module load matlab

# Run Matlab parallel program program
matlab -nodisplay -nosplash  \
-r "parpool('local',19);parallelFuncTakesLongTime();exit;" 

Notice that the local profile is used. You may need to open MATLAB and edit the local parallel profile to specify a new maximum number of workers(the default is 20). Additionally you should specify the pool to have one less worker than the number of cores requested from SLURM. This is because the main MATLAB instance will be running on one of the cores requested.  As of right now mulit-node jobs are not working.

To run parallel jobs directly from the MATLAB UI requires you to set up your profile and to connect to SLURM. This method may not currently work with the recent updates to Rivanna.

You can also use the Distributed Computing Toolkit to distribute work across different nodes.

Documentation for using parallel MATLAB on Rivanna can be found here

Documentation on how to compile MATLAB parallel code to run on all cores of a single compute node can be found here