MATLAB is a software for mathematical calculations and their visualization. The name MATLAB derives from matrix laboratory and shows the origin of the software, matrix operations. MATLAB was developed by the company MathWorks.

On the cluster, MATLAB version R2020b is installed. In order to use MATLAB, you have to load the MATLAB module (module load matlab).

On this page you can find information on how to start MATLAB, both the graphical user interface and the batch (command line) mode. There are also instructions on queuing MATLAB jobs and using the parallel computing features of MATLAB, both for single-node and multi-node jobs. Finally, we offer a helper script to download, which can help you automate many tasks for you.

Caution: you will have to pay separately for using MATLAB on the cluster and on your PC! In the past the HPC Team allowed you to use MATLAB for no additional cost on the cluster, this is no longer true. Employees (including student SHKs) need to pay for using MATLAB on the cluster!

Literature

Documentation for all features with a lot of examples can be found in the MATLAB documentation center.

Licensing

The Uni Siegen has a campus license for MATLAB, and ZIMT has a license for the MATLAB Parallel Server (formerly called the MATLAB Distributed Computing Server) All members of Uni Siegen can obtain and use MATLAB in various ways:

  • For students, there is a free student license. Details on obtaining can be found here.

  • For employees there is a campus license that is not free to use, which is described here . The costs are per workgroup and depend on the number of people who use MATLAB in that group.

  • On the login nodes of the cluster there is a MATLAB installation. This installation is governed by the same rules as any other MATLAB instance at the university, meaning it only free for students for the purpose of their own education. This includes BSc. and MSc. theses, but not student assistant (SHK) jobs. In all other cases you have to pay. There is no additional license configuration necessary on your part, but MATLAB use will be determined by Fak 4 once per year and the cost will be collected.

    The same installation is also available on the HTC nodes.

  • The MATLAB Parallel Server is available on all cluster nodes. It allows you to create worker pools over multiple nodes. ZIMT has a license for 16 workers, meaning a maximum of 16 worker processes can be launched. These workers are multithreaded and can be distributed over multiple nodes if the corresponding SLURM options (see below) are set. The Parallel Server is also available on the HTC nodes.

    Note: the actual workers are not additional MATLAB instances as far as the campus licenses are concerned. However the limit of 16 workers is for the whole cluster (not per job or per user). If you get an error message about missing worker licenses, another user was using the license at the same time.

None of the MATLAB licenses is tied to any specific version of MATLAB.

Starting MATLAB

The MATLAB graphical user interface (GUI) is started by first loading the module with module load matlab and then by simply entering the command

matlab

in the console. MATLAB will usually open a window, provided your SSH connection is running with X11 support. MATLAB can also be run in batch mode, which means that a chain of commands (for example a script) will be executed one after the other. For batch mode, -nodisplay needs to be added.

Caution: if you launch MATLAB as described here, you are still on the login node! You may only use this method for development and testing, never for computations! We reserve the right to kill MATLAB processes without prior warning if they use a large portion of a compute node’s CPU power for extended time periods!

However this is only the simplest way of launching MATLAB. MATLAB can be launched in different ways both on the login and compute nodes.

Tips:

  • Sometimes, MATLAB will launch in command line mode without you using the -nodisplay option. In those cases, it usually suffices to disconnect and then reconnect the SSH connection to the cluster.
  • ZIMT has set up MATLAB such that the folder ~/.matlab is in its search path. This means that if you place a file named ~/.matlab/startup.m in that folder, you can specify custom settings that will then be run whenever MATLAB is started.

Batch jobs with MATLAB

MATLAB may be launched in batch mode, meaning that it will run a chain of commands one after the other (this chain typically comes in the form of an M-script).

Individual MATLAB scripts (M-scripts) can be run by specifying the option -r and the script name without the suffix .m. For example, to execute a script named calculate.m, type:

matlab -nodisplay -r calculate

The script file needs to be available in the current folder. The option -nodisplay ensures that MATLAB will not open a window.

Creating a job script for MATLAB

The following example shows how to run MATLAB programs via the scheduler SLURM. In order to run the example yourself you need to create a subfolder MATLAB in your home directory and put the example MATLAB script and job script in that folder.

First, you need the M-script that you want to execute. You can use the MATLAB script sin_plot.m, which you can download here, as an example. It calculates a sine curve, creates a graph with the result and saves the graph as a PNG image file:

A=sin([1:1024]*2*pi/1024)
h=figure; plot(A)
print(h, '-dpng', '~/MATLAB/sin.png')
exit

To run this M-script, you need to create a job script, which will call MATLAB in batch mode with the M-script as an argument:

#!/bin/bash
#SBATCH --time=00:10:00
#SBATCH --partition=short
#SBATCH --ntasks-per-node=1

matlab -nodisplay -r sin_plot

This script file, called sin_batch.m, is downloadable here. More information on job scripts can be found here.

To run the job, change into the correct directory ( ~/ MATLAB in this example). The job is queued like any other SLURM job with the command:

sbatch sin_batch.sh

When the job has completed successfully, the files ~/MATLAB/my.output and ~/MATLAB/sin.png exist.

Parallel Computations with the Parallel Toolbox

The Parallel Toolbox allows running a MATLAB computation on multiple processes, so-called workers, concurrently. All workers need to be run on a single node. On the OMNI cluster, dividing a computation between multiple nodes is also possible but requires additional configuration, see below.

Using the MATLAB Parallel Server

The MATLAB Parallel Server, formerly MATLAB Distributed Computing Server (MDCS) enables MATLAB computations on multiple nodes. The server is available on the OMNI cluster.

ZIMT has configured the Parallel Server such that it uses SLURM for scheduling. That way, a job can be queued from within MATLAB and will run like any other job on the cluster. However, you first need to import the cluster profile for OMNI into MATLAB.

Note: when you run computations with the Parallel Server, you always need the parameter --licenses=matlab:X, where X is the number of workers, in your job settings. If you use the ZIMT profile like in the following section, this is preconfigured for you. If you queue your job any other way, you need to make sure that your SLURM settings contain this parameter.

Importing the cluster profile

The Parallel Server uses so-called cluster profiles in which the necessary information about the cluster is preconfigured. For that purpose, ZIMT provides the profile omni_m2020.mlsettings which you can download here and then need to import into MATLAB as follows:

  1. In the MATLAB GUI, click on Parallel in the menu Home and select the item Manage Cluster Profiles

  2. The Cluster Profile Manager will open. To import the downloaded settings file, click on Add -> Import

Alternatively, you can also import a cluster profile using only the MATLAB command line. The command to import is done by:

profile_master = parallel.importProfile('omni_m2020.mlsettings');

And you can set the profile as default with:

parallel.defaultClusterProfile(profile_master);

Creating MATLAB scripts for parallel computations

When creating scripts that use the Parallel Server, two things need to be considered:

  1. At the beginning of the MATLAB script to be run, a so-called parallel pool, meaning a group of workers, needs to be started with the correct cluster profile. This can be done in two ways. Either the pool is created explicitly as described here or it is created by MATLAB automatically (using the default settings) when a parallel operation is called, see below. The command parpool starts a pool and provides the parallel functionality for the parallel commands, the most common ones of which are parfor and spmd. Use the imported profile (its name inside MATLAB is omni) to use the scheduler SLURM. You can also use parpool to process jobs and MATLAB commands via workers interactively.

    Here are two examples for creating a parallel pool:

    % Example 1
    poolobj = parpool('omni', 2, 'AttachedFiles',{'mod1.m', 'mod2.m'}) 
    Starting parallel pool (parpool) using the 'omni' profile ...
    
    % Example 2 
    poolobj = parpool('omni', 3) 
    Starting parallel pool (parpool) using the 'omni' profile ...

    End parallel processing (deleting the pool):

    delete(poolobj)
  2. In the actual MATLAB computation, parallel operations need to actually be called. This means at least one instance of at least one of the already mentioned parallel commands, e.g. parfor or spmd.

In order to run such a MATLAB script you need to execute it inside MATLAB like any other script. Either you start it with Editor -> Run from the MATLAB GUI or you run MATLAB in batch mode with your script.

Note: you do not need to create a separate job script because the MATLAB Parallel Server will queue the job for you.

Jobs queued in such a way are treated identically to all others. That means that you can monitor them using squeue, that you may need to wait until the job starts, and that you can stop it with scancel.

Helper script for cluster computations

ZIMT has developed a MATLAB script for you which can simplify some parts of your work with the cluster. It allows you to queue jobs on the cluster (on one node, i.e. with maximum 64 workers) from your desktop PC.

The script can do the following things for you:

  • Copy your data to the cluster
  • Generate a SLURM script for you
  • Queue your job
  • And copy your data back from the cluster to your PC after the computation. You receive an email when your job is done.

You can download the script ( omni.m ) here. You only need to copy it to the directory which contains your MATLAB scripts and other input data, and then configure some parameters inside the script (like your username).

You can find more detailed instructions at the beginning of the script, or by entering help('omni') inside the MATLAB console (assuming the script omni.m is on your MATLAB path).

Aktualisiert um 15:09 am 8. February 2021 von Jan Steiner