(matlab)=

# MATLAB

## Introduction

[MATLAB](http://www.mathworks.com/) handles a range of computing tasks in engineering and science, from data acquisition and analysis to application development. The MATLAB environment integrates mathematical computing, visualization, and a powerful technical language. It is especially well-suited to vectorized calculations and has a Parallel Computing Toolbox (not included in all licenses) that streamlines parallelization of code. 

## Availability

MATLAB is available on ARC systems. ARC maintains a MATLAB Distributed Computing Server license for parallel MATLAB through cooperation with the university's [IT Procurement and Licensing Solutions](https://itpals.vt.edu/), who also offer discounted licenses to departments and students (note that MATLAB is also included in some of the [Student Bundles](https://itpals.vt.edu/softwarelicensingcenter/studentsoftware/swbundles.html)). 

## Interface

There are two types of environments in which the MATLAB application can be used on ARC resources:
- Graphical interface via [OnDemand](https://ood.arc.vt.edu/)
- Command-line interface. You can also start MATLAB from the command line on Unix systems where MATLAB is installed. Note that the command line runs on the login node, so big computations should be submitted as jobs, either from via a [traditional job submission](slurm) or from within MATLAB.


## Parallel Computing in MATLAB

There are two primary means of obtaining parallelism in MATLAB: 
- **parfor**: Replacing a for loop with a parfor loop splits the loop iterations among a group of processors. This requires that the loop iterations be independent of each other.
- **spmd**: Single program multiple data (spmd) allows multiple processors to execute a single program (similar to MPI).


##  Job Submission

This page contains instructions for submitting jobs from MATLAB to ARC clusters.

### Setup
Setup is as simple as starting MATLAB on a login node and then running
```
>> configCluster
```
**Note:** Do this once on TinkerCliffs or anytime you switch between clusters. (Or anytime you start MATLAB - it won't hurt to run it more often than necessary.)

### Running Jobs
After that, the key commands are:

- `c=parcluster` to get the cluster configuration
- `c.AdditionalProperties` is a structure where you can set job parameters. You must set `AccountName` to the allocation account to which you want to submit the job; the other paramters are optional. Commonly-used properties are:
    - `AccountName`: Allocation account (required)
    - `WallTime`
    - `Partition`
    - `GpusPerNode`
    - `AdditionalSubmitArgs`: Any other standard flags that you want to submit directly to the scheduler
- `batch(c,...)` to submit the job

An example is shown [below](matlab_job_example).

### Checking Jobs

The job structure returned by `batch()` can be queried to get the job state, outputs, diary (command line output), etc. See the [example](matlab_job_example) below.

MATLAB also comes with a [Job Monitor](https://www.mathworks.com/help/parallel-computing/job-monitor.html) to allow tracking of remote jobs via a graphical interface. Right-clicking on jobs will allow you to show its output, load its variables, delete it, etc.

### Remote Output Files

Remote MATLAB jobs start in the directory specified by the `CurrentFolder` parameter to `batch()`. Output files written to remote jobs will be saved in this location. Alternatively, you may specify the full path to where you want it to save the file, e.g.
```
save('/home/johndoe/output')
```
Note that if you submit from your personal machine, these files will not be copied back to your local machine; you will need to manually log into the machine to get them. Alternatively, you can tell MATLAB to change to the directory on the ARC cluster where job information is stored; MATLAB will automatically mirror this location to your local machine when the job completes. Here is an example command for switching to the job directory: 
```
cd(sprintf('%s/%s',getenv('MDCE_STORAGE_LOCATION'),getenv('MDCE_JOB_LOCATION')));
```

Note that once the job completes, you will need to look in its local job directory to get the output files; this location can be configured in your local cluster profile. Be sure to remove any output files you need before deleting your job (e.g. with the `delete` command).

(matlab_job_example)=
### Full Example
Here we set up a cluster profile and then submit a job to compute the number of primes between 1 and 10 million using the [prime_fun](https://github.com/AdvancedResearchComputing/examples/blob/master/matlab/) parallel MATLAB example. MATLAB runs the job and returns the correct answer: 664,579.

(Note that to run this example, we've downloaded the code to a directory on TinkerCliffs and then changed to that directory.)

```
[johndoe@tinkercliffs2 prime_fun]$ module load MATLAB
[johndoe@tinkercliffs2 prime_fun]$ matlab -nodisplay

< M A T L A B (R) >
Copyright 1984-2024 The MathWorks, Inc.
R2024b (24.2.0.2712019) 64-bit (glnxa64)
August 22, 2024

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

>> configCluster
>> c = parcluster;
>> c.AdditionalProperties.AccountName = 'arcadm';
>> j = batch(c,@prime_fun,1,{10000000},'pool',4); 

additionalSubmitArgs =

    '--ntasks=5 --cpus-per-task=1 --ntasks-per-core=1 -A arcadm'

>> j.State

ans =

    'running'

>> j.State

ans =

    'finished'

>> j.fetchOutputs{1}

ans =

      664579
```

## Submitting Jobs from the Linux Command Line

MATLAB jobs can also be submitted from the Linux command line like any other jobs; however, the parallelism is currently limited to the cores on a single node. This [example](https://github.com/AdvancedResearchComputing/examples/blob/master/matlab/) uses `parfor` to count in parallel the prime numbers between 1 and 10,000,000. (The correct answer is 664,579). A submission script to submit it as a job from the command line is provided [here](https://github.com/AdvancedResearchComputing/examples/tree/master/matlab).

## Toolbox Paths Missing Between MATLAB GUI and Command-Line Sessions

When using MATLAB on ARC, users can run MATLAB in three main ways:

1. **Launching the MATLAB GUI** through [Open OnDemand (OOD)](https://ood.arc.vt.edu/)  
2. **Loading MATLAB via the software module** and running interactively from an SSH session  
3. **Loading MATLAB via the software module** and running jobs in batch mode using a Slurm script  

A common issue arises when toolboxes installed or enabled in the **OOD MATLAB GUI** session are not recognized in the **SSH command-line** or **Slurm batch** sessions. This happens because MATLAB launched in batch or SSH mode starts in a **clean environment** and does not automatically inherit the same toolbox paths or user preferences as the GUI session.

To ensure that toolboxes installed or configured in your OOD MATLAB session are available when running MATLAB in batch or interactive command-line modes, follow these steps:

1. **Launch MATLAB GUI via Open OnDemand**  
   Go to [https://ood.arc.vt.edu/pun/sys/dashboard/](https://ood.arc.vt.edu/pun/sys/dashboard/) and start MATLAB interactively.

2. **Verify toolbox availability**  
   In the MATLAB GUI command window, verify that all required toolboxes (e.g., *Computer Vision Toolbox*, *Deep Learning Toolbox*) are available by running:
    ```
    >> ver
    ```
    This command displays the MATLAB version, release information, and a list of all installed toolboxes and MathWorks products.

3. **Save your MATLAB path**  
    In the same MATLAB GUI command window, run the following command to save your current MATLAB path (including all installed toolboxes) to your home directory:
    ```
    >> savepath('~/matlab/pathdef.m')
    ```
    This ensures that your toolbox paths are automatically loaded when MATLAB runs in non-GUI modes (such as SSH interactive or batch sessions).

4. **Update your Slurm job script**  
    In your Slurm submission script or in your SSH-based interactive session, use the following command to run MATLAB:
    ```
    $ module load MATLAB
    $ matlab -nodisplay -nosplash -nodesktop -batch Your_MATLAB_Code.m
    ```
    This command runs your MATLAB code in a clean, non-interactive environment while loading your saved pathdef.m file, ensuring that all toolboxes installed through the OOD MATLAB GUI are available for use.

## Changing MATLAB\'s Path

To add a folder to MATLAB's path on ARC's systems, edit the `MATLABPATH` environment variable. This can be made permanent by editing it in your `.bashrc` file. For example, this line would add the folder `mydir` in your Home directory to MATLAB\'s path anytime it opens in your account: 
```
echo "export MATLABPATH=\\$HOME/mydir:\$MATLABPATH\" >> ~/.bashrc
```

An alternative is to create a `pathdef.m` file in the directory where MATLAB starts. This will add folders to MATLAB\'s path whenever it starts in the folder where `pathdef.m` is located. For example, the following at the MATLAB command line would add `mydir` to the path when MATLAB opens in your Home directory: 
```
addpath('/home/johndoe/mydir');
savepath('/home/johndoe/pathdef.m')
```

## Using the MATLAB Compiler (mex)

To compile C/C++ or Fortran code in MATLAB, just make sure to load the compiler [module](modules) that you want to use before you open MATLAB. Here is an example of compiling [MatConvNet](http://www.vlfeat.org/matconvnet/), which in this case requires the GCC compiler, which is available via the `foss` module: 
```
# load modules
module reset; module load MATLAB

# open matlab and do the install 
# (vl_compilenn is the installer script in this case)
matlab -nodisplay
[matlab starts]
>> vl_compilenn
```

## Using Gurobi in MATLAB

You may use Gurobi within your MATLAB session. Simply load the Gurobi module after loading MATLAB's  module and before running MATLAB itself.

```
module load MATLAB
module load Gurobi
matlab
```