profile - Profile execution time for functions - MATLAB (original) (raw)
Profile execution time for functions
Syntax
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](#f8-618415-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](#f8-618415-action) [option1 ... optionN](#f8-618415-option1optionN)
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](#f8-618415-option1optionN)
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](#f8-618415-p) = profile('info')
stops the Profiler and displays a structure containing the results. To access the data generated by profile
, use this syntax.
[s](#f8-618415-s) = profile('status')
returns a structure with the Profiler status information.
Examples
Turn on the Profiler, and call the magic
function.
profile on n = 100; M = magic(n);
View the results in the Profiler window.
Save the results as HTML files. By default, profsave
saves the files to the profile_results
subfolder in your current working folder.
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
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 =
FunctionTable: [2x1 struct]
FunctionHistory: [2x6 double]
ClockPrecision: 3.3475e-07
ClockSpeed: 3.0600e+09
Name: 'MATLAB'
Overhead: 0
Display the function call history.
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.
s =
ProfilerStatus: 'off'
DetailLevel: 'mmex'
Timer: 'performance'
HistoryTracking: 'timestamp'
HistorySize: 5000000
Input Arguments
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. |
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 specifiedhistorysize, theprofile 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
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. |
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 theFunctionTable
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