Running MATLAB on Argo

We can only run compiled MATLAB code on ARGO due to licensing restrictions. The Matlab compiler "mcc" is a standalone environment that will allow MATLAB scripts to run without requiring a license.

MATLAB R2018b or Newer

Compiling your MATLAB script

Previous versions of the compiler could only compile a .m file if the contents were converted to a function first, but that does not appear to be the case with this version. You should be able to compile a MATLAB script without much difficulty, unless you are calling library functions that have not been implemented in the compiler version. The run() function is an example of such a function. You cannot execute code in another MATLAB script using run().

Note: To properly load MATLAB through the 'module load' command it is recommended to log in to the ARGO cluster without enabling X-forwarding, i.e., ssh user@argo.orc.gmu.edu should be used instead of ssh -X user@argo.orc.gmu.edu or ssh -Y user@argo.orc.gmu.edu.

To begin, first load the MATLAB module. Use applicable release name for e.g. R2018b or R2019b etc.

$module load matlab/

Once loaded, you will be able to run MATLAB in text mode for the purposes of testing and debugging your code as you attempt to compile it. Please DO NOT run any lengthy test jobs or experiments on the head nodes. We have scripts that look for processes that have been running too long, and then kill them.

To run an interactive MATLAB session, just type the following command:

 $matlab

To compile myMatlabScript.m with the MATLAB Compiler, you would use the following command:

$mcc -v -R -nodisplay -R -singleCompThread -m myMatlabScript.m

The "-R" option specifies the run-time options. The "-m" means create a standalone executable, and the "-v" asks for verbose output. You can get more information about "mcc" with the following command:

$mcc -?

The compiler will create a standalone executable called "myMatlabScript" and a "run_myMatlabScript.sh" shell script. It also creates a "readme.txt" which contains instructions on how to deploy the executable and "mccExcludedFiles.log" which contains a list of functions excluded from the CTF archive.

Running your compiled MATLAB script

To run your compiled script, you will first need to load the corresponding MATLAB compiler runtime environment, abbreviated to MCR. This contains all the compiled versions of the MATLAB library functions that your program will use. You should load the MATLAB/MCR module that corresponds to the version of MatLab that you have been using to develop your program:

$module load MATLAB/MCR/<matlab-release>

Your program can now be executed using the shell script generated during compilation, the environment variable MATLAB_RUN is set by the Matlab MCR module.

$./run_myMatlabScript.sh $MATLAB_RUN

Submitting your job to SLURM

Once you have your compiled script running correctly, you are ready to submit you job to the SLURM resource manager so that it can run on the cluster. Here is a sample SLURM script that you can use as a template your own script.

#!/bin/sh

## Specify the name for your job, this is the job name by which Slurm will
## refer to your job.  This can be different from the name of your executable
## or the name of your script file.
#SBATCH --job-name MyMatlabJob

#SBATCH --qos normal  # normal,cdsqos,phyqos,csqos,statsqos,hhqos,gaqos,esqos
#SBATCH -p all-LoPri  # partition (queue): all-LoPri, all-HiPri,
                      #   bigmem-LoPri, bigmem-HiPri, gpuq, CS_q, CDS_q, ...

## Deal with output and errors.  Separate into 2 files (not the default).
## NOTE: %u=userID, %x=jobName, %N=nodeID, %j=jobID, %A=arrayMain, %a=arraySub
#SBATCH -o /scratch/%u/%x-%N-%j.out    # Output file
#SBATCH -e /scratch/%u/%x-%N-%j.err    # Error file
##SBATCH --mail-type=BEGIN,END,FAIL     # NONE,BEGIN,END,FAIL,REQUEUE,ALL,...
##SBATCH --mail-user=<userID>@gmu.edu   # Put your GMU email address here

## Specifying an upper limit on needed resources will improve your scheduling
## priority, but if you exceed these values, your job will be terminated.
## Check your "Job Ended" emails for actual resource usage info.
##SBATCH --mem=<X>         # Total memory needed for your job (suffixes: K,M,G,T)
##SBATCH --time=<D-HH:MM>  # Total time needed for your job: Days-Hours:Minutes

## These options are more useful when running parallel and array jobs
#SBATCH --nodes 1         # Number of nodes (computers) to reserve
#SBATCH --tasks 1         # Number of independent processes per job

## Load the relevant modules needed for the job
module load MATLAB/MCR/R2019b
unset DISPLAY

## Start the job
./run_myMatlabScript.sh $MATLAB_RUN

Be sure to fill in the appropriate before running the sbatch command with your submission script.

Linking External Libraries to your MatLab Script

You may wish to run your MatLab script using a user-supplied library. To do this you must first configure the build environment to use the compiler used to compile the library. This is accomplished using the mbuild command. In this example we will use C as the programming language our library is compiled by, mbuild can also be configured for C++ and also FORTRAN. You must first load the compiler module that you use to build the library, e.g.:

module load gcc/8.3.1

You must also load the MatLab release module you require:

module load matlab/R2019b

Remove or rename the file \~/.matlab//MBUILD_C_glnxa64.xml if it exists.

mv ~/.matlab/R2019b/MBUILD_C_glnxa64.xml ~/.matlab/R2019b/MBUILD_C_glnxa64-default.xml

Now run the mbuild -setup command

mbuild -setup

This will create a new file: MBUILD_C_glnxa64.xml with the appropriate compiler paths configured.

There are a two different but equivalent ways of specifying the compile parameters with linking an external library.

Method 1, copy the file

~/.matlab//MBUILD_C_glnxa64.xml to new name and edit it to embed the necessary changes to CFLAGS, INCLUDES, and LDFLAGS, then compile with:

>mcc -mv mymain.m myCfile.c -f <full_path_to_new_options_file>

The alternative method is to pass the compilation options directly in the command line:

>mcc -M "-I<path/to/library/headers> -L<path/to/libraries> -l<library-to-link-1> -l <library-to-link-2> ..." -m myMatlabScript.m

NB: that all options passed usung -M must be passed in one statement or else the right most -M with override the other entries.

Calling MatLab functions from an External Program

Under Development.

MATLAB R2017a and Older

To compile the .m file it should be converted into a function, i.e., the file contains "function" followed by the name in first line. Scripts cannot be compiled. Also, calling a script from a function through the run() function will not work. You need to edit your ".m" files to convert into functions. This is done by putting "function " as the first line in your ".m" file. The main function can call other ".m" files. Remember, a function can't call a script through the "run('scriptname')" command for the MATLAB compiler to work.

Note: To properly load MATLAB through 'module load' command it is recommended to log in to Argo cluster without enabling X-forwarding, i.e., ssh user@argo.orc.gmu.edu should be used instead of ssh -X user@argo.orc.gmu.edu or ssh -Y user@argo.orc.gmu.edu.

Load the MATLAB module

$module load matlab/R2017a

To compile myMatlabFunction.m with the MATLAB Compiler, you would use the following command:

$crun mcc -v -R -nodisplay -R -singleCompThread -m myMatlabFunction.m

The "-R" option specifies the run-time options. The "-m" means create a standalone executable, and the "-v" asks for verbose output. You can get more information about "mcc" with the following command:

$crun mcc -?

The compiler will create a standalone executable called "myMatlabFunction" and a "run_myMatlabFunction.sh" shell script. It also creates a "readme.txt" which contains instructions on how to deploy the executable and "mccExcludedFiles.log" which contains a list of functions excluded from the CTF archive.

Here is a script for submitting the Matlab job, if you want to run the executable:

#!/bin/sh

## Specify the name for your job, this is the job name by which Slurm will
## refer to your job.  This can be different from the name of your executable
## or the name of your script file.
#SBATCH --job-name MyMatlabJob

#SBATCH --qos normal  # normal,cdsqos,phyqos,csqos,statsqos,hhqos,gaqos,esqos
#SBATCH -p all-LoPri  # partition (queue): all-LoPri, all-HiPri,
                      #   bigmem-LoPri, bigmem-HiPri, gpuq, CS_q, CDS_q, ...

## Deal with output and errors.  Separate into 2 files (not the default).
## NOTE: %u=userID, %x=jobName, %N=nodeID, %j=jobID, %A=arrayMain, %a=arraySub
#SBATCH -o /scratch/%u/%x-%N-%j.out    # Output file
#SBATCH -e /scratch/%u/%x-%N-%j.err    # Error file
##SBATCH --mail-type=BEGIN,END,FAIL     # NONE,BEGIN,END,FAIL,REQUEUE,ALL,...
##SBATCH --mail-user=<userID>@gmu.edu   # Put your GMU email address here

## Specifying an upper limit on needed resources will improve your scheduling
## priority, but if you exceed these values, your job will be terminated.
## Check your "Job Ended" emails for actual resource usage info.
##SBATCH --mem=<X>         # Total memory needed for your job (suffixes: K,M,G,T)
##SBATCH --time=<D-HH:MM>  # Total time needed for your job: Days-Hours:Minutes

## These options are more useful when running parallel and array jobs
#SBATCH --nodes 1         # Number of nodes (computers) to reserve
#SBATCH --tasks 1         # Number of independent processes per job

## Load the relevant modules needed for the job
module load MATLAB/MCR/R2017a
unset DISPLAY

## Start the job
crun ./myMatlabScript  # This is the compiled executable, not the original .m file

Then submit your job using the sbatch command as discussed in Getting Started with Slurm. Remember that the compilation of MATLAB functions by mcc can only be done on login nodes. If you are working in an interactive session, issuing mcc command will not work because compute nodes only have the MATLAB component runtime available that can execute a compiled MATLAB application.

Matlab Reference

MATLAB Toolboxes: The available MATLAB versions on ARGO, i.e., 2017a, 2018b come with many toolboxes commonly used, e.g., Parallel Computing Toolbox, Image Processing Toolbox, Optimization toolbox, Signal Processing Toolbox etc. To see the complete list of available toolboxes, on a MATLAB prompt execute the command 'ver'.

Information about deployed codes: 1
Path Management in deployed codes: 2
Limitations on using Matlab Toolboxes with compiled packages: 3