1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU Octave: Demonstration Functions</title>
<meta name="description" content="GNU Octave: Demonstration Functions">
<meta name="keywords" content="GNU Octave: Demonstration Functions">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Test-and-Demo-Functions.html#Test-and-Demo-Functions" rel="up" title="Test and Demo Functions">
<link href="Tips-and-Standards.html#Tips-and-Standards" rel="next" title="Tips and Standards">
<link href="Test-Functions.html#Test-Functions" rel="prev" title="Test Functions">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Demonstration-Functions"></a>
<div class="header">
<p>
Previous: <a href="Test-Functions.html#Test-Functions" accesskey="p" rel="prev">Test Functions</a>, Up: <a href="Test-and-Demo-Functions.html#Test-and-Demo-Functions" accesskey="u" rel="up">Test and Demo Functions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Demonstration-Functions-1"></a>
<h3 class="section">B.2 Demonstration Functions</h3>
<a name="XREFdemo"></a><dl>
<dt><a name="index-demo"></a>Command: <em></em> <strong>demo</strong> <em><var>name</var></em></dt>
<dt><a name="index-demo-1"></a>Command: <em></em> <strong>demo</strong> <em><var>name</var> <var>n</var></em></dt>
<dt><a name="index-demo-2"></a>Function File: <em></em> <strong>demo</strong> <em>("<var>name</var>")</em></dt>
<dt><a name="index-demo-3"></a>Function File: <em></em> <strong>demo</strong> <em>("<var>name</var>", <var>n</var>)</em></dt>
<dd>
<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>
<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 <code>"demo"</code> flush left
to the prefix with no intervening spaces. The remainder of the example
can contain arbitrary Octave code. For example:
</p>
<div class="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></div>
<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>
<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
</p>
<div class="example">
<pre class="example">%! input("Press <enter> to continue: ","s");
</pre></div>
<p>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>
<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 <code>"if 1 <demo stuff> endif"</code>
with the <code>"if"</code> on the same line as <code>"demo"</code>. For example:
</p>
<div class="example">
<pre class="example">%!demo if 1
%! function y=f(x)
%! y=x;
%! endfunction
%! f(3)
%! endif
</pre></div>
<p><strong>See also:</strong> <a href="Test-Functions.html#XREFtest">test</a>, <a href="#XREFexample">example</a>.
</p></dd></dl>
<a name="XREFexample"></a><dl>
<dt><a name="index-example"></a>Command: <em></em> <strong>example</strong> <em><var>name</var></em></dt>
<dt><a name="index-example-1"></a>Command: <em></em> <strong>example</strong> <em><var>name</var> <var>n</var></em></dt>
<dt><a name="index-example-2"></a>Function File: <em></em> <strong>example</strong> <em>("<var>name</var>")</em></dt>
<dt><a name="index-example-3"></a>Function File: <em></em> <strong>example</strong> <em>("<var>name</var>", <var>n</var>)</em></dt>
<dt><a name="index-example-4"></a>Function File: <em>[<var>s</var>, <var>idx</var>] =</em> <strong>example</strong> <em>(…)</em></dt>
<dd>
<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>
<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>
<p>See <code>demo</code> for a complete explanation.
</p>
<p><strong>See also:</strong> <a href="#XREFdemo">demo</a>, <a href="Test-Functions.html#XREFtest">test</a>.
</p></dd></dl>
<a name="XREFrundemos"></a><dl>
<dt><a name="index-rundemos"></a>Function File: <em></em> <strong>rundemos</strong> <em>()</em></dt>
<dt><a name="index-rundemos-1"></a>Function File: <em></em> <strong>rundemos</strong> <em>(<var>directory</var>)</em></dt>
<dd><p>Execute built-in demos for all function files in the specified directory.
Also executes demos in any C++ source files found in the directory, for
use with dynamically linked functions.
</p>
<p>If no directory is specified, operate on all directories in Octave’s
search path for functions.
</p>
<p><strong>See also:</strong> <a href="#XREFruntests">runtests</a>, <a href="Manipulating-the-Load-Path.html#XREFpath">path</a>.
</p></dd></dl>
<a name="XREFruntests"></a><dl>
<dt><a name="index-runtests"></a>Function File: <em></em> <strong>runtests</strong> <em>()</em></dt>
<dt><a name="index-runtests-1"></a>Function File: <em></em> <strong>runtests</strong> <em>(<var>directory</var>)</em></dt>
<dd><p>Execute built-in tests for all function files in the specified directory.
Also executes tests in any C++ source files found in the directory, for
use with dynamically linked functions.
</p>
<p>If no directory is specified, operate on all directories in Octave’s
search path for functions.
</p>
<p><strong>See also:</strong> <a href="#XREFrundemos">rundemos</a>, <a href="Manipulating-the-Load-Path.html#XREFpath">path</a>.
</p></dd></dl>
<a name="XREFspeed"></a><dl>
<dt><a name="index-speed"></a>Function File: <em></em> <strong>speed</strong> <em>(<var>f</var>, <var>init</var>, <var>max_n</var>, <var>f2</var>, <var>tol</var>)</em></dt>
<dt><a name="index-speed-1"></a>Function File: <em>[<var>order</var>, <var>n</var>, <var>T_f</var>, <var>T_f2</var>] =</em> <strong>speed</strong> <em>(…)</em></dt>
<dd>
<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.
</p>
<dl compact="compact">
<dt><code><var>f</var></code></dt>
<dd><p>The code expression to evaluate.
</p>
</dd>
<dt><code><var>max_n</var></code></dt>
<dd><p>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>.
</p>
</dd>
<dt><code><var>init</var></code></dt>
<dd><p>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 <em>k = 0</em>, so things which are constant throughout
the test series can be computed once. The default value is
<code><var>x</var> = randn (<var>n</var>, 1)</code>.
</p>
</dd>
<dt><code><var>f2</var></code></dt>
<dd><p>An alternative expression to evaluate, so that the speed of two
expressions can be directly compared. The default is <code>[]</code>.
</p>
</dd>
<dt><code><var>tol</var></code></dt>
<dd><p>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.
</p>
</dd>
<dt><code><var>order</var></code></dt>
<dd><p>The time complexity of the expression <em>O(a*n^p)</em>. This
is a structure with fields <code>a</code> and <code>p</code>.
</p>
</dd>
<dt><code><var>n</var></code></dt>
<dd><p>The values <var>n</var> for which the expression was calculated <strong>AND</strong>
the execution time was greater than zero.
</p>
</dd>
<dt><code><var>T_f</var></code></dt>
<dd><p>The nonzero execution times recorded for the expression <var>f</var> in seconds.
</p>
</dd>
<dt><code><var>T_f2</var></code></dt>
<dd><p>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>.
</p>
</dd>
</dl>
<p>The slope of the execution time graph shows the approximate
power of the asymptotic running time <em>O(n^p)</em>. 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 <em>O(n^2)</em>
rather than <em>O(n)</em> 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 <em>O(n)</em>.
</p>
<div class="example">
<pre class="example">speed ("for i = 1:n, y{i} = x(i); endfor", "", [1000, 10000])
</pre></div>
<p>But it is if you preallocate the cell array <code>y</code>:
</p>
<div class="example">
<pre class="example">speed ("for i = 1:n, y{i} = x(i); endfor", ...
"x = rand (n, 1); y = cell (size (x));", [1000, 10000])
</pre></div>
<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:
</p>
<div class="example">
<pre class="example">speed ("airy(x)", "x = rand (n, 10)", [10000, 100000])
</pre></div>
<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:
</p>
<div class="example">
<pre class="example">speed ("sum (x)", "", [10000, 100000], ...
"v = 0; for i = 1:length (x), v += x(i); endfor")
</pre></div>
<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:
</p>
<div class="example">
<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></div>
<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 ((<var>x</var> - <var>y</var>) ./ <var>y</var>)</code> rather
than absolutely as <code>abs (<var>x</var> - <var>y</var>)</code>.
</p>
<p>Type <kbd>example ("speed")</kbd> to see some real examples or
<kbd>demo ("speed")</kbd> to run them.
</p></dd></dl>
<hr>
<div class="header">
<p>
Previous: <a href="Test-Functions.html#Test-Functions" accesskey="p" rel="prev">Test Functions</a>, Up: <a href="Test-and-Demo-Functions.html#Test-and-Demo-Functions" accesskey="u" rel="up">Test and Demo Functions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
