Using MATLAB on Savio

Getting access | Loading MATLAB | Viewing Add-Ons | Batch mode | Parallel batch mode | GPUs | Interactive (command line) | Interactive (graphics)

This document describes how to use MATLAB, a matrix-based, technical computing language and environment for solving engineering and scientific problems, on the Savio high-performance computing cluster at the University of California, Berkeley.

Getting access to MATLAB on Savio

Before you can use MATLAB on the Savio cluster, you'll need to:

  • Have an account on the cluster.
  • Provide a license key for the MATLAB software that you obtained from UC Berkeley's Software Central. (As a current UC Berkeley Faculty, Staff member, or Student, you can obtain this key at no cost, via that website.)

Once you have a license file, you can request access via an email sent to Savio's Getting Help email address. You can either send your file as an attachment, or paste its contents into your email. Please send the actual license file that you obtained from Software Central, not just the license number itself.

Licenses expire annually, at the end of January each year. As a result, you'll need to obtain a new license file each new calendar year, and then send in your new license information once again, as described above.

Loading MATLAB

To load MATLAB into your current software environment on Savio, at any shell prompt, enter:

module load matlab

If you have not submitted license information, or if your license has expired, you may encounter an error message similar to the following, when attempting to load the MATLAB software module into your environment via the above command:

You do not have permission to access!.
MATLAB on BRC Savio cluster can only be used by those subscribed to
'matlab' unix group. To get access to MATLAB send us a copy of the
MATLAB license (email to brc-hpc-help@berkeley.edu) that you
obtained from UCB Software Central. We accept licenses from UCB
Software Central only. Do not send the licenses you might have
purchased directly from Mathworks.

Viewing MATLAB Add-Ons

Once you are working interactively with MATLAB, you can then enter the ver command at MATLAB's interactive '>>' prompt to view all of the MathWorks® Add-Ons (Toolboxes and Applications) currently provided on Savio; e.g.:

ver
----------------------------------------------------------------------------------
MATLAB Version: 8.5.0.197613 (R2015a)
...
----------------------------------------------------------------------------------
MATLAB                                                    Version 8.5            (R2015a)
Simulink                                                  Version 8.5            (R2015a)
Aerospace Blockset                                        Version 3.15           (R2015a)
Aerospace Toolbox                                         Version 2.15           (R2015a)
Antenna Toolbox                                           Version 1.0            (R2015a)
Bioinformatics Toolbox                                    Version 4.5.1          (R2015a)
...

Running MATLAB jobs in batch mode

To run MATLAB in batch mode on Savio's compute nodes, enter the command sbatch followed by a single argument: the name of (or full path to) a job script file.

Inside that job script file, at or near the end of that file, you will include the following:

  • A command to load MATLAB into the software environment of the compute node.
  • A command to run the MATLAB application, specifying that its input should come from a MATLAB script (.m) file. (If needed, that script file can, in turn, execute other scripts and functions.)

For more detailed information on using sbatch and job script files, see Running Your Jobs.

Here's one example, which loads MATLAB, receives input from your script file, and saves selected output into an output log file:

#!/bin/bash
# Job name:
#SBATCH --job-name=matlabhelloworld_example
#
# Partition:
#SBATCH --partition=savio
#
# QoS:
#SBATCH --qos=savio_debug
#
# Account:
#SBATCH --account=ac_scsguest
#
# Wall clock limit:
#SBATCH --time=00:02:30
#
## Command(s) to run:
module load matlab
matlab -nosplash -nodesktop -logfile helloworld.log < helloworld.m

Running MATLAB jobs in batch mode with parallel computing code

MATLAB is capable of distributing computations across multiple cores, allowing your scripts or functions to execute those computations "in parallel." That can significantly speed up some computational tasks.

MATLAB on Savio includes a license for the Parallel Computing Toolkit, which facilitates parallel computation. To use parallel computing features, you'll need to run MATLAB code that uses one or more of the parallel commands, functions, etc. available within the MATLAB programming language.

Here's an example of a job script to run a MATLAB job that contains parallel computing code, in batch mode, on up to the full 20 cores offered by a compute node on the savio partition:

#!/bin/bash
# Job name:
#SBATCH --job-name=matlabhelloworld_parallel_example
#
# Partition:
#SBATCH --partition=savio
#
# QoS:
#SBATCH --qos=savio_debug
#
# Account:
#SBATCH --account=ac_scsguest
#
# Request one node:
#SBATCH --nodes=1
#
# Number of Processors per Node:
#SBATCH --ntasks-per-node=20
#
# Wall clock limit:
#SBATCH --time=00:20:00
#
## Command(s) to run:
module load matlab/R2015a
# Make a temporary scratch directory for storing job
# and task information, to coordinate parallelization.
# This directory can then be referenced by assigning it to
# a 'parcluster.JobStorageLocation' property in your script.
mkdir -p /global/scratch/$USER/$SLURM_JOB_ID
matlab -nodisplay -nosplash -nodesktop < helloworld_parallel.m

To learn about the features of the MATLAB programming language that are capable of performing computations in parallel (e.g., parfor, batch(), spmd, and others), and how to use them in MATLAB scripts and functions, please see the MathWorks documentation, Introduction to Parallel Solutions or the brief discussion in the next section.

In addition, some MATLAB products can intrinsically use parallel computing features without requiring coding, perhaps simply by setting a flag or preference, as described in Parallel Computing Support in MATLAB and Simulink Products.

Controlling the number of cores used in MATLAB jobs

There are a various ways to control the amount of parallelization in your MATLAB code. This discussion briefly outlines two ways, focusing on use of parfor for parallel loops and on threading.

If you are running a job on the savio2_htc partition, using less than the entire node, or if you are running multiple jobs on a node that you have exclusive access to, you'll want to carefully control the number of cores in use by your MATLAB job(s).

Threading

By default, a variety of MATLAB functions will use threading to do computations in parallel. To turn threading off, you can start MATLAB with the -singleCompThread flag:

matlab -singleCompThread ...

Or, to control the number of threads used by your MATLAB process from within MATLAB, you use this syntax, in this case to use 5 cores (threads):

feature('numThreads', 5);

You can also set the number of threads programmatically; often you'll do this based on environment variables that the SLURM scheduler sets. For example, if your submission script requested five cores per task, you can do this to set the number of threads to five, without having to hard-code it into your MATLAB code:

feature('numThreads', str2num(getenv('SLURM_CPUS_PER_TASK')));

Parallel looping / parallel pool

MATLAB allows you to execute for loops in parallel via parfor. You'll first need to set up a pool of workers via parpool(), which determines how many workers will be used to execute the iterations of the loop. MATLAB will set a default number of workers (the default is 12 workers), but if you want to use fewer workers (e.g., to share the cores on a node across jobs) or more workers (e.g., to use all the cores on a node you are using exclusively), you can tell parpool() how many workers to start.

Here's an example of how to do this, in this case taking advantage of all the cores on a node:

parpool(str2num(getenv('SLURM_CPUS_ON_NODE')));

Or to use as many cores as requested via --cpus-per-task:

parpool(str2num(getenv('SLURM_CPUS_PER_TASK')));

As an alternative, if you want to change the default number of workers (e.g., to 20 if you are always using the savio partition), you can modify your ~/.matlab/MATLAB_VERSION/parallel.settings file (where MATLAB_VERSION should be replaced by the version of MATLAB you are using, such as R2015a as of May 2016) to have this stanza:

<key name="NumWorkers" visible="true">
 <double>
   <value>20.0</value>
 </double>
</key>

Running MATLAB jobs on Savio's GPU nodes with parallel computing code

To run MATLAB jobs that contain parallel computing code on Savio's Graphics Processing Unit (GPU) nodes, you'll need to write, adapt, or use MATLAB code that has been written for GPU access. To learn how to write or adapt MATLAB code that uses GPUs, please see GPU Programming in MATLAB.

When submitting your job, make sure to request one or more GPUs for its use by including the --gres=gpu:x flag (where the value of 'x' is 1, 2, 3, or 4, reflecting the number of GPUs requested), and also request two CPUs for every GPU requested, within the job script file you include in your sbatch command or as an option in your srun command. For further details, please see the GPU example in the examples of job submissions with specific resource requirements. You can monitor GPU usage and availability on your node by entering nvidia-smi from the UNIX command line (e.g., in an interactive session), as described further below.

If you requested a single GPU, you can set that up for use within MATLAB as follows:

g = gpuDevice();
% now do GPU-based operations

To use multiple GPUs (each GPU node has 4 GPUs) in the same MATLAB job, you'll first need to use --gres=gpu:x in your job submission (where 'x' is either 2, 3, or 4) and then use parfor to start up multiple processes, as with this demo code:

parfor i = 1:gpuDeviceCount
 g = gpuDevice(i);
 % now do GPU-based operations
end

Alternatively, assuming all four of a node's GPUs are available for your use, you could start four individual MATLAB jobs within your job script and set the device number, via gpuDevice(), to 1, 2, 3, and 4, respectively, within each of those individual MATLAB jobs.

To check on the current usage (and hence availability) of each of the GPUs on your GPU node, you can use the nvidia-smi command from the Linux shell within an interactive session on that GPU node. Near the end of that command's output, the "Processes: GPU Memory" table will list the GPUs currently in use, if any. For example, in a scenario where GPUs 0 and 1 are in use on your GPU node, you'll see something like the following. (By implication from the output below, GPUs 2 and 3 are currently idle - not in use, and thus fully available - on this node.)

+-----------------------------------------------------------------------------+
| Processes: GPU Memory |
| GPU PID Type Process name Usage |
|=============================================================================|
| 0 32699 C .../modules/langs/r/3.2.5/lib64/R/bin/exec/R 729MiB |
| 1 32710 C .../modules/langs/r/3.2.5/lib64/R/bin/exec/R 729MiB |
=============================================================================|

Running MATLAB interactively (command line)

Here's how to run MATLAB interactively, so you can interact directly with this application at its command line, as contrasted with running it in batch mode.

Step 1. Run an interactive shell

To use MATLAB interactively on Savio's compute nodes, you can use the following example command (which uses the long form of each option to srun) to run a bash shell as a job on a compute node. That, in turn, should then let you launch MATLAB from that shell, on that compute node, and work directly at its command line.

(Note: the following command is only an example, and you'll need to substitute your own values for the sample --partition--qos, --account, and --time values shown here; see below for more details.)

srun --unbuffered --partition=savio --qos=savio_normal --account=ac_scsguest --time=00:30:00 bash -i

For more information on running interactive SLURM jobs on Savio, please see Running Your Jobs.

Step 2: Load and run MATLAB from that shell

Once you're working on a compute node, your shell prompt will change to something like this (where 'n' followed by some number is the number of the compute node):

[myusername@n0033 ...]

At that shell prompt, you can enter the following to load the MATLAB software module:

module load matlab

To start MATLAB for interactive use, via its command line, you can then enter

matlab -nodisplay -nosplash

Running MATLAB interactively (command line plus graphics)

When you're running MATLAB on Savio in interactive mode, you can also set it up to display plots and similar graphical output on your computer. Here's how to do that:

Step 1. Have X Windows software installed and working on your computer

You'll need to have X Windows software installed and working on your computer. For instance, for Microsoft Windows, you can use Cygwin/X . For Apple Macintoshes running OS X, you can use XQuartz.

Step 2. Log into Savio using the '-Y' option to SSH

To enable applications like MATLAB and others to interact with the X Windows software on your computer, log into Savio using an ssh command that includes the -Y ("trusted X11 forwarding") option; e.g.:

ssh -Y myusername@hpc.brc.berkeley.edu

Step 3. Run an interactive shell

To use MATLAB interactively on Savio's compute nodes, you can use the following example command (which uses the long form of each option to srun) to run a bash shell as a job on a compute node. That, in turn, should then let you launch MATLAB from that shell, on that compute node, and work directly at its command line.

(Note: the following command is only an example, and you'll need to substitute your own values for the sample --partition--qos, --account, and --time values shown here; see below for more details.)

srun --pty --partition=savio --qos=savio_normal --account=ac_scsguest  --time=00:30:00 bash -i

For more information on running interactive SLURM jobs on Savio, please see Running Your Jobs.

Step 4: Load and run MATLAB from that shell

Once you're working on a compute node, your shell prompt will change to something like this (where 'n' followed by some number is the number of the compute node):

[myusername@n0033 ...]

At that shell prompt, you can enter the following to load the MATLAB software module:

module load matlab

To start MATLAB for interactive use, via its command line, in a manner that also generates graphical output from that application, you can then enter:

matlab

Step 5: (Optional) Generate a test plot

Here's a quick way to try out MATLAB in graphical, interactive mode, by generating a test plot.

The following statements, entered successively at MATLAB's interactive '>>' prompt, will display a simple plot of squares of the integers 1 through 10:

x = 1 : 10;
y = x.^2;
plot(x,y,'-o')

If all goes well, running the plot command, above, should result in output similar to the following being displayed in a window within your computer's X Windows application:

Sample plot of the squares of integers 1 through 10 generated by MATLAB