MATLAB has to be loaded using the module utility prior to running it. This ensures that the environment is correctly set. Get the list of available versions of MATLAB using
module avail matlab
(KU Leuven clusters) or
module avail MATLAB
(UAntwerpen and VUB clusters).
Load a specific version by specifying the MATLAB version in the command
module load matlab/R2014a
module load MATLAB/2014a
depending on the site you're at.
- Interactive use is possible, but is not the preferred way of using MATLAB on the cluster! Use batch processing of compiled MATLAB code instead.
- If there is an X Window System server installed on your PC (as is by default the case under Linux; you can use XMing Server under Windows or XQuartz on macOS/OS X), the full graphical MATLAB Desktop is available. If the speed is acceptable to you - much of the Matlab user interface is coded in Java and Java programs are known to be slow over remote X connections - this is the recommended way to start MATLAB for short testing purposes, simple calculations, writing programs, visualizing data. Please avoid doing extensive calculations this way, as you would be abusing the resources of the shared login-node. Your program will disturb other users, and other users will slow down execution of your program. Moreover, only a limited amount of CPU time is available to you, after which your session will be killed (with possible data loss).
matlab -nodesktopyou can start Matlab without the full desktop, while you are still able to use the visualisation features. The
editcommands also work and open GUI-style help windows or a GUI-based editor. Of course this also requires a X server.
- You can always, i.e., without X-Window server, start MATLAB in console-mode, via
matlab -nodisplayYou get a MATLAB command prompt, from where you can start m-files, but have no access to the graphical facilities. The same limitations as above on CPU time apply.
- For intensive calculations you want to run interactively, it is possible to use the PBS Job system to reserve a node for your exclusive use, while still having access to, e.g., the graphical capabilities of MATLAB, by forwarding the X output (qsub -X -I).
- WARNING: an interactive MATLAB session on a compute node can be very slow. A workaround (found at hpc.uark.edu) is:
- launch an interactive session qsub -I -X
- once the interactive session is started, (say it starts on r2i0n15), start another connection to that compute node (ssh -X r2i0n15). In this second connection, start MATLAB, and it will work at normal speed.
For any non-trivial calculation, it is strongly suggested that you use the PBS batch system.
Running a MATLAB script
You first have to write a MATLAB m-file that executes the required calculation. Make sure the last command of this m-file is 'quit' or 'exit', otherwise MATLAB might wait forever for more commands ...
Example (to be saved, e.g., in testmatlabscript.m) :
ndim = 600; a = rand(600,1)*10; b = rand(1,600)*100; c = a * b; d = max(c); e = min(d); save('testmatlab', 'd', 'e'); exit;
You can now run this program (as a test, still on the login node, from the directory were you saved the file testmatlabscript.m):
matlab -nodisplay -r testmatlabscript
The next thing is to write a small shell script, to be sent to the PBS Job System, so that the program can be executed on a compute node, rather than on the login node.
A simple example follows (to be saved, e.g., in testmatlabscript.sh ) ;
#!/bin/bash -l # The maximum duration of the program, # in the format [days:]hours:minutes:seconds #PBS -l walltime=01:00:00 # the requested amount of RAM #PBS -l pmem=950mb # The name of your job (used in mail, outputfile, showq,...) #PBS -N matlab_test_job # Set the correct environment for matlab module load matlab # Go into the directory from where 'qsub' was run cd $PBS_O_WORKDIR # Start matlab, specify the correct command-file ... matlab -nojvm -nodisplay -r test
Now you submit your job with
$ qsub testmatlabscript.sh
and you get the jobid that was assigned to your job. With
you get an overview of the status of your jobs. When the job has run, output will be available in the file <jobname>.o<jobid> in the directory where you submitted the job from. In the case of the file testmatlabscript.m above, a file testmatlabscript.mat will have been created, with the calculated data d and e, you can load the resulting file into a MATLAB for further processing.
Running a MATLAB function
If instead of a script, a MATLAB function is used, parameters can be passed into the function.
Example (to be saved, e.g., in testmatlabfunction.m) :
function testmatlabfunction(input1,input2) % source: https://wiki.inf.ed.ac.uk/ANC/MatlabComputing % change arguments to numerics if necessary - only when compiling code if ~isnumeric(input1) input1n = str2num(input1); input2n = str2num(input2); else input1n = input1; input2n = input2; end sumofinputs = input1n + input2n; outputfilename = ['testfunction_' num2str(input1n) '_' num2str(input2n)]; save(outputfilename, 'input1n', 'input2n', 'sumofinputs'); exit;
You can now run this program (as a test, still on the login node, from the directory were you saved the file testmatlabfunction.m):
matlab -nodisplay -r "testmatlabfunction 3 6"
Note the quotes around the function name and the parameters. Note also that the function name does not include the *.m extension.
Each job requires a MATLAB license while running. If you start lots of jobs, you'll use lots of licenses. When all licenses are in use, your further jobs will fail, and you'll block access to MATLAB for other people at your site.
However, when compiling your MATLAB program, no more runtime licenses are needed.
Compilation of MATLAB files is relatively easy with the MATLAB 'mcc' compiler. It works for 'function m-files' and for 'script m-files'. 'function m-files' are however preferred.
To deploy a MATLAB program as a standalone application, load the module for MATLAB as a first step and compile the code in a second step with the mcc command.
If we want to compile a MATLAB program 'main.m', the corresponding command line should be:
mcc -v -R -singleCompThread -m main.m
Where the options are:
- -m: generate a standalone application
- -v: verbose display of the compilation steps
- -R: runtime options, useful ones are: -singleCompThread, -nodisplay, -nojvm
The deployed executable is compiled to run using a single thread via the option -singleCompThread. This is important when a number of processes
are to run concurrently on the same node (e.g. worker framework).
- Parameters are always considered as strings, and thus have to be converted to, e.g., numbers inside your function when needed. You can test with 'isdeployed' or 'isstr' functions (see examples).
- The function is allowed to return a value, but that value is *not* returned to the shell. Thus, to get results out, they have to be written to the screen, or saved in a file.
- Not all MATLAB functions are allowed in compiled code (see the "Compiler Support for Matlab and Toolboxes" page at the MathWorks).
Example 1: Simple matlab script file
- File fibonacci.m contains :
function a = fibonacci(n) % FIBONACCI Calculate the fibonacci value of n. % When complied as standalone function, % arguments are always passed as strings, not nums ... if (isstr(n)) n = str2num(n); end; if (length(n)~=1) || (fix(n) ~= n) || (n < 0) error(['MATLAB:factorial:NNotPositiveInteger', ... 'N must be a positive integer.']); end first = 0;second = 1; for i=1:n-1 next = first+second; first=second; second=next; end % When called from a compiled application, display result if (isdeployed) disp(sprintf('Fibonacci %d -> %d' , n,first)) end % Also return the result, so that the function remains usable % from other Matlab scripts. a=first;
- Run the compiler
mcc -m fibonacci
- Executable file 'fibonacci' is created.
- You can now run your application as follows :
./fibonacci 6 Fibonacci 6 -> 5 $ ./fibonacci 8 Fibonacci 8 -> 13 $ ./fibonacci 45 Fibonacci 45 -> 701408733
Example 2 : Function that uses other Matlab files
- File multi_fibo.m contains :
function multi_fibo() %MULTIFIBO Calls FIBONACCI multiple times in a loop % Function calculates Fibonacci number for a matrix by calling the % fibonacci function in a loop. Compiling this file would automatically % compile the fibonacci function also because dependencies are % automatically checked. n=10:20 if max(n)<0 f = NaN; else [r c] = size(n); for i = 1:r %#ok for j = 1:c %#ok try f(i,j) = fibonacci(n(i,j)); catch f(i,j) = NaN; end end end end
- Compile :
mcc -m multi_fibo
- Run :
./multi_fibo n = 10 11 12 13 14 15 16 17 18 19 20 Fibonacci 10 -> 34 Fibonacci 11 -> 55 Fibonacci 12 -> 89 Fibonacci 13 -> 144 Fibonacci 14 -> 233 Fibonacci 15 -> 377 Fibonacci 16 -> 610 Fibonacci 17 -> 987 Fibonacci 18 -> 1597 Fibonacci 19 -> 2584 Fibonacci 20 -> 4181 f = 34 55 89 144 233 377 610 987 1597 2584 4181
Example 3 : Function that used other Matlab files in other directories
- If your script uses MATLAB files (e.g., self-made scripts, compiled mex files) other than those part of the MATLAB-distribution, include them at compile time as follows:
mcc -m -I /path/to/MyMatlabScripts1/ -I /path/to/MyMatlabScripts2 .... -I /path/to/MyMatlabScriptsN multi_fibo
(on a single line).