Example Deploying MATLAB script for Launchpad

This page demonstrates with simple examples how a MATLAB script can be designed to be deployed (compiled) so that it can be run on the Martinos Launchpad without requiring a MATLAB license. Instructions for actually deploying the script can be found here.

Disclaimer

Tested in MATLAB version v8.3 (R2014a) using MATLAB Compiler Runtime MCR '/cluster/matlab/8.2'



Example 1: Very simple script

Step 1: Write the script

This example uses the MATLAB data file 'sunspots.dat' and performs a Fast Fourier Transform (FFT) on it to produce a frequency spectrum of the sunspot data which is then just printed to the screen.

		function DeployTest(outfile)
		% DEPLOYTEST Test DeployTool
		% Simple function to test the deploytool
		% Example program copied from 
		% http://www.mathworks.com/help/matlab/examples/using-fft.html
		% Deployment procedure found at
		% http://nmr.mgh.harvard.edu/martinos/itgroup/deploytool.html

		  load sunspot.dat;
		  year=sunspot(:,1);
		  relNums=sunspot(:,2);
		  y=fft(relNums);
		  y(1)=[];

		  fid=fopen(outfile,'w');
		  fprintf(fid,'Running DeployTest\noutfile = %s\n',outfile);

		  for i=1:length(y)
		    fprintf(fid,'%+08.3f  +  %08.3f\n',real(y(i)),imag(y(i)));
		  end

		  fprintf(fid,'DeployTest done!\n');
		  fclose(fid);

		end

Note how the function takes only a plain text input argument, the name of the output file, and it writes all its outputs to the file 'outfile' to avoid interfacing with the unix environment.

Step 2: Test the script in MATLAB environment

First we test it in the MATLAB environment to check for any syntax errors.

    >> DeployTest('outfile.txt');
    

Note that we call the MATLAB function DeployTest(), not the file DeployTest.m and thus leave off the ".m" extension.

Step 3: Test on unix command line

Next we test it from the unix command line. Make sure to cd to the directory containing DeployTest.m because you cannot put the path in front of the MATLAB function.

  % matlab -nosplash -nodesktop -nodisplay -nojvm -r "DeployTest 'outfile.txt'; exit;"

Note do not use '(' parentheses ')' around the argument list, pass single-quoted whitespace separated strings. The [optional] final exit is to exit MATLAB after the script is done.

Step 4: Deploy the script

Next we deploy ("compile") the function. Open MATLAB and at the MATLAB prompt type

  >> deploytool

This produces a pop-up window to choose between Application Compiler and Library Compiler, the latter being beyond the scope of this document, select Application Compiler. This will open the Deploytool window. with the APPLICATION TYPE preset to Standalone Application.

For MAIN FILE Add main file click the big plus and browse to our script ~/matlab/DeployTest/DeployTest.m

Under PACKAGE click the Package check mark to deploy your script.

This will create an xml-format project file called DeployTest.prj, and a folder at ~/matlab/DeployTest/DeployTest/ inside of which you will find three subdirectories called
~/matlab/DeployTest/DeployTest/for_redistribution/,
~/matlab/DeployTest/DeployTest/for_redistribution_files_only/, and
~/matlab/DeployTest/DeployTest/for_testing/
.

Inside the for_testing/ subdirectory you will find the shell script run_DeployTest.sh. This is your deployed MATLAB function as a shell script.

Step 5: Run the deployed script

Before you run the script, make sure you set the MATLAB Compiler Root MCR environment variable with:

  setenv MCR '/usr/pubsw/common/matlab/8.2'

Now to run the compiled script type:

  cd ~/matlab/DeployTest
  DeployTest/for_testing/run_DeployTest.sh $MCR 'outfile.txt' 

Note how we pass the argument 'outfile.txt' without '(' parentheses ')' like a unix shell script argument.

Step 6: Running on the launchpad

Next we ssh to launchpad to submit it as a launchpad job. Be careful when testing between launchpad and your normal host that you don't accidentally run a big script at the launchpad command line instead of submitting it as a job, the launchpad should not be used in this manner. To avoid this problem I insert this line in my .cshrc file:

		if ( $HOSTNAME == 'launchpad' ) then
			set prompt = "launchpad-> "
		endif
    

to make the prompt look distinctive on the launchpad.

To launch the script as a pbs job type the command:

launchpad-> pbsubmit -c "DeployTest/for_testing/run_DeployTest.sh $MCR 'outfile.txt';"

Note that 'launchpad-> ' is just the prompt that we defined, not part of the command. The -c argument of pbsubmit takes the command that is to be launched, which is our shell script that runs the deployte MATLAB script, followed by $MCR the MATLAB Compiler Runtime, and finally 'outfile.txt' is the argument passed to the script. Do not be dismayed if the file 'output.txt' does not appear immediately, despite the fact that this simple script takes barely a second to run, the output file does not appear until perhaps 30 seconds later. This command returns the 'job number' of the launched job, e.g.

  Opening pbsjob_85
and the job number can be used to retrieve information on the job, including its status, the output it generated while running, whether there was an error (non-zero status value), and the error output.


Example 2: Script with 'addpath' functionality

WARNING! I could not get this to compile successfully. For work-around see next example.

MATLAB scripts that are to be deployed may not use addpath, instead, paths that are not on the MATLABPATH are accessed through the deploytool interface, as shown in this example. This script performs a nonlinear unwarping on MRI images from the connectome scanner (Bay 8) using Jonathan Polimeni's unwarping script which is written in MATLAB.

This script has three addpath calls which are placed in an if block so that they are only called if the script is NOT deployed. That way the script can be called with or without being deployed. When we deploy this script we will have to perform the addpath functionality using the deploytool interface.

Step 1: Write the script

    function unwarpone(infile,outfile,logfile)
    % Unwarp just one image using Jonathan Polimeni's function
    % mris_gradient_nonlin__unwarp_volume__batchmode_HCPS()

        gradfile = 'coeff_AS302.grad'; % The gradient file for Connectome magnet

        % Open log file
        fid=fopen(logfile,'w');
          fprintf(fid,'In unwarpone %s\n',datestr(now,31));
          fprintf(fid,'infile:   %s\n',infile);
          fprintf(fid,'outfile:  %s\n',outfile);
          fprintf(fid,'logfile:  %s\n',logfile);

        % If script is not deployed (MATLAB compiled) then add paths
        % (Forbidden to addpath in deployed scripts)
        if isdeployed==0;
          addpath /cluster/freesurfer/centos6_x86_64/dev/matlab;
          addpath ~nummenma/matlab/work/connectome/HCP_preproc_tools;
          addpath /cluster/freesurfer/centos6_x86_64/dev/gradient_nonlin_unwarp
        end;

        %%%% UNWARP %%%%
        mris_gradient_nonlin__unwarp_volume__batchmode_HCPS(infile, outfile, gradfile);
        fprintf(fid,'Unwarpone DONE! %S\n',datestr(now,31));
        fclose(fid);
    end
		

Step 2: Test script in MATLAB environment

First lets test the script in the MATLAB environment. First we set the FREESURFER environment required for this unwarping by typing 'nmrenv' or

 
    source /usr/local/freesurfer/nmr-stable53-env"
    

Then we open MATLAB

    matlab -nosplash -nodisplay -nodesktop -nojvm
Then we do the unwarping:
  >> imgwarped = '/space/ficus/4/users/SLOTS_sessions/SLOTS023/aahscout/001/001.mgz'

  >> imgunwarped = '/space/ficus/4/users/SLOTS_sessions_unwarp/SLOTS023/aahscout/001/001.mgz'

  >> logfile = '/space/ficus/4/users/SLOTS_sessions_unwarp/SLOTS023/aahscout/001/unwarp.log'

  >> unwarpone(imgwarped,imgunwarped,logfile)
    

Step 3: Deploy the script

Next we deploy ("compile") the function. Open MATLAB and at the MATLAB prompt type

  >> deploytool

This produces a pop-up window to choose between Application Compiler and Library Compiler. Select Application Compiler. This will open the Deploytool window. with the APPLICATION TYPE preset to Standalone Application.

For MAIN FILE Add main file click the big plus and browse to our script ~/matlab/unwarp/unwarpone.m Click the SETTINGS gear icon to change the location of your script, if required. Under Additional parameters passed to MCC: you can add additional flags to the MCC command.

This is where you insert the addpath functionality!

I inserted the additional paths in the Settings window as shown below.

Note that I had to change the relative path ~nummenma/ to an absolute path /homes/14/nummenma/ to get it to compile.

Nevertheless this project failed to link to the added paths!

For a work-around see the next example.


Example 3: Using "Wrapper" script

The addpath functionality through the deploytool interface seems to introduce complications. There is a simple solution and that is to write a "wrapper" script to call our script which does not have any input arguments, and it reads its arguments from a text file with a pre-determined filename, in this example 'unwarpfiles.txt', which in this case contains a single line:

/space/ficus/4/users/SLOTS_sessions/SLOTS023/flair/021/001.mgz

Step 1: Write the script

		function rununwarp1()
		% RUNUNWARP
		% Wrapper to call unwarpone(infile, outfile, logfile);
		% Calling MATLAB functions from the unix command-line or script can be problematic
		% when passing arguments to the called function. This wrapper takes no arguments
		% but finds the filenames to unwarp in a file 'unwarpfiles.txt' in this directory.
		%

			fid=fopen('unwarpfiles.txt','r');

			line=fgetl(fid);
			while ischar(line) && ~isempty(line)
				infile=line;
				outfile=regexprep(infile,'SLOTS_sessions','SLOTS_sessions_unwarp');
				logfile=regexprep(infile,'001.mgz','unwarp.log');
				unwarpone(infile,outfile,logfile);
			end
		end
    

Step 2: Run the script in MATLAB environment

The FreeSurfer functionality of the unwarping requires setting up the FreeSurfer environment in advance, either by typing 'nmrenv' or

 
    source /usr/local/freesurfer/nmr-stable53-env"
    
Then open MATLAB and at the MATLAB prompt type:
>> rununwarp1
This worked for me, at least for a smaller image. However when I tried it on a larger T2 image (t2_spc_da-fl_sag_p2_iso_0.9) it failed with this error:
		==> [mris_gradient_nonlin__spharm_evaluate]: calculating displacements (in mm) using spherical harmonic coefficients...

		start time: 23-Oct-2014 17:39:11

		  computing displacements along x
			Out of memory. Type HELP MEMORY for your options.
    

I suppose I should put in a request to the help desk to increase the swap space on my computer. In the meantime let us compile this script because on the launchpad you can request more virtual memory for your job.

Step 3: Deploy the script

Next we deploy ("compile") the function. Open MATLAB and at the MATLAB prompt type

  >> deploytool

This produces a pop-up window to choose between Application Compiler and Library Compiler. Select Application Compiler. This will open the Deploytool window. with the APPLICATION TYPE preset to Standalone Application.

For MAIN FILE Add main file click the big plus and browse to our script ~/matlab/unwarp/rununwarp1.m


Example 4: Using "Wrapper" script with "consumable" text file

Back to top.