Fork me on GitHub

MATLAB

Scientific computing and visualisation.

Interactive usage

After connecting to ShARC (see Establishing a SSH connection), start an interactive session with the qrshx command.

The latest version of MATLAB (currently 2019a) is made available by running:

module load apps/matlab

Alternatively, you can load a specific version with one of the following commands:

module load apps/matlab/2016a/binary
module load apps/matlab/2016b/binary
module load apps/matlab/2017a/binary
module load apps/matlab/2017b/binary
module load apps/matlab/2018a/binary
module load apps/matlab/2018b/binary
module load apps/matlab/2019a/binary

You can then run MATLAB by entering matlab.

Serial (one CPU) batch usage

Here, we assume that you wish to run the program helloworld.m on the system:

function helloworld
    disp('Hello World!')
end

First, you need to write a batch submission file. We assume you’ll call this my_job.sge:

#!/bin/bash
#$ -l rmem=4G                                # Request  4 GB of real memory
#$ -cwd                                      # Run job from current directory
module load apps/matlab/2019a/binary         # Make specific version of MATLAB available

matlab -nodesktop -nosplash -r helloworld

Ensure that helloworld.m and my_job.sge are both in your current working directory, then submit your job to the batch system:

qsub my_job.sge

Note that we are running the script helloworld.m but we drop the .m in the call to MATLAB. That is, we do -r helloworld rather than -r helloworld.m. The output will be written to the job .o file when the job finishes.

MATLAB Compiler and running free-standing compiled MATLAB programs

The MATLAB compiler mcc can be used to generate standalone executables. These executables can then be run on other computers that does not have MATLAB installed. We strongly recommend you use R2016b or later versions to take advantage of this feature.

To compile a MATLAB function or script for example called myscript.m the following steps are required:

# Load the matlab 2019a module
module load apps/matlab/2019a/binary

# Compile your program to generate the executable myscript and
# also generate a shell script named run_myscript.sh
mcc -m myscript.m

# Finally run your program
./run_myscript.sh $MCRROOT

If myscript.m is a MATLAB function that require inputs then these can be suplied on the command line. For example if the first line of myscript.m reads:

function out = myscript ( a , b , c )

then to run it with 1.0, 2.0, 3.0 as its parameters you will need to type:

./run_myscript.sh $MCRROOT 1.0 2.0  3.0

After a successful compilation and running you can transfer your executable and the runscript to another computer. That computer does not have to have MATLAB installed or licensed on it but it will have to have the MATLAB runtime system installed. This can be done by either downloading the MATLAB runtime environment from Mathworks web site or by copying the installer file from the cluster itself which resides in the .zip file:

$MCRROOT/toolbox/compiler/deploy/glnxa64/MCRInstaller.zip

This file can be unzipped in a temporary area and run the setup script that unzipping yields to install the MATLAB runtime environment. Finally the environment variable $MCRROOT can be set to the directory containing the runtime environment.

Parallel MATLAB: single node

Parallel MATLAB can be run exclusively on a single node.

An example batch script my_parallel_job.sh is:

#!/bin/bash
#$ -l rmem=2G
#$ -pe smp 12
#$ -M someuser@sheffield.ac.uk
#$ -m bea
#$ -j y

module load apps/matlab/2019a/binary

# Run parallel_example.m
matlab -nodisplay -r parallel_example

where parallel_example.m is:

% Create parallel pool of workers on the local node.
% Ensure that this is the same number as what you requested from the scheduler
pool = parpool('local',12)
disp('serial time')
tic
n = 200;
A = 500;
a = zeros(n);
for i = 1:n
     a(i) = max(abs(eig(rand(A))));
end
toc

disp('Parallel time')
tic
n = 200;
A = 500;
a = zeros(n);
parfor i = 1:n
     a(i) = max(abs(eig(rand(A))));
end
toc

delete(pool)

Parallel MATLAB: multiple nodes

Parallel MATLAB using multiple nodes is restricted to 32 cores.

The user must first configure MATLAB for cluster usage by starting MATLAB interactively. This is done by logging into ShARC, launching a qrshx session, loading a version of MATLAB (e.g. using module load apps/matlab/2019a) and launching MATLAB with matlab. You then need to type the following at the prompt within the MATLAB GUI:

configCluster;

The MATLAB GUI can then be closed.

An example batch script submit_Matlab_mpi.sh is:

#!/bin/bash
#$ -M someuser@sheffield.ac.uk
#$ -m bea
#$ -j y

module load apps/matlab/2019a/binary

# Run parallel_example.m
matlab -nodisplay -nosplash -r submit_matlab_fnc

where submit_matlab_fnc.m is:

function submit_matlab_fnc

cd path_working_directory;
c = parcluster;
c.AdditionalProperties.EmailAddress = 'someuser@sheffield.ac.uk';
% Configure runtime e.g. 40 minutes
c.AdditionalProperties.WallTime = '00:40:00';
% Configure rmem per process e.g. 4 Gb
c.AdditionalProperties.AdditionalSubmitArgs = ' -l rmem=4G';
% Parallel_example.m contains the parfor loop, no_of_cores < 31
j = c.batch(@parallel_example, 1, {}, 'Pool', no_of_cores);

and parallel_example.m is:

function time = parallel_example
cd path_working_directory;
outfile = ['output.txt'];
fileID = fopen(outfile, 'w');
%disp('Parallel time')
tic
n = 200;
A = 500;
a = zeros(n);
parfor i = 1:n
    a(i) = max(abs(eig(rand(A))));
end
time = toc;
fprintf(fileID, '%d', time);
fclose(fileID);

Note that for multi-node parallel MATLAB the maximum number of workers allowed is 31 since the master process requires a parallel licence. Task arrays are supported by all versions, however it is recommended that 2017a (or later) is used.

MATLAB Engine for Python

This is a MathWorks-developed way of running MATLAB from Python. On ShARC the recommended way of installing this is into a conda environment. Here’s how you can install the R2017b version into a new conda environment called my-environment-name:

module load apps/python/conda
conda create -n my-environment-name python=2.7
source activate my-environment-name

pushd /usr/local/packages/apps/matlab/2017b/binary/extern/engines/python
python setup.py build -b $TMPDIR install
popd

More information on the MATLAB Engine for Python, including basic usage.

Training

Installation notes

These notes are primarily for system administrators.

Installation and configuration is a five-stage process:

  • Set up the floating license server (the license server for earlier MATLAB versions can be used), ensuring that it can serve licenses for any new versions of MATLAB that you want to install

  • Run a graphical installer to download MATLAB archive files used by the main (automated) installation process

  • Run the same installer in ‘silent’ command-line mode to perform the installation using those archive files and a text config file.

  • Install a relevant modulefile

  • Configure MATLAB parallel (multi-node)

In more detail:

  1. If necessary, update the floating license keys on licserv4.shef.ac.uk to ensure that the licenses are served for the versions to install.

  2. Log on to Mathworks site to download the MATLAB installer package for 64-bit Linux ( for R2019a this was called matlab_R2019a_glnxa64.zip )

  3. unzip the installer package in a directory with ~10GB of space (needed as many MATLAB archive files will subsequently be downloaded here). Using a directory on an NFS mount (e.g. /data/${USER}/MathWorks/R2019a) allows the same downloaded archives to be used to install MATLAB on multiple clusters.

  4. ./install to start the graphical installer (needed to download the MATLAB archive files).

  5. Select install choice of Log in to Mathworks Account and log in with a License Administrator account (not a Licensed End User (personal) account).

  6. Select Download only.

  7. Select the offered default Download path and select the directory you ran ./install from. Wait a while for all requested archive files to be downloaded.

  8. Next, ensure installer_input.txt looks like the following

    fileInstallationKey=XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX
    agreeToLicense=yes
    outputFile=matlab_2019a_install.log
    mode=silent
    licensePath=/usr/local/packages/matlab/network.lic
    lmgrFiles=false
    lmgrService=false
    
  9. Create the installation directory e.g.:

    mkdir -m 2755 -p /usr/local/packages/apps/matlab/R2019a/binary
    chown ${USER}:app-admins /usr/local/packages/apps/matlab/R2019a/binary
    
  10. Run the installer using our customized installer_input.txt like so: ./install -mode silent -inputFile ${PWD}/installer_input.txt ; installation should finish with exit status 0 if all has worked.

  11. Ensure the contents of the install directory and the modulefile are writable by those in app-admins group e.g.:

    chmod -R g+w ${USER}:app-admins /usr/local/packages/apps/matlab/R2019a /usr/local/modulefiles/apps/matlab/2019a
    
  12. The modulefile is /usr/local/modulefiles/apps/matlab/2019a/binary.

  13. Copy integration scripts to MATLAB local directory (required for MATLAB parallel (multi-node)):

    cd /usr/local/packages/apps/matlab/2019a/binary/toolbox/local
    cp -r /usr/local/packages/apps/matlab/parallel_mpi_integration_scripts_2019a/* .
    NOTE: for all other Matlab versions
    cp -r /usr/local/packages/apps/matlab/parallel_mpi_integration_scripts/* .
    
  14. R2018a Update 4 to mitigate Matlab crashes on Centos 7.5. Download R2018a Update 4 installer. Copy to ShARC, and run using ./R2018a_Update_4_glnxa64.sh, and specify install directory /usr/local/packages/matlab/2018a/binary