gitea-pages/docs/merlin7/07-software-support/matlab.md

MATLAB

Best practices when running MATLAB

• Use matlab -batch for non-interactive production jobs. It is cleaner and better suited for batch execution than starting the full GUI.
• Prefer -nodesktop -nosplash for interactive terminal-based sessions on compute nodes in case of Slurm allocations (e.g. salloc or interactive Slurm sessions.
• If using MATLAB parallel features (parpool), make sure the number of workers matches the CPUs requested from Slurm.
• Write temporary files to appropriate scratch storage if large I/O is expected.
• For batch jobs, test first with a small input and short walltime before scaling up.

MATLAB via interactive sessions

MATLAB for interactive usage should be always started on a compute node through an interactive Slurm session, and never directly on a login node.

!!! danger "Do not run MATLAB on login nodes" Do not start MATLAB directly on Merlin7 login nodes.

Login nodes are not meant for CPU-intensive, memory-intensive, or long-running MATLAB workloads.
Running MATLAB there **can slow down the system for all users** and may lead to your session or 
process **being terminated by administrators**.

For any real computation, start an interactive or batch job with Slurm and run MATLAB inside that allocation.
Start an [interactive session](../04-slurm-general-documentation/interactive-sessions.md) first, then run 
MATLAB on the allocated compute node.

There are two common ways to use MATLAB interactively via interactive sessions:

• Option 1: with X11-forwarding, for the full graphical MATLAB desktop
• Option 2: without X11-forwarding, for terminal-based MATLAB sessions or batch-like interactive testing

Choosing between X11 and non-X11 mode:

Use case	Recommended command
MATLAB graphical desktop	interactive --x11
Terminal MATLAB session	interactive then matlab -nodisplay
Running scripts interactively	interactive then matlab -nodisplay -r "script; exit"
Long-lived detachable session	interactive

!!! warning "Do not use X11 mode for detachable work" X11 mode is intended for live graphical sessions only.

If you need to disconnect and reconnect later, use the default non-X11 mode.

Option 1: MATLAB with X11 forwarding

Use this mode if you need the MATLAB graphical desktop.

From a Merlin7 login node, start an X11 interactive session:

interactive --x11

Then load and start MATLAB as usual, for example:

module load matlab
matlab

!!! warning "X11 sessions are not detachable" interactive --x11 starts a foreground salloc --x11 session.

If you exit the shell or lose the connection, the allocation ends and cannot be re-attached.

!!! tip "Use X11 only when you need the GUI" For the MATLAB desktop, figures shown through the GUI, or graphical debugging, use:

```bash
interactive --x11
```

For terminal-only work, use the non-X11 mode described below.

To request more resources, pass Slurm options after --:

interactive --x11 -- --cpus-per-task=8 --mem=16G

!!! tip "Request resources with --cpus-per-task" For most interactive MATLAB work, request CPUs with --cpus-per-task.

Avoid `--ntasks` unless you really need multiple Slurm tasks, for example for MPI-style workflows.

Option 2: MATLAB without X11

Use this mode for terminal-based MATLAB work, scripts, testing, or workflows that do not need the graphical desktop.

Start a normal detachable interactive session:

interactive

Then load MATLAB and start it without the desktop:

module load matlab
matlab -nodisplay

You can also run a MATLAB command and return to the shell:

matlab -nodisplay -r "my_script; exit"

!!! note "Non-X11 sessions are detachable" The default interactive mode creates a persistent allocation.

If you leave the shell with `exit`, the allocation keeps running until you cancel it.

!!! warning "Cancel detached allocations when finished" In non-X11 mode, exit does not stop the Slurm allocation.

When you are done, cancel it explicitly:

```bash
interactive --cancel
```

To request more resources:

interactive -- --cpus-per-task=8 --mem=16G

Troubleshooting

MATLAB GUI does not open

Make sure you started the session with X11 support:

interactive --x11

Also check that your local SSH client supports X11 forwarding and that an X server is available on your local machine.

No active allocation found

Start a new interactive allocation:

interactive

or, for the graphical desktop:

interactive --x11

I lost my connection

If this was an X11 session, the allocation may have ended.

If this was a normal non-X11 session, reconnect from a Merlin7 login node with:

interactive

Check active sessions with:

interactive --status

MATLAB batch jobs with Slurm

Simple batch job example

For production runs, use sbatch. For example:

#!/bin/bash
#SBATCH --job-name=matlab_test
#SBATCH --output=matlab_test-%j.out
#SBATCH --error=matlab_test-%j.err
#SBATCH --time=02:00:00
#SBATCH --cpus-per-task=4
#SBATCH --mem=8G
#SBATCH --partition=hourly

module purge
module load matlab

matlab -batch "my_script"

Submit it with:

sbatch matlab_job.sh

If your code is a function, you can also do:

matlab -batch "my_function(arg1, arg2)"

MATLAB parallel workers batch job example

If your MATLAB code uses the Parallel Computing Toolbox, request matching CPU resources. For example:

#!/bin/bash
#SBATCH --job-name=matlab_par
#SBATCH --output=matlab_par-%j.out
#SBATCH --time=02:00:00
#SBATCH --cpus-per-task=8
#SBATCH --mem=16G
#SBATCH --partition=hourly

module purge
module load matlab

matlab -batch "parpool('local', 8); my_parallel_script"

In general, the number of MATLAB workers should not exceed the number of CPUs allocated by Slurm.

MATLAB via Open OnDemand

{% include-markdown "merlin7/07-software-support/includes/open-ondemand-alternative.md" %}