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
319
320
321
322
323
324
325
|
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Demonstration Functions (GNU Octave (version 10.3.0))</title>
<meta name="description" content="Demonstration Functions (GNU Octave (version 10.3.0))">
<meta name="keywords" content="Demonstration Functions (GNU Octave (version 10.3.0))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Concept-Index.html" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Test-and-Demo-Functions.html" rel="up" title="Test and Demo Functions">
<link href="Test-Functions.html" rel="prev" title="Test Functions">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
kbd.kbd {font-style: oblique}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">
</head>
<body lang="en">
<div class="section-level-extent" id="Demonstration-Functions">
<div class="nav-panel">
<p>
Previous: <a href="Test-Functions.html" accesskey="p" rel="prev">Test Functions</a>, Up: <a href="Test-and-Demo-Functions.html" 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" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h3 class="section" id="Demonstration-Functions-1"><span>B.2 Demonstration Functions<a class="copiable-link" href="#Demonstration-Functions-1"> ¶</a></span></h3>
<a class="anchor" id="XREFdemo"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-demo"><span><strong class="def-name">demo</strong> <code class="def-code-arguments"><var class="var">name</var></code><a class="copiable-link" href="#index-demo"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-demo-1"><span><strong class="def-name">demo</strong> <code class="def-code-arguments"><var class="var">name</var> <var class="var">n</var></code><a class="copiable-link" href="#index-demo-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-demo-2"><span><strong class="def-name">demo</strong> <code class="def-code-arguments">("<var class="var">name</var>")</code><a class="copiable-link" href="#index-demo-2"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-demo-3"><span><strong class="def-name">demo</strong> <code class="def-code-arguments">("<var class="var">name</var>", <var class="var">n</var>)</code><a class="copiable-link" href="#index-demo-3"> ¶</a></span></dt>
<dd>
<p>Run example code block <var class="var">n</var> associated with the function <var class="var">name</var>.
</p>
<p>If <var class="var">n</var> is not specified, all examples are run.
</p>
<p>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 <code class="code">%!</code>. Each example must also be
introduced by the keyword <code class="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">
<div class="group"><pre class="example-preformatted">%!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
</pre></div></div>
<p>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 <code class="code">title</code> or <code class="code">text</code>. It is generally
<strong class="strong">not</strong> necessary to use <code class="code">disp</code> or <code class="code">printf</code> within the demo.
</p>
<p>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
</p>
<div class="example">
<pre class="example-preformatted">%! input ("Press <enter> to continue: ", "s");
</pre></div>
<p>between the sections, but this usage is discouraged. Other techniques to
avoid multiple initialization blocks include using multiple plots with a new
<code class="code">figure</code> command between each plot, or using <code class="code">subplot</code> to put
multiple plots in the same window.
</p>
<p>Finally, because <code class="code">demo</code> 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 <strong class="strong">must</strong> be
used then the code <code class="code">eval (example ("function", n))</code> will allow Octave
to see them. This has its own problems, however, as <code class="code">eval</code> only
evaluates one line or statement at a time. In this case the function
declaration must be wrapped with <code class="code">"if 1 <demo stuff> endif"</code> where
<code class="code">"if"</code> is on the same line as <code class="code">"demo"</code>. For example:
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">%!demo if 1
%! function y = f(x)
%! y = x;
%! endfunction
%! f(3)
%! endif
</pre></div></div>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFrundemos">rundemos</a>, <a class="ref" href="#XREFexample">example</a>, <a class="ref" href="Test-Functions.html#XREFtest">test</a>.
</p></dd></dl>
<a class="anchor" id="XREFexample"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-example"><span><strong class="def-name">example</strong> <code class="def-code-arguments"><var class="var">name</var></code><a class="copiable-link" href="#index-example"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-example-1"><span><strong class="def-name">example</strong> <code class="def-code-arguments"><var class="var">name</var> <var class="var">n</var></code><a class="copiable-link" href="#index-example-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-example-2"><span><strong class="def-name">example</strong> <code class="def-code-arguments">("<var class="var">name</var>")</code><a class="copiable-link" href="#index-example-2"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-example-3"><span><strong class="def-name">example</strong> <code class="def-code-arguments">("<var class="var">name</var>", <var class="var">n</var>)</code><a class="copiable-link" href="#index-example-3"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-example-4"><span><code class="def-type">[<var class="var">codestr</var>, <var class="var">codeidx</var>] =</code> <strong class="def-name">example</strong> <code class="def-code-arguments">(…)</code><a class="copiable-link" href="#index-example-4"> ¶</a></span></dt>
<dd>
<p>Display the code for example <var class="var">n</var> associated with the function
<var class="var">name</var>, but do not run it.
</p>
<p>If <var class="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 class="var">codestr</var>, with <var class="var">codeidx</var> indicating the ending position of
the various examples.
</p>
<p>For a complete explanation see <a class="pxref" href="#XREFdemo"><code class="code">demo</code></a>.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFdemo">demo</a>, <a class="ref" href="Test-Functions.html#XREFtest">test</a>.
</p></dd></dl>
<a class="anchor" id="XREForuntests"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-oruntests"><span><strong class="def-name">oruntests</strong> <code class="def-code-arguments">()</code><a class="copiable-link" href="#index-oruntests"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-oruntests-1"><span><strong class="def-name">oruntests</strong> <code class="def-code-arguments">(<var class="var">directory</var>)</code><a class="copiable-link" href="#index-oruntests-1"> ¶</a></span></dt>
<dd><p>Execute built-in tests for all m-files in the specified <var class="var">directory</var>.
</p>
<p>Test blocks in any C++ source files (<samp class="file">*.cc</samp>) will also be executed
for use with dynamically linked oct-file functions.
</p>
<p>If no directory is specified, operate on all directories in Octave’s search
path for functions.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFrundemos">rundemos</a>, <a class="ref" href="Test-Functions.html#XREFtest">test</a>, <a class="ref" href="Manipulating-the-Load-Path.html#XREFpath">path</a>.
</p></dd></dl>
<a class="anchor" id="XREFrundemos"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-rundemos"><span><strong class="def-name">rundemos</strong> <code class="def-code-arguments">()</code><a class="copiable-link" href="#index-rundemos"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-rundemos-1"><span><strong class="def-name">rundemos</strong> <code class="def-code-arguments">(<var class="var">directory</var>)</code><a class="copiable-link" href="#index-rundemos-1"> ¶</a></span></dt>
<dd><p>Execute built-in demos for all m-files in the specified <var class="var">directory</var>.
</p>
<p>Demo blocks in any C++ source files (<samp class="file">*.cc</samp>) will also be executed
for use with dynamically linked oct-file functions.
</p>
<p>If no directory is specified, operate on all directories in Octave’s search
path for functions.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFdemo">demo</a>, <a class="ref" href="#XREForuntests">oruntests</a>, <a class="ref" href="Manipulating-the-Load-Path.html#XREFpath">path</a>.
</p></dd></dl>
<a class="anchor" id="XREFspeed"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-speed"><span><strong class="def-name">speed</strong> <code class="def-code-arguments">(<var class="var">f</var>, <var class="var">init</var>, <var class="var">max_n</var>, <var class="var">f2</var>, <var class="var">tol</var>)</code><a class="copiable-link" href="#index-speed"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-speed-1"><span><code class="def-type">[<var class="var">order</var>, <var class="var">n</var>, <var class="var">T_f</var>, <var class="var">T_f2</var>] =</code> <strong class="def-name">speed</strong> <code class="def-code-arguments">(…)</code><a class="copiable-link" href="#index-speed-1"> ¶</a></span></dt>
<dd>
<p>Determine the execution time of an expression (<var class="var">f</var>) for various input
values (<var class="var">n</var>).
</p>
<p>The <var class="var">n</var> are log-spaced from 1 to <var class="var">max_n</var>. For each <var class="var">n</var>, an
initialization expression (<var class="var">init</var>) is computed to create any data needed
for the test. If a second expression (<var class="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 class="table">
<dt><code class="code"><var class="var">f</var></code></dt>
<dd><p>The code expression to evaluate.
</p>
</dd>
<dt><code class="code"><var class="var">max_n</var></code></dt>
<dd><p>The maximum test length to run. The default value is 100. Alternatively,
use <code class="code">[min_n, max_n]</code> or specify the <var class="var">n</var> exactly with
<code class="code">[n1, n2, …, nk]</code>.
</p>
</dd>
<dt><code class="code"><var class="var">init</var></code></dt>
<dd><p>Initialization expression for function argument values. Use <var class="var">k</var> for
the test number and <var class="var">n</var> for the size of the test. This should compute
values for all variables used by <var class="var">f</var>. Note that <var class="var">init</var> will be
evaluated first for <em class="math">k = 0</em>, so things which are constant throughout
the test series can be computed once. The default value is
<code class="code"><var class="var">x</var> = randn (<var class="var">n</var>, 1)</code>.
</p>
</dd>
<dt><code class="code"><var class="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 class="code">[]</code>.
</p>
</dd>
<dt><code class="code"><var class="var">tol</var></code></dt>
<dd><p>Tolerance used to compare the results of expression <var class="var">f</var> and expression
<var class="var">f2</var>. If <var class="var">tol</var> is positive, the tolerance is an absolute one.
If <var class="var">tol</var> is negative, the tolerance is a relative one. The default is
<code class="code">eps</code>. If <var class="var">tol</var> is <code class="code">Inf</code>, then no comparison will be made.
</p>
</dd>
<dt><code class="code"><var class="var">order</var></code></dt>
<dd><p>The time complexity of the expression <em class="math">O(a*n^p)</em>. This is a
structure with fields <code class="code">a</code> and <code class="code">p</code>.
</p>
</dd>
<dt><code class="code"><var class="var">n</var></code></dt>
<dd><p>The values <var class="var">n</var> for which the expression was calculated <strong class="strong">AND</strong>
the execution time was greater than zero.
</p>
</dd>
<dt><code class="code"><var class="var">T_f</var></code></dt>
<dd><p>The nonzero execution times recorded for the expression <var class="var">f</var> in seconds.
</p>
</dd>
<dt><code class="code"><var class="var">T_f2</var></code></dt>
<dd><p>The nonzero execution times recorded for the expression <var class="var">f2</var> in seconds.
If required, the mean time ratio is simply <code class="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 class="math">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 class="math">O(n^2)</em> rather than
<em class="math">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 class="math">O(n)</em>.
</p>
<div class="example">
<pre class="example-preformatted">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 class="code">y</code>:
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">speed ("for i = 1:n, y{i} = x(i); endfor", ...
"x = rand (n, 1); y = cell (size (x));", [1000, 10000])
</pre></div></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 class="code">n</code>. For example:
</p>
<div class="example">
<pre class="example-preformatted">speed ("airy(x)", "x = rand (n, 10)", [10000, 100000])
</pre></div>
<p>When comparing two different expressions (<var class="var">f</var>, <var class="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">
<div class="group"><pre class="example-preformatted">speed ("sum (x)", "", [10000, 100000], ...
"v = 0; for i = 1:length (x), v += x(i); endfor")
</pre></div></div>
<p>The following is a more complex example. If there was an original version
of <code class="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">
<div class="group"><pre class="example-preformatted">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></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 class="code">100*eps</code>.
In this case, the comparison should be computed relatively, as
<code class="code">abs ((<var class="var">x</var> - <var class="var">y</var>) ./ <var class="var">y</var>)</code> rather than absolutely as
<code class="code">abs (<var class="var">x</var> - <var class="var">y</var>)</code>.
</p>
<p>Type <kbd class="kbd">example ("speed")</kbd> to see some real examples or
<kbd class="kbd">demo ("speed")</kbd> to run them.
</p>
</dd></dl>
</div>
<hr>
<div class="nav-panel">
<p>
Previous: <a href="Test-Functions.html">Test Functions</a>, Up: <a href="Test-and-Demo-Functions.html">Test and Demo Functions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
