MATLAB

M​​​ATL​AB is centrally installed on all WIN (FMRIB and OHBA) Linux desktops, before use you should select the version of MATLAB you wish to run using the Shell Module system.

For interactive use please use your personal computer where possible or jalapeno00.cluster.fmrib.ox.ac.uk/jalapeno18.cluster.fmrib.ox.ac.uk if you need access to central datasets. For non-interactive tasks that you are submitting to the queues please use compiled matlab​ where possible.

To list the available versions use:

module avail

This will report, for example:

MATLAB/2021a
MATLAB/2015b

​​​To configure your session to use a particular version and to start it use:

module add MATLAB/current
​​​matlab

Switching versions​

​If you want to switch to using a different version of MATLAB then you can use the 'switch' option:

module switch MATLAB/current MATLAB/2014b

Finding out which version you have configured​​ 

module list

Unloading from your session​

​​If​ you wish to unload the MATLAB configuration from your shell session use:

module unload MATLAB/current

(changing t​he module as appropr​iate)

​​​​Licensing

​MATLAB is available, free of charge, to all University members under a Total Academic Headcount agreement. The licensing is managed by IT services; what follows is a summary of the licensing options available. Full details on the licensing agreement and available toolboxes is available on the Engineering Science MATLAB page. 

​Where will I be running MATLAB?

1. Centre iMacs, Jalapeno Cluster ('''NOT''' jalapeno.fmrib.ox.ac.uk)
   These machines use a license server provided by IT Services to provide the necessary license and the installation is maintained by the WIN computing staff.
   Please contact computing-help@win.ox.ac.uk if you have any issues.
2. Personally owner or operated computers should use MathWorks individual licenses - see https://eng.ox.ac.uk/matlab/install/
3. Devices needing MATLAB without access to the internet or critical operation - these devices need a standalone license. Please contact computing-help@win.ox.ac.uk for assistance with this.

​Compiling MATLAB functions​

The main restriction on MATLAB use i​​s the availability of licenses for toolboxes or the MATLAB environment itself - whilst this is not generally an issue under the campus agreement it is of use where you wish to run a significant number of tasks across the cluster or to distribute code to third-parties who may not have access to MATLAB.

By compiling your MATLAB code you free yourself from any licensing restrictions, so can run as many instances as you require. There are also some performance advantages when the software is stored on a network resource (although the main workload will be no faster than in the interactive MATLAB environment). Compilation is a relatively straightforward process and is detailed here. Be aware that the binary program that this procedure produces will ONLY run on the platform you compiled it on, eg if you compile on a macOS computer it will not run on our Linux based compute cluster. 

Using D​​eploytool

​MATLAB includes a tool to ease the compilation process called `deploytool`. Launch this from within a MATLAB prompt: 

   
   deploytool

This will open a new sub-window, offering to create a new or open and old project. Give your new project an appropriate name, specify where to save the project and then choose Standalone Applicati​on to produce a single executable program.

Click OK In the next window, click on Add Main File in the Build tab. Navigate to and select your primary .m file containing the function to be compiled. Now click on Add files/directories in the Shared Resources and Helper Files section and add any additional MATLAB function files not on your current MATLAB path or any functions you call using eval (the compiler will automatically include functions on your path, but cannot find those called via eval). 

Now click on the Package tab and you will see a list of the files that will be included in the compiled package. You can use the Add files/directories button to include additional resources in the package and Add MCR to include the MCR installer too (MCR - MATLAB Compiled Runtime - this is a cut down non-interactive version of MATLAB that is required to be installed on the machine that will run the compiled code. You need the version specifically produced for the MATLAB release used to compile the code, this option will include the required MCR installation package with the compiled code).

Once you are happ​y you have everything you need click on the build button (box with three downward pointing arrows). A progress window will open and after a minute or two the package will be created in the folder you specified at the start.

Running the Compiled Program​ 

After packaging, you will find a folder named the same as the project with two sub-folders, distrib and src. The runnable program can be found in the distrib folder. To run, the c​ompiled program needs to be able to find the correct version of the MCR. You can add the paths specified when you installed the MCR to your LD_LIBRARY_PATH environment variable, but to avoid this hassle, the package includes a shell script that will do all of this for you. If your function is called my_function (stored in the file my_function.m) then you will find a script called run_my_function.sh (along with the binary program my_function and a readme.txt file detailing how to use your program). To call your program use: 

cd my_function/distrib
   ./run_my_function.sh /opt/fmrib/MATLAB/MATLAB_Compiler_Runtime/v717 arg1 arg2 ...

Replacing ​/opt/fmrib/MATLAB/MATLAB_Compiler_Runtime/v717 with the path to the MCR for the version of MATLAB used to compile the code and providing the function arguments as space separated values.

Using Makefiles

It is also possible to create Makefiles which allow compilation in a easily repeatable and scriptable fashion. For example:

.PHONY : all
.PHONY : directories

MKDIR_P=mkdir -p

# Where is the MATLAB folder?
MATLAB_DIR=/opt/fmrib/MATLAB/R2017a
# And the MATLAB command within...
MATLAB=$(MATLAB_DIR)/bin/matlab
# Where is the MATLAB compiler?
MCC=$(MATLAB_DIR)/bin/mcc
# Options to use when calling MATLAB - '-nodisplay' is a minimum
MOPTS=-nodisplay
# Options to use when calling the compiler - '-m' is the minimum
# -v turns on verbose output
# -R xxx passes 'xxx' as an option to the runtime when the program is run
#   some acceptable values are:
#   -nodisplay
#   -nojvm
# See https://uk.mathworks.com/help/mps/ml_code/mcc.html
MCCOPTS=-mv -R -nodisplay
OUTDIR=compiled
OS=$(shell uname -s)
ARCH=$(shell ​uname -m)

# If you use a common library of functions in a folder outside of your sources point this variable to it:
MYLIB=/path/to/my/utils/folder
MYOTHERLIB=/another/library/used/by/myscript_2

MYSCRIPTS=myscript_1 myscript_2

all: directories MCR $(REQ_MODS)

MCR:
	$(eval MCRV := $(shell echo "$(MATLAB) $(MOPTS) \
	 -r \"[maj,min,upd,pt] = mcrversion; \
	 if upd ~= 0, disp(sprintf('MCR=%d%d', maj, min, upd)); \
	 else; disp(sprintf('MCR=v%d%d', maj, min)); end\"" | \
	 sh | grep "MCR=" | awk -F"=" '{ print $$2 }'))
ifeq ($(OS),Darwin)
	$(eval mccdeploydir := maci64)
else
ifeq ($(OS),Linux)
ifeq ($(ARCH),x86_64)
	$(eval mccdeploydir := glnxa64)
else
&tab;$(eval mccdeploydir := glnx86)
endif
else
	echo "Platform unknown"
	false
endif
endif

	$(eval RTI := ${MATLAB_DIR}/toolbox/compiler/deploy/$(mccdeploydir)/MCRInstaller.zip)
	if [ -f ${OUTDIR}/MCRInstaller.zip ]; then \
	rm -f ${OUTDIR}/MCRInstaller.zip; \
	fi
	cp $(RTI) ${OUTDIR}/
	echo $(MCRV) > MCR.version

directories: ${OUTDIR}

${OUTDIR}:
	${MKDIR_P} ${OUTDIR}

myscript_1: myscript_1.m
	${MCC} $(MCCOPTS) -I ${MY_LIB} -d ${OUTDIR} $<

myscript_2: myscript_2.m
	${MCC} $(MCCOPTS) -I ${MY_LIB} -I ${MY_OTHERLIB} -d ${OUTDIR} $<

N.B​ Indented lines must begin with a TAB character - this is unlikely to be copied over if the above is copy/pasted.​

With a suitably written Makefile you can then build the compiled version with:

make​​

​​issued in the source folder. This will create a folder compiled putting a copy of the MCR and the compiled scripts within held in platform/architecture subfolders, e.g. Darwin/x86_64​ for a macOS machine. See the MCC pages for details on compiler options.

Gotc​has

​There are several things you must be aware of when compiling code - check the MATLAB documentation for information (http://www.mathworks.co.uk/help/compiler/compiler-tips.html is especially useful). But a quick list include:

• Variables passed on the command line are text, so when passing numbers you need to convert them in your program - use isdeployed to limit this conversion to compiled versions:
  if (isdeployed) arg1 = str2num(arg1) end
• Functions called through eval cannot be automatically included by the compiler - make sure you add them specifically to the project.
• The MATLAB path is baked into the binary, so you can't addpath in your script - to add code from different folders, add the .m files to the project (or ​​-I​​​​ options in the Makefile. 

MCR

All compiled MATLAB programs require access to the MATLAB Compiler Runtime (MCR), which is a package of shared libraries that are required to be installed somewhere on the computer you will be using to do the computation. You have to match the ve​​​rsion of the MCR to the version of MATLAB that you compiled the software with. The cluster has the MCR installed in /opt/fmrib/MATLAB/MATLAB_Compiler_Runtime. To find out the which version you need and where you can find the installer for installation on other machines, use the MATLAB command `mcrinstaller`. MATLAB2012a, for example, requires version 7.17 of the MCR, so programs generated from that version of MATLAB will need to use /opt/fmrib/MATLAB/MATLAB_Compiler_Runtime/v717, MATLAB2014a needs /opt/fmrib/MATLAB/MATLAB_Compiler_Runtime/v83.

Any software compiled with MATLAB needs a wrapper script that sets up two environment variables - this should have been created for you by the compiler.