Users.Matlab.Compiler

About the use of the Matlab compiler for WavePacket

Note that the following text may be outdated. In fact, the use of the Matlab compiler hasn't been tested by us for a number of years.

A typical problem: You have this cool new cluster with 100 high-end processors that you would like to use to run 100 jobs in parallel, but you only have 10 Matlab licenses. What now?

The best solution is to compile 100 simulations to 100 stand-alone applications, and run these applications on your cluster. Matlab comes with a compiler that can do this. Unfortunately, the documentation is much more complicated than the actual use of the compiler, and, well, does not document some details very well. So this HowTo contains the essential information to get you up and running.

I assume that you use a Unix shell, if you do the compilation under Windows, the things might turn out to be slightly different. Throughout the text, I use the following variables:

Variable	contents
$OUTDIR	the directory where you output the executable and all the temporary files to
$WAVEPACKETDIR	the directory where WavePacket is installed
$INITFILE	The full path to the file initialize.m that contains your setup
$MATLABDIR	the directory where you have installed Matlab to
$MCRDIR	the directory where the MCR resides (MCR = Matlab Compiler Runtime)

Requirements

To compile a program, you need to meet the following requirements:

• you need at least MatLab 7.5 installed (the compiler in previous versions is more or less broken)
• You need to have the MatLab compiler installed and set up (if the directory $MATLABDIR/toolbox/compiler exists, you do have it installed)
• The installed MatLab version must be on the same operating system and processor type as the nodes you later want to run the compiled program on

License

The MatLab license explicitely allows the distribution of the compiled program under relatively generous terms. See $MATLABDIR/license.txt, Deployment addendum, section 5.1 (towards the very end of the file).

Note that I am not a lawyer, and I have not read the whole license, but it seems that the use sketched in the overview is not only possible, but even legal and intended.

Using the Compiler

It is actually very easy to use the compiler. The sequence is

• Compile your program
• Install the MatLab runtime libraries (MCR)
• Execute the program

I have verified this for WavePacket 4.7.2, using the PlanePendulum/Coherent/pi1 demo and a Solaris MatLab 7.5. If something fails for you, just send a mail to the list. Here I only give the recipe

Compilation

• Create the output directory

  mkdir $OUTDIR

• Switch to the wavepacket source directory

  cd $WAVEPACKETDIR/Sources

• Compile qm_propa with your setup as initialization function, and dump the content in the output directory; verbose output

  mcc -m -v -d $OUTDIR qm_propa $INITFILE

If you need to include some additional files, just append them to the commands.

The output directory now contains various files. The only important ones are an executable called ''qm_propa'' and a shell script called ''run_qm_propa.sh''.

Install MCR libraries

Note: Every MatLab installation comes with a full set of runtime libraries in the correct paths. If the nodes that you run your program on can access the MatLab directory, you do not need to install the runtime libraries, and just replace $MCRPATH by $MATLABPATH when running your program.

• Create the directory where you want to install the runtime libraries to

  mkdir my_mcr_dir

• Copy the MCR installer to the target system and execute it. The installer is located under $MATLABDIR/toolbox/compiler/deploy/<system name="">/MCRInstaller.bin. As installation directory you give the directory that you just created. (the installer comes with a graphical installation client, and eats up around 1 Gigabyte of space)</system>

The runtime libraries (that is, the value of $MCRDIR) are now located under a directory like my_mcr_dir/v75.

Run the program

• Go to the output file, and execute

  sh run_qm_propa.sh $MCRDIR

The program should now just run through. If you have problems, a mail to ulf82@users.sf.net should solve them. :)

Tips and Caveats

• The compiler is rather slow. Compiling a simple program can easily take a minute.

• If your program uses graphical output, it will not finish until you close the windows that popped up. It is a good idea to put the following lines in your initialize.m file to disable graphical output

  plots.expect.on = false;
  plots.density.on = false;

• If you start the calculations manually by logging in to the remote server via ssh and executing the shell scripts, you should explicitly forbid X11-forwarding in the ssh connection ("-x") unless you need the graphics. The reason is that the executables will try to get hold of an X11 screen, and consequently crash once you close or interrupt the ssh session. If you do not offer an X11 server to start with, graphics will be silently disabled.