Update MATLAB.md (#28)

Signed-off-by: Cal <[email protected]>

docs/Scientific_Computing/Supported_Applications/MATLAB.md

@@ -3,82 +3,70 @@ created_at: '2015-10-14T22:58:53Z'
 hidden: false
 position: 35
 tags:
-- mahuika
 - engineering
-- general
+- ml
 title: MATLAB
 vote_count: 1
 vote_sum: 1
 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)
-
-<!-- The above lines, specifying the category, section and title, must be
-present and always comprising the first three lines of the article. -->
-!!! 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/<cluster>/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 <mex.h>
 #include <matrix.h>
 
@@ -294,22 +288,22 @@ 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]);
 ```
 
 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.
+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.