Alternative ways to access MATLAB on the cluster¶

NOTE: Our recommendation is to run MATLAB from the GUI, through ThinLinc (or OnDemand). See the main MATLAB page for this.

Using MATLAB Desktop/graphical interface BUT with X11 forwarding enabled instead of the ThinLinc client¶

These commands are all done in a terminal, like MobaXterm, PuTTY, etc. See the connection guides.

ssh -Y <username>@kebnekaise.hpc2n.umu.se

The method has security implications for your client and should only be used by those familiar and well-versed with the issues and risks.

You need to load and start MATLAB interface manually:

Check for available versions

module spider matlab

Select desired version (remember that you need to configure MATLAB if you have not used that version before - see Configuration and setup for MATLAB.

Example, MATLAB 2023a

module load MATLAB/2023a.Update4
matlab -singleCompThread

Load and run MATLAB in a Linux shell¶

This section will show you how to use MATLAB completely from the shell/terminal without having to open the GUI. This could be useful if you only have a regular SSH connection or otherwise need to run something fast and lightweight instead of having to open the GUI. This is an extra advantage when you have a poor network connection.

One-time configuration

Just like when you are using MATLAB in the GUI, you need to configure MATLAB once per version before using it. You do that after loading the MATLAB module in a shell (here version 2023a.Update4):

module load MATLAB/2023a.Update4
configCluster.sh

configCluster.sh

Start MATLAB in the shell¶

When you have done this, you are ready to start MATLAB.

matlab -singleCompThread -nodisplay -nosplash -nodesktop

Warning

On the login-nodes MATLAB MUST be started with the option ‘-singleCompThread’, preventing MATLAB from using more than one thread.

This will NOT stop the parallel toolbox from working.

Working in MATLAB in the shell¶

We can work in MATLAB in the shell in exactly the same way as in the GUI:

$ matlab -singleCompThread -nodisplay -nosplash -nodesktop
Opening log file:  /home/b/bbrydsoe/java.log.43927

                                  < M A T L A B (R) >
                        Copyright 1984-2023 The MathWorks, Inc.
                   R2023a Update 4 (9.14.0.2306882) 64-bit (glnxa64)
                                     June 19, 2023


To get started, type doc.
For product information, visit www.mathworks.com.

>> a = [ 1 2 3 ; 4 5 6; 7 8 9];
>> b = [ 7 5 6 ; 2 0 8; 5 7 1];
>> c = a + b

c =

     8     7     9
     6     5    14
    12    15    10

>> d = a - b

d =

    -6    -3    -3
     2     5    -2
     2     1     8

>> e = c + d;
>> e

e =

     2     4     6
     8    10    12
    14    16    18

>>

Job settings¶

In order to run in batch, you have to do some job settings. Inside MATLAB, do this:

>> c=parcluster('kebnekaise');
>> c.AdditionalProperties.AccountName = 'PROJECT-ID';
>> c.AdditionalProperties.WallTime = 'HHH:MM:SS';
>> c.saveProfile

where you change PROJECT-ID to your own project id and HHH:MM:SS to the desired walltime.

There are also some optional settings, which depends on your needs:

Constraints (type of node, CPU, GPU, etc.):

>> c.AdditionalProperties.Constraint = 'feature';

To see possible features, check the Requesting specific features section.

Specify cores per node:

>> c.AdditionalProperties.ProcsPerNode = <num-cores>;

Use GPUs:

c.AdditionalProperties.Constraint = 'GPU type';
c.AdditionalProperties.GpusPerNode = 'number of GPU cards';

You find the ‘GPU type’ from the Requesting specific features section, where you can also see how many GPU cards are on the various types.

Example

Assume you want to request 1 L40s GPU card these options would do the work:

c.AdditionalProperties.Constraint = 'l40s';
c.AdditionalProperties.GpusPerNode = 1;

If you want to request 2 V100 GPU cards (whole node for that type) these options should work:

c.AdditionalProperties.Constraint = 'v100';
c.AdditionalProperties.GpusPerNode = 2;

Note

In order to list the content of your profile, you can always do c.AdditionalProperties.

To clear a value, assign the property an empty value (‘’, [], or false). Example:
```
c.AdditionalProperties.Constraint = ‘’;
```
Always save the profile after changing a property:
```
c.saveProfile
```

Warning

If you set the GPU values in your Cluster profile all the jobs that you submit through this profile will allocate GPU resources even though they aren’t GPU aware.

Thus, if you initially set the GPU values and for your current workflow you won’t be using them, you can reset these values as follows:

Start a MATLAB session and get a handle to the cluster:

c = parcluster('kebnekaise');

now, reset the values and save the profile:

c.AdditionalProperties.Constraint = '';
c.AdditionalProperties.GpusPerNode = '';
c.saveProfile

Running a job from within MATLAB terminal interface¶

When starting a simple MATLAB program inside MATLAB on the terminal, it will as default use your cluster profile which you just created and saved above. job is just the name I have given the job object - you could call it j or whatever you want instead.

job = batch('myScript');

batch does not block MATLAB and you can continue working while computations take place.

If you want to block MATLAB until the job finishes, use the wait function on the job object.

wait(job);

By default, MATLAB saves the Command Window output from the batch job to the diary of the job. To retrieve it, use the diary function.

diary(job)

After the job finishes, fetch the results by using the load function.

load(job,'x');

or with

job.fetchOutputs{:}

If you need the Job id, run squeue --me on the command line while the job is running.
To get the MATLAB jobid do id=job.ID within MATLAB.
To see if the job is running, inside MATLAB, do job.State

Serial job

Inside MATLAB you can do things like:

Get a handle to the cluster

>> c=parcluster('kebnekaise')

myfcn is a command or serial MATLAB program.
N is the number of output arguments from the evaluated function
x1, x2, x3,… are the input arguments

job = c.batch(@myfcn, N, {x1,x2,x3,...})

Query the state of the job

job.State

If the state of the job is finished, fetch the result

job.fetchOutputs{:}

when you do not need the result anymore, delete the job

job.delete

If you are running a lot of jobs or if you want to quit MATLAB and restart it at a later time you can retrieve the list of jobs:

Get the list of jobs

jobs = c.Jobs

Retrieve the output of the second job (if there is one)

job2=jobs(2)
output = job2.fetchOutputs{:}

Example, serial job

We will use the example file add2.m which adds two numbers.

I used 1 and 2 here.

job = c.batch(@add2, 1, {1,2})

Check if it has finished with:

job.State

When it has finished, retrieve the result with:

job.fetchOutputs{:}

Parallel job

Running parallel batch jobs are quite similar to running serial jobs, we just need to specify a MATLAB Pool to use and of course MATLAB code that is parallelized.

To make a pool of workers, and to give input etc.

>> job = c.batch(@SCRIPT, #output, {input1, input2, input3, ...}, 'pool', #workers);

Example, parallel job

Running a simple Matlab script, parallel_example.m, giving the input “16”, creating 4 workers, expecting 1 output.

I use j instead of job in this example to show that you can name as you want.

>> j = c.batch(@parallel_example, 1, {16}, 'pool', 4);

additionalSubmitArgs =

   '--ntasks=5 --cpus-per-task=1 -A hpc2n2024-114 -t 01:00:00'

>> j.State

ans =

    'running'

>> j.State

ans =

    'finished'

>> j.fetchOutputs{:}

ans =

    9.3387

>>

There is more information about batch jobs here on Mathworks.

Using MATLAB in batch scripts¶

MATLAB can also be used in batch scripts, though this is not generally recommended as it can be difficult to get the parallelization right.

While we can submit batch jobs (or even batch jobs of batch jobs) from inside MATLAB (and that may be the most common way of using the batch system with MATLAB), it is also possible to create a batch submit script and use that to run MATLAB.

The difference here is that when the batch script has been submitted, you cannot make changes to your job. It is not interactive. That is also an advantage - you can submit the job, log out, and then come back later and see the results.

You submit a batch job with sbatch <name-of-batchscript.sh>.

Example, serial batch job

The MATLAB code in this example is monte_carlo_pi.m

#!/bin/bash
# Change to your actual project number 
#SBATCH -A hpc2nXXXX-YYY
# Asking for 1 core
#SBATCH -n 1
# Asking for 30 min (change as you want)
#SBATCH -t 00:30:00
#SBATCH --error=matlab_%J.err
#SBATCH --output=matlab_%J.out

# Clean the environment
module purge > /dev/null 2>&1

# Change depending on resource and MATLAB version
# to find out available versions: module spider matlab
module add MATLAB/2023a.Update4

# Executing the matlab program monte_carlo_pi.m for the value n=100000
# (n is number of steps - see program).
# The command 'time' is timing the execution
time matlab -nojvm -nodisplay -r "monte_carlo_pi(100000)"

Submit with sbatch <mybatch.sbatch> (change to what you named the batch script.

The output will end up in matlab_JOBID.out and any errors will end in matlab_JOBID.err.

Example, parallel batch job

This example runs the parallel MATLAB script parallel_example.m that was run inside MATLAB in the example further up on the page.

Inside the MATLAB code, the number of CPU-cores (NumWorkers in MATLAB terminology) can be specified when creating the parallel pool, for example, with 8 threads:

poolobj = parpool('local', 8);

Then, an example script to run that could look like this:

#!/bin/bash
# Change to your actual project number
#SBATCH -A hpc2nXXXX-YYY
# Remember, there are 4 workers and 1 master in the example! 
#SBATCH --ntasks=5
#SBATCH --cpus-per-task=1
#SBATCH --ntasks-per-node=5
#SBATCH --ntasks-per-core=1

# Asking for 30 min (change as you want)
#SBATCH -t 00:30:00
#SBATCH --error=matlab_%J.err
#SBATCH --output=matlab_%J.out

# Clean the environment
module purge > /dev/null 2>&1

# Change depending on resource and MATLAB version
# to find out available versions: module spider matlab
module add MATLAB/2023a.Update4 

# Executing a parallel matlab program
srun matlab -nojvm -nodisplay -nodesktop -nosplash -r "parallel-example(16)"