Add matlab

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.

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