Difference between revisions of "Matlab"

From UFRC
Jump to navigation Jump to search
 
(59 intermediate revisions by 7 users not shown)
Line 1: Line 1:
__NOTOC__
+
{|align=right
 +
  |__TOC__
 +
  |}
 
__NOEDITSECTION__
 
__NOEDITSECTION__
[[Category:Software]]
+
[[Category:Software]][[Category:Language]][[Category:Math]]
 
{|<!--Main settings - REQUIRED-->
 
{|<!--Main settings - REQUIRED-->
 
|{{#vardefine:app|matlab}}
 
|{{#vardefine:app|matlab}}
Line 7: Line 9:
 
|{{#vardefine:exe|1}} <!--Present manual instructions for running the software -->
 
|{{#vardefine:exe|1}} <!--Present manual instructions for running the software -->
 
|{{#vardefine:conf|}} <!--Enable config wiki page link - {{#vardefine:conf|1}} = ON/conf|}} = OFF-->
 
|{{#vardefine:conf|}} <!--Enable config wiki page link - {{#vardefine:conf|1}} = ON/conf|}} = OFF-->
|{{#vardefine:pbs|}} <!--Enable PBS script wiki page link-->
+
|{{#vardefine:job|1}} <!--Enable job script wiki page link-->
 
|{{#vardefine:policy|}} <!--Enable policy section -->
 
|{{#vardefine:policy|}} <!--Enable policy section -->
 
|{{#vardefine:testing|}} <!--Enable performance testing/profiling section -->
 
|{{#vardefine:testing|}} <!--Enable performance testing/profiling section -->
Line 18: Line 20:
 
{{App_Description|app={{#var:app}}|url={{#var:url}}|name={{#var:app}}}}|}}
 
{{App_Description|app={{#var:app}}|url={{#var:url}}|name={{#var:app}}}}|}}
  
MATLAB is a programming environment for algorithm development, data analysis, visualization, and numerical computation. Using MATLAB, you can solve technical computing problems faster than with traditional programming languages, such as C, C++, and Fortran.
+
MATLAB is a programming environment for algorithm development, data analysis, visualization, and numerical computation. Using MATLAB, you can solve technical computing problems faster than traditional programming languages, such as C, C++, and Fortran.
  
You can use MATLAB in a wide range of applications, including signal and image processing, communications, control design, test and measurement, financial modeling and analysis, and computational biology. For a million engineers and scientists in industry and academia, MATLAB is the language of technical computing.
+
You can use MATLAB in various applications, including signal and image processing, communications, control design, test and measurement, financial modeling and analysis, and computational biology. MATLAB is the language of technical computing for a million engineers and scientists in industry and academia.
 
<!--Modules-->
 
<!--Modules-->
==Required Modules==
+
==Environment Modules==
[[Modules|modules documentation]]
+
Run <code>module spider matlab</code> or <code>module spider mcr</code> to find out what environment modules are available for the MATLAB GUI and for the MATLAB Compiler Runtime. Use Matlab to compile your code and mcr to run it. The mcr does not consume MATLAB licenses.
===Serial===
+
 
*{{#var:app}}
+
==Restrictions==
 +
The MATLAB install on HiPerGator is restricted to the toolboxes available under the UF license. The complete list of ineligible toolboxes is on the MATLAB website: [https://www.mathworks.com/support/requirements/product-requirements-platform-availability-list.html MATLAB Add-On Availability]
 +
 
 +
Run <code>matlab_show_license_use</code> after loading a Matlab module to see what licenses are available and how many are in use.
 +
 
 
==System Variables==
 
==System Variables==
* HPC_{{#uppercase:{{#var:app}}}}_DIR - installation directory
+
* HPC_{{uc:{{#var:app}}}}_DIR - installation directory
 
<!--Additional-->
 
<!--Additional-->
{{#if: {{#var: exe}}|==Additional Information==
 
|}}
 
 
{{#if: {{#var: conf}}|==Configuration==
 
{{#if: {{#var: conf}}|==Configuration==
 
See the [[{{PAGENAME}}_Configuration]] page for {{#var: app}} configuration details.
 
See the [[{{PAGENAME}}_Configuration]] page for {{#var: app}} configuration details.
 
|}}
 
|}}
{{#if: {{#var: pbs}}|==PBS Script Examples==
 
See the [[{{PAGENAME}}_PBS]] page for {{#var: app}} PBS script examples.|}}
 
 
{{#if: {{#var: policy}}|==Usage Policy==
 
{{#if: {{#var: policy}}|==Usage Policy==
 
WRITE USAGE POLICY HERE (perhaps templates for a couple of main licensing schemes can be used)
 
WRITE USAGE POLICY HERE (perhaps templates for a couple of main licensing schemes can be used)
Line 49: Line 51:
 
|}}
 
|}}
 
==Policies==
 
==Policies==
# You may not run MatLab nor compiled MatLab executables interactively on submit1 or submit2.
+
# You may not interactively run Matlab or compiled MATLAB executables on the login servers.
# You must use the test nodes (test01 - test05) to test and compile your MatLab programs.
+
# Long running (more than 10 minutes) MATLAB jobs must be in compiled form and submitted to the batch system.
# Long running (more than 30 minutes) MatLab jobs must be submitted to the batch system.
+
# UF Research Computing has no budget for application software and licensing. All MATLAB licenses (including the compiler) come from and are shared with the entire UF campus. For this reason, it is sometimes difficult to obtain a license, or MATLAB may take a long time to start. If your research depends on MatLab and you do not want to be delayed by licensing issues, you should consider purchasing a MATLAB license for your personal or group use.
# Large numbers of jobs must not be run on the test nodes but must be submitted to the batch system.
+
 
# The UF HPC Center has no budget for application software and licensing.   All MatLab licenses (including the compiler) come from, and are shared with, all of campus.   For this reason it is sometimes difficult to obtain a license.   If your research depends on MatLab and you do not want to be delayed by licensing issues, you should consider purchasing a MatLab license for your personal or group use.
+
==Available components==
 +
See the [[Matlab add-ons]] for a full list of licensed MATLAB components.
  
 
==Compiling MatLab Programs==
 
==Compiling MatLab Programs==
MatLab programs must be compiled via the MatLab compiler before they can be run in batch mode on the HPC Center cluster.
+
MATLAB programs must be compiled via the MATLAB compiler before they can be run in batch mode on HiPerGator. To compile MATLAB programs, you should
In order to compile MatLab programs you should
 
  
1. Once on submit1 or submit2, log into one of the test nodes (test01 - test06) via ssh.  Due to user memory constraints on submit1 and submit2, the MatLab compiler cannot be used on those servers.
+
# See [[Development and Testing]] page to learn how to get an interactive developmental session on HiPerGator under SLURM.
submit1% ssh test05
+
# Set up your environment so that the libraries needed by the compiler can be found.
2. Set up your environment so that the libraries needed by the compiler can be found.
+
#*<pre>module load matlab</pre>
test05% module load matlab
+
#*'''Note:''' The module load command should also be included in your batch submission script since your compiled Matlab executable must also find the appropriate dynamically loaded libraries.
'''Note:''' The module load command should be included in your batch submission script as well since your compiled matlab executable will also need to find the appropriate dynamically loaded libraries.
+
# Compile your MATLAB program (.m) files using the MatLab compiler.
 
+
#*<pre>mcc -R -singleCompThread -m some_prog.m</pre>
3a. For batch jobs, you should also set the MCR_CACHE_ROOT environment variable in your PBS job script.
+
#*'''Note:'''  The "<code>-R -singleCompThread</code>" options on the mcc command line will result in a '''single-threaded''' executable. By default, multithreading is enabled in executables produced by mcc.  One computational thread will be started for each processor in a machine that runs your executable. That's not usually what you want. Unless you know what you are doing and intend to take advantage of multithreading (including requesting the appropriate resources in your submission script), you should use these options and generate a '''single-threaded''' executable.
test05% export MCR_CACHE_ROOT=${TMPDIR}
 
Please see the [[PBS Sample Job Scripts]] for a sample MatLab submission script.
 
 
 
3b. For an interactive run (only on the test nodes), you should set MCR_CACHE_ROOT to a directory /scratch/local.
 
test05% mkdir -p /scratch/local/$USER/mcr_cache
 
test05% export MCR_CACHE_ROOT=/scratch/local/$USER/mcr_cache
 
 
 
4. Compile your matlab program (.m) files using the MatLab compiler ([[mcc]]).
 
test05% mcc -R -singleCompThread -m some_prog.m
 
 
===Example===
 
===Example===
Let us say that we have a program such as that below in a source file named houdini.m
+
<div class="mw-collapsible mw-collapsed" style="width:70%; padding: 5px; border: 1px solid gray;">
<source lang=matlab>
+
''Expand this section to view MATLAB example.''
 +
<div class="mw-collapsible-content" style="padding: 5px;">
 +
Let us say we have a program like that below in a source file named houdini.m
 +
<pre>
 
function [m,t] = houdini();
 
function [m,t] = houdini();
 
% Doc example, chapter 3.
 
% Doc example, chapter 3.
Line 87: Line 83:
 
t = m .^ 3;  % Cube each element of m.  
 
t = m .^ 3;  % Cube each element of m.  
 
disp(t);      % Display the value of t.
 
disp(t);      % Display the value of t.
</source>
+
</pre>
Since we already have the environment setup, we can compile this program. It is recommended that this be done in a separate directory as a number of files are produced.
+
Since we already have the environment set, we can compile this program. It is recommended that this be done in a separate directory as several files are produced.
<source lang=bash>
+
<pre>
 
  mkdir tmp
 
  mkdir tmp
 
  cd tmp
 
  cd tmp
Line 95: Line 91:
 
  module load matlab
 
  module load matlab
 
  mcc -R -singleCompThread -m houdini.m  
 
  mcc -R -singleCompThread -m houdini.m  
</source>
+
  ls -l
<pre>
 
  test05% ls -l
 
 
total 124
 
total 124
 
-rwxr-xr-x  1 root root 12299 Apr  3 10:08 houdini
 
-rwxr-xr-x  1 root root 12299 Apr  3 10:08 houdini
Line 109: Line 103:
 
-rwxr--r--  1 root root  1446 Apr  3 10:08 run_houdini.sh
 
-rwxr--r--  1 root root  1446 Apr  3 10:08 run_houdini.sh
 
</pre>
 
</pre>
The MatLab executable '''houdini''' has been generated.
+
The MATLAB executable '''houdini''' has been generated and can be run by typing ./houdini, or by putting that command in a batch submission script.
 +
</div></div>
 +
----
 +
[http://www.mathworks.com/access/helpdesk/help/toolbox/compiler MATLAB Compiler Documentation] can be found on the MatLab Website.
 +
 
 +
==MATLAB GUI use on HiPerGator==
 +
 
 +
If you must use the Graphical User Interface for MATLAB, use [[Open OnDemand|Open on Demand]]
 +
 
 +
==MATLAB online training==
 +
 
 +
Mathworks also has several free [https://www.mathworks.com/services/training.html online training resources].
  
'''Note:'''  The "<code>-R -singleCompThread</code>" options on the mcc command line will result in a '''single-threaded''' executable.  By default, multi-threading is enabled in executables produced by mcc.  The result is that one computational thread will be started for each processor in a machine that runs your executable.  That's not usually what you want.  Unless you know what you are doing and intend to take advantage of multithreading (including requesting the appropriate resources in your submission script) you should use these options and generate a '''single-threaded''' executable.  Otherwise, your MatLab jobs will oversubscribe the compute nodes and interfere with other users' programs.
 
----
 
Documentation for the MatLab compiler can be viewed on the [http://www.mathworks.com/access/helpdesk/help/toolbox/compiler MatLab Website].
 
  
===Available components===
+
==Compiled DLL==
See the [[Matlab add-ons]] for a full list of licensed Matlab components.
+
If you have compiled a MATLAB DLL to use as an executable, it will not run on the cluster. DLL's are Microsoft Windows based dynamically linked libraries that will only work under the Windows operating system.
===Compiled DLL===
 
If you have compiled a DLL to use as an executable, it will not run on the cluster. DLL's are Microsoft Windows based dynamically linked libraries that will only work under the Windows operating system.
 
  
===Setting a Path===
+
==Setting a Command Path==
In order to set a path in your MatLab program should add the following code.
+
To set a command path in your MATLAB program, should add the following code.
 
<pre>
 
<pre>
path(path, '/path/to/wherever/you/want')
+
path(path, '/path/to/matlab/binaries')
 
</pre>
 
</pre>
This would add a search path to the MatLab system. For more information see the [http://www.mathworks.com/access/helpdesk/help/techdoc/index.html?/access/helpdesk/help/techdoc/ref/path.html&http://www.google.com/search?hl=en&q=matlab+set+path&btnG=Google+Search&aq=f&oq= Matlab] web site.
+
This will add the specified directory to the MATLAB search path. For more information, see the [http://www.mathworks.com/access/helpdesk/help/techdoc/index.html?/access/helpdesk/help/techdoc/ref/path.html&http://www.google.com/search?hl=en&q=matlab+set+path&btnG=Google+Search&aq=f&oq= Matlab] web site.
  
 
==Known Issues==
 
==Known Issues==
 +
<div class="mw-collapsible mw-collapsed" style="width:70%; padding: 5px; border: 1px solid gray;">
 +
''Expand this section to view common troubleshooting steps.''
 +
<div class="mw-collapsible-content" style="padding: 5px;">
 
===No Licenses Available===
 
===No Licenses Available===
You may run into an error when using the MatLab compiler such as  
+
You may run into an error when using the MATLAB compiler, such as  
  
 
'''Licensed number of users already reached.'''
 
'''Licensed number of users already reached.'''
  
If so, the number of licenses available for the MatLab compiler has been exceeded. There are only two shared among the entire university so you should expect to see this problem from time to time if you use the MatLab compiler frequently.
+
If so, the number of licenses available for the MATLAB compiler has been exceeded. Only two are shared among the entire university, so you should expect to see this problem occasionally if you use the MATLAB compiler frequently. If the problem persists for over a few hours, please open a [https://support.rc.ufl.edu support request].
  
 
===MCR_CACHE_ROOT Directory===
 
===MCR_CACHE_ROOT Directory===
 
'''Could not access the MCR component cache'''
 
'''Could not access the MCR component cache'''
  
This error message means that MatLab is not able to access the MCR cache directory which, by default, is created by MatLab in your home directory. If you are running a large number of MatLab jobs, the file locking used by MatLab to manage concurrent access to files in the MCR_CACHE_ROOT directory can generate a significant load on the file system on which these files reside.  Thus, we ask that you use a '''local scratch''' directory for your MCR_CACHE_ROOT directory.   To do so, set the value of MCR_CACHE_ROOT to $TMPDIR in your job submission script.
+
This error message means that MATLAB cannot access the MCR cache directory. When you load the MATLAB module, MCR_CACHE_ROOT is set for you, and you should not encounter this error. If you do, please open a [https://support.rc.ufl.edu support request]. For batch jobs, <code>module load matlab</code> uses the $TMPDIR variable, and MCR_CACHE_ROOT is set to $TMPDIR/mcr_cache. For non-batch jobs, MCR_CACHE_ROOT is set to /scratch/local/$USER/mcr_cache
  export MCR_CACHE_ROOT=$TMPDIR
+
   
==Interactive Use==
+
===Older Versions===
See [[GUI_Programs]] for information on running the matlab GUI interface for short debugging sessions.
+
To use older versions of MATLAB that are installed on the cluster, you can list them via the following command:
 +
<pre>
 +
$ module spider matlab
 +
</pre>
 +
If you were to see that an older version of MATLAB is available, such as version r2012a, you would then load the appropriate module for that version:
 +
<pre>
 +
$ module load matlab/2012a
 +
</pre>
 +
</div></div>

Latest revision as of 16:06, 28 November 2023

Description

matlab website  

MATLAB is a programming environment for algorithm development, data analysis, visualization, and numerical computation. Using MATLAB, you can solve technical computing problems faster than traditional programming languages, such as C, C++, and Fortran.

You can use MATLAB in various applications, including signal and image processing, communications, control design, test and measurement, financial modeling and analysis, and computational biology. MATLAB is the language of technical computing for a million engineers and scientists in industry and academia.

Environment Modules

Run module spider matlab or module spider mcr to find out what environment modules are available for the MATLAB GUI and for the MATLAB Compiler Runtime. Use Matlab to compile your code and mcr to run it. The mcr does not consume MATLAB licenses.

Restrictions

The MATLAB install on HiPerGator is restricted to the toolboxes available under the UF license. The complete list of ineligible toolboxes is on the MATLAB website: MATLAB Add-On Availability

Run matlab_show_license_use after loading a Matlab module to see what licenses are available and how many are in use.

System Variables

  • HPC_MATLAB_DIR - installation directory



Policies

  1. You may not interactively run Matlab or compiled MATLAB executables on the login servers.
  2. Long running (more than 10 minutes) MATLAB jobs must be in compiled form and submitted to the batch system.
  3. UF Research Computing has no budget for application software and licensing. All MATLAB licenses (including the compiler) come from and are shared with the entire UF campus. For this reason, it is sometimes difficult to obtain a license, or MATLAB may take a long time to start. If your research depends on MatLab and you do not want to be delayed by licensing issues, you should consider purchasing a MATLAB license for your personal or group use.

Available components

See the Matlab add-ons for a full list of licensed MATLAB components.

Compiling MatLab Programs

MATLAB programs must be compiled via the MATLAB compiler before they can be run in batch mode on HiPerGator. To compile MATLAB programs, you should

  1. See Development and Testing page to learn how to get an interactive developmental session on HiPerGator under SLURM.
  2. Set up your environment so that the libraries needed by the compiler can be found.
    • module load matlab
    • Note: The module load command should also be included in your batch submission script since your compiled Matlab executable must also find the appropriate dynamically loaded libraries.
  3. Compile your MATLAB program (.m) files using the MatLab compiler.
    • mcc -R -singleCompThread -m some_prog.m
    • Note: The "-R -singleCompThread" options on the mcc command line will result in a single-threaded executable. By default, multithreading is enabled in executables produced by mcc. One computational thread will be started for each processor in a machine that runs your executable. That's not usually what you want. Unless you know what you are doing and intend to take advantage of multithreading (including requesting the appropriate resources in your submission script), you should use these options and generate a single-threaded executable.

Example

Expand this section to view MATLAB example.

Let us say we have a program like that below in a source file named houdini.m

function [m,t] = houdini();
% Doc example, chapter 3.

% Copyright 1997 The MathWorks, Inc.
% $Revision: 1.1.6.1 $

m = magic(2); % Assign 2x2 matrix to m. 
t = m .^ 3;   % Cube each element of m. 
disp(t);      % Display the value of t.

Since we already have the environment set, we can compile this program. It is recommended that this be done in a separate directory as several files are produced.

 mkdir tmp
 cd tmp
 cp ../houdini.m .
 module load matlab
 mcc -R -singleCompThread -m houdini.m 
 ls -l
total 124
-rwxr-xr-x  1 root root 12299 Apr  3 10:08 houdini
-rw-r--r--  1 root root 63146 Apr  3 10:08 houdini.ctf
-rw-r--r--  1 root root   239 Apr  3 10:06 houdini.m
-rw-r--r--  1 root root  2900 Apr  3 10:08 houdini_main.c
-rw-r--r--  1 root root  6328 Apr  3 10:08 houdini_mcc_component_data.c
-rw-r--r--  1 root root  5461 Apr  3 10:08 houdini.prj
-rw-r--r--  1 root root  1010 Apr  3 10:08 mccExcludedFiles.log
-rw-r--r--  1 root root  6757 Apr  3 10:08 readme.txt
-rwxr--r--  1 root root  1446 Apr  3 10:08 run_houdini.sh

The MATLAB executable houdini has been generated and can be run by typing ./houdini, or by putting that command in a batch submission script.


MATLAB Compiler Documentation can be found on the MatLab Website.

MATLAB GUI use on HiPerGator

If you must use the Graphical User Interface for MATLAB, use Open on Demand

MATLAB online training

Mathworks also has several free online training resources.


Compiled DLL

If you have compiled a MATLAB DLL to use as an executable, it will not run on the cluster. DLL's are Microsoft Windows based dynamically linked libraries that will only work under the Windows operating system.

Setting a Command Path

To set a command path in your MATLAB program, should add the following code.

path(path, '/path/to/matlab/binaries')

This will add the specified directory to the MATLAB search path. For more information, see the Matlab web site.

Known Issues

Expand this section to view common troubleshooting steps.

No Licenses Available

You may run into an error when using the MATLAB compiler, such as

Licensed number of users already reached.

If so, the number of licenses available for the MATLAB compiler has been exceeded. Only two are shared among the entire university, so you should expect to see this problem occasionally if you use the MATLAB compiler frequently. If the problem persists for over a few hours, please open a support request.

MCR_CACHE_ROOT Directory

Could not access the MCR component cache

This error message means that MATLAB cannot access the MCR cache directory. When you load the MATLAB module, MCR_CACHE_ROOT is set for you, and you should not encounter this error. If you do, please open a support request. For batch jobs, module load matlab uses the $TMPDIR variable, and MCR_CACHE_ROOT is set to $TMPDIR/mcr_cache. For non-batch jobs, MCR_CACHE_ROOT is set to /scratch/local/$USER/mcr_cache

Older Versions

To use older versions of MATLAB that are installed on the cluster, you can list them via the following command:

$ module spider matlab

If you were to see that an older version of MATLAB is available, such as version r2012a, you would then load the appropriate module for that version:

$ module load matlab/2012a