octave: Demonstration Functions
B.2 Demonstration Functions
===========================
-- : demo NAME
-- : demo NAME N
-- : demo ("NAME")
-- : demo ("NAME", N)
Run example code block N associated with the function NAME.
If N is not specified, all examples are run.
The preferred location for example code blocks is embedded within
the script m-file immediately following the code that it exercises.
Alternatively, the examples may be stored in a file with the same
name but no extension located on Octave’s load path. To separate
examples from regular script code all lines are prefixed by ‘%!’.
Each example must also be 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);
%! title ("one cycle of a sine wave");
%! #-------------------------------------------------
%! # the figure window shows one cycle of a sine wave
Note that the code is displayed before it is executed so that a
simple comment at the end suffices for labeling what is being
shown. For plots, labeling can also be done with ‘title’ or
‘text’. It is generally *not* necessary to use ‘disp’ or ‘printf’
within the demo.
Demos are run in a stand-alone function environment with no access
to external variables. This means that every demo must have
separate initialization code. Alternatively, all demos can be
combined into a single large demo with the code
%! input ("Press <enter> to continue: ", "s");
between the sections, but this usage is discouraged. Other
techniques to avoid multiple initialization blocks include using
multiple plots with a new ‘figure’ command between each plot, or
using ‘subplot’ to put multiple plots in the same window.
Finally, because ‘demo’ evaluates within a function context it is
not possible to define new functions within the code. Anonymous
functions make a good substitute in most instances. If function
blocks *must* be used then the code ‘eval (example ("function",
n))’ will allow Octave to see them. This has its own problems,
however, as ‘eval’ only evaluates one line or statement at a time.
In this case the function declaration must be wrapped with "if 1
<demo stuff> endif" where "if" is on the same line as "demo". For
example:
%!demo if 1
%! function y = f(x)
%! y = x;
%! endfunction
%! f(3)
%! endif
See also: 
rundemos XREFrundemos, example XREFexample,
test XREFtest.
-- : example NAME
-- : example NAME N
-- : example ("NAME")
-- : example ("NAME", N)
-- : [S, IDX] = example (...)
Display the code for example N associated with the function NAME,
but do not run it.
If N is not specified, all examples are displayed.
When called with output arguments, the examples are returned in the
form of a string S, with IDX indicating the ending position of the
various examples.
See ‘demo’ for a complete explanation.
See also: demo XREFdemo, test XREFtest.
-- : rundemos ()
-- : rundemos (DIRECTORY)
Execute built-in demos for all m-files in the specified DIRECTORY.
Demo blocks in any C++ source files (‘*.cc’) will also be executed
for use with dynamically linked oct-file functions.
If no directory is specified, operate on all directories in
Octave’s search path for functions.
DONTPRINTYET See also: demo XREFdemo, runtests XREFruntests, *noteDONTPRINTYET See also: demo XREFdemo, runtests XREFruntests,
path XREFpath.
-- : runtests ()
-- : runtests (DIRECTORY)
Execute built-in tests for all m-files in the specified DIRECTORY.
Test blocks in any C++ source files (‘*.cc’) will also be executed
for use with dynamically linked oct-file functions.
If no directory is specified, operate on all directories in
Octave’s search path for functions.
DONTPRINTYET See also: rundemos XREFrundemos, test XREFtest, *noteDONTPRINTYET See also: rundemos XREFrundemos, test XREFtest,
path XREFpath.
-- : speed (F, INIT, MAX_N, F2, TOL)
-- : [ORDER, N, T_F, T_F2] = speed (...)
Determine the execution time of an expression (F) for various input
values (N).
The N are log-spaced from 1 to MAX_N. For each N, an
initialization expression (INIT) is computed to create any data
needed for the test. If a second expression (F2) is given then the
execution times of the two expressions are compared. When called
without output arguments the results are printed to stdout and
displayed graphically.
‘F’
The code expression to evaluate.
‘MAX_N’
The maximum test length to run. The default value is 100.
Alternatively, use ‘[min_n, max_n]’ or specify the N exactly
with ‘[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 used by F. Note that
INIT will be evaluated first for k = 0, so things which are
constant throughout the test series can be computed once. The
default value is ‘X = randn (N, 1)’.
‘F2’
An alternative expression to evaluate, so that the speed of
two expressions can be directly compared. The default is
‘[]’.
‘TOL’
Tolerance used to compare the results of expression F and
expression F2. If TOL is positive, the tolerance is an
absolute one. If TOL is negative, the tolerance is a relative
one. The default is ‘eps’. If TOL is ‘Inf’, then no
comparison will be made.
‘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 required, the mean time ratio is simply ‘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 an algorithm. It
should indicate if, for example, the implementation is unexpectedly
O(n^2) rather than O(n) because it extends a vector each time
through the loop rather than pre-allocating storage. In the
current version of Octave, the following is not the expected O(n).
speed ("for i = 1:n, y{i} = x(i); endfor", "", [1000, 10000])
But it is if you preallocate the cell array ‘y’:
speed ("for i = 1:n, y{i} = x(i); endfor", ...
"x = rand (n, 1); y = cell (size (x));", [1000, 10000])
An attempt is made to approximate the cost of 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 two different expressions (F, F2), the slope of 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 will shift it relative to the
original. For example:
speed ("sum (x)", "", [10000, 100000], ...
"v = 0; for i = 1:length (x), v += x(i); endfor")
The following is a more complex example. If there was an original
version of ‘xcorr’ using for loops and a second version using an
FFT, then one could compare the run speed for various lags as
follows, or for a fixed lag with varying vector lengths as follows:
speed ("xcorr (x, n)", "x = rand (128, 1);", 100,
"xcorr_orig (x, n)", -100*eps)
speed ("xcorr (x, 15)", "x = rand (20+n, 1);", 100,
"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 one must specify an acceptable tolerance
on the comparison ‘100*eps’. In this case, the comparison should
be computed relatively, as ‘abs ((X - Y) ./ Y)’ rather than
absolutely as ‘abs (X - Y)’.
Type ‘example ("speed")’ to see some real examples or ‘demo
("speed")’ to run them.
Info Catalog
octave: Test Functions
octave: Test and Demo Functions