# Using MATLAB

MATLAB is a proprietary scientific computing language and environment.

### Using MATLAB on CARC systems

Begin by logging in. You can find instructions for this in the Getting Started with Discovery or Getting Started with Endeavour user guides.

To use MATLAB, either interactively or in batch mode, load the corresponding module:

`module load matlab`

This loads the default version, currently 2020b, and is equivalent to `module load matlab/2020b`

. If you require a different version, specify the version of MATLAB when loading. For example:

`module load matlab/2019a`

To see all available versions of MATLAB, enter:

`module spider matlab`

#### Requesting newer versions of MATLAB

It may be necessary to run MATLAB using a version that is not currently available. Licensed software such as MATLAB requires license setup by CARC staff. If there is a new version of MATLAB that you want to use, please submit a help ticket and we will install it for you.

#### Installed toolboxes

To check installed toolboxes and their versions, enter the `ver`

command when using MATLAB in interactive mode.

#### MATLAB GUI

Please note that we do not currently support the use of the MATLAB GUI on CARC systems.

### Running MATLAB in interactive mode

After loading the module, you can run MATLAB interactively on the **login node** by entering the command `matlab -nodisplay`

. Using MATLAB on the login node should be reserved for non-intensive work. Conversely, using MATLAB interactively on a **compute node** is useful for more intensive work like exploring data, testing models, and debugging.

A common mistake for new users of HPC clusters is to run heavy workloads directly on a login node (e.g., `discovery.usc.edu`

or `endeavour.usc.edu`

). Unless you are only running a small test, **please make sure to run your program as a job** interactively on a compute node. Processes left running on login nodes may be terminated without warning. For more information on jobs, see our Running Jobs user guide.

To run MATLAB interactively on a compute node, first use Slurm's `salloc`

command to reserve job resources on a node:

```
user@discovery1:~$ salloc --time=2:00:00 --ntasks=1 --cpus-per-task=8 --mem=16GB --account=<project_id>
salloc: Pending job allocation 24316
salloc: job 24316 queued and waiting for resources
salloc: job 24316 has been allocated resources
salloc: Granted job allocation 24316
salloc: Waiting for resource configuration
salloc: Nodes d05-08 are ready for job
```

Make sure to change the resource requests (the `--time=2:00:00 --ntasks=1 --cpus-per-task=8 --mem=16GB --account=<project_id>`

part after your `salloc`

command) as needed, such as the number of cores and memory required. Also make sure to substitute your project ID, which is of the form `<PI_username>_<id>`

. You can find your project ID in the CARC User Portal.

Once you are granted the resources and logged in to a compute node, load the module and then enter `matlab -nodisplay`

:

```
user@d05-08:~$ module load matlab
user@d05-08:~$ matlab -nodisplay
< M A T L A B (R) >
Copyright 1984-2020 The MathWorks, Inc.
R2020b Update 4 (9.9.0.1570001) 64-bit (glnxa64)
January 7, 2021
To get started, type doc.
For product information, visit www.mathworks.com.
>>
```

Notice that the shell prompt changes from `user@discovery1`

to `user@<nodename>`

to indicate that you are now on a compute node (e.g., `d05-08`

).

To exit the node and relinquish the job resources, enter `exit`

to exit MATLAB and then enter `exit`

in the shell. This will return you to the login node:

```
>> exit
user@d05-08:~$ exit
exit
salloc: Relinquishing job allocation 24316
user@discovery1:~$
```

Please note that compute nodes do not have access to the public internet, so any data or other downloads should first be completed on the login or transfer nodes.

### Running MATLAB in batch mode

In order to submit jobs to the Slurm job scheduler, you will need to use MATLAB in batch mode. There are a few steps to follow:

- Create a MATLAB script
- Create a Slurm job script that runs the MATLAB script
- Submit the job script to the job scheduler using
`sbatch`

Your MATLAB script should consist of the sequence of MATLAB commands needed for your analysis or simulation.

A Slurm job script is a special type of Bash shell script that the Slurm job scheduler recognizes as a job. For a job running MATLAB, a Slurm job script should look something like the following:

```
#!/bin/bash
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=8
#SBATCH --mem=16GB
#SBATCH --time=1:00:00
#SBATCH --account=<project_id>
module purge
module load matlab/2020b
# Do not include the .m extension in your script name (script.m)
matlab -batch 'script'
```

Each line is described below:

Command or Slurm argument | Meaning |
---|---|

`#!/bin/bash` | Use Bash to execute this script |

`#SBATCH` | Syntax that allows Slurm to read your requests (ignored by Bash) |

`--nodes=1` | Use 1 compute node |

`--ntasks=1` | Run 1 task (e.g., running a MATLAB script) |

`--cpus-per-task=8` | Reserve 8 CPUs for your exclusive use |

`--mem=16GB` | Reserve 16 GB of memory for your exclusive use |

`--time=1:00:00` | Reserve resources described for 1 hour |

`--account=<project_id>` | Charge compute time to <project_id>. If not specified, you may use up the wrong PI's compute hours |

`module purge` | Clear environment modules |

`module load matlab/2020b` | Load the `matlab` environment module |

`matlab -batch 'script'` | Use `matlab` to run `script.m` in batch mode |

Make sure to adjust the resources requested based on your needs, but remember that fewer resources requested leads to less queue time for your job. Note that to fully utilize the resources, especially the number of cores, you may need to explicitly change your MATLAB code to do so (see the section on the parallel computing toolbox below).

You can develop MATLAB scripts and job scripts on your local computer and then transfer them to CARC storage, or you can use one of the available text editor modules (e.g., `micro`

) to develop the scripts directly on the cluster.

Save the job script as `matlab.job`

, for example, and then submit it to the job scheduler with Slurm's `sbatch`

command:

```
user@discovery1:~$ sbatch matlab.job
Submitted batch job 170554
```

To check the status of your job, enter `squeue -u <username>`

. For example:

```
user@discovery1:~$ squeue -u user
JOBID PARTITION NAME USER ST TIME NODES NODELIST(REASON)
170554 main matlab.j user R 3:07 1 d11-04
```

If there is no job status listed, then this means the job has completed.

The results of the job will be logged and, by default, saved to a plain-text file of the form `slurm-<jobid>.out`

in the same directory where the job script was submitted from. To view the contents of this file, enter `less slurm-<jobid>.out`

, and then enter `q`

to exit the viewer.

For more information on running and monitoring jobs, see the Running Jobs guide.

### Using the parallel computing toolbox

To run a MATLAB script using the parallel computing toolbox, you will first need to create a **cluster profile** in order to start a pool of parallel workers. There are two types of clusters: *local* and *remote*. A local cluster will run on only a single compute node. A remote cluster is necessary when you want to run your script across multiple compute nodes.

#### Setting up a local cluster (single node)

To set up a local cluster, add the following lines to your script:

```
cluster = parallel.cluster.Local;
nproc = str2num(getenv('SLURM_CPUS_PER_TASK')) - 1;
```

Here we define the `nproc`

variable to reserve one core for overhead, to be used when starting the pool.

#### Setting up a remote cluster (multiple nodes)

To start a worker pool larger than can fit on a single node (based on the number of cores), you will need to set up a remote cluster. With the remote cluster, MATLAB will submit a Slurm job on your behalf to allocate resources. To do this, add the following lines to your MATLAB script:

```
cluster = parallel.cluster.Slurm;
set(cluster,'JobStorageLocation',<directory>);
set(cluster,'HasSharedFilesystem',true);
set(cluster,'SubmitArguments','--time=1:00:00 --mem-per-cpu=2GB');
set(cluster,'ResourceTemplate','--ntasks=^N^');
```

where `JobStorageLocation`

, `SubmitArguments`

, and `ResourceTemplate`

are defined below:

Cluster attribute | Meaning |
---|---|

`JobStorageLocation` | Path to directory for temporary job storage (e.g., `/project/ttrojan_123/matlabJobStorage` ) |

`SubmitArguments` | Arguments to Slurm job scheduler |

`ResourceTemplate` | Template for compute resources (recommended to keep as `'--ntasks=^N^'` ) |

Make sure to update the `JobStorageLocation`

and `SubmitArguments`

attributes as necessary. For example, you may wish to increase the time or memory requirements for your worker pool.

To automate the creation of unique job storage locations, based on the job ID, add lines like the following to your script before setting up the remote cluster:

```
job_folder = fullfile('/scratch/ttrojan',getenv('SLURM_JOB_ID'));
mkdir(job_folder);
```

Then set the `JobStorageLocation`

attribute to the `job_folder`

variable:

`set(cluster,'JobStorageLocation',job_folder);`

#### Starting a pool of workers

Once a cluster profile has been configured, the process for starting up a pool of workers for both a local and remote cluster is the same.

Assuming you have created a cluster object named `cluster`

, you can start up a pool of workers using the `parpool`

command:

`pool=parpool(cluster,N)`

where `N`

is the number of workers (CPUs) to use.

If starting a **local cluster**, `N`

must be 1 less than the total number of available CPUs requested, as MATLAB requires 1 CPU to delegate work. We automated this above by creating an `nproc`

variable based on the `SLURM_CPUS_PER_TASK`

environment variable, so `N`

can be set to `nproc`

:

`pool=parpool(cluster,nproc)`

If starting a **remote cluster**, MATLAB will submit a job requesting resources for `N`

workers using the `ResourceTemplate`

defined in the cluster profile. For example, to use 64 workers, add the following line:

`pool=parpool(cluster,64)`

Once the pool is started, you can then use parallel commands like `parfor`

or `spmd`

in your script.

Make sure that you close your parallel pool when you are done with it by adding the following command to your script:

`delete(pool)`

### Additional resources

If you have questions about or need help with MATLAB, please submit a help ticket and we will assist you.

MATLAB website

MATLAB documentation

MATLAB parallel computing documentation