Use MATLAB on Quartz at IU

On this page:

Overview
Set up your user environment
Submit a MATLAB batch job
Run MATLAB interactively
Use the MATLAB GUI
Get help

Overview

On Quartz at Indiana University, you can use MATLAB interactively from the command line or in batch mode using a Slurm submission script. If your interactive session will require more than 20 minutes of processor time, you must run it as an interactive job on one of Quartz's compute nodes. You also can use the MATLAB graphical user interface (GUI) for interactive sessions by using SSH with X forwarding enabled.

The Indiana University research supercomputers use the Slurm workload manager for resource management and job scheduling; see Use Slurm to submit and manage jobs on IU's research computing systems.

In Slurm, compute resources are grouped into logical sets called partitions, which are essentially job queues. To view details about available partitions and nodes, use the sinfo command; for more about using sinfo, see the View partition and node information section of Use Slurm to submit and manage jobs on IU's research computing systems.

Set up your user environment

On the research supercomputers at Indiana University, the Modules environment management system provides a convenient method for dynamically customizing your software environment.

To use MATLAB on Quartz, you first must add the matlab module to your user environment. To make sure the matlab module is added every time you log in, you can add the following line to your ~/.modules file:

module load matlab

For more, see Use modules to manage your software environment on IU research supercomputers.

Submit a MATLAB batch job

To submit a MATLAB batch job on Quartz:

Create a MATLAB script containing the commands MATLAB should run, and then save it with a .m extension (for example, matlab_script.m).
Create a Slurm submission script (for example, my_matlab_job.script) to specify the application you want to run and the resources required to run it.
For example, a Slurm submission script for running a batch MATLAB job on Quartz may look similar to the following:
```
#!/bin/bash 

#SBATCH -J matlab_job
#SBATCH -p general
#SBATCH -o filename_%j.txt
#SBATCH -e filename_%j.err
#SBATCH --mail-type=ALL
#SBATCH --mail-user=username@iu.edu
#SBATCH --nodes=1
#SBATCH --ntasks-per-node=1
#SBATCH --cpus-per-task=12
#SBATCH --time=01:00:00
#SBATCH --mem=20G
#SBATCH -A slurm-account-name

cd /path/to/your/matlab_script.m
matlab < matlab_script.m
```
In the above example:
- The first line indicates that the script should be read using the Bash command interpreter.
- The next lines are #SBATCH directives used to pass options to the sbatch command:
  - -J matlab_job names the job matlab_job.
  - -p general specifies that the job should run in the general partition.
  - -o filename_%j.txt and -e filename_%j.err instructs Slurm to connect the job's standard output and standard error, respectively, to the file names specified, where %j is automatically replaced by the job ID.
  - --mail-type=<type> directs Slurm to send job-related email when an event of the specified type(s) occurs; valid type values include all, begin, end, and fail.
  - --mail-user=username@iu.edu indicates the email address to which Slurm will send job-related mail.
  - --nodes=1 requests that a minimum of one node be allocated to this job.
  - --ntasks-per-node=1 specifies that one task should be launched per node.
  - --cpus-per-task=12 allots 12 processors to the task.
  - --time=01:00:00 allots a maximum of one hour for the job to run.
  - --mem=20G requests 20 GB of RAM.
  - -A slurm-account-name indicates the Slurm Account Name to which resources used by this job should be charged.
    Users belonging to projects approved through RT Projects can find their allocation's Slurm Account Name on the "Home" page in RT Projects; look under "Submitting Slurm Jobs with your Project's Account"; alternatively, on the "Home" page, under "Allocations", select an allocation and look in the table under "Allocation Attributes".
    
    For more about RT Projects, see Use RT Projects to request and manage access to specialized Research Technologies resources.
- The last two lines are the two executable lines that the job will run. In this case, the cd command is used to change the working directory to the directory where matlab_script.m is located before making MATLAB run the commands in the matlab_script.m script.
To submit your job script (my_matlab_job.script) to Slurm; from the command prompt, enter:
```
sbatch my_matlab_job.script
```

Run MATLAB interactively

Note:

If your interactive session will require less than 20 minutes of processor time, you can load the matlab module and launch the application from the Quartz command line.

Interactive sessions requiring more than 20 minutes of processor time must be submitted as interactive jobs to compute nodes on Quartz. This method of interactive execution is strongly recommended, as the login nodes on either system are not intended for computational work.

To run an interactive MATLAB job on Quartz:

Make sure your user environment is configured properly; see Setting up your user environment above.
To request resources for an interactive job, use the srun command with the --pty option; for example:
```
srun -p general -A slurm-account-name --pty bash
```
The above example requests a single core on a single processor.

Users belonging to projects approved through RT Projects can find their allocation's Slurm Account Name on the "Home" page in RT Projects; look under "Submitting Slurm Jobs with your Project's Account"; alternatively, on the "Home" page, under "Allocations", select an allocation and look in the table under "Allocation Attributes".

For more about RT Projects, see Use RT Projects to request and manage access to specialized Research Technologies resources.
When the resources needed to run your job are available, your job will start, and then you will be placed on a compute node.
From the compute node command prompt, enter matlab to launch MATLAB.

Use the MATLAB GUI

You can use the MATLAB graphical user interface (GUI) in interactive sessions on Quartz's login and compute nodes. To do so, you must enable X forwarding in your SSH client's connection settings. Additionally, you must have an X server program (such as Xming for Windows or XQuartz for macOS) running on your local computer before connecting via SSH with X forwarding enabled.

Once you've established an SSH connection to Quartz with X forwarding enabled:

To use the MATLAB GUI for an interactive session on a login node, load the matlab module, and then launch MATLAB from the command line.
To use the MATLAB GUI for an interactive job on a compute node, use the srun command with the --pty and --x11 options added; for example:
```
srun -p general -A slurm-account-name --x11 -N 1 --ntasks-per-node=1 --cpus-per-task=12 --time=01:00:00 --pty bash
```
Users belonging to projects approved through RT Projects can find their allocation's Slurm Account Name on the "Home" page in RT Projects; look under "Submitting Slurm Jobs with your Project's Account"; alternatively, on the "Home" page, under "Allocations", select an allocation and look in the table under "Allocation Attributes".

For more about RT Projects, see Use RT Projects to request and manage access to specialized Research Technologies resources.

For instructions on setting up and using X forwarding, see Use X forwarding on a personal computer to securely run graphical applications installed on IU's research supercomputers.

Get help

If you need help or have a question about using MATLAB on IU's research supercomputers, contact the UITS Research Applications and Deep Learning team.