MATLAB

From ScientificComputing
Jump to: navigation, search

Category

Mathematics, Numerics

Description

MATLAB (matrix laboratory) is a multi-paradigm numerical computing environment and fourth-generation programming language. A proprietary programming language developed by MathWorks, MATLAB allows matrix manipulations, plotting of functions and data, implementation of algorithms, creation of user interfaces, and interfacing with programs written in other languages, including C, C++, Java, Fortran and Python.

Available versions (Euler, old software stack)

Legacy versions Supported versions New versions
8.2, 8.5, R2017b 8.4, 8.6, 8.7, 9.1, R2018a, R2019a, R2019b

Please note that this page refers to installations from the old software stack. There are two software stacks on Euler. Newer versions of software are found in the new software stack.

Environment modules (Euler, old software stack)

Version Module load command Additional modules loaded automatically
8.2 module load matlab/8.2
8.5 module load matlab/8.5
R2017b module load new matlab/9.1
8.4 module load new matlab/8.4
8.6 module load new matlab/8.6
8.7 module load new matlab/8.7
9.1 module load new matlab/9.1
R2018a module load new matlab/R2018a
R2019a module load new matlab/R2019a
R2019b module load new matlab/R2019b

Please note that this page refers to installations from the old software stack. There are two software stacks on Euler. Newer versions of software are found in the new software stack.

Interactive session

You can run an interactive MATLAB session on the login node, to do some quick tests, but larger calculations must be submitted through the batch system. In order to start an interactive MATLAB session, load the matlab module and type the command matlab.
[sfux@eu-login-03 ~]$ module load matlab/8.2
[sfux@eu-login-03 ~]$ matlab -nodisplay -nojvm -singleCompThread
Warning: No display specified.  You will not be able to display graphics on the screen.
Warning: No window system found.  Java option 'Desktop' ignored.

                                                   < M A T L A B (R) >
                                         Copyright 1984-2013 The MathWorks, Inc.
                                           R2013b (8.2.0.701) 64-bit (glnxa64)
                                                     August 13, 2013

No window system found.  Java option 'Desktop' ignored.

To get started, type one of these: helpwin, helpdesk, or demo.
For product information, visit www.mathworks.com.


>> vpa(exp(1),50)                                                                                                             
                                                                                                                             
ans =                                                                                                                         
                                                                                                                             
2.7182818284590455348848081484902650117874145507812                                                                           
                                                                                                                             
>>
If you have established an SSH connection with X11 forwarding enabled, then the matlab command will start the MATLAB GUI.

How to submit a job

Assuming that you already loaded the MATLAB module and have a MATLAB program simulation.m you would like to run, the command to submit a job to the batch system would look like
sbatch [Slurm options] --wrap="matlab -nodisplay -nojvm -singleCompThread -r simulation"

Please note, that you have to leave away the file ending .m. Here you need to replace [Slurm options] with Slurm parameters for the resource requirements of the job. Please find a documentation about the parameters of sbatch on the wiki page about the batch system.

We suggest you include the extra options shown above:

-nodisplay
since jobs on compute nodes are not run interactively, this flag explicitly tells Matlab that no graphical display (X server) is available is available.
-singleCompThread
forces Matlab to use only one thread for its computations. This option is crucial to prevent MATLAB from overloading the compute nodes.
-nojvm
(optional) prevents the JVM (Java virtual machine) from being used. Add this flag unless you need the JVM, such as the with the PCT (Parallel Computing Toolbox).
For submitting parallel MATLAB jobs, please have a look at the tutorials about running MATLAB in parallel.

Parallel jobs

MATLAB's Parallel Computing Toolbox lets you run suitably-written programs in parallel. Several cores calculate different parts of a problem at the same time to reduce the time-to-solution.

For running MATLAB in parallel, you can either use a local parpool (up to 24 cores), an LSF parpool (24+ cores) or use the MATLAB distributed computing server (MDCS), which allows to offload jobs from a local MATLAB instance running on your computer to the Euler cluster. Please find below the documentation about using a local parpool. Instructions for using an SLURM parpool as well as for using the MDCS are provided on separate wiki pages.

Use a parpool

For suitable MATLAB programs (such as those containing parfor loops), using the Parallel Computing Toolbox requires two steps:

  1. use a parpool in your MATLAB program and
  2. request multiple cores from Euler's SLURM batch scheduler.

One-time preparation: Before using the SLURM job pool for the first time, you need to import a cluster profile. For that, start MATLAB and then call configCluster . For each cluster, configCluster only needs to be called once per version of MATLAB. Please be aware that running this command more than once per version will reset your cluster profile back to default settings and erase any saved modifications to the profile.

A trivial parallel program (simulation.m) is shown below:

squares = zeros(10,1);
local_job = parcluster('local');
pool = parpool(local_job, 4);
parfor i = 1:10
    squares(i) = i^2;
end
disp(squares)
pool.delete()

Note that the local parpool is limited to 12 cores in releases up to R2016a (8.7/9.0). From release R2016b (9.1) on, you can use all the cores of Euler nodes (effectively 24).

Older versions of MATLAB used a matlabpool instead of a parpool. For using a local pool there is no need to load a cluster profile.

Submit a parallel job

To submit this program, pass the number of cores to the sbatch --cpus-per-task argument. This should be greater or equal to the size of the pool requested in your MATLAB script (e.g., 4).

sbatch --tasks=1  --cpus-per-task=4 --time=1:00:00 --mem-per-cpu=2g --wrap="matlab -nodisplay -singleCompThread -r simulation"

You must not use the -nojvm MATLAB argument but you should include the -singleCompThread MATLAB argument. MATLAB is quite memory-hungry, so request at least 2 GB of memory per core as shown above.

Troubleshoot parallel jobs

Using parallel pools often results in hard-to-diagnose errors. Many of these errors are related to running several pools at the same time, which is not what MATLAB expects. If you encounter persistent problems starting pools, try to perform one of these commands. Before running them, make sure that you do not have a MATLAB processes running.

  1. Remove the matlab_metadat.mat file in your current working directory.
  2. Remove the $HOME/.matlab/local_cluster_jobs directory.
  3. Remove the entire $HOME/.matlab directory. Warning: Your MATLAB settings on Euler will be lost.
In case this does not solve the problem, then please contact cluster support.

Example

As an example for a MATLAB job, we are calculating the determinant of a 3x3 Matrix.
[sfux@eu-login-01-ng ~]$ cat matrix_determinant.m 
A = [1 -2 4; -5 2 0; 1 0 3]
d = det(A)
[sfux@eu-login-01-ng ~]$ module load new matlab/9.1
[sfux@eu-login-01-ng ~]$ bsub -n 1 -W 1:00 -R "rusage[mem=512]" "matlab -nodisplay -nojvm -singleCompThread -r matrix_determinant" 
MATLAB job.
Job <30576749> is submitted to queue <normal.4h>.
[sfux@eu-login-01-ng ~]$ bjobs
JOBID      USER        STAT  QUEUE      FROM_HOST   EXEC_HOST   JOB_NAME   SUBMIT_TIME
30576749   sfux        PEND  normal.4h  eu-login-01-ng          *terminant Oct 21 13:32
[sfux@eu-login-01-ng ~]$ bjobs
JOBID      USER        STAT  QUEUE      FROM_HOST   EXEC_HOST   JOB_NAME   SUBMIT_TIME
30576749   sfux        PEND  normal.4h  eu-login-01-ng          *terminant Oct 21 13:32
[sfux@eu-login-01-ng ~]$ bjobs
JOBID      USER        STAT  QUEUE      FROM_HOST   EXEC_HOST   JOB_NAME   SUBMIT_TIME
30576749   sfux        RUN   normal.4h  eu-login-01-ng    e1245 *terminant Oct 21 13:32
[sfux@eu-login-01-ng ~]$ grep -A9 "A =" lsf.o30576749 
A =

     1    -2     4
    -5     2     0
     1     0     3

d =

   -32
[sfux@eu-login-01-ng ~]$
The output of the MATLAB calculation can be found in the LSF log file lsf.o30576749.

License information

Commercial (centrally provided by IT shop)

Troubleshooting

Sometimes, MATLAB jobs crash with a segmentation fault (exit code 137).
Your job looked like:

------------------------------------------------------------
# LSBATCH: User input
matlab -nodisplay -nojvm -singleCompThread -r matlab_script_that_uses_more_memory_than_requested
------------------------------------------------------------

Exited with exit code 137.

Resource usage summary:

   CPU time :                                   12385.20 sec.
   Max Memory :                                 14133 MB
   Average Memory :                             12578 MB
   Total Requested Memory :                     15000 MB
   Delta Memory :                                 867 MB
   Max Swap :                                   -
   Max Processes :                              4
   Max Threads :                                11
   Run time :                                    8433 sec.
   Turnaround time :                             8534 sec.

Usually this means that not enough memory was requested from the batch system. This can happen, even if the resource usage summary in the LSF logfile shows a positive delta memory. The resource usage summary only includes successful memory allocations. If a job tries to allocate a larger amount of memory and fails, then this is not reflected in the resource usage summary.

In such a case, please restart the job and request a larger amount of memory.

Notes

===Configuring the ETH proxy server in Matlab===

You can configure MATLAB to use a proxy:

com.mathworks.mlwidgets.html.HTMLPrefs.setUseProxy(true)
com.mathworks.mlwidgets.html.HTMLPrefs.setProxyHost('proxy.ethz.ch')  
com.mathworks.mlwidgets.html.HTMLPrefs.setProxyPort('3128') 

You need to run this just once per version.

Alternative to MATLAB

There is a freely available alternative to MATLAB, which is called Octave. It understands most MATLAB programs. It is not directly compatible with Matlab toolboxes but alternatives to some toolboxes exist.

Compiling MATLAB programs

MATLAB programs can be compiled into standalone executable programs using the Matlab Compiler mcc. A key benefit is that the compiled program does not check out a Matlab license. However, many toolboxes can not be used with compiled programs.

A function simulation defined in a file simulation.m is compiled into a standalone executable program simulation using the

mcc -m -R -nodisplay -R -nojvm -R -singleCompThread simulation.m

command. Note the dashes in front of the options, especially -R -singleCompThread.

To run the program, execute it through the generated script, which is call run_simulation.sh, where simulation is the name of your script.

sbatch --wrap="./run_simulation.sh $MATLAB"
The script needs the $MATLAB argument, which is defined when the appropriate Matlab module is loaded.

Links

Using MATLAB in parallel

The MATLAB server (MDCS)
http://www.mathworks.ch/products/matlab
http://en.wikipedia.org/wiki/MATLAB