Matlab Parallel Server
################################

Introduction
============

MATLAB Parallel Server allows you to run parallel jobs efficiently on Rockfish by using a cluster profile that integrates with SLURM. This approach avoids requesting a separate MATLAB license for each ``parpool`` or ``parfor`` call and improves resource utilization.

Create a Cluster Profile
========================

You only need to create the cluster profile once.

.. note::
   You can create the cluster profile by launching MATLAB either through **Open OnDemand** or from the **command line**. This tutorial uses the command-line method (without GUI).

Option: Create Profile via Command Line
---------------------------------------

1. Start an interactive session on a compute node:

   .. code-block:: bash

      interact -p shared -n 4 -t 01:00:00

2. Load the MATLAB module:

   .. code-block:: bash

      module load matlab/R2024a

3. Launch MATLAB in terminal mode:

   .. code-block:: bash

      matlab -nodisplay -nosplash

4. Inside MATLAB, create the cluster profile:

   .. code-block:: matlab

      configCluster;

   This creates a cluster profile named ``rockfish``.

5. Exit MATLAB:

   .. code-block:: matlab

      exit

6. Exit the interactive session:

   .. code-block:: bash

      exit

Write Your MATLAB Parallel Script
=================================

To run a parallel job, set up the cluster configuration and define the desired resources in your MATLAB script.

Example: ``test_matlab_parallel.m``

.. code-block:: matlab

   % test_matlab_parallel.m

   % Load the cluster profile
   rf = parcluster('rockfish');

   % Set SLURM resource parameters
   rf.AdditionalProperties.Partition = 'parallel';  % Specify partition
   rf.AdditionalProperties.WallTime = '02:00:00';   % Wall time must match SLURM script
   rf.AdditionalProperties.AdditionalSubmitArgs = '--nodes=2 --ntasks-per-node=32 --cpus-per-task=1';

   % Display properties (optional)
   disp(rf.AdditionalProperties);

   % Start parallel pool
   disp('Starting a parallel pool...');
   parpool(rf, 64);  % 2 nodes × 32 tasks

   % Run a sample parallel computation
   disp('Running parallel computation...');
   results = zeros(1, 64);
   parfor i = 1:64
       results(i) = i^2;
   end
   disp('Results:');
   disp(results);

   % Shut down the parallel pool
   delete(gcp('nocreate'));

Submit Your Job to SLURM
=========================

While you can run MATLAB interactively, the recommended approach is to submit your job using a SLURM script.

.. important::
   The ``--time`` specified in your SLURM script **must match** the ``WallTime`` defined in your MATLAB cluster profile. Other SLURM parameters in the script (e.g., ``--nodes``, ``--ntasks``) are not relevant because resource allocation is handled by MATLAB itself.

Example: ``run_matlab_test.sh``

.. code-block:: bash

   #!/bin/bash
   #SBATCH --job-name=matlab_test
   #SBATCH --nodes=1
   #SBATCH --time=02:00:00      # Must match WallTime in MATLAB script
   #SBATCH --partition=shared
   #SBATCH --output=matlab_test.out
   #SBATCH --error=matlab_test.err

   module load matlab/R2024a

   # Run MATLAB in batch mode
   matlab -nodisplay -nosplash -r "test_matlab_parallel; exit"

Submit the SLURM Job:

.. code-block:: bash

   sbatch run_matlab_test.sh

Final Notes
===========

- Only set up the cluster profile once per user.
- Always ensure ``WallTime`` in the MATLAB script matches the SLURM ``--time`` value.
- MATLAB handles resource allocation via the SLURM backend — no need to manually manage ``--nodes`` or ``--ntasks`` in the SLURM script.
- You can view SLURM output and MATLAB results in the ``.out`` and ``.err`` files generated by SLURM.