Welcome to our Support Center
< All Topics
Print

Matlab Deploytool Example for MLSC

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 MLSC cluster 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 MLSC

Next we ssh to MLSC to submit it as a MLSC job. Be careful when testing between MLSC and your normal linux desktop that you don’t accidentally run a big script on the mlsc login node command line instead of submitting it as a job. To avoid this problem I insert this line in my .cshrc file:

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

to make the prompt look distinctive on mlsc.

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

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

The -c argument of pbsubmit takes the command that is to be launched, which is our shell script that runs the deployed MATLAB script, followed by $MCR the MATLAB Compiler Runtime, and finally ‘outfile.txt’ is the argument passed to the script. The output file does not appear until at least 30 seconds after the job is running.

This command returns the ‘job number’ of the MLSC 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.

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.