Matlab

Introduction#

MATLAB is a numerical computing environment and proprietary programming language developed by MathWorks.

More documentation#

The following documentation is specifically intended for using Matlab on Sherlock. For more complete documentation about Matlab in general, please see the official MATLAB documentation.

MATLAB on Sherlock#

Licensing#

MATLAB is a commercial software suite, which is now available to no cost for all Stanford Faculty, students, and staff.

Note: a number of free, open-source alternatives exist and can be used in many situations: Octave, R, Julia, or Python are all available on Sherlock, and can often replace MATLAB with good results.

Using MATLAB#

The MATLAB module can be loaded with:

$ ml load matlab

This will load the current default version. For a list of available versions run ml spider matlab at the Sherlock prompt, or refer to the Software list page.

-----------------------------------------------------------------------
WARNING: running MATLAB directly on login nodes is not supported.  Please
make sure you request an interactive session on a compute node with "sh_dev"
for instance) before launching MATLAB interactively.
-----------------------------------------------------------------------

Once you are on a compute node and your environment is configured (ie. when the matlab module is loaded), MATLAB can be started by simply typing matlab at the shell prompt.

$ sh_dev
$ ml load matlab
$ matlab
MATLAB is selecting SOFTWARE OPENGL rendering.
                          < M A T L A B (R) >
                Copyright 1984-2019 The MathWorks, Inc.
                R2019a (9.6.0.1072779) 64-bit (glnxa64)
                             March 8, 2019

To get started, type doc.
For product information, visit www.mathworks.com.

>>

For a listing of command line options:

$ matlab -help

Running a MATLAB script#

There are several ways to launch a MATLAB script on the command line, as documented in the MATLAB documentation:

MATLAB GUI#

It's often best to use your laptop or desktop to develop, debug MATLAB and visualize the output. If you do need to use the MATLAB GUI on a large cluster like Sherlock, you will need to enable X11 forwarding in your SSH client.

For instance:

$ ssh -X <YourSUNetID>@login.sherlock.stanford.edu

And then, once on Sherlock:

$ sh_dev
$ ml load matlab
$ matlab

For more info on X11 forwarding, you can refer to this UIT page.

Examples#

Simple MATLAB job#

Here is an example MATLAB batch script that can submitted with sbatch:

#!/bin/bash
#SBATCH --job-name=matlab_test
#SBATCH --output=matlab_test."%j".out
#SBATCH --error=matlab_test."%j".err
#SBATCH --partition=normal
#SBATCH --time=00:10:00
#SBATCH --cpus-per-task=1
#SBATCH --mem=8G
#SBATCH --mail-type=ALL

module load matlab
matlab -nodisplay < example.m

This simple job, named matlab_test will run a MATLAB script named example.m in the normal partition, for a duration of 10 minutes, and use 1 CPU and 8GB of RAM. It will send you an email (to whatever email you used wen you signed up for Sherlock) when it begins, ends or fails.

Additionally, to aid in debugging, it will log any errors and output to the files matlab_test.JOBID.{out,err} with the jobid appended to the filename (%j).

To create the script, open a text editor on Sherlock, copy the contents of the script, and save it as matlab_test.sbatch

Then, submit the job with the sbatch command:

$ sbatch matlab_test.sbatch
Submitted batch job 59942277

You can check the status of the job with the squeue command, and check the contents of the matlab_test.JOBID.{out,err} files to see the results.

Parallel loop#

You can run your MATLAB code across multiple CPUs on Sherlock using parfor loops, to take advantage of the multiple CPU cores that each node features. You can submit a job requesting as many CPUs as there are on a node in a single job. The key is to grab the SLURM environment variable $SLURM_CPUS_PER_TASK and create the worker pool in your MATLAB code with:

parpool('local', str2num(getenv('SLURM_CPUS_PER_TASK')))

Here is an example of a sbatch submission script that requests 16 CPUs on a node, and runs a simple MATLAB script using parfor.

Save the two scripts below as parfor.sbatch and parfor_loop.m:

#!/bin/bash
#SBATCH -J pfor_matlab
#SBATCH -o pfor".%j".out
#SBATCH -e pfor".%j".err
#SBATCH -t 20:00
#SBATCH -p normal
#SBATCH -c 16
#SBATCH --mail-type=ALL

module load matlab
matlab -batch parfor_loop

%============================================================================
% Parallel Monte Carlo calculation of PI
%============================================================================
parpool('local', str2num(getenv('SLURM_CPUS_PER_TASK')))
R = 1;
darts = 1e7;
count = 0;
tic
parfor i = 1:darts
   % Compute the X and Y coordinates of where the dart hit the...............
   % square using Uniform distribution.......................................
   x = R*rand(1);
   y = R*rand(1);
   if x^2 + y^2 <= R^2
      % Increment the count of darts that fell inside of the.................
      % circle...............................................................
     count = count + 1; % Count is a reduction variable.
   end
end
% Compute pi.................................................................
myPI = 4*count/darts;
T = toc;
fprintf('The computed value of pi is %8.7f.n',myPI);
fprintf('The parallel Monte-Carlo method is executed in %8.2f seconds.n', T);
delete(gcp);
exit;

You can now submit the job with the following command:

sbatch parfor.sbatch

If you run htop or pstree -u $USER on the compute node that is running your job, you will see all 16 cores allocated to your MATLAB code.

You can also try that same job with different numbers of CPUs, and see how well it scales.