coder.timeit

Measure execution time of generated C/C++ code

Since R2024b

collapse all in page

Syntax

[t,trObj,benchObj] = coder.timeit(fcnName,numOutputs,runtimeArgs)
[~,~,benchObj] = coder.timeit(fcnName,numOutputs,runtimeArgs,"generatecodeonly")
[t,trObj,benchObj] = coder.timeit(___,Name=Value)

Description

[t,trObj,benchObj] = coder.timeit(fcnName,numOutputs,runtimeArgs) measures the execution time of the code generated from the MATLAB® function fcnName. The generated code is executed with input arguments runtimeArgs and returns numOutputs output arguments.

  • By default, coder.timeit uses a MEX configuration object with IntegrityChecks and ResponsivenessChecks properties set to false.

  • coder.timeit measures the execution times for multiple runs and returns the median execution time.

  • The coder.timeit function uses internal heuristics to determine the number of runs.

  • coder.timeit excludes the timing overhead incurred by the data transfer between MATLAB and generated code execution.

example

[~,~,benchObj] = coder.timeit(fcnName,numOutputs,runtimeArgs,"generatecodeonly") creates a coder.performance.Benchmarkable object that can be used to time fcnName multiple times with different inputs without having to regenerate code every time. The function packages the generated code inside a wrapper object benchObj.

example

[t,trObj,benchObj] = coder.timeit(___,Name=Value) specifies additional options using one or more name-value arguments.

example

Examples

collapse all

Open Live Script

Measure the execution time of the generated C code for the MATLAB® function linearInterp.

Define the MATLAB® function linearInterp.

function out = linearInterp(x,v,xq)
    out = interp1(x,v,xq,"linear");
end

Measure the execution time of linearInterp by using the coder.timeit function.

x = 0:pi/1000:2*pi; 
v = sin(x);
xq = 0:pi/10000:2*pi;

t = coder.timeit("linearInterp",1,{x,v,xq})
- Generating code and building MEX.
- Running MEX.
TimingResult with 1031 Runtime Sample(s)

Statistical Overview:
   mean = 4.85e-04 s    max = 1.02e-02 s     sd = 8.24e-04 s
 median = 3.38e-04 s    min = 1.90e-04 s   90th = 5.55e-04 s

t = 
3.3850e-04
Open Live Script

Generate code without executing the timing function and times the function for multiple sets of inputs using the generated code.

Define the MATLAB® function filterSignal:

function out = filterSignal(a,b,x)
    out = filter(a,b,x);
end

Define compile-time input arguments and generate code with the coder.timeit function using the "generatecodeonly" option. The coder.timeit function creates a wrapper object that you can use to measure the execution time of the generated code with different input arguments.

a = [1 1];
b = [2 2];
x = 1:1e7;

[~,~,bObj] = coder.timeit("filterSignal",1,{a,b,x},"generatecodeonly", ...
                                    CompileArgs={a,b,coder.typeof(x,[1 Inf])})
- Generating code and building MEX.

bObj = 
  Benchmarkable with properties:

    CompileArguments: {[1 1]  [2 2]  [1×1 coder.PrimitiveType]}
         CoderConfig: [1×1 coder.MexCodeConfig]
                Name: 'filterSignalTestWrapper'

Measure the execution time of the generated code for different input values.

t1 = run(bObj,a,b,1:1e4)
- Running MEX.
TimingResult with 4591 Runtime Sample(s)

Statistical Overview:
   mean = 1.09e-04 s    max = 4.88e-03 s     sd = 1.19e-04 s
 median = 9.94e-05 s    min = 9.84e-05 s   90th = 1.12e-04 s

t1 = 
9.9382e-05

t2 = run(bObj,a,b,1:1e7)
- Running MEX.
TimingResult with 10 Runtime Sample(s)

Statistical Overview:
   mean = 2.10e-01 s    max = 2.60e-01 s     sd = 2.97e-02 s
 median = 2.07e-01 s    min = 1.49e-01 s   90th = 2.50e-01 s

t2 = 
0.2065

t = table([1e4; 1e7],[t1; t2],'VariableNames',{'Size','Runtime (s)'})
t=2×2 table
    Size     Runtime (s)
    _____    ___________

    10000    9.9382e-05 
    1e+07       0.20653
Open Live Script

Measure the execution time of the generated code for the linearInterp function as a standalone C static library.

Define the MATLAB® function linearInterp.

function out = linearInterp(x,v,xq)
    out = interp1(x,v,xq,"linear");
end

Measure the execution time of linearInterp. Specify the code configuration, working directory, and code generation options.

x = 0:pi/100:2*pi; 
v = sin(x);
xq = 0:pi/400:2*pi;
cfg = coder.config("lib");
[t,trObj] = coder.timeit("linearInterp",1,{x,v,xq},CoderConfig=cfg, ...
                WorkDirectory='RowMajor_folder',codegenCmdArgs={'-rowmajor'})
- Generating code and building SIL/PIL MEX.
- Running MEX.
TimingResult with 5413 Runtime Sample(s)

Statistical Overview:
   mean = 9.24e-05 s    max = 1.02e-02 s     sd = 3.43e-04 s
 median = 4.44e-05 s    min = 2.43e-05 s   90th = 8.07e-05 s

t = 
4.4361e-05

trObj = 
TimingResult with 5413 Runtime Sample(s)

Statistical Overview:
   mean = 9.24e-05 s    max = 1.02e-02 s     sd = 3.43e-04 s
 median = 4.44e-05 s    min = 2.43e-05 s   90th = 8.07e-05 s

Input Arguments

collapse all

Name of entry-point function, specified as a character vector or string scalar.

Number of outputs the function returns, specified as a nonnegative integer.

Run-time input arguments to fcnName, specified as a cell array.

Name-Value Arguments

collapse all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: t = coder.timeit("testPerf",1,{1:1000},CompileArgs={coder.typeof(0,[1 Inf])},MinRuns=10,MinTime=1,CoderConfig={mcfg},WorkDirectory=fullfile(pwd,'newworkdir'),CodegenCmdArgs={'-rowmajor','-g'})

Compile time input arguments to MATLAB fcnName, specified as a cell array.

Use these input arguments to specify input types for code generation.

Example: t = coder.timeit("testPerf",1,{1:1000},CompileArgs={coder.typeof(0,[1 Inf])})

Minimum number of trials to ensure runtime stability, specified as a nonnegative integer. The default value of MinRuns is:

  • 5 — When execution time is greater than or equal to 30 seconds

  • 10 — When execution time is less then 30 seconds

Example: t = coder.timeit("testPerf",1,{1:1000},MinRuns=7)

Minimum time duration in seconds, specified as a nonnegative double.

Example: t = coder.timeit("testPerf",1,{1:1000},MinTime=1)

Code generation configurations object. To create the object, use coder.config.

For build types lib and dll, generated code is executed using software-in-the-loop (SIL) or processor-in-the-loop (PIL) simulation, which requires an Embedded Coder® license.

Example: t = coder.timeit("testPerf",1,{1:1000},CoderConfig=cfg)

Work directory path for generating code, specified as a character vector.

Example: coder.timeit("testPerf",1,{1:1000},WorkDirectory= fullfile(pwd,'newworkdir'))

Code generation arguments, specified as cell array of character vectors or cell array of string scalars.

For more information on code generation options, see codegen.

Example: coder.timeit("testPerf",1,{1:1000},CodegenCmdArgs={'-rowmajor', '-g'})

Output Arguments

collapse all

Median of all run time measurements in seconds, specified as double scalar.

Detailed information about the run, returned as a coder.performance.TimingResult object. Use this object for result analysis and comparison.

Input and output information for benchmarking of the generated code, specified as coder.performance.Benchmarkable object. Use this object to rerun coder.timeit without regenerating code and evaluate performance across multiple input sets.

Tips

  • To achieve consistent results, make sure no other computation-intensive processes are running on the machine where you measure the execution time of the MATLAB function or the generated code.

  • Use the name-value arguments MinRuns and MinTime to can control the number of times to run the generated code.

  • The code generator takes longer to measure the execution time of code generated with lib or dll build types than with the mex build type.

  • When using multiple instances of MATLAB and running coder.timeit from the same folder, use the WorkDirectory name-value argument to specify different folders.

Version History

Introduced in R2024b

See Also

| |