Tested in MATLAB version v8.3 (R2014a) using MATLAB Compiler Runtime MCR '/cluster/matlab/8.2'
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.
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.
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.
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.
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.
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_85and 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.
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.
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
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 -nojvmThen 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)
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.
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.
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
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
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:
>> rununwarp1This 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.
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
Back to top.