Page tree
Skip to end of metadata
Go to start of metadata

MATLAB is a general purpose analysis and graphics plotter from MathWorks. With more than 600 mathematical, statistical, and engineering functions, MATLAB provides immediate access to high-performance numerical computing. This functionality is extended with interactive graphical capabilities for creating plots, images, surfaces, and volumetric representations.

A toolbox algorithms enhance MATLAB's functionality in domains such as signal and image processing, data analysis and statistics, mathematical modeling, and control design. Toolboxes are collections of algorithms, written by experts in their fields, that provide application-specific numerical, analysis, and graphical capabilities.

Usage

Typically, running a Matlab job on Raijin that benefits from the speedup of multi-cores would require, 

  1. joining the matlab software group for your institution, matlab_<institution>, to get access to the Matlab license
  2. setting up both your .m file and the job submission script to allow the computation- and data-intensive problems using multi-cores, GPUs and multi-nodes. 
  3. Make use of the smpd deamon available in Matlab for parallelisation.

    When using smpd, please specify -smpdfile to $PBS_JOBFS/<file> to avoid creating smpd files in /tmp.

Regarding the license access, please check the section License below for more details.   

If you know your Matlab application is neither computation nor data intensive, please see the advice in the section 'Running Single-core Jobs'.


Once get the access to the matlab license on Raijin, please confirm with your institution that if the license comes with either of the features 'Parallel Computing Toolbox' and 'Distributed Computing Server'. Although some linear algebra and numerical functions, such as matrix products, ffteigsort, are implicitly multi-threaded and make use of all the cores available to the job without any extra programming efforts, see an incomplete list provided by Mathworks Support Team here, the majority of the functions provided by matlab runs only on a single core and users need to explicitly use the functionalities provided by these two features to enable the utilisation of multi-cores and multi-compute nodes, respectively. As of 29 May 2017, the majority of NCI-hosted matlab licenses provides only the feature Parallel Computing Toolbox, therefore, supports jobs running only within a single compute node. 

In order to utilise multi-cores within a single compute node, typically, the minimum programming effort would be the revision of the for loops into parfor loops in the .m file. For example, to parallelise the matlab application with the majority computation in a for loop read as

A = 512;
N = 1024;
y = NaN(1,N);
for i = 1:N
  y(i) = max(abs(eig(rand(A))))
end

simply do 

numberOfWorkers=8;
A = 512;
N = 1024;
y = NaN(1,N);
parfor (i=1:N,numberOfWorkers)
  y(i) = max(abs(eig(rand(A))))
end

For further explorations of the functionality provided by the Parallel Computing Toolbox, please refer to Mathworks website [https://au.mathworks.com/help/distcomp/index.html].  If you want to run Matlab jobs across more than one compute nodes and confirm that you get access to the feature Distributed Computing Server, please contact help@nci.org.au for further instructions.


Once the .m file is ready, you will need to load the MATLAB module in your shell environment in the following way:

module load matlab

to get the default version. To load the specific version of R2019b do

module load matlab/R2019b


An example job submission script (matlabjob.sh) is provided below. It requests 16 processors, 32GB of memory, 300GB of local disk space, and 10 hours of walltime for the job and passes the number of CPUs as the number of matlabWorkers and the JOBFS folder as the output directory outputDir, both of which are used in the matlab script mfile.m. This submission script should be saved in the working directory from which the analysis will be done. Note that the submission script uses the PBS software resource flag #PBS -l software=matlab_<institution>, where the placeholder <institution> needs to be replaced by your own institution, see details in the section License requirements below. To change the number of processors, memory, or jobfs required, simply modify the appropriate PBS resource requests at the top of this file.

#!/bin/bash
#PBS -q normal
#PBS -l walltime=10:00:00
#PBS -l ncpus=48
#PBS -l mem=190GB
#PBS -l jobfs=400GB
#PBS -l storage=scratch/ab01+gdata/ab01
#PBS -l software=matlab_<institution>
#PBS -l wd

module load matlab/R2019b
module load matlab_licence/<institution>
matlab -nodisplay -nosplash -r "outputDir='$PBS_JOBFS',numberOfWorkers=$PBS_NCPUS, mfile, exit" > $PBS_JOBID.log

Please note, the flag -nodisplay passed to matlab enables running without the GUI, while the flag -nosplash disables the display of the Matlab logo.


Once the job submission script is ready, please do 

qsub matlabjob.sh 

to submit your job to the PBS scheduler.


Running Single-core Jobs

Since Matlab is automatically multithreaded and, by default, it generates as many matlabWorkers as it is allowed to, it is always safe to explicitly set the maximum number of computational threads to one by adding the following line 

maxNumCompThreads(1)

at the beginning of the .m file or starting matlab with the option -singleCompThread as shown in the following example submission script.

#!/bin/bash
#PBS -q normal
#PBS -l ncpus=1
#PBS -l walltime=00:02:00
#PBS -l mem=250MB
#PBS -l storage=scratch/ab01+gdata/ab01
#PBS -l software=matlab_<institution>
#PBS -l wd

module load matlab/R2016a
matlab -nosplash -nojvm -singleCompThread < mfile.m > $PBS_JOBID.log

License requirements

NCI has a Hosting Provider Agreement with MathWorks that allows for us to install MATLAB on our systems and have users provide their own licence to access it. In particular, if your institution has a licence for MATLAB that you can use on the computer in your office then it will most likely be possible to use it on NCI systems.

There are two methods for providing your licence details to MATLAB on the NCI, and which to use depends on how your plan on running your jobs.

  1. If you want to use MATLAB in a non-interactive fashion, you will need to checkout a licence directly from your institution’s licence servers or checkout a license belongs to your institution but hosted by NCI's license server. As of 19 July 2017, there are 11 institutions have setup their configurations with NCI. Please see which software group you need to join in the table below before running Matlab on Raijin. If it’s not already set up, we will ask you to contact your licence administrator to ask them to provide us with the details of their licence server (but note that not all institutions allow this).


    Institutionsoftware group
    The Australian National Universitymatlab_anu
    University of Canberramatlab_canberra
    The University of Newcastlematlab_newcastle
    Deakin Universitymatlab_deakin
    Latrobe Universitymatlab_latrobe
    Macquarie Universitymatlab_mq
    The University of Melbournematlab_melbourne
    Monash Universitymatlab_monash
    Royal Melbourne Institute of Technologymatlab_rmit
    The University of New South Walesmatlab_unsw
    The University of Wollongongmatlab_wollongong
    Western Sydney Universitymatlab_wsu



  2. If you only plan on using MATLAB interactively with the GUI (e.g. in an interactive batch job submitted with qsub -I -X or in the virtual desktop environment) then you can use the MathWorks-hosted, online checkout mechanism. This is the MathWorks-preferred solution, however your licence will need to be configured as a Login Named User (LNU) licence. Using this method, MATLAB will prompt you for your MathWorks account credentials on startup (this prompt is an X-windows dialog box, which is why it can only be used interactively). If you are using your institution’s licence, contact your licence administrator first to ensure that LNU is enabled on the licence. If you are using your own licence, you can enable LNU by logging into your MathWorks account via your browser. To allow Raijin's compute nodes to contact MathWorks' servers, you need to run config_matlab.sh the first time you use each version of MATLAB.

    If MATLAB asks you to activate the installation after entering your MathWorks credentials, it means that either your MathWorks account hasn’t been properly associated with your licence or the licence isn’t LNU-enabled. Do not activate your licence on Raijin as this will lock that licence to that particular node (and so probably won’t work next time your login since you’ll almost certainly be on a different node).


Additional Notes


Interactive access to Matlab 

If you are using ssh to connect then you may consider unencrypting the X windows packets. See our ssh web page for more details on setting the DISPLAY environment variable to speed up the interactive graphics response.

MATLAB starts up faster if you use the -nodesktop option and also after closing unnecessary windows on the desktop e.g. the help window, exiting and restarting. 

There are also occasional problems with using OpenGL for rendering. If you get error or warning messages relating to libGL.so and slow rendering of complicated figures you might like to try changing the method of rendering as follows. Do 
set (gcf,'Renderer','Zbuffer') before drawing any figures to change to Zbuffering.

Windows users using VNC to access the APAC machines have found that settting 16 bit graphics rather than 24 bit graphics improves performance. 

Further hints for solutions to performance problems can be gained by searching for references from http://www.mathworks.com/support

MATLAB Compiler 

Due to how the various institutional licences are configured on Raijin, the MATLAB compiler (mcc) is currently unable to locate them – and thus cannot be used on Raijin. If you wish to pre-compile your MATLAB using mcc, we recommend you do so on your own machine and copy the resulting binary to Raijin. You will need to build it on a CentOS 6 machine to maximise compatibility. If you don't have access to CentOS 6 machine other than Raijin, consider launching a VM in Nectar and installed mcc there yourself.