<html lang="en"> <head> <title>Demonstration Functions - GNU Octave</title> <meta http-equiv="Content-Type" content="text/html"> <meta name="description" content="GNU Octave"> <meta name="generator" content="makeinfo 4.13"> <link title="Top" rel="start" href="index.html#Top"> <link rel="up" href="Test-and-Demo-Functions.html#Test-and-Demo-Functions" title="Test and Demo Functions"> <link rel="prev" href="Test-Functions.html#Test-Functions" title="Test Functions"> <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> <meta http-equiv="Content-Style-Type" content="text/css"> <style type="text/css"><!-- pre.display { font-family:inherit } pre.format { font-family:inherit } pre.smalldisplay { font-family:inherit; font-size:smaller } pre.smallformat { font-family:inherit; font-size:smaller } pre.smallexample { font-size:smaller } pre.smalllisp { font-size:smaller } span.sc { font-variant:small-caps } span.roman { font-family:serif; font-weight:normal; } span.sansserif { font-family:sans-serif; font-weight:normal; } --></style> </head> <body> <div class="node"> <a name="Demonstration-Functions"></a> <p> Previous: <a rel="previous" accesskey="p" href="Test-Functions.html#Test-Functions">Test Functions</a>, Up: <a rel="up" accesskey="u" href="Test-and-Demo-Functions.html#Test-and-Demo-Functions">Test and Demo Functions</a> <hr> </div> <h3 class="section">B.2 Demonstration Functions</h3> <!-- demo scripts/testfun/demo.m --> <p><a name="doc_002ddemo"></a> <div class="defun"> — Command: <b>demo</b><var> name<a name="index-demo-3390"></a></var><br> — Command: <b>demo</b><var> name n<a name="index-demo-3391"></a></var><br> — Function File: <b>demo</b> (<var>'name'</var>)<var><a name="index-demo-3392"></a></var><br> — Function File: <b>demo</b> (<var>'name', n</var>)<var><a name="index-demo-3393"></a></var><br> <blockquote> <p>Run example code block <var>n</var> associated with the function <var>name</var>. If <var>n</var> is not specified, all examples are run. <p>Examples are stored in the script file, or in a file with the same name but no extension located on Octave's load path. To keep examples separate from regular script code, all lines are prefixed by <code>%!</code>. 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: <pre class="example"> %!demo %! t=0:0.01:2*pi; x = sin (t); %! plot (t,x) %! %------------------------------------------------- %! % the figure window shows one cycle of a sine wave </pre> <p>Note that the code is displayed before it is executed, so a simple comment at the end suffices for labeling what is being shown. It is generally not necessary to use <code>disp</code> or <code>printf</code> within the demo. <p>Demos are run in a 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 <pre class="example"> %! input("Press <enter> to continue: ","s"); </pre> <p class="noindent">between the sections, but this is discouraged. Other techniques to avoid multiple initialization blocks include using multiple plots with a new <code>figure</code> command between each plot, or using <code>subplot</code> to put multiple plots in the same window. <p>Also, because demo evaluates within a function context, you cannot define new functions inside a demo. If you must have function blocks, rather than just anonymous functions or inline functions, you will have to use <code>eval(example('function',n))</code> 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: <pre class="example"> %!demo if 1 %! function y=f(x) %! y=x; %! endfunction %! f(3) %! endif </pre> <!-- Texinfo @sp should work but in practice produces ugly results for HTML. --> <!-- A simple blank line produces the correct behavior. --> <!-- @sp 1 --> <p class="noindent"><strong>See also:</strong> <a href="doc_002dtest.html#doc_002dtest">test</a>, <a href="doc_002dexample.html#doc_002dexample">example</a>. </p></blockquote></div> <!-- example scripts/testfun/example.m --> <p><a name="doc_002dexample"></a> <div class="defun"> — Command: <b>example</b><var> name<a name="index-example-3394"></a></var><br> — Command: <b>example</b><var> name n<a name="index-example-3395"></a></var><br> — Function File: <b>example</b> (<var>'name'</var>)<var><a name="index-example-3396"></a></var><br> — Function File: <b>example</b> (<var>'name', n</var>)<var><a name="index-example-3397"></a></var><br> — Function File: [<var>s</var>, <var>idx</var>] = <b>example</b> (<var><small class="dots">...</small></var>)<var><a name="index-example-3398"></a></var><br> <blockquote> <p>Display the code for example <var>n</var> associated with the function '<var>name</var>', but do not run it. If <var>n</var> is not specified, all examples are displayed. <p>When called with output arguments, the examples are returned in the form of a string <var>s</var>, with <var>idx</var> indicating the ending position of the various examples. <p>See <code>demo</code> for a complete explanation. <!-- Texinfo @sp should work but in practice produces ugly results for HTML. --> <!-- A simple blank line produces the correct behavior. --> <!-- @sp 1 --> <p class="noindent"><strong>See also:</strong> <a href="doc_002ddemo.html#doc_002ddemo">demo</a>, <a href="doc_002dtest.html#doc_002dtest">test</a>. </p></blockquote></div> <!-- rundemos scripts/testfun/rundemos.m --> <p><a name="doc_002drundemos"></a> <div class="defun"> — Function File: <b>rundemos</b> ()<var><a name="index-rundemos-3399"></a></var><br> — Function File: <b>rundemos</b> (<var>directory</var>)<var><a name="index-rundemos-3400"></a></var><br> <blockquote><p>Execute built-in demos for all function files in the specified directory. If no directory is specified, operate on all directories in Octave's search path for functions. <!-- Texinfo @sp should work but in practice produces ugly results for HTML. --> <!-- A simple blank line produces the correct behavior. --> <!-- @sp 1 --> <p class="noindent"><strong>See also:</strong> <a href="doc_002druntests.html#doc_002druntests">runtests</a>, <a href="doc_002dpath.html#doc_002dpath">path</a>. </p></blockquote></div> <!-- runtests scripts/testfun/runtests.m --> <p><a name="doc_002druntests"></a> <div class="defun"> — Function File: <b>runtests</b> ()<var><a name="index-runtests-3401"></a></var><br> — Function File: <b>runtests</b> (<var>directory</var>)<var><a name="index-runtests-3402"></a></var><br> <blockquote><p>Execute built-in tests for all function files in the specified directory. If no directory is specified, operate on all directories in Octave's search path for functions. <!-- Texinfo @sp should work but in practice produces ugly results for HTML. --> <!-- A simple blank line produces the correct behavior. --> <!-- @sp 1 --> <p class="noindent"><strong>See also:</strong> <a href="doc_002drundemos.html#doc_002drundemos">rundemos</a>, <a href="doc_002dpath.html#doc_002dpath">path</a>. </p></blockquote></div> <!-- speed scripts/testfun/speed.m --> <p><a name="doc_002dspeed"></a> <div class="defun"> — Function File: <b>speed</b> (<var>f, init, max_n, f2, tol</var>)<var><a name="index-speed-3403"></a></var><br> — Function File: [<var>order</var>, <var>n</var>, <var>T_f</var>, <var>T_f2</var>] = <b>speed</b> (<var><small class="dots">...</small></var>)<var><a name="index-speed-3404"></a></var><br> <blockquote> <p>Determine the execution time of an expression (<var>f</var>) for various input values (<var>n</var>). The <var>n</var> are log-spaced from 1 to <var>max_n</var>. For each <var>n</var>, an initialization expression (<var>init</var>) is computed to create any data needed for the test. If a second expression (<var>f2</var>) 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. <dl> <dt><var>f</var><dd>The code expression to evaluate. <br><dt><var>max_n</var><dd>The maximum test length to run. The default value is 100. Alternatively, use <code>[min_n, max_n]</code> or specify the <var>n</var> exactly with <code>[n1, n2, ..., nk]</code>. <br><dt><var>init</var><dd>Initialization expression for function argument values. Use <var>k</var> for the test number and <var>n</var> for the size of the test. This should compute values for all variables used by <var>f</var>. Note that <var>init</var> will be evaluated first for k = 0, so things which are constant throughout the test series can be computed once. The default value is <var>x</var><code> = randn (</code><var>n</var><code>, 1)</code>. <br><dt><var>f2</var><dd>An alternative expression to evaluate, so that the speed of two expressions can be directly compared. The default is <code>[]</code>. <br><dt><var>tol</var><dd>Tolerance used to compare the results of expression <var>f</var> and expression <var>f2</var>. If <var>tol</var> is positive, the tolerance is an absolute one. If <var>tol</var> is negative, the tolerance is a relative one. The default is <code>eps</code>. If <var>tol</var> is <code>Inf</code>, then no comparison will be made. <br><dt><var>order</var><dd>The time complexity of the expression O(a*n^p). This is a structure with fields <code>a</code> and <code>p</code>. <br><dt><var>n</var><dd>The values <var>n</var> for which the expression was calculated <strong>AND</strong> the execution time was greater than zero. <br><dt><var>T_f</var><dd>The nonzero execution times recorded for the expression <var>f</var> in seconds. <br><dt><var>T_f2</var><dd>The nonzero execution times recorded for the expression <var>f2</var> in seconds. If required, the mean time ratio is simply <code>mean (T_f ./ T_f2)</code>. </dl> <p>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). <pre class="example"> speed ("for i = 1:n, y{i} = x(i); endfor", "", [1000, 10000]) </pre> <p class="noindent">But it is if you preallocate the cell array <code>y</code>: <pre class="example"> speed ("for i = 1:n, y{i} = x(i); endfor", ... "x = rand (n, 1); y = cell (size (x));", [1000, 10000]) </pre> <p>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 <code>n</code>. For example: <pre class="example"> speed ("airy(x)", "x = rand (n, 10)", [10000, 100000]) </pre> <p>When comparing two different expressions (<var>f</var>, <var>f2</var>), 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: <pre class="example"> speed ("sum (x)", "", [10000, 100000], ... "v = 0; for i = 1:length (x), v += x(i); endfor") </pre> <p>The following is a more complex example. If there was an original version of <code>xcorr</code> 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: <pre class="example"> 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) </pre> <p>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 <code>100*eps</code>. In this case, the comparison should be computed relatively, as <code>abs ((</code><var>x</var><code> - </code><var>y</var><code>) ./ </code><var>y</var><code>)</code> rather than absolutely as <code>abs (</code><var>x</var><code> - </code><var>y</var><code>)</code>. <p>Type <kbd>example ("speed")</kbd> to see some real examples or <kbd>demo ("speed")</kbd> to run them. </p></blockquote></div> <!-- DO NOT EDIT! Generated automatically by munge-texi.pl. --> <!-- Copyright (C) 1996-2012 John W. Eaton --> <!-- This file is part of Octave. --> <!-- Octave is free software; you can redistribute it and/or modify it --> <!-- under the terms of the GNU General Public License as published by the --> <!-- Free Software Foundation; either version 3 of the License, or (at --> <!-- your option) any later version. --> <!-- Octave is distributed in the hope that it will be useful, but WITHOUT --> <!-- ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or --> <!-- FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --> <!-- for more details. --> <!-- You should have received a copy of the GNU General Public License --> <!-- along with Octave; see the file COPYING. If not, see --> <!-- <http://www.gnu.org/licenses/>. --> </body></html>