From 388e6fbc517924c2a17d997883d91d746331bc9d Mon Sep 17 00:00:00 2001
From: caubet_m <marc.caubet@psi.ch>
Date: Mon, 30 Mar 2026 08:02:22 +0200
Subject: [PATCH] Add matlab

---
 docs/merlin7/05-Software-Support/matlab.md | 104 +++++++++++++++++++++
 mkdocs.yml                                 |   1 +
 2 files changed, 105 insertions(+)
 create mode 100644 docs/merlin7/05-Software-Support/matlab.md

diff --git a/docs/merlin7/05-Software-Support/matlab.md b/docs/merlin7/05-Software-Support/matlab.md
new file mode 100644
index 0000000..bcce8a0
--- /dev/null
+++ b/docs/merlin7/05-Software-Support/matlab.md
@@ -0,0 +1,104 @@
+## Best practices
+
+* **Always run MATLAB on compute nodes via Slurm**, never on login nodes.
+* Request only the resources you need (`--cpus-per-task`, `--mem`, `--time`).
+* 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.
+* 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.
+* Test first with a small input and short walltime before scaling up.
+
+### Why not on the login nodes?
+
+Login nodes are shared service nodes intended for light tasks such as:
+
+* editing files
+* compiling small programs
+* preparing job scripts
+* submitting jobs
+* checking job status
+
+!!! warning
+    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.
+
+## Running MATLAB
+
+### Environment modules
+
+MATLAB installations are available on PModules:
+
+```bash
+module search matlab -a
+module load matlab
+```
+
+### Interactive use on a compute node
+
+For short tests or interactive debugging or usage, request resources with `salloc` and then start MATLAB on the allocated compute node:
+
+```bash
+salloc --partition=interactive --reservation=interactive --time=01:00:00 --cpus-per-task=4 --mem=8G
+module load matlab
+matlab -nodesktop -nosplash
+```
+
+This is appropriate for interactive work, but still uses compute-node resources rather than the login node.
+
+### Batch use on compute nodes
+
+#### 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:
+
+```
+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.
diff --git a/mkdocs.yml b/mkdocs.yml
index fb53e00..864dee0 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -129,6 +129,7 @@ nav:
       - merlin7/05-Software-Support/gromacs.md
       - merlin7/05-Software-Support/ippl.md
       - merlin7/05-Software-Support/lammps.md
+      - merlin7/05-Software-Support/matlab.md
       - merlin7/05-Software-Support/opal-x.md
       - merlin7/05-Software-Support/quantum-espresso.md
       - merlin7/05-Software-Support/spack.md