You are here: Home Help/User Support Parallel Computing in the CAE Lab Cluster Job Example: MATLAB

Cluster Job Example: MATLAB

MATLAB

Any MATLAB .m file can be run in the queue. The -r command flag for MATLAB will cause it to run a single command specified on the command line. For proper batch usage, the specified command should be your own short script. Make sure that you put an exit command at the end of the script so that MATLAB will automatically exit after finishing your work. In the example given below, debugging runs of the program on a workstation or in interactive queue runs will print a message when the job is finished, and unattended batch runs will automatically save results in a file based off the job ID and then exit. Failure to include the exit command will cause your job to hang around until its wall clock allocation is expired, which will keep other jobs in the queue longer, and also tie up MATLAB licenses unnecessarily.

Sample MATLAB program (matlabdemo.m)

% Matlab demo for PBS queuing
format long
% Demonstrate roundoff error in floating-point calculations
sum=9
   for n=1:10000
   sum=sum+0.1;
end
for n=1:10000
  sum=sum-0.1;
end
sum
format short

% Save results in unique filename if running in batch. Otherwise, don't.
switch getenv('PBS_ENVIRONMENT')
  case {'PBS_INTERACTIVE',''} % either PBS interactive or non-PBS
    disp('Job finished. Results not yet saved.');
  case 'PBS_BATCH' % PBS batch
    % Save the results
    disp('Job finished. Saving results.')
    matfile=sprintf('matlabdemo-%s.mat',getenv('PBS_JOBID'));
    save(matfile);
    exit
  otherwise
    disp([ 'Unknown PBS environment ' getenv('PBS_ENVIRONMENT')]);
end

Sample qsub command file (matlabdemo.sh)

New for MATLAB 7.4 (r2007a) and later: MATLAB versions earlier than 7.4 (r2007a) were explicitly single-threaded, and never took advantage of multiple processor cores. MATLAB version r2007a and later are automatically multhreaded, and you need to take steps to ensure that your Matlab jobs allocate sufficient resources to run quickly, and to ensure that your Matlab jobs don't take up more resources than you request.

By default, multithreading versions of Matlab will detect how many cores are on the compute node, and create an equal number of threads. While this is an acceptable default for single-user systems, for shared nodes, this can create huge performance penalties for all jobs on the node. On a quad-core node, if four users submit Matlab jobs, and each automatically creates four threads, then the node ends up running 16 threads at once, and runs them all at 25% efficiency. To keep Matlab jobs from interfering with others' jobs by default, CAE Linux and Solaris systems changed the default number of threads to 1.

To increase your MATLAB jobs' performance, make two changes to the .sh file you use to run MATLAB. First, allocate a particular number of processors with a "#PBS -l nodes=1:ppn=N" line that allocates N nodes (replace N with a positive integer between 1 and 8, preferably 2, 3, or 4). Second, use the MATLAB maxNumCompThreads command to limit the number of threads MATLAB will create. Use the same value for N in the maxNumCompThreads argument as you used in the "#PBS -l nodes=1:ppn=N" line. For example, if you allocate 4 cores, limit MATLAB to 4 threads.

#!/bin/bash
# Example Matlab job

# Request 1 node with 4 CPUs or cores: recent versions of
# MATLAB parallelize.
#PBS -l nodes=1:ppn=4

# Send mail to address given below when the job begins, aborts, or ends normally
#PBS -m bae
#PBS -M myusername@tntech.edu

# Reserve 24 hours on selected cores
#PBS -l walltime=24:00:00

cd $PBS_O_WORKDIR
#
# Run MATLAB with no GUI elements, no splash screen, no Java
# Virtual Machine. Upon starting MATLAB, create no more than 4
# compute threads, then run the program in matlabdemo.m
#
matlab -nodisplay -nosplash -nojvm \
    -r "maxNumCompThreads(4); matlabdemo"

MATLAB jobs running more threads than they allocated through the queuing system may be killed without warning, to ensure that all jobs run as efficiently as possible. If your job is killed for this reason, you'll be emailed at your TTU email address and directed to this page for further instructions.