MATLAB ========== MathWorks MATLAB MATLAB is a high-level programming language and computing environment for engineers and scientists. It integrating computation, visualization, and programming in an single user interface. Learn more in the `official MATLAB documentation `__. Launching MATLAB ---------------- **Using Magellano OnDemand:** from the ``Interactive Apps`` menu, click on ``MATLAB``. Fill the form with the required job options and click ``Launch``. When your job is up and running, click on the ``Launch JuyterLab`` in the ``My Interactive Sessions`` page. You will be redirected to a new browser tab. From there you can use the MATLAB GUI in a VNC session. **Using Environment Modules:** load the MATLAB module and run MATLAB as follows:: module load matlab/${MATLAB_VERSION} matlab -desktop Licensing --------- When you start MATLAB for the first time, your will be asked to sign in. You can use the national **INFN academic license** for MATLAB. Follow these steps: * Under **Email**, insert your infn email and click **Next**. * A window will appear showing the INFN AAI login page. Login using your INFN credentials. If the login was successful, you will have access to the MATLAB graphic interface. Alternatively, you can use your personal MATLAB account or another academic license. Parallel Computing Toolbox -------------------------- The installed MATLAB software comes with the MATLAB Parallel Computing Toolbox. The **Magellano Slurm plugin** allows you to submit batch and parallel jobs from your MATLAB workspace to the magellano HPC resources. To start, set up the **cluster profile** by issuing the ``configCluster`` command in the MATLAB command window:: >> configCluster; Username on MAGELLANO (e.g. jdoe): neo Complete. Default cluster profile set to "Magellano R2025b". When prompted, enter your INFN AAI username. This command creates a default cluster profile named ``Magellano R2025b``. The version string may change depending on the MATLAB version you are using. .. Note:: Alternatively, you can run parallel MATLAB functions on the local machine using the ``local`` cluster profile. Configuring Jobs ^^^^^^^^^^^^^^^^ To start using MATLAB Parallel, load the default profile ``Magellano R2025b`` with the following command:: >> c = parcluster; Prior to submitting the job, various parameters can be assigned, such as partition, account and walltime. You can set parameters as in the example below:: >> c.AdditionalProperties.Partition = "levante"; Unset a value when no longer needed:: >> c.AdditionalProperties.Partition = ""; Save changes after modifying ``AdditionalProperties`` for the above changes to persist between MATLAB sessions:: >> c.saveProfile; The following is a partial list of parameters. Call ``c.AdditionalProperties`` for the complete list. .. list-table:: :header-rows: 1 :widths: 25 75 * - Parameter - Description * - ``AccountName`` - Specify the Slurm account, default is ``default`` * - ``Constraint`` - Specify job constraints based on node features * - ``.GPUsPerNode`` - Specify the number of GPUs, default is ``0`` * - ``GPUCard`` - Specify the GPU type * - ``MemPerCPU`` - Specify the memory per CPU, default is ``4gb`` * - ``RequireExclusiveNode`` - Set node exclusivity, default is ``true`` * - ``Partition`` - Specify the Slurm account * - ``ProcsPerNode`` - Specify the cores per node * - ``RequireExclusiveNode`` - Set node exclusivity, default is ``true`` * - ``WallTime`` - Specify the walltime Interactive Jobs ^^^^^^^^^^^^^^^^ To run an interactive pool job on the cluster, use the ``parpool`` function:: >> pool = c.parpool(64); The pool can now run across multiple nodes on the cluster:: >> % Run a parfor over 1000 iterations >> parfor idx = 1:1000 a(idx) = rand; end Delete the pool when it's no longer needed:: >> pool.delete Independent Batch Jobs ^^^^^^^^^^^^^^^^^^^^^^ Use the ``batch`` command to submit asynchronous jobs to the cluster. The batch command will return a job object which is used to access the output of the submitted job. Submit job to query where MATLAB is running on the cluster:: >> job = c.batch(@pwd, 1, {}, "CurrentFolder",'.'); Query job for state:: >> job.State If state is finished, fetch the results:: >> job.fetchOutputs{1} The ``fetchOutputs`` function is used to retrieve function output arguments; if calling batch with a script, use ``load`` instead. Data that has been written to files on the cluster needs be retrieved directly from the file system. Delete the job after results are no longer needed:: >> job.delete To retrieve a list of running or completed jobs, call ``parcluster`` to return the ``cluster`` object. The ``cluster`` object stores an array of jobs that are queued to run, are running, have run, or have failed. Parallel Batch Jobs ^^^^^^^^^^^^^^^^^^^ The ``batch`` function can also submit parallel workflows. Let’s use the following example for a parallel job, which is saved as ``parallel_example.m``:: function [sim_t, A] = parallel_example(iter) if nargin==0 iter = 8; end disp("Start sim") t0 = tic; parfor idx = 1:iter A(idx) = idx; pause(2) idx end sim_t = toc(t0); disp("Sim completed") save RESULTS A end This time, when using the ``batch`` command, also specify a MATLAB Pool argument:: >> c = parcluster; >> % Submit a batch pool job using 4 workers for 16 simulations >> job = c.batch(@parallel_example, 1, {16}, "Pool",4, "CurrentFolder",'.'); >> job.State >> job.fetchOutputs{1} ans = 8.8872 .. Note:: These jobs will always request N+1 CPU cores, since one worker is required to manage the batch job and pool of workers. Run the same simulation but increase the pool size. This time, to retrieve the results later, keep track of the job ID:: >> c = parcluster; >> % Submit a batch pool job using 8 workers for 16 simulations >> job = c.batch(@parallel_example, 1, {16}, "Pool",8, "CurrentFolder",'.'); >> id = job.ID id = 4 >> clear job .. Note:: For some applications, there will be a diminishing return when allocating too many workers, as the overhead may exceed computation time. With a handle to the cluster, the ``findJob`` method searches for the job with the specified job ID:: >> c = parcluster; >> job = c.findJob("ID", 4); >> job.State ans = finished >> job.fetchOutputs{1}; ans = 4.7270 Alternatively, to retrieve job results via a graphical user interface, use the Job Monitor (**Parallel** > **Monitor Jobs**). Helper Functions ^^^^^^^^^^^^^^^^ .. list-table:: :header-rows: 1 :widths: 25 75 * - Function - Description * - ``clusterFeature`` - List of cluster features/constraints * - ``clusterGpuCards`` - List of cluster GPU cards * - ``clusterPartitionNames`` - List of cluster partition names * - ``fixConnection`` - Reestablish cluster connection * - ``willRun`` - Explain why job is queued Debugging ^^^^^^^^^ If a serial job produces an error, call the ``getDebugLog`` method to view the error log file. When submitting an independent job, specify the task:: >> c.getDebugLog(job.Tasks) For pool jobs, only specify the job object:: >> c.getDebugLog(job) When troubleshooting a job, the cluster admin may request the scheduler ID of the job. This can be derived by calling ``getTaskSchedulerIDs``:: >> job.getTaskSchedulerIDs() ans = 25539 Learn more ^^^^^^^^^^ To learn more about the MATLAB Parallel Computing Toolbox, check out these resources: * `Parallel Computing Overview `__ * `Parallel Computing Documentation `__ * `Parallel Computing Coding Examples `__ * `Parallel Computing Tutorials `__ * `Parallel Computing Videos `__ * `Parallel Computing Webinars `__