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.

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 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`

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:

Bash

interactive --x11

Then load and start MATLAB as usual, for example:

Bash

module load matlab
matlab

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.

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 --:

Bash

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

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:

Bash

interactive

Then load MATLAB and start it without the desktop:

Bash

module load matlab
matlab -nodisplay

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

Bash

matlab -nodisplay -r "my_script; exit"

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.

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:

Bash

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

Troubleshooting¶

MATLAB GUI does not open¶

Make sure you started the session with X11 support:

Bash

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:

Bash

interactive

or, for the graphical desktop:

Bash

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:

Bash

interactive

Check active sessions with:

Bash

interactive --status

MATLAB batch jobs with Slurm¶

Simple batch job example¶

For production runs, use sbatch. For example:

Bash

#!/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:

Bash

sbatch matlab_job.sh

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

Bash

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:

Bash

#!/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¶

As an alternative to creating an interactive session with or without X11 forwarding, you can also use Open OnDemand on Merlin7.

Open OnDemand provides web-based access to HPC resources and can be used to start graphical applications such as VS Code or MATLAB directly from a browser. Sometimes, this can be more convenient than setting up local SSH configuration, X11 forwarding, or VS Code Remote SSH manually.

Tip

If you mainly need a graphical VS Code or MATLAB session, Open OnDemand on Merlin7 is often the easiest option.

Warning

The same login-node rule still applies: do not run heavy interactive applications directly on login nodes.

Use either an interactive Slurm allocation, as described in this page, or the Open OnDemand web interface.