Jobs or Workflow Components in matlab

TODO: update mcr version number, 64 bits and make doc consistent in the documentation

It is possible to run matlab programs on the grid as single gris jobs or as components of a workflow.

This requires compiling the matlab code/script/macro to generate an executable program (binary) that no longer needs the matlab interpreter, but only the Matlab Compiled Runtime ( MCR) library. This library is (in principle) pre-installed on the grid worker nodes, so the grid job just has to set the environment properly to use it.

Preparing the matlab program

1. convert your matlab script to a function.
2. Note that input args will come in as strings, you need to convert those to numerical first thing in the function.
3. Eliminate all interactive fuctions (no reading from stdin, only from files)
4. Make all arguments explicit, avoiding usage of environment variables. For example, the name of the file to read (accept complete path).
5. If you use external packages or libraries then... (check: what do do?)
6. How to handle errors??
7. Make sure that the file startup.m is correctly adapted. Specifically, addpath should be differently called. Multithreading must be disabled. See this example: startup.m.

Getting ready

Get access to a system where the compiler (mcc) is installed. In our infrastructure we currently have 1 machine with the matlab environment:

• this is the server at SARA: ui.grid.sara.nl.

1. Join the matlab group at the ui.grid.sara.nl. Send an e-mail to grid.support@sara.nl asking this. To check if you are already a member:

   Login at ui.grid.sara.nl
   Run command groups (will list the groups a user belongs to)

2. Configure the bash enviroment on this account by running the following commands. These can be executed by hand or added to the file ~/.bash_profile.
   • to run matlab or compile a matlab program:

     module load matlab

   • run a compiled matlab program (Optionally, a version number may be added, e.g. matlab/r2009b, and/or mcr/7.11):

     module load mcr

3. Clean and configure the matlab settings in the first time you run:

   cd ~
   rm -rf ~/.matlab
   matlab
   >> mbuild -setup
   (choose option 1)

4. Change your startup.m (example) file. addpath should not be called in deployed (compiled) mode. Also, Matlab by default enables multithreading. This is not allowed when running on the grid! Use these commands to adapt your startup file (see also startup.m):

% are we in non-compiled mode?
if ~isdeployed
addpath(genpath(~/matlab)) % recursively add matlab path
end
% disable multithreading
maxNumCompThreads(1)

Compiling the program

1. If you haven't added matlab to ~/.bash_profile, load matlab environment:

   module load matlab/r2009b

2. Get a matlab function, for example

   cp /opt/matlab2009b/extern/examples/compiler/magicsquare.m .

3. Compile the function

   mcc -R singleCompThread -m magicsquare.m

This will generate the file magicsquare (among others), which is the binary program. See also the generated file readme.txt for more info.

Running the program

To run the program it is necessary to configure the run time environment (if you haven't already configured so in ~/bash_profile):

module load mcr/7.11
./magicsquare 3

Currently we have 1 UI machine on the Grid that supports the mcr library:

1. ui.grid.sara.nl

Running the program as a grid job

Need to

1. make a shell script file (magicsquare.sh) to load MCR and run magicsquare: magicsquare.sh
2. make a jdl (job description file): magicsquare.jdl
3. Test which CEs are available that meet your needs and have correct and working MCR installation. See an useful tool to test this on a grid UI system. (download the zip file containing a matlab binary, jdl and submission script and other useful tools).
4. Adapt your jdl-file so that only those CEs are included that have a working MCR, see for an example: coregDataset1to2.jdl

NOTE: we are currently missing a requirement tag that just selects the right CEs for us. This may come after transition of all CEs to 64bit.

Running as a workflow component

TODO

Notes and Tips

• you might have problems to run matlab or the compiler, since the number of licenses available is limited.
• matlab, mcc and the compiled program try to show graphics on the device given by the bash environment variable DISPLAY. This is no problem if you have an X-client running on your workstation. Otherwise, you'll get an error ("broken pipe") or see nothing. You can tell matlab to work on non-graphical mode by setting the DISPLAY variable to null:

  export DISPLAY=
  matlab

• first try to run the compiled program locally, testing it fully.
• you need MCR (matlab component runtime) installed on the worker node of all clusters you're using to run the job.To our knowledge the environment is currently installed on all nodes of the vlemed VO. Contact us when you experience difficulty running matlab jobs on the grid.

Useful links & docs:

• SARA's wikipage on matlab jobs
• Matthan's notes
• General Executor