Function Reference
— Function File: speed (f, init, max_n, f2, tol)
— Function File: [order, n, T_f, T_f2] = speed (...)

Determine the execution time of an expression for various n. The n are log-spaced from 1 to max_n. For each n, an initialization expression is computed to create whatever data are needed for the test. If a second expression is given, the execution times of the two expressions will be compared. Called without output arguments the results are presented graphically.

f
The expression to evaluate.
max_n
The maximum test length to run. Default value is 100. Alternatively, use [min_n,max_n] or for complete control, [n1,n2,...,nk].
init
Initialization expression for function argument values. Use k for the test number and n for the size of the test. This should compute values for all variables listed in args. Note that init will be evaluated first for k=0, so things which are constant throughout the test can be computed then. The default value is x = randn (n, 1);.
f2
An alternative expression to evaluate, so the speed of the two can be compared. Default is [].
tol
If tol is Inf, then no comparison will be made between the results of expression f and expression f2. Otherwise, expression f should produce a value v and expression f2 should produce a value v2, and these shall be compared using assert(v,v2,tol). If tol is positive, the tolerance is assumed to be absolute. If tol is negative, the tolerance is assumed to be relative. The default is eps.
order
The time complexity of the expression O(a n^p). This is a structure with fields a and p.
n
The values n for which the expression was calculated and the execution time was greater than zero.
T_f
The nonzero execution times recorded for the expression f in seconds.
T_f2
The nonzero execution times recorded for the expression f2 in seconds. If it is needed, the mean time ratio is just mean(T_f./T_f2).

The slope of the execution time graph shows the approximate power of the asymptotic running time O(n^p). This power is plotted for the region over which it is approximated (the latter half of the graph). The estimated power is not very accurate, but should be sufficient to determine the general order of your algorithm. It should indicate if for example your implementation is unexpectedly O(n^2) rather than O(n) because it extends a vector each time through the loop rather than preallocating one which is big enough. For example, in the current version of Octave, the following is not the expected O(n):

            speed("for i=1:n,y{i}=x(i); end", "", [1000,10000])

but it is if you preallocate the cell array y:

            speed("for i=1:n,y{i}=x(i);end", ...
                  "x=rand(n,1);y=cell(size(x));", [1000,10000])

An attempt is made to approximate the cost of the individual operations, but it is wildly inaccurate. You can improve the stability somewhat by doing more work for each n. For example:

            speed("airy(x)", "x=rand(n,10)", [10000,100000])

When comparing a new and original expression, the line on the speedup ratio graph should be larger than 1 if the new expression is faster. Better algorithms have a shallow slope. Generally, vectorizing an algorithm will not change the slope of the execution time graph, but it will shift it relative to the original. For example:

            speed("v=sum(x)", "", [10000,100000], ...
                  "v=0;for i=1:length(x),v+=x(i);end")

A more complex example, if you had an original version of xcorr using for loops and another version using an FFT, you could compare the run speed for various lags as follows, or for a fixed lag with varying vector lengths as follows:

            speed("v=xcorr(x,n)", "x=rand(128,1);", 100, ...
                  "v2=xcorr_orig(x,n)", -100*eps)
            speed("v=xcorr(x,15)", "x=rand(20+n,1);", 100, ...
                  "v2=xcorr_orig(x,n)", -100*eps)

Assuming one of the two versions is in xcorr_orig, this would compare their speed and their output values. Note that the FFT version is not exact, so we specify an acceptable tolerance on the comparison 100*eps, and the errors should be computed relatively, as abs((x - y)./y) rather than absolutely as abs(x - y).

Type example('speed') to see some real examples. Note for obscure reasons, you can't run examples 1 and 2 directly using demo('speed'). Instead use, eval(example('speed',1)) and eval(example('speed',2)).