— Function File: demo ('name',n)

Runs any examples associated with the function 'name'. Examples are stored in the script file, or in a file with the same name but no extension somewhere on your path. To keep them separate from the usual script code, all lines are prefixed by %!. Each example is introduced by the keyword 'demo' flush left to the prefix, with no intervening spaces. The remainder of the example can contain arbitrary octave code. For example:

             %!demo
             %! t=0:0.01:2*pi; x = sin(t);
             %! plot(t,x)
             %! %-------------------------------------------------
             %! % the figure window shows one cycle of a sine wave
     

Note that the code is displayed before it is executed, so a simple comment at the end suffices. It is generally not necessary to use disp or printf within the demo.

Demos are run in a function environment with no access to external variables. This means that all demos in your function must use separate initialization code. Alternatively, you can combine your demos into one huge demo, with the code:

             %! input("Press <enter> to continue: ","s");
     

between the sections, but this is discouraged. Other techniques include using multiple plots by saying figure between each, or using subplot to put multiple plots in the same window.

Also, since demo evaluates inside a function context, you cannot define new functions inside a demo. Instead you will have to use eval(example('function',n)) to see them. Because eval only evaluates one line, or one statement if the statement crosses multiple lines, you must wrap your demo in "if 1 <demo stuff> endif" with the 'if' on the same line as 'demo'. For example,

            %!demo if 1
            %!  function y=f(x)
            %!    y=x;
            %!  endfunction
            %!  f(3)
            %! endif
     

See also: test, example.

— Function File: example ('name',n)
— Function File: [x, idx] = example ('name',n)

Display the code for example n associated with the function 'name', but do not run it. If n is not given, all examples are displayed.

Called with output arguments, the examples are returned in the form of a string x, with idx indicating the ending position of the various examples.

See demo for a complete explanation.

See also: demo, test.

— Function File: speed (f, init, max_n, f2, tol, err)
— Function File: r = 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. Called without output arguments the data is presented graphically. Called with an output argument r, the speedup ratio is returned instead of displaying it graphically.

f

The expression to evaluate.

max_n

The maximum test length to run. Default value is 100.

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,err). The default is eps.

Some global variables are also referenced. Choose values suitable to your machine and your work style.

speed_test_plot

If true, plot a nice speed comparison graph. Default is true.

speed_test_numtests

Number of vector lengths to test. The default is 25.

Some comments on the graphs. The line on the speedup ratio graph should be larger than 1 if your function is faster. The slope on the runtime graph shows you the O(f) speed characteristics. Where it is flat, execution time is O(1). Where it is sloping, execution time is O(n^m), with steeper slopes for larger n. Generally vectorizing a function will not change the slope of the run-time graph, but it will shift it relative to the original.

A simple example is

            speed("strrep(s,x,y)", "s=blanks(n);x=' ';y='b';", 100)
     

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,'rel')
            speed("v=xcorr(x,15)", "x=rand(20+n,1);", 100, ...
                  "v2=xcorr_orig(x,n)", 100*eps,'rel')
     

Assuming one of the two versions is in xcorr_orig, this would 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)).