From 6ca3aec4e264ad6d498065c0a5b85201abca2cc8 Mon Sep 17 00:00:00 2001 From: Cal <35017184+CallumWalley@users.noreply.github.com> Date: Mon, 27 Nov 2023 07:59:42 +1300 Subject: [PATCH] Update MATLAB.md (#28) Signed-off-by: Cal <35017184+CallumWalley@users.noreply.github.com> --- .../Supported_Applications/MATLAB.md | 173 +++++++++--------- 1 file changed, 89 insertions(+), 84 deletions(-) diff --git a/docs/Scientific_Computing/Supported_Applications/MATLAB.md b/docs/Scientific_Computing/Supported_Applications/MATLAB.md index 4221e7200..d81ad060d 100644 --- a/docs/Scientific_Computing/Supported_Applications/MATLAB.md +++ b/docs/Scientific_Computing/Supported_Applications/MATLAB.md @@ -3,9 +3,8 @@ created_at: '2015-10-14T22:58:53Z' hidden: false position: 35 tags: -- mahuika - engineering -- general +- ml title: MATLAB vote_count: 1 vote_sum: 1 @@ -13,72 +12,61 @@ zendesk_article_id: 212639047 zendesk_section_id: 360000040076 --- +!!! warning "No Licence?" + If you want to run MATLAB code on the cluster, but are not a member of an institution without access to floating licences, MATLAB code can still be run on the cluster using MCR. - -[//]: <> (REMOVE ME IF PAGE VALIDATED) -[//]: <> (vvvvvvvvvvvvvvvvvvvv) -!!! warning - This page has been automatically migrated and may contain formatting errors. -[//]: <> (^^^^^^^^^^^^^^^^^^^^) -[//]: <> (REMOVE ME IF PAGE VALIDATED) - - -!!! prerequisite No Licence? - If you want to run MATLAB code on the cluster, but are not a member of - an institution without access to floating licences, MATLAB code can - still be run on the cluster using MCR. - -## Example script +## Example scripts !!! prerequisite Note - When developing MATLAB code on your local machine, take measures to - ensure it will be platform independent.  Use relative paths when - possible and not avoid using '\\s see - [here](https://www.mathworks.com/help/matlab/ref/fullfile.html). - -### Script Example - -``` bash -#!/bin/bash -e -#SBATCH --job-name MATLAB_job # Name to appear in squeue -#SBATCH --time 01:00:00 # Max walltime -#SBATCH --mem 512MB # Max memory - -module load MATLAB/2021b -# Run the MATLAB script MATLAB_job.m -matlab -nodisplay < MATLAB_job.m -``` - -### Function Example + When developing MATLAB code on your local machine, take measures to ensure it will be platform independent.  Use relative paths when possible and not avoid using '\\s see [here](https://www.mathworks.com/help/matlab/ref/fullfile.html). + +=== "Script" + + ```sl + #!/bin/bash -e + #SBATCH --job-name MATLAB_job # Name to appear in squeue + #SBATCH --time 01:00:00 # Max walltime + #SBATCH --mem 512MB # Max memory + + module load MATLAB/{{applications.MATLAB.machines.mahuika.versions | last}} + + # Run the MATLAB script MATLAB_job.m + matlab -nodisplay < MATLAB_job.m + ``` + +=== "Function" ``` sl -#!/bin/bash -e -#SBATCH --job-name MATLAB_job # Name to appear in squeue -#SBATCH --time 06:00:00 # Max walltime -#SBATCH --mem 2048MB # Max memory -#SBATCH --cpus-per-task 4 # 2 physical cores. -#SBATCH --output %x.log # Location of output log - -module load MATLAB/2021b - -#Job run -matlab -batch "addpath(genpath('../parentDirectory'));myFunction(5,20)" -# For versions older than 2019a, use '-nodisplay -r' instead of '-batch' -``` -!!! prerequisite Command Line + #!/bin/bash -e + + #SBATCH --job-name MATLAB_job # Name to appear in squeue + #SBATCH --time 06:00:00 # Max walltime + #SBATCH --mem 2048MB # Max memory + #SBATCH --cpus-per-task 4 # 2 physical cores. + #SBATCH --output %x.log # Location of output log + + module load MATLAB/{{applications.MATLAB.machines.mahuika.versions | last}} + + #Job run + matlab -batch "addpath(genpath('.'));myFunction(5,20)" + # For versions older than 2019a, use '-nodisplay -r' instead of '-batch' + ``` + +!!! tip "Command Line" When using matlab on command line, all flag options use a single '`-`' e.g. `-nodisplay`, this differs from the GNU convention of using `--` for command line options of more than one character. -!!! prerequisite Bash in MATLAB + + +!!! tip Using the prefix `!` will allow you to run bash commands from within MATLAB. e.g. `!squeue -u $USER` will print your currently queued slurm jobs. ## Parallelism -MATLAB does not support MPI therefore #SBATCH --ntasks should always be +MATLAB does not support MPI therefore `#SBATCH --ntasks` should always be 1, but if given the necessary resources some MATLAB functions can make -use of multiple threads (--cpus-per-task) or GPUs (--gpus-per-node). +use of multiple threads (`--cpus-per-task`) or GPUs (`--gpus-per-node`). ### Implicit parallelism. @@ -89,33 +77,43 @@ utilise more than a 4-8 CPUs this way. ### Explicit parallelism. +!!! tip + If your code is explicitly parallel at a high level it is preferable to use + [SLURM job + arrays](https://support.nesi.org.nz/hc/en-gb/articles/360000690275-Parallel-Execution#t_array) + as there is less computational overhead and the multiple smaller jobs + will queue faster and therefore improve your throughput. + Explicit parallelism is when you write your code specifically to make use of multiple CPU's. This can be done using MATLABs *parpool*-based language constructs, MATLAB assigns each thread a 'worker' that can be assigned sections of code. MATLAB will make temporary files under your home directory (in -~/.matlab/local\_cluster\_jobs) for communication with worker processes. +`~/.matlab/local//jobs`) for communication with worker processes. To prevent simultaneous parallel MATLAB jobs from interfering with each other you should tell them to each use their own job-specific local directories: -``` sl +```matlab pc = parcluster('local') pc.JobStorageLocation = getenv('TMPDIR') parpool(pc, str2num(getenv('SLURM_CPUS_PER_TASK'))) ``` -!!! prerequisite Note + +!!! tip Parpool will throw a warning when started due to a difference in how time zone is specified. To fix this, add the following line to your SLURM script: `export TZ="Pacific/Auckland'`  The main ways to make use of parpool are; -**parfor: **Executes each iteration of a loop on a different worker. +#### parfor + +Executes each iteration of a loop on a different worker. e.g. -``` sl +```matlab parfor i=1:100 %Your operation here. @@ -131,12 +129,12 @@ static (not changing during execution of loop). More info [here](https://au.mathworks.com/help/parallel-computing/parfor.html). -**parfeval:** +#### parfeval `parfeval` is used to assign a particular function to a thread, allowing it to be run asynchronously. e.g. -``` sl +```matlab my_coroutine=parfeval(@my_async_function,2,in1,in2); % Do something that doesn't require outputs from 'my_async_function' @@ -154,23 +152,17 @@ end More info [here](https://au.mathworks.com/help/parallel-computing/parfeval.html). -!!! prerequisite Note + + +!!! tip When killed (cancelled, timeout, etc), job steps utilising parpool may show state `OUT_OF_MEMORY`, this is a quirk of how the steps are ended and not necessarily cause to raise total memory requested. ------------------------------------------------------------------------- - Determining which of [these](https://au.mathworks.com/help/parallel-computing/troubleshoot-variables-in-parfor-loops.html) categories your variables fall under is a good place to start when attempting to parallelise your code. -!!! prerequisite Tip - If your code is parallel at a high level it is preferable to use - [SLURM job - arrays](https://support.nesi.org.nz/hc/en-gb/articles/360000690275-Parallel-Execution#t_array) - as there is less computational overhead and the multiple smaller jobs - will queue faster. ## Using GPUs @@ -191,13 +183,15 @@ If you want to know more about how to access the different type of available GPUs on NeSI, check the [GPU use on NeSI](https://support.nesi.org.nz/hc/en-gb/articles/360001471955) support page. -!!! prerequisite Support for A100 GPUs + +!!! tip "Support for A100 GPUs" To use MATLAB with a A100 or a A100-1g.5gb GPU, you need to use a version of MATLAB supporting the *Ampere* architecture (see [GPU Support by Release](https://nl.mathworks.com/help/releases/R2021b/parallel-computing/gpu-support-by-release.html)). We recommend that you use R2021a or a more recent version. -!!! prerequisite Note on GPU cost + +!!! tip "GPU cost" A GPU device-hour costs more than a core-hour, depending on the type of GPU. You can find a comparison table in our [What is an allocation?](https://support.nesi.org.nz/hc/en-gb/articles/360001385735) @@ -240,8 +234,8 @@ library.](https://github.com/kyamagu/mexopencv) Some of the internal MATLAB libraries clash with those used by OpenCV, to avoid problems cause by this -- Use a version of OpenCV built using GCC (as opposed to gimkl). -- Compile using the -DWITH\_OPENCL=OFF flag. +- Use a version of OpenCV built using GCC (as opposed to gimkl). +- Compile using the -DWITH\_OPENCL=OFF flag. Please contact support if you have any issues. @@ -264,17 +258,17 @@ more info about compiling software on NeSI   This involves the following steps (using C++ as an example): -1. Focus on a loop to extend, preferably a nested set of loops. -2. Identify the input and output variables of the section of code to +1. Focus on a loop to extend, preferably a nested set of loops. +2. Identify the input and output variables of the section of code to extend. -3. Write C++ code. The name of the C++ file should match the name of +3. Write C++ code. The name of the C++ file should match the name of the function to call from MATLAB, e.g. `myFunction.cpp` for a function named `myFunction`. -4. Compile the extension using the MATLAB command `mex myFunction.cpp` +4. Compile the extension using the MATLAB command `mex myFunction.cpp` At the minimum, the C++ extension should contain: -``` sl +```matlab #include #include @@ -294,14 +288,14 @@ the type of argument, whether it is a number, a matrix or an object, its type is `mxArray`. Often you will need to cast the argument into a corresponding C++ type, e.g. -``` sl +```matlab // cast as a double, note the asterisk in front of mxGetPr double x = (double) *mxGetPr(prhs[0]); ``` or -``` sl +```matlab // cast as an array of doubles double* arr = (double*) mxGetPr(prhs[0]); ``` @@ -309,7 +303,7 @@ double* arr = (double*) mxGetPr(prhs[0]); Use `mxCreateDoubleMatrix` and `mxCreateDoubleScalar` to create a matrix and a number, respectively. For example: -``` sl +```matlab // function returns [plhs[0], plhs[1]] plhs[0] = mxCreateDoubleMatrix(3, 2, mxREAL); // 3 by 2 matrix plhs[1] = mxCreateDoubleScalar(2); // number @@ -358,11 +352,22 @@ it is Windows specific. | Linker | `LDFLAGS` | For example, adding OpenMP flags for a fortran compile: -!!! prerequisite Compiler Version Errors + + +!!! warning "Compiler Version" Using an 'unsupported' compiler with versions of MATLAB 2020b onward will result in an Error (previously was a 'Warning'). ## Known Bugs When using versions of MATLAB more recent than 2021a you may notice the -following warning. \ No newline at end of file +following warning. + +```matlab +ldd +``` +This is due to our operating system being too old. + +With the exception of a few commands that directly make requests of the OS, your code should run fine. + +If you believe this bug is causing problems, running on our newer hardware will fix it.