Profile parallel communication and execution times


mpiprofile on <options>
mpiprofile off
mpiprofile resume
mpiprofile clear
mpiprofile status
mpiprofile reset
mpiprofile info
mpiprofile viewer


mpiprofile enables or disables the parallel profiler data collection on a MATLAB® worker running a communicating job. mpiprofile aggregates statistics on execution time and communication times. The statistics are collected in a manner similar to running the profile command on each MATLAB worker. By default, the parallel profiling extensions include array fields that collect information on communication with each of the other workers. This command in general should be executed in pmode or as part of a task in a communicating job.

mpiprofile on <options> starts the parallel profiler and clears previously recorded profile statistics.

mpiprofile takes the following options.


-detail mmex

-detail builtin

This option specifies the set of functions for which profiling statistics are gathered. -detail mmex (the default) records information about functions, local functions, and MEX-functions. -detail builtin additionally records information about built-in functions such as eig or labReceive.

-messagedetail default

-messagedetail simplified

This option specifies the detail at which communication information is stored.

-messagedetail default collects information on a per-lab instance.

-messagedetail simplified turns off collection for *PerLab data fields, which reduces the profiling overhead. If you have a very large cluster, you might want to use this option; however, you will not get all the detailed inter-lab communication plots in the viewer.

For information about the structure of returned data, see mpiprofile info below.



-historysize <size>

mpiprofile supports these options in the same way as the standard profile.

No other profile options are supported by mpiprofile. These three options have no effect on the data displayed by mpiprofile viewer.

mpiprofile off stops the parallel profiler. To reset the state of the profiler and disable collecting communication information, you should also call mpiprofile reset.

mpiprofile resume restarts the profiler without clearing previously recorded function statistics. This works only in pmode or in the same MATLAB worker session.

mpiprofile clear clears the profile information.

mpiprofile status returns a valid status when it runs on the worker.

mpiprofile reset turns off the parallel profiler and resets the data collection back to the standard profiler. If you do not call reset, subsequent profile commands will collect MPI information.

mpiprofile info returns a profiling data structure with additional fields to the one provided by the standard profile info in the FunctionTable entry. All these fields are recorded on a per-function and per-line basis, except for the *PerLab fields.

BytesSentRecords the quantity of data sent
BytesReceivedRecords the quantity of data received
TimeWastedRecords communication waiting time
CommTimeRecords the communication time
CommTimePerLabVector of communication receive time for each lab
TimeWastedPerLabVector of communication waiting time for each lab
BytesReceivedPerLabVector of data received from each lab

The three *PerLab fields are collected only on a per-function basis, and can be turned off by typing the following command in pmode:

mpiprofile on -messagedetail simplified

mpiprofile viewer is used in pmode after running user code with mpiprofile on. Calling the viewer stops the profiler and opens the graphical profile browser with parallel options. The output is an HTML report displayed in the profiler window. The file listing at the bottom of the function profile page shows several columns to the left of each line of code. In the summary page:

  • Column 1 indicates the number of calls to that line.

  • Column 2 indicates total time spent on the line in seconds.

  • Columns 3–6 contain the communication information specific to the parallel profiler

mpiprofile('viewer',<profinfoarray>) in function form can be used from the client. A structure <profinfoarray> needs be passed in as the second argument, which is an array of mpiprofile info structures. See pInfoVector in the Examples section below.

mpiprofile does not accept -timer clock options, because the communication timer clock must be real.

For more information and examples on using the parallel profiler, see Profiling Parallel Code.


In pmode, turn on the parallel profiler, run your function in parallel, and call the viewer:

mpiprofile on;
% call your function;
mpiprofile viewer;

If you want to obtain the profiler information from a communicating job outside of pmode (i.e., in the MATLAB client), you need to return output arguments of mpiprofile info by using the functional form of the command. Define your function foo(), and make it the task function in a communicating job:

function [pInfo,yourResults] = foo
mpiprofile on
initData = (rand(100, codistributor()) ...
                   * rand(100,codistributor()));
pInfo = mpiprofile('info');
yourResults = gather(initData,1)

After the job runs and foo() is evaluated on your cluster, get the data on the client:

A = fetchOutputs(yourJob);

Then view parallel profile information:

pInfoVector = [A{:,1}];

Introduced in R2007b