Matlab
MATLAB® (MATrix LABoratory) is a high-level language and interactive environment for numerical computation, visualization, and programming. MATLAB is a product of MathWorks.
MATLAB, Simulink, Compiler, and several of the optional toolboxes are available to faculty, staff, and students. To see the kind and quantity of all MATLAB licenses plus the number that you are currently using you can use the matlab_licenses command:
$ module load matlab
$ matlab_licenses
The MATLAB client can be run in the front-end for application development, however, computationally intensive jobs must be run on compute nodes.
The following sections provide several examples illustrating how to submit MATLAB jobs to a Linux compute cluster.
Matlab Script (.m File)
This section illustrates how to submit a small, serial, MATLAB program as a job to a batch queue. This MATLAB program prints the name of the run host and gets three random numbers.
Prepare a MATLAB script myscript.m, and a MATLAB function file myfunction.m:
% FILENAME: myscript.m
% Display name of compute node which ran this job.
[c name] = system('hostname');
fprintf('\n\nhostname:%s\n', name);
% Display three random numbers.
A = rand(1,3);
fprintf('%f %f %f\n', A);
quit;
% FILENAME: myfunction.m
function result = myfunction ()
% Return name of compute node which ran this job.
[c name] = system('hostname');
result = sprintf('hostname:%s', name);
% Return three random numbers.
A = rand(1,3);
r = sprintf('%f %f %f', A);
result=strvcat(result,r);
end
Also, prepare a job submission file, here named myjob.sub. Run with the name of the script:
#!/bin/bash
# FILENAME: myjob.sub
echo "myjob.sub"
# Load module, and set up environment for Matlab to run
module load matlab
unset DISPLAY
# -nodisplay: run MATLAB in text mode; X11 server not needed
# -singleCompThread: turn off implicit parallelism
# -r: read MATLAB program; use MATLAB JIT Accelerator
# Run Matlab, with the above options and specifying our .m file
matlab -nodisplay -singleCompThread -r myscript
myjob.sub
< M A T L A B (R) >
Copyright 1984-2011 The MathWorks, Inc.
R2011b (7.13.0.564) 64-bit (glnxa64)
August 13, 2011
To get started, type one of these: helpwin, helpdesk, or demo.
For product information, visit www.mathworks.com.
hostname:hammer-a001.rcac.purdue.edu
0.814724 0.905792 0.126987
Output shows that a processor core on one compute node (hammer-a001) processed the job. Output also displays the three random numbers.
For more information about MATLAB:
Implicit Parallelism
MATLAB implements implicit parallelism which is automatic multithreading of many computations, such as matrix multiplication, linear algebra, and performing the same operation on a set of numbers. This is different from the explicit parallelism of the Parallel Computing Toolbox.
MATLAB offers implicit parallelism in the form of thread-parallel enabled functions. Since these processor cores, or threads, share a common memory, many MATLAB functions contain multithreading potential. Vector operations, the particular application or algorithm, and the amount of computation (array size) contribute to the determination of whether a function runs serially or with multithreading.
When your job triggers implicit parallelism, it attempts to allocate its threads on all processor cores of the compute node on which the MATLAB client is running, including processor cores running other jobs. This competition can degrade the performance of all jobs running on the node.
When you know that you are coding a serial job but are unsure whether you are using thread-parallel enabled operations, run MATLAB with implicit parallelism turned off. Beginning with the R2009b, you can turn multithreading off by starting MATLAB with -singleCompThread:
$ matlab -nodisplay -singleCompThread -r mymatlabprogram
When you are using implicit parallelism, make sure you request exclusive access to a compute node, as MATLAB has no facility for sharing nodes.
For more information about MATLAB's implicit parallelism:
Profile Manager
MATLAB offers two kinds of profiles for parallel execution: the 'local' profile and user-defined cluster profiles. The 'local' profile runs a MATLAB job on the processor core(s) of the same compute node, or front-end, that is running the client. To run a MATLAB job on compute node(s) different from the node running the client, you must define a Cluster Profile using the Cluster Profile Manager.
To prepare a user-defined cluster profile, use the Cluster Profile Manager in the Parallel menu. This profile contains the scheduler details (queue, nodes, processors, walltime, etc.) of your job submission. Ultimately, your cluster profile will be an argument to MATLAB functions like batch().
For your convenience, a generic cluster profile is provided that can be downloaded: myslurmprofile.settings
Please note that modifications are very likely to be required to make myslurmprofile.settings work. You may need to change values for number of nodes, number of workers, walltime, and submission queue specified in the file. As well, the generic profile itself depends on the particular job scheduler on the cluster, so you may need to download or create two or more generic profiles under different names. Each time you run a job using a Cluster Profile, make sure the specific profile you are using is appropriate for the job and the cluster.
To import the profile, start a MATLAB session and select Manage Cluster Profiles... from the Parallel menu. In the Cluster Profile Manager, select Import, navigate to the folder containing the profile, select myslurmprofile.settings and click OK. Remember that the profile will need to be customized for your specific needs. If you have any questions, please contact us.
For detailed information about MATLAB's Parallel Computing Toolbox, examples, demos, and tutorials:
Parallel Computing Toolbox (parfor)
The MATLAB Parallel Computing Toolbox (PCT) extends the MATLAB language with high-level, parallel-processing features such as parallel for loops, parallel regions, message passing, distributed arrays, and parallel numerical methods. It offers a shared-memory computing environment running on the local cluster profile in addition to your MATLAB client. Moreover, the MATLAB Distributed Computing Server (DCS) scales PCT applications up to the limit of your DCS licenses.
This section illustrates the fine-grained parallelism of a parallel for loop (parfor) in a pool job.
The following examples illustrate a method for submitting a small, parallel, MATLAB program with a parallel loop (parfor statement) as a job to a queue. This MATLAB program prints the name of the run host and shows the values of variables numlabs and labindex for each iteration of the parfor loop.
This method uses the job submission command to submit a MATLAB client which calls the MATLAB batch() function with a user-defined cluster profile.
Prepare a MATLAB pool program in a MATLAB script with an appropriate filename, here named myscript.m:
% FILENAME: myscript.m
% SERIAL REGION
[c name] = system('hostname');
fprintf('SERIAL REGION: hostname:%s\n', name)
numlabs = parpool('poolsize');
fprintf(' hostname numlabs labindex iteration\n')
fprintf(' ------------------------------- ------- -------- ---------\n')
tic;
% PARALLEL LOOP
parfor i = 1:8
[c name] = system('hostname');
name = name(1:length(name)-1);
fprintf('PARALLEL LOOP: %-31s %7d %8d %9d\n', name,numlabs,labindex,i)
pause(2);
end
% SERIAL REGION
elapsed_time = toc; % get elapsed time in parallel loop
fprintf('\n')
[c name] = system('hostname');
name = name(1:length(name)-1);
fprintf('SERIAL REGION: hostname:%s\n', name)
fprintf('Elapsed time in parallel loop: %f\n', elapsed_time)
The execution of a pool job starts with a worker executing the statements of the first serial region up to the parfor block, when it pauses. A set of workers (the pool) executes the parfor block. When they finish, the first worker resumes by executing the second serial region. The code displays the names of the compute nodes running the batch session and the worker pool.
Prepare a MATLAB script that calls MATLAB function batch() which makes a four-lab pool on which to run the MATLAB code in the file myscript.m. Use an appropriate filename, here named mylclbatch.m:
% FILENAME: mylclbatch.m
!echo "mylclbatch.m"
!hostname
pjob=batch('myscript','Profile','myslurmprofile','Pool',4,'CaptureDiary',true);
wait(pjob);
diary(pjob);
quit;
Prepare a job submission file with an appropriate filename, here named myjob.sub:
#!/bin/bash
# FILENAME: myjob.sub
echo "myjob.sub"
hostname
module load matlab
unset DISPLAY
matlab -nodisplay -r mylclbatch
Submit the job as a single compute node with one processor core.
One processor core runs myjob.sub and mylclbatch.m.
Once this job starts, a second job submission is made.
myjob.sub
< M A T L A B (R) >
Copyright 1984-2013 The MathWorks, Inc.
R2013a (8.1.0.604) 64-bit (glnxa64)
February 15, 2013
To get started, type one of these: helpwin, helpdesk, or demo.
For product information, visit www.mathworks.com.
mylclbatch.mhammer-a000.rcac.purdue.edu
SERIAL REGION: hostname:hammer-a000.rcac.purdue.edu
hostname numlabs labindex iteration
------------------------------- ------- -------- ---------
PARALLEL LOOP: hammer-a001.rcac.purdue.edu 4 1 2
PARALLEL LOOP: hammer-a002.rcac.purdue.edu 4 1 4
PARALLEL LOOP: hammer-a001.rcac.purdue.edu 4 1 5
PARALLEL LOOP: hammer-a002.rcac.purdue.edu 4 1 6
PARALLEL LOOP: hammer-a003.rcac.purdue.edu 4 1 1
PARALLEL LOOP: hammer-a003.rcac.purdue.edu 4 1 3
PARALLEL LOOP: hammer-a004.rcac.purdue.edu 4 1 7
PARALLEL LOOP: hammer-a004.rcac.purdue.edu 4 1 8
SERIAL REGION: hostname:hammer-a001.rcac.purdue.edu
Elapsed time in parallel loop: 5.411486
To scale up this method to handle a real application, increase the wall time in the submission command to accommodate a longer running job. Secondly, increase the wall time of myslurmprofile by using the Cluster Profile Manager in the Parallel menu to enter a new wall time in the property SubmitArguments.
For more information about MATLAB Parallel Computing Toolbox:
Parallel Toolbox (spmd)
The MATLAB Parallel Computing Toolbox (PCT) extends the MATLAB language with high-level, parallel-processing features such as parallel for loops, parallel regions, message passing, distributed arrays, and parallel numerical methods. It offers a shared-memory computing environment with a maximum of eight MATLAB workers (labs, threads; versions R2009a) and 12 workers (labs, threads; version R2011a) running on the local configuration in addition to your MATLAB client. Moreover, the MATLAB Distributed Computing Server (DCS) scales PCT applications up to the limit of your DCS licenses.
This section illustrates how to submit a small, parallel, MATLAB program with a parallel region (spmd statement) as a MATLAB pool job to a batch queue.
This example uses the submission command to submit to compute nodes a MATLAB client which interprets a Matlab .m with a user-defined cluster profile which scatters the MATLAB workers onto different compute nodes. This method uses the MATLAB interpreter, the Parallel Computing Toolbox, and the Distributed Computing Server; so, it requires and checks out six licenses: one MATLAB license for the client running on the compute node, one PCT license, and four DCS licenses. Four DCS licenses run the four copies of the spmd statement. This job is completely off the front end.
Prepare a MATLAB script called myscript.m:
% FILENAME: myscript.m
% SERIAL REGION
[c name] = system('hostname');
fprintf('SERIAL REGION: hostname:%s\n', name)
p = parpool('4');
fprintf(' hostname numlabs labindex\n')
fprintf(' ------------------------------- ------- --------\n')
tic;
% PARALLEL REGION
spmd
[c name] = system('hostname');
name = name(1:length(name)-1);
fprintf('PARALLEL REGION: %-31s %7d %8d\n', name,numlabs,labindex)
pause(2);
end
% SERIAL REGION
elapsed_time = toc; % get elapsed time in parallel region
delete(p);
fprintf('\n')
[c name] = system('hostname');
name = name(1:length(name)-1);
fprintf('SERIAL REGION: hostname:%s\n', name)
fprintf('Elapsed time in parallel region: %f\n', elapsed_time)
quit;
Prepare a job submission file with an appropriate filename, here named myjob.sub. Run with the name of the script:
#!/bin/bash
# FILENAME: myjob.sub
echo "myjob.sub"
module load matlab
unset DISPLAY
matlab -nodisplay -r myscript
Run MATLAB to set the default parallel configuration to your job configuration:
$ matlab -nodisplay
>> parallel.defaultClusterProfile('myslurmprofile');
>> quit;
$
Once this job starts, a second job submission is made.
myjob.sub
< M A T L A B (R) >
Copyright 1984-2011 The MathWorks, Inc.
R2011b (7.13.0.564) 64-bit (glnxa64)
August 13, 2011
To get started, type one of these: helpwin, helpdesk, or demo.
For product information, visit www.mathworks.com.
SERIAL REGION: hostname:hammer-a001.rcac.purdue.edu
Starting matlabpool using the 'myslurmprofile' profile ... connected to 4 labs.
hostname numlabs labindex
------------------------------- ------- --------
Lab 2:
PARALLEL REGION: hammer-a002.rcac.purdue.edu 4 2
Lab 1:
PARALLEL REGION: hammer-a001.rcac.purdue.edu 4 1
Lab 3:
PARALLEL REGION: hammer-a003.rcac.purdue.edu 4 3
Lab 4:
PARALLEL REGION: hammer-a004.rcac.purdue.edu 4 4
Sending a stop signal to all the labs ... stopped.
SERIAL REGION: hostname:hammer-a001.rcac.purdue.edu
Elapsed time in parallel region: 3.382151
Output shows the name of one compute node (a001) that processed the job submission file myjob.sub and the two serial regions. The job submission scattered four processor cores (four MATLAB labs) among four different compute nodes (a001,a002,a003,a004) that processed the four parallel regions. The total elapsed time demonstrates that the jobs ran in parallel.
For more information about MATLAB Parallel Computing Toolbox:
Distributed Computing Server (parallel job)
The MATLAB Parallel Computing Toolbox (PCT) enables a parallel job via the MATLAB Distributed Computing Server (DCS). The tasks of a parallel job are identical, run simultaneously on several MATLAB workers (labs), and communicate with each other. This section illustrates an MPI-like program.
This section illustrates how to submit a small, MATLAB parallel job with four workers running one MPI-like task to a batch queue. The MATLAB program broadcasts an integer to four workers and gathers the names of the compute nodes running the workers and the lab IDs of the workers.
This example uses the job submission command to submit a Matlab script with a user-defined cluster profile which scatters the MATLAB workers onto different compute nodes. This method uses the MATLAB interpreter, the Parallel Computing Toolbox, and the Distributed Computing Server; so, it requires and checks out six licenses: one MATLAB license for the client running on the compute node, one PCT license, and four DCS licenses. Four DCS licenses run the four copies of the parallel job. This job is completely off the front end.
Prepare a MATLAB script named myscript.m :
% FILENAME: myscript.m
% Specify pool size.
% Convert the parallel job to a pool job.
parpool('4');
spmd
if labindex == 1
% Lab (rank) #1 broadcasts an integer value to other labs (ranks).
N = labBroadcast(1,int64(1000));
else
% Each lab (rank) receives the broadcast value from lab (rank) #1.
N = labBroadcast(1);
end
% Form a string with host name, total number of labs, lab ID, and broadcast value.
[c name] =system('hostname');
name = name(1:length(name)-1);
fmt = num2str(floor(log10(numlabs))+1);
str = sprintf(['%s:%d:%' fmt 'd:%d '], name,numlabs,labindex,N);
% Apply global concatenate to all str's.
% Store the concatenation of str's in the first dimension (row) and on lab #1.
result = gcat(str,1,1);
if labindex == 1
disp(result)
end
end % spmd
matlabpool close force;
quit;
Also, prepare a job submission, here named myjob.sub. Run with the name of the script:
# FILENAME: myjob.sub
echo "myjob.sub"
module load matlab
unset DISPLAY
# -nodisplay: run MATLAB in text mode; X11 server not needed
# -r: read MATLAB program; use MATLAB JIT Accelerator
matlab -nodisplay -r myscript
Run MATLAB to set the default parallel configuration to your appropriate Profile:
$ matlab -nodisplay
>> defaultParallelConfig('myslurmprofile');
>> quit;
$
Submit the job as a single compute node with one processor core.
Once this job starts, a second job submission is made.
myjob.sub
< M A T L A B (R) >
Copyright 1984-2011 The MathWorks, Inc.
R2011b (7.13.0.564) 64-bit (glnxa64)
August 13, 2011
To get started, type one of these: helpwin, helpdesk, or demo.
For product information, visit www.mathworks.com.
>Starting matlabpool using the 'myslurmprofile' configuration ... connected to 4 labs.
Lab 1:
hammer-a006.rcac.purdue.edu:4:1:1000
hammer-a007.rcac.purdue.edu:4:2:1000
hammer-a008.rcac.purdue.edu:4:3:1000
hammer-a009.rcac.purdue.edu:4:4:1000
Sending a stop signal to all the labs ... stopped.
Did not find any pre-existing parallel jobs created by matlabpool.
Output shows the name of one compute node (a006) that processed the job submission file myjob.sub. The job submission scattered four processor cores (four MATLAB labs) among four different compute nodes (a006,a007,a008,a009) that processed the four parallel regions.
To scale up this method to handle a real application, increase the wall time in the submission command to accommodate a longer running job. Secondly, increase the wall time of myslurmprofile by using the Cluster Profile Manager in the Parallel menu to enter a new wall time in the property SubmitArguments.
For more information about parallel jobs: