**Table of Contents**

Setting up the environment and invoking from a Research Computing server

Submitting Matlab jobs on a Research Computing server

## Overview

Matlab is a high performance language for technical computing. Computation, visualization, and programming are integrated in an easy-to-use environment. Matlab can be used for mathematics, modeling, simulation, data analysis, visualization, scientific and engineering graphics.

Default Version: |
2013a (Kure/Killdevil) |

Installed Version(s): |
2012a, 2012b, 2013a (Kure/Killdevil) |

Research Computing Servers: |
Kure, Killdevil |

Research Computing purchases the licenses (for university owned machines) for not only the basic Matlab but also for a number of toolboxes. Too see the complete list run the Matlab command

ver

from within Matlab.

You can choose to either install Matlab locally in your personal computer by ordering copy of Matlab from UNC’s Software Acquisition office or run Matlab on ITS lab computers, or the Research Computing server. Campus-wide licenses for the use of Matlab at UNC-CH are checking out from the UNC license server.

## Installation

You can install Matlab locally in your computer but check out licenses from the UNC license server. Matlab is available to faculty/staff and students for various operating systems through UNC Software Acquisition Office. Please visit their webpage for more information.

Matlab will be started locally on your machine, but the application will look for the UNC license servers through the Internet and check out licenses when it starts. **Therefore, a network connection for your machine is required for Matlab to run. **

After you get the installation copy of Matlab, refer to these directions:

- You will need a license file in order to install Matlab. Refer to these instructions to obtain a license file (license.dat).
- Follow these installation instructions to install Matlab locally.

## Setting up the environment and invoking from a Research Computing server

Matlab is available for use on the Research Computing Servers: Kure, and Killdevil. The following documents provide instructions for invoking Matlab and other high performance computing software. These documents include general instructions common to all applications, and specific instructions for each application.

- Invoking applications on a Research Computing Server from a UNIX/Linux desktop computer
- Invoking applications on a Research Computing Server from a Microsoft Windows computer

## Submitting Matlab jobs on a Research Computing server

This section covers specific examples of how to submit various types of Matlab jobs on Research Computing’s two main compute clusters: Kure and KillDevil.

To start you will need to add Matlab to your cluster environment using the module commands:

module add matlab

module initadd matlab

All of the following examples assume you are in the directory where your Matlab script is located.

### Interactive job submission

Finally, to start a Matlab job on the compute cluster which gives you the Matlab GUI you can do the command

xmatlab

For the “xmatlab” command to work you need to have an X connection to the server.

### Serial job submission

The first examples cover submitting serial Matlab jobs. On Kure and KillDevil, the easiest way to submit a serial Matlab job is to use the **bmatlab** script:

bmatlab matlabjob.m

In the above example, “matlabjob.m” is the name of the Matlab script being submitted.

If you do not want to use the bmatlab script then you can use the following command instead and modify it as necessary to suit your job’s requirements:

bsub matlab -nodisplay -nosplash -singleCompThread -r matlabjob

-logfile matlabjob.out

The above command (which should all be on one line) submits the Matlab script “matlabjob.m” (yes, leave the .m off in the “-r” part of job submission command) and creates an output file called “matlabjob.out” in the current working directory.

### Parallel job submission

Research Computing licenses the Matlab Disbtributed Computing Server (MDCS) which can be used to run parallel Matlab jobs in a distributed fashion on its compute clusters. **To use the MDCS you need to use the matlab/2013a module**, which you can do by using the aforementioned module commands.

To get started, you will first need to run (just once) the command

configCluster

in Matlab- either interactively (at the Matlab shell) or in a Matlab script you submit- before using the MDCS.

Doing this will change your default cluster profile to the one we have created (“**killdevil_local_r2013a**“) for use with the MDCS. This profile gives you access to up to 64 workers (which is also the overall per user limit for MDCS usage). Then you can use the “matlabpool open” command to set the poolsize. For example, if I wanted to set a poolsize of 14 then my Matlab script would have

matlabpool open 14

By leaving out the name of a cluster profile in the above “matlabpool open” statement you are by default using the “**killdevil_local_r2013a**” profile we have set up.

You can create your own cluster profile using the Matlab GUI. If you decide to do this you should use the “**killdevil_local_r2013a**” profile as the template for your new cluster profile.

Another thing to keep in mind is that, given how the MDCS works, you should have your matlabpool open and close statements directly around the parfor loop, i.e.

[...Matlab code...]

matlabpool open 14

parfor loop

mablabpool close

[...rest of Matlab code...]

That is, open and close the matlabpools specifically around the portions of your code that are parallel.

To submit the Matlab job, you can use the usual Matlab job submission command:

bsub matlab -nodisplay -nosplash -singleCompThread

-r MyMDCScode -logfile MyMDCScode.out

Note that with the MDCS **it is not necessary to specify the number of job slots** for your job submission. This is because of how the MDCS works, which is that when Matlab executes your script and hits the “matlabpool open” statement it turns around and submits a **n-way** job for you where “**n**” is the size of your matlabpool (as indicated in your “matlabpool open” statement). So, when you submit the original script (i.e. the one containing the matlabpool calls) there is no need to ask for multiple job slots (because Matlab takes care of this detail for you); it is sufficient to ask for just one job slot (which is the default). Because of this behavior, it is important to make sure you open and close matlabpools around the parallel portion of your code (as discussed above).

An alternative to using the MDCS is to use Matlab’s **Parallel Computing Toolbox (PCT)** which runs in parallel locally (i.e. not distributed) and allows up to the use of 12 workers. To use the PCT you would use the **local profile **(already provided to you) in your matlabpool open statement:

matlabpool open local 8

In this example, I have created a pool size of 8 using the local profile.

To submit a Matlab job that specifically uses (for example) 8 workers and the PCT to run in parallel you would do

bsub -n 8 -R "span[hosts=1]" matlab -nodisplay -nosplash -singleCompThread

-r MyPCTcode -logfile MyPCTcode.out

Note that the parameter for the bsub “-n” option matches the pool size (**this** **is important**). In addition, note the use of the

-R “span[hosts=1]”

syntax. **This is also important** **and necessary** because the PCT runs in parallel locally (instead of distributed). Therefore all the requested job slots (in this case 8) need to be on the same host, which this syntax accomplishes.

For further questions regarding how to run Matlab parallel jobs on the Research Computing clusters, please contact Research Computing (research@unc.edu).

## Tutorials

- Introduction to Matlab is an online documentation written by the Research Computing group can help you start learning Matlab. It contains a number of examples.
- The Matlab Tutorial section of the Matlab online documentation provided by MathWorks is also useful for users new to this software.

## FAQs

## Useful links

## References

- D. Redfern and C. Campbell, “The Matlab 5 Handbook”, Springer, New York, 1998.
- D. Hanselman and B. Littlefield, “Mastering Matlab 6 – A Comprehensive Tutorial and Reference”, Prentice Hall, New Jersey, 2001.

## Additional help