Matlab

module avail matlab/

Matlab is an integrated system covering tools for symbolic and numeric computations, analyses and data visualizations, modeling and simulations of real processes.

Usage

OnDemand

The most straightforward and simplest way to run Matlab is through the OnDemand service, which allows users to access Matlab directly from their web browser. This option provides an intuitive and user-friendly interface, making it an excellent choice for most users.

Choose Matlab button among the apllications.

As a Jupyter Notebook in Kubernetes

Matlab can also be run from the JupyterHub. For detailed instructions on how to use Matlab with Jupyter Notebook, please refer Jupyter documentation.

Remote desktop

Using Remote desktop, Matlab can be also run from a module.

This option is recommended to advanced users or as a fallback option in case OnDemand and/or Kubernetes service are down.

Licences

Any of the purchased licenses permit **just an academic use** of the program!

Matlab 9.14 and newer

For versions 9.14 and newer, MetaCentrum offers a license valid for 200 instances of MATLAB and a wide set of its toolboxes.

A default version of Matlab (`module add matlab`) runs also on this 200-pieces license.

PBS tracks these licenses as a "matlab" resource, therefore unless you use older Matlab version, always submit the job as

qsub ... -l matlab=1 ...   # ask for 1 Matlab license

In principle a license reservation is needed both for Matlab core and each one of the toolboxes you will need to use. **However, since the number of respective toolbox licenses is large, it is improbable that they will "run out"**. For most cases, you will be safe with the following simplified version which reserves only the core Matlab license `qsub ... -l matlab=1 ...` .

This new license comes with stricter conditions than the previous one: it can be used only from MetaCentum IP adresses, i.e. you cannot use it for Matlab running on your desktop/university lecture rooms.

Troubleshooting tools

List all licenses for Matlab and its available toolboxes:

$ cat /software/matlab-latest/etc/license.dat | grep INCREMENT   

$ module add matlab/9.14
$ matlab
>> ver                                 # alternative way from inside Matlab

List currently issued and available licences of Matlab core:

$ /software/matlab-latest/etc/lmstat -a | grep "Users of MATLAB:"

List currently issued (reserved) licenses of Matlab core as well as toolboxes:

$ /software/matlab-latest/etc/lmstat -a | grep "in use"

Get type of license used in current instance of Matlab:

$ module add matlab/9.14 
$ matlab
$ >> license                # should return '41204682'

Matlab 9.13 and older

For versions 9.13 and older, MetaCentrum offers a variable amount of licenses for Matlab core and its respective toolboxes.

To find number of licenses:

/software/matlab-X.XX/etc/lmstat -a | grep "Users of"   # X.XX = version

Unless they have a specific reason, **we urge users to use version 9.14 and newer**.

PBS dorces not anymore track the licenses for older Matlab versions, therefore **when you submit the job, do not use the `-l matlab=XX` option**.

Troubleshooting tools

List all licenses for Matlab and its available toolboxes:

$ cat /software/matlab-latest/etc/license.dat | grep INCREMENT   

$ module add matlab/9.13
$ matlab
>> ver                                 # alternative way from inside Matlab

List currently issued and available licences of Matlab core:

$ /software/matlab-latest/etc/lmstat -a | grep "Users of MATLAB:"

List currently issued (reserved) licenses of Matlab core as well as toolboxes:

$ /software/matlab-latest/etc/lmstat -a | grep "in use"

Get type of license used in current instance of Matlab:

$ module add matlab/9.13 
$ matlab
$ >> license                # should return '84911'

ZCU users

Users of ZČU (West Bohemian University, Plzeň) have their own license for 10k MATLAB instances. Therefore they should not apply for MetaCentrum PBS resource.

 In [Perun](https://perun.e-infra.cz/), search for group `users-zcu` and see if you are a member.   

Bring your own license

If your home institution has its own Matlab license, we can incorporate it so that you can use them while running Matlab on MetaCentrum machines.

To consult this possibility, contact us at meta@cesnet.cz.

Troubleshooting tools

Get type of license used in current instance of Matlab:

$ module add matlab/9.14 
$ matlab
$ >> license                # should return '41198919'

Built-in documentation

From the MATLAB command window one can use the command help to get help with a a particular command, e.g.

>> help rand

in the desktop environment one can use also the command doc

>> doc rand

Online documentation is available at MATLAB Product Documentation.

Tips and notes

Matlab as interactive job

Interactive regime brings no significant speed-up comparing to running MATLAB locally on your machine unless parallelism is used. Interactive regime is recommended for development of your code and its testing.

1. OnDemand interface

This is the most easy and straighforward way to run Matlab in graphical mode. Follow the OnDemand tutorial.

2. Interactive job with remote desktop

If you prefer to stay with command line or if, for some reason, you cannot use web browser, it is possible to run Matlab as interactive job and get the graphical output to your screen by configuring remote desktop (recommended) or X-Window. Follow the tutorials to learn how to setup the graphical connection.

After the graphical connection is set up, Matlab can be run from the provided menu or by typing the following code into a terminal window:

$ module add matlab
$ matlab

3. Interactive job without GUI

It is possible to run MATLAB in the text regime only, when the graphical mode is not necessary (you may even create figures, work with them, save them to a disk, though they are not visible). The relevant keywords for this case are:

$ matlab -nosplash -nodisplay -nodesktop

Matlab as batch job

If you do not need the graphical environment, it is is possible to run MATLAB in batch regime. Create batch script myjob.sh with the following contents:

#!/bin/bash

# set PATH to find MATLAB
module add matlab

# go to my working directory
cd $HOME/matlab/

# run MATLAB
matlab -nosplash -nodesktop -nodisplay -r "myFunction()"

# or in a different way:
#matlab -nosplash -nodesktop -nodisplay < myFunction.m > output.txt

Put all your MATLAB files (your *.mat and *.m files) to the directory $HOME/matlab/ and submit this shell script like

qsub -l select=1:ncpus=10:mem=1gb -l matlab=1 myjob.sh

Batch jobs are useful especially if you want to run more jobs in parallel or if you do not want to block your local machine with running jobs.

If you are planning to run more then a few Matlab jobs simultaneously, please see Running multiple MATLAB jobs.

Turn off Java Virtual Machine (JVM)

MATLAB uses its own java virtual machine for the desktop environment. Many jobs can be sped-up by turning the JVM off (option matlab -nojvm). Keep in mind, however, that some internal functions and toolboxes (e.g. Distributed Computing Toolbox) need Java.

Matlab with Maple symbolic environment

Since the Maple’s symbolic environment is not fully compatible with the Matlab’s symbolic environment, the Matlab symbolic environment is used by default when starting the Matlab within MetaCentrum environment.

In case the Maple symbolic environment is needed, it must be required explicitly:

$ module add matlab
$ matlab-sym-maple       # the options of this command are the same as for the original 'matlab' command
                         # an alternative -- the 'matlab-sym-matlab' command -- explicitly requires the Matlab symbolic environment

CPU usage

Depending on the structure of script and functions being called, Matlab may use more CPUs than granted by the scheduler. This may result in your job being killed by the scheduler.

Incorrect CPU usage can be prevented by resorting to one of the extremes:

1. Force Matlab to work on one CPU only by using --singleCompThread option

qsub ... ncpus=1 ...
matlab ... -nojvm --singleCompThread ...

Obvious disadvantage is no speedup due to parallelization. On poorly (or partly) parallelized codes, or if the 1-CPU-speed-only is not an issue, --singleCompThread is often a good choice.

2. Reserve whole computational node by exclhost option

qsub -l select=1:ncpus=1 -l place=exclhost

This requirement is done on the PBS level and essentially asks the PBS to grant whole computational node to your job only. Being so, even if Matlab code uses all’ available CPUs, your job won’t be killed.

On the other hand, exclhost is a large requirement. If the grid is busy, jobs with exclhost may wait for a long time (even several days!) to run.

exclhost may be effective in case you have a number of Matlab jobs which use parallelization only in some critical part. You can group them into one PBS job and run them all at once in background, e.g.

qsub ... place=exclhost ...
(cd Dataset1; matlab ... ) &
(cd Dataset2; matlab ... ) &
...
(cd DatasetN; matlab ... )

3. Find the optimal number of CPUs using cgroups

If you need some level of parallelizations, but don’t want to use exclhost, you can limit number of available CPUs by using cgroups, which is Linux kernel tool. Only some machines are able to use cgroups.

qsub -l select=1:ncpus=N:cgroups=cpuset ... # N is the the optimal number of CPUs

Finding the optimal number (N) of CPUs can be tricky and sometimes reduced to trial-and-error approach, especially if your code calls external libraries. You can use top command to watch the CPU load.

Distributed and parallel jobs

MATLAB now supports distributed and parallel jobs on multiprocessor machines using the Parallel Computing Toolbox (the name of the licence is Distrib_Computing_Toolbox) and on clusters using the MATLAB Distributed Computing Server (name of the licence is MATLAB_Distrib_Comp_Engine).

Parallel Matlab computations in MetaCentrum

To prepare an environment for parallel computations, it is necessary to initialize a parallel pool of so-called workers using the function parpool (called matlabpool in previous versions). This standard initialization requires to specify an amount of workers to initialize; moreover, thanks to shared filesystems, it may also result in a collision when trying to initialize several pools simultaneously.

To make the initialization of parallel pool easier as well as to cope with the collision problems, we have prepared a function MetaParPool:

MetaParPool('open');        % initializes parallel pool (returns the number of initialized workers)
...
x = MetaParPool('size');    % allows to discover the size of parallel pool (returns the number of workers)
                            % may be called as MetaParPool('info'); as well
...
% a computation using parfor, spmd and other Matlab functions
...
MetaParPool('close');       % closing the parallel pool

Notes

• the function automatically detects the number of cores assigned to a job - the size of parallel pool is always automatically set based on resources assigned to a job
• it is necessary to ask for N computing cores on a single node (qsub -l select=1:ncpus=N ...)
• to make parallel computations using this function, there are 1 Matlab license and 1 Distributed Computing Toolbox license and N-1 MATLAB Distributed Computing Engine licenses necessary (N denotes the number of requested cores)
• a reservation can be thus performed via -l matlab=1,matlab_Distrib_Computing_Toolbox=1
• an example of parallel computation using the MetaParPool function can be found in the /software/matlab-meta_ext/examples directory (file example-parallel.m shows the Matlab input file itself while the file run_parallel.sh shows an example startup script).

Running multiple MATLAB jobs simultaneously

If there is a need to run multiple instances of Matlab simultaneously, users are strongly encouraged to run them on as few nodes as possible. Matlab takes one licence per user per node, regardless of number of Matlab instances running there. For example, you can run 64 instances of Matlab on one node while using only 1 licence.

An easy way to group Matlab instances offers parallel command.

The parallel command is particularly useful for distributing Matlab tasks across available CPUs effectively.

First, make sure you have loaded the Matlab and Parallel Computing Toolbox modules as shown in the myjob.sh script:

#!/bin/bash 

# set PATH to find Matlab and Parallel
module add matlab
module add -s parallel 

# go to my working directory
cd $HOME/matlab/ 

# run multiple MATLAB instances in parallel
cat <<EOF | parallel -j${PBS_NCPUS}
matlab -nosplash -nodesktop -nodisplay -r "myFunction()" > output-0.txt
matlab -nosplash -nodesktop -nodisplay -r "myFunction()" > output-1.txt
matlab -nosplash -nodesktop -nodisplay -r "myFunction()" > output-2.txt
EOF

# # (You can use also a more succint one-line variant:)
# parallel -j${PBS_NCPUS} matlab -nosplash -nodesktop -nodisplay -r "myFunction()" > output-{%}.txt ::: 0 1 2 

Submit your job with a command like:

qsub -l select=1:ncpus=10:mem=5gb place=pack -l matlab=1 myjob.sh

By adding place=pack, you are instructing the job scheduler to try to allocate all the requested resources on a single server if possible. This will run multiple MATLAB instances concurrently, each executing myFunction() and saving their output to separate files.