profile

Profile execution time for functions

Syntax

profile action

profile action option1 ... optionN

profile option1 ... optionN

p = profile('info')

s = profile('status')

Description

Use the Profiler to track execution time. Knowing the execution time of your MATLAB^® code helps you to debug and optimize it. For information on the user interface to the Profiler, see Profiler.

profile action profiles the execution time for functions. Use action to start, stop, and restart the Profiler, and view or clear profile statistics. For example, profile on starts the Profiler.

profile action option1 ... optionN starts or restarts the Profiler with the specified options. For example, profile resume -history restarts the Profiler and records the sequence of function calls.

profile option1 ... optionN sets the specified Profiler options. If the Profiler is on and you specify one of the options, MATLAB throws an error. To change options, first specify profile off, and then specify the new options.

p = profile('info') stops the Profiler and displays a structure containing the results. To access the data generated by profile, use this syntax.

s = profile('status') returns a structure with the Profiler status information.

Examples

Save Profiling Results as HTML Files

Turn on the Profiler, and call the magic function.

profile on
n = 100;
M = magic(n);

View the results in the Profiler window.

profile viewer

Save the results as HTML files. By default, profsave saves the files to the profile_results subfolder in your current working folder.

profsave

Save Profiling Results as MAT-File

Turn on the Profiler, and call the magic function.

profile on
n = 100;
M = magic(n);

Save the results to a MAT-file.

p = profile('info')
save myprofiledata p

p = 

      FunctionTable: [1x1 struct]
    FunctionHistory: [2x2 double]
     ClockPrecision: 3.3475e-07
         ClockSpeed: 3.0600e+09
               Name: 'MATLAB'
           Overhead: 0

Display Function Call History

Create the file myFunction.m using this main function and local function.

function c = myFunction(a,b)
c = sqrt(square(a)+square(b));
end

function y = square(x)
y = x.^2;
end

Turn on the Profiler, and enable the function call history option. Profile a call to the myFunction function.

profile on -history
a = rand(5);
b = rand(5);
c = myFunction(a,b);

Save the profiling results.

p = profile('info')

p = 

      FunctionTable: [2x1 struct]
    FunctionHistory: [2x6 double]
     ClockPrecision: 3.3475e-07
         ClockSpeed: 3.0600e+09
               Name: 'MATLAB'
           Overhead: 0

Display the function call history.

p.FunctionHistory

ans =

     0     0     1     0     1     1
     1     2     2     2     2     1

Display function entry and exit information by iterating over the function call history.

numEvents = size(p.FunctionHistory,2);
for n = 1:numEvents
    name = p.FunctionTable(p.FunctionHistory(2,n)).FunctionName;
    
    if p.FunctionHistory(1,n) == 0
        disp(['Entered ' name]);
    else
        disp(['Exited ' name]);
    end
end

Entered myFunction
Entered myFunction>square
Exited myFunction>square
Entered myFunction>square
Exited myFunction>square
Exited myFunction

Set the function call history to the default value.

profile -timestamp

View Current Profiler Settings

s = profile('status')

s = 

     ProfilerStatus: 'off'
        DetailLevel: 'mmex'
              Timer: 'performance'
    HistoryTracking: 'timestamp'
        HistorySize: 5000000

Input Arguments

action — Control options for Profiler

on | off | resume | clear | viewer | info | status

Control options for the Profiler specified as one of these options.

Option	Result
on	Start the Profiler, clearing any previously recorded profile statistics.
off	Stop the Profiler.
clear	Stop the Profiler and clear the recorded statistics.
viewer	Stop the Profiler and display the results in the Profiler window. For more information, see Profiler. The Profiler user interface is not supported in MATLAB Online™.
info	Stop the Profiler and return a structure containing the results.
resume	Restart the Profiler without clearing previously recorded statistics.
status	Return a structure with the Profiler status information.

option1 ... optionN — One or more profiling options

character vectors

One or more profiling options, specified as character vectors corresponding to valid settings from the history and clock option tables.

If you change the Profiler settings, the settings persist when you stop the Profiler or clear the statistics. To revert to default Profiler behavior, manually set the options to the default values or start a new MATLAB session.

History Options

Option	Result
-nohistory	Record basic profiling statistics.
-history	Record basic profiling statistics, as well as the exact sequence of function calls, including function entry and exit events.
-timestamp	Default value. Record basic profiling statistics, as well as the exact sequence of function calls including entry and exit events, and the timestamp for each event.
-historysize integer	Specify the number of function entry and exit events to record. By default, historysize is 5,000,000. If the number of function calls exceeds the specified historysize, the profile function continues to record profiling statistics other than the sequence of calls.

Clock Options

Option	Result
-timer 'performance'	Default value. Use wall-clock time from the clock that the operating system supplies to measure performance.
-timer 'processor'	Use the wall-clock time directly from the processor. Sometimes your power savings settings or use of multiple processors influence this measurement.
-timer 'real'	Use system time reported by the operating system. This option is the most computationally expensive measurement and has the most impact on the performance of profiled code. Changing the time on the operating system clock influences this measurement.
-timer 'cpu'	Use computer time and sums time across all threads. This measurement is different from wall-clock time. For example, the computer time for the pause function is typically small, but wall-clock time accounts for the actual time paused, which is larger.

Output Arguments

p — Profiler statistics

structure

Profiler statistics, returned as a structure containing these fields.

Field	Description
FunctionTable	Function statistics, returned as a structure array. Each structure in the array contains information about one of the functions or local functions called during profiling. Each structure contains the following fields: CompleteName – Full path to FunctionName. FunctionName – Name of function. If the function is a local function, FunctionName includes the main function. FileName – Full path to FunctionName, with the file extension. If the function is a local function, FileName is the full path to the main function. Type – Type of function. For example, MATLAB function, MEX-function, local function, or nested function. NumCalls – Number of times the profiled code called the function. TotalTime – Total time spent in the function and its child functions. TotalRecursiveTime – MATLAB no longer uses this field. Children – Information about functions that the function called. Each entry in the array contains information about one child function. The structure contains these fields: Index – Index to child function information structure within FunctionTable. NumCalls – Number of times the profiled code called the child function. TotalTime – Total time spent in the child function. Parents – Information about the parent functions of FunctionName. Each structure in the array contains information about one of the parents. The structure contains these fields: Index – Index to parent function information structure within FunctionTable. NumCalls – Number of times the parent function called this function. ExecutedLines – Array containing line-by-line details for the profiled function. Column 1 – Line number for the executed line of code in FileName. Column 2 – Number of times the profiled code executed the line of code. Column 3 – Total time spent on the line of code. The sum of Column 3 entries does not necessarily add up to the TotalTime. IsRecursive – Indicator of whether the function is recursive. If the value is 1 (true), the function is recursive. If the value is 0 (false), the function is nonrecursive. PartialData – Indicator of whether the profile statistics are incomplete. If the value is logical 1 (true), the function was modified during profiling. For example, if you edited the function or cleared it from memory. In that event, the Profiler collects data only up until you modified the function.
FunctionHistory	Function call history, returned as an array. Row 1 – Indicator of function entry or exit. The Profiler records function entry with a 0, and function exit with a 1. Row 2 – Index to function information structure within FunctionTable. Row 3 – Seconds portion of the function entry or exit timestamp, specified as the time that has elapsed since the operating system Epoch time. This row is only returned if the -timestamp history option is specified. Row 4 – Microseconds portion of the function entry or exit timestamp, specified as the time that has elapsed since the operating system Epoch time. This row is only returned if the -timestamp history option is specified.
ClockPrecision	Precision of the time measurement of the profile function, returned as a double.
ClockSpeed	Estimated CPU clock speed, returned as a double.
Name	Name of the profiler, returned as a character array.
Overhead	Reserved for future use.

s — Profiler status

structure

Profiler status, returned as a structure containing these fields.

Field	Values	Default Value
ProfilerStatus	'on', 'off'	'off'
DetailLevel	'mmex'	'mmex'
Timer	'performance', 'processor', 'cpu', or 'real'	'performance'
HistoryTracking	'on', 'off', or 'timestamp'	'timestamp'
HistorySize	integer	5000000

Limitations

• The MATLAB Profiler performs calculations and collects data while the code is running. This requires additional computational resources and will result in code running slower with the Profiler active than identical code without. For this reason execution times measured by the Profiler should be treated as relative measures of code performance rather than absolute.

• If the profiled code uses indirect (or mutual) recursion, the Profiler might return inaccurate results. If the recursion is direct (a single function calling itself), then the Profiler returns the total time for the non-recursive calls to the function. To determine if a function in the profiled code is recursive (directly or indirectly), examine the value of the IsRecursive field in the FunctionTable entry.

• The Profiler is not supported when evaluating code sections.

Tips

• To open the Profiler user interface, use the profile viewer syntax or see Profiler. The Profiler user interface is not supported in MATLAB Online.

• As of MATLAB R2015b, the default timer is 'performance'. In previous versions of MATLAB, the default profiler timer was 'cpu', which measures compute time instead of wall-clock time.

Version History

Introduced before R2006a