# MATLAB

## Introduction

MATLAB (an abbreviation of "MATrix LABoratory") is a proprietary multi-paradigm programming language
and numeric computing environment developed by MathWorks.
MATLAB allows matrix manipulations, plotting of functions and data, implementation of algorithms,
creation of user interfaces, and interfacing with programs written in other languages.

## Installed Versions

For the current list of installed versions, use:

```console
$ ml av MATLAB
```

## MATLAB GUI

If you need to use the MATLAB GUI to prepare your MATLAB programs, you can use MATLAB directly on the login nodes.
However, for all computations, use MATLAB on the compute nodes via Slurm workload manager.

If you require the MATLAB GUI, follow the general information about [running graphical applications][1].

MATLAB GUI is quite slow using the X forwarding built in the PBS (`qsub -X`),
so using X11 display redirection either via SSH or directly by `xauth`
(see the [GUI Applications on Compute Nodes over VNC][1] section) is recommended.

To run MATLAB with GUI, use:

```console
$ matlab
```

To run MATLAB in text mode, without the MATLAB Desktop GUI environment, use:

```console
$ matlab -nodesktop -nosplash
```

plots, images, etc. will be still available.

## MATLAB Configuration

### Client Configuration

After logging into the cluster, start MATLAB.
On the Home tab, click Parallel > Discover Clusters… to discover the profile.

![](../../img/dis_clluster.png)

Jobs will now default to the cluster rather than submit to the local machine.

### Job Configuration

Prior to submitting the job, various parameters can be assigned, such as queue, e-mail,walltime, etc.
The following is a partial list of parameters.
See `AdditionalProperties` for the complete list.
Only the `ProjectName` is required.

```
>> % Get a handle to the cluster
>> c = parcluster;

[REQUIRED]

>> % Specify the project name
>> c.AdditionalProperties.ProjectName = 'project-name';

[OPTIONAL]

>> % Specify a constraint
>> c.AdditionalProperties.Constraint = 'feature-name';

>> % Request email notification of job status
>> c.AdditionalProperties.EmailAddress = 'user-id@university.edu';


>> % Specify number of GPUs
>> c.AdditionalProperties.GpusPerNode = 1;
>> c.AdditionalProperties.GpuCard = 'gpu-card';

>> % Specify memory to use, per core (default: 4gb) [FOR GPU NODES]
>> c.AdditionalProperties.MemPerCPU = '6gb';

>> % Specify the partition
>> c.AdditionalProperties.Partition = 'partition-name';

>> % Specify cores per node
>> c.AdditionalProperties.ProcsPerNode = 4;

>> % Specify QoS
>> c.AdditionalProperties.QoS = 'qos-name';

>> % Use reservation
>> c.AdditionalProperties.Reservation = 'reservation-name';

>> % Specify the wall time (e.g., 1 day, 5 hours, 30 minutes)
>> c.AdditionalProperties.WallTime = '1-05:30';
```

Save changes after modifying AdditionalProperties for the above changes to persist between MATLAB sessions.

```
>> c.saveProfile
```

To see the values of the current configuration options, display AdditionalProperties.

```
>> % To view current properties
>> c.AdditionalProperties
```

Unset a value when no longer needed.

```
>> % Turn off email notifications
>> c.AdditionalProperties.EmailAddress = '';
>> c.saveProfile
```

## Running Job

### Interactive Jobs

To run an interactive pool job on the cluster, continue to use `parpool` as before.

```
>> % Get a handle to the cluster
>> c = parcluster;

>> % Open a pool of 64 workers on the cluster
>> pool = c.parpool(64);
```

Rather than running local on the local machine, the pool can now run across multiple nodes on the cluster.

```
>> % Run a parfor over 1000 iterations
>> parfor idx = 1:1000
      a(idx) = rand;
   end
```

Delete the pool when it’s no longer needed.

```
>> % Delete the pool
>> pool.delete
```

### Independent Batch Job

Use the batch command to submit asynchronous jobs to the cluster.
The batch command will return a job object which is used to access the output of the submitted job.
See the MATLAB documentation for more help on batch.

```
>> % Get a handle to the cluster
>> c = parcluster;

>> % Submit job to query where MATLAB is running on the cluster
>> job = c.batch(@pwd, 1, {});

>> % Query job for state
>> job.State

>> % If state is finished, fetch the results
>> job.fetchOutputs{:}

>> % Delete the job after results are no longer needed
>> job.delete
```

To retrieve a list of running or completed jobs, call `parcluster` to return the cluster object.
The cluster object stores an array of jobs that are queued to run, are running, have run, or have failed.
Retrieve and view the list of jobs as shown below.

```
>> c = parcluster;
>> jobs = c.Jobs
>>
>> % Get a handle to the second job in the list
>> job2 = c.Jobs(2);
```

Once the job has been selected, fetch the results as previously done.

`fetchOutputs` is used to retrieve function output arguments; if calling `batch` with a script, use `load` instead.
Data that has been written to files on the cluster needs be retrieved directly from the file system (e.g., via sftp).

```
>> % Fetch all results from the second job in the list
>> job2.fetchOutputs{:}
```

### Parallel Batch Job

`batch` can also submit parallel workflows.
Let’s use the following example for a parallel job, which is saved as `parallel_example.m`.

```
function [sim_t, A] = parallel_example(iter)

if nargin==0
    iter = 8;
end

disp('Start sim')

t0 = tic;
parfor idx = 1:iter
    A(idx) = idx;
    pause(2)
    idx
end
sim_t = toc(t0);

disp('Sim completed')

save RESULTS A

end
```

This time when using the `batch` command, also specify a MATLAB `Pool` argument.

```
>> % Get a handle to the cluster
>> c = parcluster;

>> % Submit a batch pool job using 4 workers for 16 simulations
>> job = c.batch(@parallel_example, 1, {16}, 'Pool',4);

>> % View current job status
>> job.State

>> % Fetch the results after a finished state is retrieved
>> job.fetchOutputs{:}

ans =
	8.8872
```

The job ran in 8.89 seconds using four workers.
Note that these jobs will always request N+1 CPU cores, since one worker is required to manage the batch job and pool of workers.
For example, a job that needs eight workers will request nine CPU cores.

Run the same simulation but increase the Pool size. This time, to retrieve the results later, keep track of the job ID.

!!! note
    For some applications, there will be a diminishing return when allocating too many workers,
    as the overhead may exceed computation time.

```
>> % Get a handle to the cluster
>> c = parcluster;

>> % Submit a batch pool job using 8 workers for 16 simulations
>> job = c.batch(@parallel_example, 1, {16}, 'Pool',8);

>> % Get the job ID
>> id = job.ID
id =
	4
>> % Clear job from workspace (as though MATLAB exited)
>> clear job
```

With a handle to the cluster, the `findJob` method searches for the job with the specified job ID.

```
>> % Get a handle to the cluster
>> c = parcluster;

>> % Find the old job
>> job = c.findJob('ID', 4);

>> % Retrieve the state of the job
>> job.State

ans =
finished

>> % Fetch the results
>> job.fetchOutputs{:};

ans =
4.7270
```

The job now runs in 4.73 seconds using eight workers.
Run code with different number of workers to determine the ideal number to use.

Alternatively, to retrieve job results via a graphical user interface, use the Job Monitor (Parallel > Monitor Jobs).

![](../../img/monitor_job.png)

## Helper Functions

| Function              | Description                          |
| --------------------- | ------------------------------------ |
| clusterFeatures       | List of cluster features/constraints |
| clusterGpuCards       | List of cluster GPU cards            |
| clusterPartitionNames | List of cluster partition            |
| willRun               | Explain why job is queued            |

### Debugging

If a serial job produces an error, call the `getDebugLog` method to view the error log file.
When submitting an independent job, specify the task.

```
>> c.getDebugLog(job.Tasks)
```

For Pool jobs, only specify the job object.

```
>> c.getDebugLog(job)
```

When troubleshooting a job, the cluster admin may request the scheduler ID of the job.
This can be derived by calling `getTaskSchedulerIDs`).

```
>> job.getTaskSchedulerIDs()
ans =
25539
```

## Additional Information

For more information about the MATLAB Parallel Computing Toolbox,
see the following resources:

* [Parallel Computing Overview][c]
* [Parallel Computing Documentation][d]
* [Parallel Computing Coding Examples][e]
* [Parallel Computing Tutorials][f]
* [Parallel Computing Videos][g]
* [Parallel Computing Webinars][h]

[1]: ../../general/accessing-the-clusters/graphical-user-interface/vnc.md#gui-applications-on-compute-nodes-over-vnc
[2]: #running-parallel-matlab-using-distributed-computing-toolbox---engine
[3]: ../isv_licenses.md
[4]: #parallel-matlab-batch-job-in-local-mode

[a]: https://www.mathworks.com/help/parallel-computing/release-notes.html
[b]: https://www.e-infra.cz/en
[c]: https://www.mathworks.com/products/parallel-computing.html
[d]: https://www.mathworks.com/help/parallel-computing/index.html
[e]: https://www.mathworks.com/help/parallel-computing/examples.html
[f]: https://www.mathworks.com/videos/series/parallel-and-gpu-computing-tutorials-97719.html
[g]: https://www.mathworks.com/videos/search.html?q=&fq%5B%5D=product:DM&page=1
[h]: https://www.mathworks.com/videos/search.html?q=&fq%5B%5D=product:DM&fq%5B%5D=video-external-category:recwebinar&page=1