MATLAB

Basics

Workers and pools

In MATLAB’s terminology, a worker is a CPU-core and a pool is a set of workers (i.e. a group of CPU-cores in a machine). By default, a parallel pool starts automatically when needed by parallel language features such as parfor (parallel for-loop), parfeval (parallel function evaluation), mapreduce, among others.

Users are strongly encouraged to read the “Run Code on Parallel Pools” section of MathWorks documentation before attempting to parallelize their code.

Parallel and distributed execution

When reserving a pool of workers for execution, MATLAB handles communication between workers automatically. This also includes workers running on different machines. Thus, parallel and distributed execution look the same from an user’s point of view.

Cluster profiles

As per MathWorks’ documentation, cluster profiles let users define certain properties for a cluster, then have these properties applied when they create cluster, job, and task objects in the MATLAB client. For instance, the code below shows an example where an user creates a cluster profile from MATLAB’s command-line. Option JobStorageLocation specifies the path at the user’s workstation (i.e. their local machine) where information about a job submitted to a cluster is to be stored. Option NumWorkers represents the number of workers allowed by the MATLAB license in the cluster (i.e. the remote machine). Option ClusterMatlabRoot specifies the full path to the MATLAB install folder on the cluster. Option OperatingSystem specifies the category of the cluster’s operating system. Option HasSharedFilesystem indicates whether or not there is a disk location accessible to the user’s workstation and the workers on the cluster. Option PluginScriptsLocation specifies the full path to the plugin script folder that contains the matlab-parallel-slurm-plugin or other scheduler related plugin.

>> cluster = parallel.cluster.Generic( ...
>> 'JobStorageLocation', 'C:\MatlabJobs', ...
>> 'NumWorkers', 20, ...
>> 'ClusterMatlabRoot', '/usr/local/MATLAB/R2025b', ...
>> 'OperatingSystem', 'unix', ...
>> 'HasSharedFilesystem', false, ...
>> 'PluginScriptsLocation', 'C:\MatlabSlurmPlugin\shared');

Some of the functions that support the use of cluster profiles are: batch, parpool, parcluster. Uses of some of these functions alongside a cluster profile for LARCC’s login node are shown later in Sections Submitting a batch job and and Creating a cluster profile for Zurada respectively.

Users are encouraged to read more about cluster profiles in the “Use Cluster Profiles” section of MathWorks’ documentation.

Submitting a batch job

There are three options to submit MATLAB batch jobs:

Using a Batch Script:
MATLAB is invoked directly from the shell within the batch script, where the project’s main .m source file is passed to the MATLAB executable. For a detailed walkthrough, refer to Section Submit jobs through a batch script. This method is often the easiest, but distributed execution is not available with this option.
Using MATLAB’s Command Prompt:
Users initiate the matlab command from the head node. Within the MATLAB prompt, they load the relevant cluster profile and leverage the batch option, as detailed in Section Submit jobs through MATLAB’s command prompt.
Using a Batch Script and a MATLAB Submission Script:
This approach mixes elements from the preceding two methods. A job is scheduled using option 1, which, in turn, allocates a second job executing the main project’s code in parallel. The process involves creating a batch script, akin to the first option. However, instead of passing the project’s main .m source file to the MATLAB executable, an intermediate .m file, functioning as the MATLAB submission script, is passed. This intermediate file employs the same commands outlined in option 2 to schedule a new job that employs multiple workers.

Note

Most users should default to launching matlab using method 1 (i.e. a simple batch script), as it is the easiest and supports parallel execution. Users whose workloads benefit from distributed execution should familiarize themselves with Matlab Cluster Profiles first.

Submit jobs through a batch script

Copy the Matlab project to the cluster. That is, all .m source code files that are to be passed to matlab for execution. For example, assume the file $WORK/test.m has the following content:
p = parpool(str2num(getenv('SLURM_NTASKS'))); t0 = tic; A = 500; a = zeros(1000); parfor i = 1:1000 a(i) = max(abs(eig(rand(A)))); end t = toc(t0) exit

Create a batch script. For example, assume the file $WORK/matlab_test.sh has the following content:

#!/bin/bash
#SBATCH -J test_matlab
#SBATCH -o /work/user/test_matlab-%j.out
#SBATCH -e /work/user/tmp/test_matlab-%j.err
#SBATCH -p cpu384g
#SBATCH -n 4
#SBATCH -t 20:00

module load matlab/r2025b
matlab -nosplash -nodesktop < /home/user/test.m

Use the sbatch command to schedule the job. Following the example from previous steps: sbatch $WORK/matlab_test.sh.

Submit jobs through MATLAB’s command prompt

Copy the Matlab project to the cluster. That is, all .m source code files that are to be passed to matlab for execution. For example, assume the file $WORK/parallelExample.m has the following content:

function t = parallelExample(n)
    t0 = tic;
    A = 500;
    a = zeros(n);
    parfor i = 1:n
        a(i) = max(abs(eig(rand(A))));
    end
    t = toc(t0);
end

Execute MATLAB’s prompt by loading the appropriate matlab module and running the command matlab -nodisplay -nosplash -nodesktop from the head node. For example,

user@login01:~$ module load matlab/r2025b
user@login01:~$ matlab -nodisplay  -nosplash -nodesktop

                                                < M A T L A B (R) >
                                      Copyright 1984-2025 The MathWorks, Inc.
                                 R2025b (25.2.0.2998904) 64-bit (glnxa64)
                                                 August 21, 2025


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

>>

Once in the prompt, load the cluster profile using the parcluster command, add additional slurm properties like the job’s time limit and queue to submit the job to, and finally execute the job using the batch command from the object obtained from the parcluster command. For example:

>> % The following line loads the zurada-local profile
>> cluster = parcluster('zurada-local');
>> % The following line sets the job's time limit
>> cluster.AdditionalProperties.WallTime = '1:00:00';
>> % The following line sets the queue to where the job will be submitted to
>> cluster.AdditionalProperties.Partition = 'cpu384g';
>> % The following line submits the job. Here is a breakdown of the line:
>> % - @parallelExample refers to the function in $WORK/parallelExample.m
>> % - 1 is the number of outputs returned by the function
>> % - {1000} are the arguments to be passed to the function
>> % - 'Pool' indicates matlab to create a pool of workers for parallel
>> %   (or distributed) execution
>> % - 8 indicates the number of workers to use in the pool
>> job = cluster.batch(@parallelExample, 1, {1000}, 'Pool', 8);

After the job has been submitted, users can wait for the job to finish and fetch any result not persisted to disk by executing in the prompt job.fetchOutputs{:};.

Submit jobs through a batch script and a MATLAB submission script

Copy the Matlab project to the cluster. That is, all .m source code files that are to be passed to matlab for execution. For example, assume the file $WORK/parallelExample.m has the following content:

function t = parallelExample(n)
    t0 = tic;
    A = 500;
    a = zeros(n);
    parfor i = 1:n
        a(i) = max(abs(eig(rand(A))));
    end
    t = toc(t0);
    fileToSaveResultTo = "result.txt";
    save(fileToSaveResultTo)
end

Create a MATLAB submission script that invokes project’s code. For example, assume the file $WORK/matlabSubmissionScript.m has the following content:

% Get the number of workers from the slurm scheduler. The SLURM_NTASKS
% environmental variable is set automatically by slurm.
workers = str2num(getenv('SLURM_NTASKS'));
% Load the zurada-local cluster profile
cluster = parcluster('zurada-local');
% Set the job's time limit
cluster.AdditionalProperties.TimeLimit = '1:00:00';
% Set the queue to where the job will be submitted to
cluster.AdditionalProperties.Partition = 'cpu384g';
% Submit the job. Here is a breakdown of the line:
% - @parallelExample refers to the function in $WORK/parallelExample.m
% - 1 is the number of outputs returned by the function
% - {1000} are the arguments to be passed to the function
% - 'Pool' indicates matlab to create a pool of workers for parallel
%   (or distributed) execution
% - 8 indicates the number of workers to use in the pool
job = cluster.batch(@parallelExample, 1, {1000}, 'pool', workers);

Create a sbatch script that invokes the matlab submission script from the previous step. For example, assume the file $WORK/matlab_test.sh has the following content:

#!/bin/bash

#SBATCH -J test_matlab
#SBATCH -o /work/user/test_matlab-%j.out
#SBATCH -e /work/user/tmp/test_matlab-%j.err
#SBATCH -p cpu384g
#SBATCH -n 20
#SBATCH -t 20:00

module load matlab/r2025b
matlab -nodisplay -nosplash -nodesktop -r "matlabSubmissionScript"

Use the sbatch command to schedule the job. Following the example from previous steps: sbatch $WORK/matlab_test.sh

Creating a cluster profile for Zurada

The login node acts as a Matlab client in this case. This means that instead of creating a cluster profile in their personal or university workstation, an user creates a cluster profile in the login node. The steps are as follows:

Log into the cluster.
Load the matlab module you would like to use. For example, module load matlab/r2025b.

Create a cluster profile by running the command below. Make sure to modify the value of variables: profileName, numWorkers, and jobStorageLocation as you see fit.

(
cat << EOF
profileName = 'zurada-cluster';
numWorkers = 60;
jobStorageLocation = '$WORK/.matlab/local_cluster_jobs/r2025b';
profiles = parallel.listProfiles;
if ~any(strcmp(profileName, profiles))
    c = parallel.cluster.Generic( ...
          'JobStorageLocation', jobStorageLocation, ...
          'NumWorkers', numWorkers, ...
          'ClusterMatlabRoot', '/mnt/apps/manual/matlab/r2025b', ...
          'OperatingSystem', 'unix', ...
          'HasSharedFilesystem', true, ...
          'PluginScriptsLocation', '/mnt/apps/manual/matlab/r2025b/toolbox/matlab-parallel-slurm-plugin-2.3.0');
    saveAsProfile(c, profileName);
end
EOF
) | matlab -nodisplay -nosplash -nodesktop

Validate that the cluster profile was saved. To do this, execute matlab again as follows: matlab -nodisplay -nosplash -nodesktop -batch "disp(parallel.listProfiles)". The output list should include a cluster profile with the name set in the profileName variable.