MATLAB® Compiling & Running on CBI Cluster

May 25th, 2012 By: CBI Development Team

Overview

The Matlab® Compiler & Deployment Tool Compiling benefitsDesigning your code for compilationCompilation example( Example workflow )Running compiled .exe on CBI clusterHands-on training

Compiler Toolbox Overview Framework to package .m code as a native executable or shared

library.

Matlab® Compiler Runtime(MCR) provides access to Matlab® functionality from the native operating system executable wrapper or from a shared library.

No royalties/Matlab® licenses needed to use the exe + MCR infrastructure.[30,31]

Multi-platform ( Linux, Windows, Mac )

Deployment Tool is a GUI front-end to the Matlab® compiler + build tools command line (mcc,mbuild).

Most functions can be deployed. Some exceptions apply, mostly due to toolbox functions that generate .m code dynamically at runtime.

Compiler Toolbox Overview Version 4 of the Compiler Toolbox:

– An encrypted .m file + C wrapper + run-time interpretation model[7],[9]

– Executable wrapper calls functionality within Matlab® Compiler Runtime shared library.

– A great resource for enabling high throughput computing with Matlab® codes, allowing many distributed jobs to be submitted to the CBI cluster without using Matlab® licenses.

– Performance: Should expect similar runtime to running Matlab® from the command line.[7]

– GUI interface called Deploytool.

Deploytool

Deploytool is a GUI Tool that simplifies the process of creating executable projects.

File--> New--> Deployment ProjectAllows you to select

files to deploy

Key Benefits Summary

Minimize Matlab® + Toolbox license utilization in a grid settingDeploy to users without a Matlab® license(MCR Installer + Your Deployed Code)Enable High Throughput Computing solutionsIntellectual property: Deploy proprietary closed source algorithms securelyDeploy to multiple platforms( Linux, Windows, Mac)Ability to use functionality from most toolboxesLeaves open the possibility of speed improvements by incorporating custom C/C++ code via the MEX interface.

Code Design: Background on Internal Infrastructure

.m

.c/.cpp

mcc,mbuild,gcc

libmwmclmcrrt.so.7.15

Interface to shared modules:MCLMCR,MCR, ...

ELF_64 format

ExecutableWith CTF

Archive data

Linux uses the ELF format file

to create a process

The above diagram is based on research from the following sources: [3],[4],[17],[18]

Code Design: Background on Internal Infrastructure

Code Design Points Convert your script code into functional form, or wrap your script with

a function.

Argument processing: use str2num function for numeric parameters

Output handling: Only 2 ways to get your output

– Standard output or File I/O

Toolbox utilization: Check whether your toolbox functions are deployable.[13]

Must compile on the same OS version where software to be deployed

Do you dynamically generate Matlab® code? Generate your dynamic code and then compile different versions of the dynamic code to enable compiling your project.

Code Design Points Avoid using relative paths, instead allow for user to provide absolute

path as a parameter or to provide for an absolute path to a parameter file.

Using .mat data files within your deployed project: You can embed the .mat data files within the Component Technology File (CTF) archive.

– RuntimeFolder = ctfroot;

Avoid calling help, edit, doc commands in compiled code( See Compiler Toolbox User's Guide for more info )[1]

You can display figures in compiled version, however make sure to disable figure display for running in batch mode on the cluster.

Example Workflow Create a top level

function for your project

Note how in the non-compiled environment, Matlab® automatically treats rows and cols as numeric data types

In the compiled version we can only get results via standard output or via a file.

Will this work in the deployed standalone executable? Why/Why Not?

Example Workflow Key changes:

1) isdeployed check

2) str2num

3) sending results to standard output

4) We could also have sent the results to a file... more on this later.

Example Workflow Go to File, New, Deployment Project

Then, create a new deployment project

Example Workflow When creating a deployment project, there are a few options:

– Standalone Application, C/C++ Shared Library, Java Package

– For grid deployment @ CBI Cluster, you will normally use the Standalone Application option.

Example Workflow Normally, the only file that needs to be added is the top level

function for the project.

Many more things can be added to the CTF archive in more advanced setups.

Build Button

Example Workflow After the top-level function file is added, click on the build button.

The Build window will pop-up, and 2 directories will be created within the current working directory: distrib, and src directories

Example WorkflowPackaging: Allows the inclusion of the MCR Installer within a single

installable package. However, the MCR is over 200 MB. This stage is not needed to run @ CBI since the MCR is already installed at: /share/apps/matlab2011a

Creating a package with the MCR installer included is a good idea, in case you want to deploy it to a system that does not have the MCR.

( Note: As of R2012a, MCR can be downloaded directly from Mathworks @ http://www.mathworks.com/products/compiler/mcr/index.html )

Example Workflow: Running Standalone exe @ CBI

How is the exe called? Is it called directly?

An auto-generated .sh script is created during the deployment process. It sets up the the environment variable containing the path to the MCR shared library( In Linux, its the LD_LIBRARY_PATH environment variable )

The wrapper script sets environment variables and then calls the executable.

Example Workflow: Running Standalone exe @ CBI

Creating a job script for the Sun Grid Engine @ CBI

The script takes the 1st parameter given to it and uses it to update the LD_LIBRARY_PATH environment variable.

It then passes subsequent parameters to the executable as strings. ( Remember about why we need to use str2num in the Matlab® code )

Example Workflow: Running Standalone exe @ CBI

Submitting the job:

Hands-On Example

Hands-On Example High Throughput Mandelbrot

Set Image Generation via Deployed Executable Matlab® Application + Sun Grid Engine running @ CBI Cluster.

Compile as Standalone executable

Submit multiple jobs to the CBI Cluster, each with a different set of parameters.

The Sun Grid Engine can then schedule these jobs to run concurrently.

Hands-On Example High Throughput Mandelbrot Set image generation:

– This batch processing pattern is used by many types of

workflows.

– Running the same code with different

parameter sets.

Code Design Overview for Compilation

– Using parameter files

– Saving data as images

Deploying the Matlab® code packaged as a standalone executable

Running from Linux command line

Using the Sun Grid Engine to a submit a single job using the executable

Using the Sun Grid Engine to submit a set of jobs using the job array feature

We've successfully helped a number of users greatly reduce their project runtime expectations via this Standalone executable + Grid deployment workflow. Can make infeasible projects possible!

CBI Laboratoryhttp://cbi.utsa.edu

Development team:

Zhiwei Wang, Director

David Noriega, Yung Lai, Jean-Michel Lehker, Nelson Ramirez

References[1]http://www.mathworks.com/help/pdf_doc/compiler/compiler.pdf( Product documentation )

[2]http://www.mathworks.com/help/toolbox/compiler/bsfez67.html( dynamic code generation not supported )

[3]http://www.mathworks.com/help/toolbox/compiler/bsfey7f.html ( diagram#1, build process )

[4]http://www.mathworks.com/help/toolbox/compiler/f2-995712.html (diagram#2, build process )

[5]http://www.mathworks.com/help/toolbox/compiler/f13-1003481.html ( preferable to use a functional form )

[6]http://www.mathworks.com/support/solutions/en/data/1-QXFMQ/index.html?product=CO&solution=1-QXFMQ ( addpath info )

[7]http://www.mathworks.com/support/solutions/en/data/1-1ARNS/index.html?product=CO&solution=1-1ARNS ( performance vs regular matlab, changes from version 3 to 4)

[8]http://www.mathworks.com/help/toolbox/compiler/bs_kqkf.html( Compiler toolbox also works for MacOS)

[9]http://www.mathworks.com/help/toolbox/compiler/rn/bqnylfk-1.html (Version 4 differences from Version 3 of the Compiler Toolbox )

[10]http://www.linuxjournal.com/content/embedding-file-executable-aka-hello-world-version-5967( You can embed data within executables )

[11]ttp://www.mathworks.com/help/toolbox/compiler/rn/bqnylfk-1.html#f6-52806( Compiler version 4 overview )

[12]http://www.mathworks.com/products/compiler/requirements.html( Compiler supported on Linux,Mac,Windows )

[13]http://www.mathworks.com/products/compiler/compiler_support.html ( Compiler toolbox support information, cannot be compiled info for each toolbox )

[14]http://www.mathworks.com/support/compilers/R2011b/maci64.html#matlab ( Supported native compilers )

[15]http://www.mathworks.com/help/toolbox/compiler/btcdq67.html ( licensing terms of compiled apps )

[16]http://www.mathworks.com/help/toolbox/compiler/br2cqa0-20.html ( unsupported functions )

[17]http://www.mathworks.com/help/toolbox/compiler/f2-972343.html#bsic1of-2( diagram#3, build process)

[18]http://www.mathworks.com/help/toolbox/compiler/bsfey7f.html#bsfj66v-1(diagram#4, build process)

References[19]http://www.mathworks.com/help/toolbox/compiler/f2-972343.html( C code integration )

[20]http://www.mathworks.com/help/toolbox/compiler/ismcc.html ( startup.m information )

[21]http://www.mathworks.com/products/compiler/demos.html( compiler demos on Windows )

[22]http://blogs.mathworks.com/loren/2011/04/21/deploying-multiple-c-shared-libraries/#2 ( Using deployed shared library from C++ )

[23]http://www.nmr.mgh.harvard.edu/martinos/itgroup/deploytool.html#TOC ( deploytool guide )

[24]http://www.linuxjournal.com/article/1060 ( Linux ELF file format )

[25]http://mathtools.web.cern.ch/node/20( Matlab compiler user guide from CERN )

[26]http://www.mathworks.com/support/tech-notes/1600/1608.html#Section_4 ( Deployment guides )

[27]http://www.mathworks.com/support/solutions/en/data/1-2YVMOV/index.html ( Web deployment guide )

[28]http://www.mathworks.com/support/solutions/en/data/1-WK5DJ/index.html?solution=1-WK5DJ( Web deployment guide)

[29]http://www.mathworks.com/support/solutions/en/data/1-30REEY/index.html?solution=1-30REEY( Web deployment guide)

[30]http://www.mathworks.com/products/compiler/ ( License terms )

[31]http://www.mathworks.com/help/toolbox/compiler/br5w5e9-2.html (License terms )

[32]http://www.mathworks.com/support/tech-notes/1600/1605.html#intro ( MEX interface, gcc version requirements )

Trademarks: http://www.mathworks.com/company/aboutus/policies_statements/trademarks.html