Fork me on GitHub

MATLAB

Scientific computing and visualisation.

Interactive Usage

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

The latest version of MATLAB (currently 2017b) is made available with the command:

module load apps/matlab

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

module load apps/matlab/2013a
module load apps/matlab/2013b
module load apps/matlab/2014a
module load apps/matlab/2015a
module load apps/matlab/2016a
module load apps/matlab/2016b
module load apps/matlab/2017b

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/2017b  # Make specific version of MATLAB available
matlab -nodesktop -r helloworld

Ensuring that helloworld.m and my_job.sge are both in your current working directory, 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 do 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 2017b module
module load apps/matlab/2017b

# 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 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:

$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 on iceberg

Currently we recommend the 2015a version of MATLAB for parallel work, and task arrays requiring more than a few hours runtime.

The default cluster configuration named local provides parallel working environment by using the CPUs of the worker node that is running the current MATLAB session. Each iceberg worker node can run multiple users’ jobs simultaneously. Therefore depending on who else is using that node at the time, parallel MATLAB jobs can create contentions between jobs and slow them considerably. It is therefore advisable to start parallel MATLAB jobs that will use the local profile from a parallel SGE job. For example, to use the local profile with 5 workers, do the following;

Start a parallel OpenMP job with 6 workers:

qsh -pe smp 6

Run MATLAB in that session and select 5 workers:

matlab
parpool ('local' , 5 )

The above example will use 5 MATLAB workers on a single iceberg node to run a parallel task. Note that being granted a multi-core interactive session by the scheduler is dependent on Iceberg’s loading at the time of request. It is not guaranteed. However the user can reduce the number of cores requested, which will improve their chances of being granted a multi-core session.

To take advantage of the multiple iceberg nodes, you will need to make use of a parallel cluster profile named sge. This can be done by issuing a locally provided MATLAB command named iceberg that imports the parallel cluster profile named sge that can take advantage of the SGE scheduler to run larger parallel jobs.

When using the sge profile, MATLAB will be able to submit multiple MATLAB jobs the the SGE scheduler from within MATLAB itself. However, each job will have the default resource requirements unless the following trick is deployed. For example, during your MATLAB session type:

global sge_params
sge_params='-l rmem=8G -l h_rt=36:00:00'

to make sure that all the MATLAB batch jobs will use up to 8 GBytes of memory and will not be killed unless they exceed 36 hours of run time.

Training

Installation notes

These notes are primarily for system administrators.

Installation and configuration is a four-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

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 R2017b this was called matlab_R2017b_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/R2017b) 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_2017b_install.log
    mode=silent
    licensePath=/usr/local/packages6/matlab/network.lic
    lmgrFiles=false
    lmgrService=false
    
  9. Create the installation directory e.g.:

    mkdir -m 2755 -p /usr/local/packages6/matlab/R2017b
    chown ${USER}:app-admins /usr/local/packages6/matlab/R2017b
    
  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. Install a modulefile with a name and path like /usr/local/modulefiles/apps/matlab/2017b and contents like

    #%Module1.0#####################################################################
    
    ## Module file logging
    source /usr/local/etc/module_logging.tcl
    
    proc ModulesHelp { } {
        global version
        puts stderr "   Makes MATLAB 2017b available for use"
    }
    module-whatis   "Makes MATLAB 2017b available"
    
    # Do not use other versions at the same time.
    conflict apps/matlab
    
    set     version        2017b
    set     matlabroot     /usr/local/packages6/matlab/R$version
    prepend-path PATH $matlabroot/bin
    
  12. 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/packages6/matlab/R2017b /usr/local/modulefiles/apps/matlab/2017b
    

TODO: Documentation for MATLAB parallel configuration.