Mercurial > octave

annotate doc/interpreter/vectorize.txi @ 32489:a4506463f341 stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: grammarcheck Octave manual before 9.1 release. * doc/interpreter/func.txi, doc/interpreter/numbers.txi, doc/interpreter/octave.texi, doc/interpreter/plot.txi, doc/interpreter/sparse.txi, doc/interpreter/vectorize.txi, scripts/miscellaneous/jupyter_notebook.m, scripts/plot/draw/stemleaf.m: grammarcheck Octave manual before 9.1 release.
author Rik <rik@octave.org>
date Thu, 23 Nov 2023 20:30:44 -0800
parents ffc410f26506
children 386d05bbae5a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
31706
597f3ee61a48 update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents: 31376
diff changeset
1 @c Copyright (C) 2012-2023 The Octave Project Developers
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
2 @c
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
3 @c This file is part of Octave.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
4 @c
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
5 @c Octave is free software: you can redistribute it and/or modify it
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
6 @c under the terms of the GNU General Public License as published by
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
7 @c the Free Software Foundation, either version 3 of the License, or
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
8 @c (at your option) any later version.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
9 @c
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
10 @c Octave is distributed in the hope that it will be useful, but
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
11 @c WITHOUT ANY WARRANTY; without even the implied warranty of
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
12 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
13 @c GNU General Public License for more details.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
14 @c
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
15 @c You should have received a copy of the GNU General Public License
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
16 @c along with Octave; see the file COPYING. If not, see
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
17 @c <https://www.gnu.org/licenses/>.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
18
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
19 @node Vectorization and Faster Code Execution
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
20 @chapter Vectorization and Faster Code Execution
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
21 @cindex vectorization
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
22 @cindex vectorize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
23
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
24 Vectorization is a programming technique that uses vector operations
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
25 instead of element-by-element loop-based operations. Besides frequently
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
26 producing more succinct Octave code, vectorization also allows for better
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
27 optimization in the subsequent implementation. The optimizations may occur
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
28 either in Octave's own Fortran, C, or C++ internal implementation, or even at a
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
29 lower level depending on the compiler and external numerical libraries used to
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
30 build Octave. The ultimate goal is to make use of your hardware's vector
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
31 instructions if possible or to perform other optimizations in software.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
32
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
33 Vectorization is not a concept unique to Octave, but it is particularly
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
34 important because Octave is a matrix-oriented language. Vectorized
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
35 Octave code will see a dramatic speed up (10X--100X) in most cases.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
36
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
37 This chapter discusses vectorization and other techniques for writing faster
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
38 code.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
39
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
40 @menu
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
41 * Basic Vectorization:: Basic techniques for code optimization
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
42 * Broadcasting:: Broadcasting operations
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
43 * Function Application:: Applying functions to arrays, cells, and structs
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
44 * Accumulation:: Accumulation functions
31246
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
45 * Memoization:: Memoization techniques
32429
ffc410f26506 doc: Rename virtual machine / VM as bytecode interpreter
Arun Giridhar <arungiridhar@gmail.com>
parents: 32422
diff changeset
46 * Bytecode interpreter:: Bytecode interpreter
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
47 * Miscellaneous Techniques:: Other techniques for speeding up code
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
48 * Examples::
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
49 @end menu
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
50
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
51 @node Basic Vectorization
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
52 @section Basic Vectorization
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
53
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
54 To a very good first approximation, the goal in vectorization is to
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
55 write code that avoids loops and uses whole-array operations. As a
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
56 trivial example, consider
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
57
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
58 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
59 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
60 for i = 1:n
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
61 for j = 1:m
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
62 c(i,j) = a(i,j) + b(i,j);
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
63 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
64 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
65 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
66 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
67
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
68 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
69 compared to the much simpler
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
70
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
71 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
72 c = a + b;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
73 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
74
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
75 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
76 This isn't merely easier to write; it is also internally much easier to
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
77 optimize. Octave delegates this operation to an underlying
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
78 implementation which, among other optimizations, may use special vector
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
79 hardware instructions or could conceivably even perform the additions in
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
80 parallel. In general, if the code is vectorized, the underlying
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
81 implementation has more freedom about the assumptions it can make
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
82 in order to achieve faster execution.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
83
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
84 This is especially important for loops with "cheap" bodies. Often it
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
85 suffices to vectorize just the innermost loop to get acceptable
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
86 performance. A general rule of thumb is that the "order" of the
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
87 vectorized body should be greater or equal to the "order" of the
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
88 enclosing loop.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
89
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
90 As a less trivial example, instead of
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
91
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
92 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
93 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
94 for i = 1:n-1
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
95 a(i) = b(i+1) - b(i);
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
96 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
97 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
98 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
99
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
100 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
101 write
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
102
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
103 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
104 a = b(2:n) - b(1:n-1);
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
105 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
106
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
107 This shows an important general concept about using arrays for indexing
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
108 instead of looping over an index variable. @xref{Index Expressions}.
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
109 Also use boolean indexing generously. If a condition needs to be tested,
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
110 this condition can also be written as a boolean index. For instance,
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
111 instead of
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
112
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
113 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
114 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
115 for i = 1:n
16934
48f5b993b819 doc: Use parentheses around if, switch conditions in documentation.
Rik <rik@octave.org>
parents: 16878
diff changeset
116 if (a(i) > 5)
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
117 a(i) -= 20
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
118 endif
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
119 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
120 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
121 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
122
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
123 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
124 write
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
125
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
126 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
127 a(a>5) -= 20;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
128 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
129
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
130 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
131 which exploits the fact that @code{a > 5} produces a boolean index.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
132
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
133 Use elementwise vector operators whenever possible to avoid looping
28428
e9a12be5fd79 don't document the vectorize function.
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
134 (operators like @code{.*} and @code{.^}). @xref{Arithmetic Ops}.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
135
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
136 Also exploit broadcasting in these elementwise operators both to avoid
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
137 looping and unnecessary intermediate memory allocations.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
138 @xref{Broadcasting}.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
139
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
140 Use built-in and library functions if possible. Built-in and compiled
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
141 functions are very fast. Even with an m-file library function, chances
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
142 are good that it is already optimized, or will be optimized more in a
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
143 future release.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
144
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
145 For instance, even better than
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
146
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
147 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
148 a = b(2:n) - b(1:n-1);
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
149 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
150
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
151 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
152 is
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
153
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
154 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
155 a = diff (b);
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
156 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
157
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
158 Most Octave functions are written with vector and array arguments in
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
159 mind. If you find yourself writing a loop with a very simple operation,
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
160 chances are that such a function already exists. The following functions
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
161 occur frequently in vectorized code:
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
162
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
163 @itemize @bullet
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
164 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
165 Index manipulation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
166
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
167 @itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
168 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
169 find
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
170
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
171 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
172 sub2ind
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
173
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
174 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
175 ind2sub
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
176
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
177 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
178 sort
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
179
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
180 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
181 unique
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
182
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
183 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
184 lookup
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
185
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
186 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
187 ifelse / merge
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
188 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
189
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
190 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
191 Repetition
14853
72b8b39e12be doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
192
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
193 @itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
194 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
195 repmat
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
196
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
197 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
198 repelems
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
199 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
200
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
201 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
202 Vectorized arithmetic
14853
72b8b39e12be doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
203
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
204 @itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
205 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
206 sum
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
207
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
208 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
209 prod
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
210
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
211 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
212 cumsum
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
213
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
214 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
215 cumprod
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
216
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
217 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
218 sumsq
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
219
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
220 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
221 diff
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
222
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
223 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
224 dot
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
225
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
226 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
227 cummax
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
228
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
229 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
230 cummin
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
231 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
232
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
233 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
234 Shape of higher dimensional arrays
14853
72b8b39e12be doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
235
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
236 @itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
237 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
238 reshape
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
239
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
240 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
241 resize
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
242
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
243 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
244 permute
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
245
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
246 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
247 squeeze
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
248
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
249 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
250 deal
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
251 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
252
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
253 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
254
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
255 @node Broadcasting
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
256 @section Broadcasting
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
257 @cindex broadcast
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
258 @cindex broadcasting
25003
2365c2661b3c doc: Spellcheck documentation ahead of 4.4 release.
Rik <rik@octave.org>
parents: 24534
diff changeset
259 @cindex @nospell{BSX}
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
260 @cindex recycling
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
261 @cindex SIMD
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
262
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
263 Broadcasting refers to how Octave binary operators and functions behave
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
264 when their matrix or array operands or arguments differ in size. Since
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
265 version 3.6.0, Octave now automatically broadcasts vectors, matrices,
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
266 and arrays when using elementwise binary operators and functions.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
267 Broadly speaking, smaller arrays are ``broadcast'' across the larger
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
268 one, until they have a compatible shape. The rule is that corresponding
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
269 array dimensions must either
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
270
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
271 @enumerate
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
272 @item
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
273 be equal, or
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
274
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
275 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
276 one of them must be 1.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
277 @end enumerate
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
278
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
279 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
280 In case all dimensions are equal, no broadcasting occurs and ordinary
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
281 element-by-element arithmetic takes place. For arrays of higher
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
282 dimensions, if the number of dimensions isn't the same, then missing
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
283 trailing dimensions are treated as 1. When one of the dimensions is 1,
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
284 the array with that singleton dimension gets copied along that dimension
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
285 until it matches the dimension of the other array. For example, consider
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
286
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
287 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
288 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
289 x = [1 2 3;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
290 4 5 6;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
291 7 8 9];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
292
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
293 y = [10 20 30];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
294
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
295 x + y
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
296 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
297 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
298
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
299 @noindent
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
300 Without broadcasting, @code{x + y} would be an error because the dimensions
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
301 do not agree. However, with broadcasting it is as if the following
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
302 operation were performed:
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
303
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
304 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
305 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
306 x = [1 2 3
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
307 4 5 6
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
308 7 8 9];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
309
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
310 y = [10 20 30
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
311 10 20 30
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
312 10 20 30];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
313
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
314 x + y
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
315 @result{} 11 22 33
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
316 14 25 36
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
317 17 28 39
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
318 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
319 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
320
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
321 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
322 That is, the smaller array of size @code{[1 3]} gets copied along the
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
323 singleton dimension (the number of rows) until it is @code{[3 3]}. No
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
324 actual copying takes place, however. The internal implementation reuses
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
325 elements along the necessary dimension in order to achieve the desired
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
326 effect without copying in memory.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
327
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
328 Both arrays can be broadcast across each other, for example, all
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
329 pairwise differences of the elements of a vector with itself:
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
330
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
331 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
332 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
333 y - y'
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
334 @result{} 0 10 20
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
335 -10 0 10
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
336 -20 -10 0
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
337 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
338 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
339
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
340 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
341 Here the vectors of size @code{[1 3]} and @code{[3 1]} both get
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
342 broadcast into matrices of size @code{[3 3]} before ordinary matrix
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
343 subtraction takes place.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
344
14123
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
345 A special case of broadcasting that may be familiar is when all
14853
72b8b39e12be doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
346 dimensions of the array being broadcast are 1, i.e., the array is a
32489
a4506463f341 doc: grammarcheck Octave manual before 9.1 release.
Rik <rik@octave.org>
parents: 32429
diff changeset
347 scalar. Thus, for example, operations like @code{x - 42} and
a4506463f341 doc: grammarcheck Octave manual before 9.1 release.
Rik <rik@octave.org>
parents: 32429
diff changeset
348 @code{max (x, 2)} are basic examples of broadcasting.
14123
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
349
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
350 For a higher-dimensional example, suppose @code{img} is an RGB image of
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
351 size @code{[m n 3]} and we wish to multiply each color by a different
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
352 scalar. The following code accomplishes this with broadcasting,
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
353
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
354 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
355 img .*= permute ([0.8, 0.9, 1.2], [1, 3, 2]);
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
356 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
357
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
358 @noindent
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
359 Note the usage of permute to match the dimensions of the
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
360 @code{[0.8, 0.9, 1.2]} vector with @code{img}.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
361
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
362 For functions that are not written with broadcasting semantics,
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
363 @code{bsxfun} can be useful for coercing them to broadcast.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
364
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
365 @DOCSTRING(bsxfun)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
366
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
367 Broadcasting is only applied if either of the two broadcasting
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
368 conditions hold. As usual, however, broadcasting does not apply when two
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
369 dimensions differ and neither is 1:
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
370
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
371 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
372 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
373 x = [1 2 3
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
374 4 5 6];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
375 y = [10 20
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
376 30 40];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
377 x + y
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
378 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
379 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
380
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
381 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
382 This will produce an error about nonconformant arguments.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
383
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
384 Besides common arithmetic operations, several functions of two arguments
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
385 also broadcast. The full list of functions and operators that broadcast
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
386 is
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
387
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
388 @example
30327
256fad4ac653 eiminate .+ and .- from documentation
John W. Eaton <jwe@octave.org>
parents: 30321
diff changeset
389 plus +
256fad4ac653 eiminate .+ and .- from documentation
John W. Eaton <jwe@octave.org>
parents: 30321
diff changeset
390 minus -
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
391 times .*
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
392 rdivide ./
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
393 ldivide .\
30321
2ba4758654ca deprecate ** and .** operators (bug #60882)
John W. Eaton <jwe@octave.org>
parents: 29949
diff changeset
394 power .^
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
395 lt <
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
396 le <=
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
397 eq ==
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
398 gt >
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
399 ge >=
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
400 ne != ~=
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
401 and &
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
402 or |
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
403 atan2
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
404 hypot
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
405 max
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
406 min
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
407 mod
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
408 rem
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
409 xor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
410
30327
256fad4ac653 eiminate .+ and .- from documentation
John W. Eaton <jwe@octave.org>
parents: 30321
diff changeset
411 += -= .*= ./= .\= .^= &= |=
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
412 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
413
31376
ad8a4102f910 doc: Spellcheck documentation for 8.1 release.
Rik <rik@octave.org>
parents: 31375
diff changeset
414 Here is a real example of the power of broadcasting. The
ad8a4102f910 doc: Spellcheck documentation for 8.1 release.
Rik <rik@octave.org>
parents: 31375
diff changeset
415 @nospell{Floyd-Warshall} algorithm is used to calculate the shortest path
ad8a4102f910 doc: Spellcheck documentation for 8.1 release.
Rik <rik@octave.org>
parents: 31375
diff changeset
416 lengths between every pair of vertices in a graph. A naive implementation for
ad8a4102f910 doc: Spellcheck documentation for 8.1 release.
Rik <rik@octave.org>
parents: 31375
diff changeset
417 a graph adjacency matrix of order @var{n} might look like this:
30605
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
418
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
419 @example
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
420 @group
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
421 for k = 1:n
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
422 for i = 1:n
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
423 for j = 1:n
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
424 dist(i,j) = min (dist(i,j), dist(i,k) + dist(k,j));
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
425 endfor
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
426 endfor
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
427 endfor
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
428 @end group
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
429 @end example
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
430
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
431 Upon vectorizing the innermost loop, it might look like this:
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
432
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
433 @example
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
434 @group
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
435 for k = 1:n
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
436 for i = 1:n
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
437 dist(i,:) = min (dist(i,:), dist(i,k) + dist(k,:));
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
438 endfor
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
439 endfor
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
440 @end group
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
441 @end example
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
442
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
443 Using broadcasting in both directions, it looks like this:
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
444
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
445 @example
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
446 @group
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
447 for k = 1:n
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
448 dist = min (dist, dist(:,k) + dist(k,:));
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
449 endfor
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
450 @end group
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
451 @end example
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
452
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
453 The relative time performance of the three techniques for a given graph with
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
454 100 vertices is 7.3 seconds for the naive code, 87 milliseconds for the
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
455 singly vectorized code, and 1.3 milliseconds for the fully broadcast code.
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
456 For a graph with 1000 vertices, vectorization takes 11.7 seconds while
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
457 broadcasting takes only 1.15 seconds. Therefore in general it is worth
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
458 writing code with broadcasting semantics for performance.
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
459
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
460 However, beware of resorting to broadcasting if a simpler operation will
02e4fd516f0a doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents: 30564
diff changeset
461 suffice. For matrices @var{a} and @var{b}, consider the following:
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
462
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
463 @example
14123
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
464 @var{c} = sum (permute (@var{a}, [1, 3, 2]) .* permute (@var{b}, [3, 2, 1]), 3);
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
465 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
466
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
467 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
468 This operation broadcasts the two matrices with permuted dimensions
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
469 across each other during elementwise multiplication in order to obtain a
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
470 larger 3-D array, and this array is then summed along the third dimension.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
471 A moment of thought will prove that this operation is simply the much
14123
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
472 faster ordinary matrix multiplication, @code{@var{c} = @var{a}*@var{b};}.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
473
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
474 A note on terminology: ``broadcasting'' is the term popularized by the
31376
ad8a4102f910 doc: Spellcheck documentation for 8.1 release.
Rik <rik@octave.org>
parents: 31375
diff changeset
475 @nospell{Numpy} numerical environment in the Python programming language. In
ad8a4102f910 doc: Spellcheck documentation for 8.1 release.
Rik <rik@octave.org>
parents: 31375
diff changeset
476 other programming languages and environments, broadcasting may also be known
25003
2365c2661b3c doc: Spellcheck documentation ahead of 4.4 release.
Rik <rik@octave.org>
parents: 24534
diff changeset
477 as @emph{binary singleton expansion} (@nospell{BSX}, in @sc{matlab}, and the
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
478 origin of the name of the @code{bsxfun} function), @emph{recycling} (R
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
479 programming language), @emph{single-instruction multiple data} (SIMD),
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
480 or @emph{replication}.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
481
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
482 @subsection Broadcasting and Legacy Code
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
483
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
484 The new broadcasting semantics almost never affect code that worked
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
485 in previous versions of Octave. Consequently, all code inherited from
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
486 @sc{matlab} that worked in previous versions of Octave should still work
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
487 without change in Octave. The only exception is code such as
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
488
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
489 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
490 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
491 try
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
492 c = a.*b;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
493 catch
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
494 c = a.*a;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
495 end_try_catch
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
496 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
497 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
498
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
499 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
500 that may have relied on matrices of different size producing an error.
20491
6ef177ddc1ee doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents: 19836
diff changeset
501 Because such operation is now valid Octave syntax, this will no longer
6ef177ddc1ee doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents: 19836
diff changeset
502 produce an error. Instead, the following code should be used:
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
503
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
504 @example
20491
6ef177ddc1ee doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents: 19836
diff changeset
505 @group
6ef177ddc1ee doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents: 19836
diff changeset
506 if (isequal (size (a), size (b)))
6ef177ddc1ee doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents: 19836
diff changeset
507 c = a .* b;
6ef177ddc1ee doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents: 19836
diff changeset
508 else
6ef177ddc1ee doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents: 19836
diff changeset
509 c = a .* a;
6ef177ddc1ee doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents: 19836
diff changeset
510 endif
6ef177ddc1ee doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents: 19836
diff changeset
511 @end group
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
512 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
513
14123
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
514
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
515 @node Function Application
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
516 @section Function Application
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
517 @cindex map
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
518 @cindex apply
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
519 @cindex function application
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
520
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
521 As a general rule, functions should already be written with matrix
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
522 arguments in mind and should consider whole matrix operations in a
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
523 vectorized manner. Sometimes, writing functions in this way appears
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
524 difficult or impossible for various reasons. For those situations,
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
525 Octave provides facilities for applying a function to each element of an
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
526 array, cell, or struct.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
527
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
528 @DOCSTRING(arrayfun)
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
529
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
530 @DOCSTRING(spfun)
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
531
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
532 @DOCSTRING(cellfun)
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
533
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
534 @DOCSTRING(structfun)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
535
19435
51a1d1164449 Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents: 18815
diff changeset
536 Consistent with earlier advice, seek to use Octave built-in functions whenever
51a1d1164449 Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents: 18815
diff changeset
537 possible for the best performance. This advice applies especially to the four
51a1d1164449 Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents: 18815
diff changeset
538 functions above. For example, when adding two arrays together
51a1d1164449 Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents: 18815
diff changeset
539 element-by-element one could use a handle to the built-in addition function
51a1d1164449 Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents: 18815
diff changeset
540 @code{@@plus} or define an anonymous function @code{@@(x,y) x + y}. But, the
51a1d1164449 Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents: 18815
diff changeset
541 anonymous function is 60% slower than the first method.
51a1d1164449 Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents: 18815
diff changeset
542 @xref{Operator Overloading}, for a list of basic functions which might be used
51a1d1164449 Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents: 18815
diff changeset
543 in place of anonymous ones.
51a1d1164449 Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents: 18815
diff changeset
544
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
545 @node Accumulation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
546 @section Accumulation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
547
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
548 Whenever it's possible to categorize according to indices the elements
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
549 of an array when performing a computation, accumulation functions can be
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
550 useful.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
551
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
552 @DOCSTRING(accumarray)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
553
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
554 @DOCSTRING(accumdim)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
555
31246
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
556 @node Memoization
31250
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
557 @section Memoization
31246
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
558
31247
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
559 Memoization is a technique to cache the results of slow function calls and
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
560 return the cached value when the function is called with the same inputs again,
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
561 instead of reevaluating it. It is very common to replace function calls with
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
562 lookup tables if the same inputs are happening over and over again in a known,
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
563 predictable way. Memoization is, at its core, an extension of this practice
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
564 where the lookup table is extended even during runtime for new arguments not
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
565 seen previously. A basic theoretical background can be found on Wikipedia or
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
566 any undergraduate-level computer science textbook.
31246
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
567
31247
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
568 Octave's @code{memoize} function provides drop-in memoization functionality for
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
569 any user function or Octave function, including compiled functions.
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
570
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
571 @DOCSTRING(memoize)
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
572
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
573 To memoize a function @code{z = foo(x, y)}, use this general pattern:
31246
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
574
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
575 @example
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
576 @group
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
577 foo2 = memoize (@@(@var{x, y}) @var{foo(x, y)});
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
578 z = foo2 (x, y);
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
579 @end group
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
580 @end example
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
581
31247
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
582 In the above example, the first line creates a memoized version @code{foo2} of
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
583 the function @code{foo}. For simple functions with only trivial wrapping, this
31250
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
584 line can also be shortened to:
31375
96f751f8392c doc: grammar check documentation ahead of 8.1 release.
Rik <rik@octave.org>
parents: 31250
diff changeset
585
31246
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
586 @example
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
587 @group
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
588 foo2 = memoize (@@foo);
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
589 @end group
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
590 @end example
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
591
31247
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
592 The second line @code{z = foo2 (x, y);} calls that memoized version @code{foo2}
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
593 instead of the original function, allowing @code{memoize} to intercept the call
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
594 and replace it with a looked-up value from a table if the inputs have occurred
31250
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
595 before, instead of evaluating the original function again.
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
596
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
597 Note that this will not accelerate the @emph{first} call to the function but
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
598 only subsequent calls.
31246
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
599
31247
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
600 Note that due to the overhead incurred by @code{memoize} to create and manage
31250
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
601 the lookup tables for each function, this technique is useful only for
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
602 functions that take at least a couple of seconds to execute. Such functions
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
603 can be replaced by table lookups taking only a millisecond or so, but if the
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
604 original function itself was taking only milliseconds, memoizing it will not
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
605 speed it up.
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
606
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
607 Recursive functions can be memoized as well, using a pattern like:
31375
96f751f8392c doc: grammar check documentation ahead of 8.1 release.
Rik <rik@octave.org>
parents: 31250
diff changeset
608
31250
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
609 @example
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
610 @group
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
611 function z = foo (x, y)
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
612 persistent foo2 = memoize (@@foo);
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
613 foo2.CacheSize = 1e6;
31246
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
614
31250
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
615 ## Call the memoized version when recursing
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
616 z = foo2 (x, y);
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
617 endfunction
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
618 @end group
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
619 @end example
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
620
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
621 The @code{CacheSize} can be optionally increased in anticipation of a large
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
622 number of function calls, such as from inside a recursive function. If
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
623 @code{CacheSize} is exceeded, the memoization tables are resized, causing a
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
624 slowdown. Increasing the @code{CacheSize} thus works like preallocation to
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
625 speed up execution.
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
626
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
627 The function @code{clearAllMemoizedCaches} clears the memoization tables when
f957849b2ba5 doc: Minor addition to memoization section for recursive functions (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31247
diff changeset
628 they are no longer needed.
31247
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
629
3dae836c598c doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 31246
diff changeset
630 @DOCSTRING(clearAllMemoizedCaches)
31246
43a6be589387 doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents: 30605
diff changeset
631
32429
ffc410f26506 doc: Rename virtual machine / VM as bytecode interpreter
Arun Giridhar <arungiridhar@gmail.com>
parents: 32422
diff changeset
632 @node Bytecode interpreter
ffc410f26506 doc: Rename virtual machine / VM as bytecode interpreter
Arun Giridhar <arungiridhar@gmail.com>
parents: 32422
diff changeset
633 @section Bytecode interpreter
32347
11586c2d002e doc: Add section on VM to Octave manual
Arun Giridhar <arungiridhar@gmail.com>
parents: 31706
diff changeset
634
32429
ffc410f26506 doc: Rename virtual machine / VM as bytecode interpreter
Arun Giridhar <arungiridhar@gmail.com>
parents: 32422
diff changeset
635 Octave's bytecode interpreter allows faster execution of existing
ffc410f26506 doc: Rename virtual machine / VM as bytecode interpreter
Arun Giridhar <arungiridhar@gmail.com>
parents: 32422
diff changeset
636 code. Octave versions 9 onwards have the bytecode interpreter built-in
ffc410f26506 doc: Rename virtual machine / VM as bytecode interpreter
Arun Giridhar <arungiridhar@gmail.com>
parents: 32422
diff changeset
637 by default. It is still considered experimental, therefore the related
ffc410f26506 doc: Rename virtual machine / VM as bytecode interpreter
Arun Giridhar <arungiridhar@gmail.com>
parents: 32422
diff changeset
638 functions are not explicitly documented in this manual. Instead, the command
ffc410f26506 doc: Rename virtual machine / VM as bytecode interpreter
Arun Giridhar <arungiridhar@gmail.com>
parents: 32422
diff changeset
639 @code{bytecode} describes how to invoke it.
32347
11586c2d002e doc: Add section on VM to Octave manual
Arun Giridhar <arungiridhar@gmail.com>
parents: 31706
diff changeset
640
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
641 @node Miscellaneous Techniques
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
642 @section Miscellaneous Techniques
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
643 @cindex execution speed
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
644 @cindex speedups
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
645 @cindex optimization
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
646
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
647 Here are some other ways of improving the execution speed of Octave
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
648 programs.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
649
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
650 @itemize @bullet
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
651
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
652 @item Avoid computing costly intermediate results multiple times.
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
653 Octave currently does not eliminate common subexpressions. Also, certain
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
654 internal computation results are cached for variables. For instance, if
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
655 a matrix variable is used multiple times as an index, checking the
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
656 indices (and internal conversion to integers) is only done once.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
657
19593
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 17744
diff changeset
658 @item Be aware of lazy copies (copy-on-write).
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
659 @cindex copy-on-write
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
660 @cindex COW
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
661 @cindex memory management
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
662 When a copy of an object is created, the data is not immediately copied, but
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
663 rather shared. The actual copying is postponed until the copied data needs to
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
664 be modified. For example:
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
665
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
666 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
667 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
668 a = zeros (1000); # create a 1000x1000 matrix
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
669 b = a; # no copying done here
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
670 b(1) = 1; # copying done here
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
671 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
672 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
673
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
674 Lazy copying applies to whole Octave objects such as matrices, cells,
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
675 struct, and also individual cell or struct elements (not array
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
676 elements).
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
677
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
678 Additionally, index expressions also use lazy copying when Octave can
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
679 determine that the indexed portion is contiguous in memory. For example:
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
680
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
681 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
682 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
683 a = zeros (1000); # create a 1000x1000 matrix
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
684 b = a(:,10:100); # no copying done here
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
685 b = a(10:100,:); # copying done here
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
686 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
687 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
688
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
689 This applies to arrays (matrices), cell arrays, and structs indexed
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
690 using @samp{()}. Index expressions generating comma-separated lists can also
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
691 benefit from shallow copying in some cases. In particular, when @var{a} is a
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
692 struct array, expressions like @code{@{a.x@}, @{a(:,2).x@}} will use lazy
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
693 copying, so that data can be shared between a struct array and a cell array.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
694
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
695 Most indexing expressions do not live longer than their parent
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
696 objects. In rare cases, however, a lazily copied slice outlasts its
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
697 parent, in which case it becomes orphaned, still occupying unnecessarily
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
698 more memory than needed. To provide a remedy working in most real cases,
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
699 Octave checks for orphaned lazy slices at certain situations, when a
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
700 value is stored into a "permanent" location, such as a named variable or
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
701 cell or struct element, and possibly economizes them. For example:
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
702
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
703 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
704 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
705 a = zeros (1000); # create a 1000x1000 matrix
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
706 b = a(:,10:100); # lazy slice
17170
d6499c14021c doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents: 17097
diff changeset
707 a = []; # the original "a" array is still allocated
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
708 c@{1@} = b; # b is reallocated at this point
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
709 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
710 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
711
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
712 @item Avoid deep recursion.
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
713 Function calls to m-file functions carry a relatively significant overhead, so
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
714 rewriting a recursion as a loop often helps. Also, note that the maximum level
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
715 of recursion is limited.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
716
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
717 @item Avoid resizing matrices unnecessarily.
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
718 When building a single result matrix from a series of calculations, set the
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
719 size of the result matrix first, then insert values into it. Write
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
720
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
721 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
722 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
723 result = zeros (big_n, big_m)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
724 for i = over:and_over
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
725 ridx = @dots{}
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
726 cidx = @dots{}
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
727 result(ridx, cidx) = new_value ();
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
728 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
729 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
730 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
731
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
732 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
733 instead of
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
734
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
735 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
736 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
737 result = [];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
738 for i = ever:and_ever
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
739 result = [ result, new_value() ];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
740 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
741 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
742 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
743
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
744 Sometimes the number of items can not be computed in advance, and
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
745 stack-like operations are needed. When elements are being repeatedly
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
746 inserted or removed from the end of an array, Octave detects it as stack
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
747 usage and attempts to use a smarter memory management strategy by
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
748 pre-allocating the array in bigger chunks. This strategy is also applied
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
749 to cell and struct arrays.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
750
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
751 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
752 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
753 a = [];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
754 while (condition)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
755 @dots{}
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
756 a(end+1) = value; # "push" operation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
757 @dots{}
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
758 a(end) = []; # "pop" operation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
759 @dots{}
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
760 endwhile
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
761 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
762 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
763
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
764 @item Avoid calling @code{eval} or @code{feval} excessively.
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
765 Parsing input or looking up the name of a function in the symbol table are
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
766 relatively expensive operations.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
767
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
768 If you are using @code{eval} merely as an exception handling mechanism, and not
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
769 because you need to execute some arbitrary text, use the @code{try}
15684
ddc651eecf7a Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents: 14138
diff changeset
770 statement instead. @xref{The try Statement}.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
771
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
772 @item Use @code{ignore_function_time_stamp} when appropriate.
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
773 If you are calling lots of functions, and none of them will need to change
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
774 during your run, set the variable @code{ignore_function_time_stamp} to
22299
9fc91bb2aec3 doc: grammarcheck documentation for 4.2 release.
Rik <rik@octave.org>
parents: 20491
diff changeset
775 @qcode{"all"}. This will stop Octave from checking the time stamp of a
9fc91bb2aec3 doc: grammarcheck documentation for 4.2 release.
Rik <rik@octave.org>
parents: 20491
diff changeset
776 function file to see if it has been updated while the program is being run.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
777 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
778
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
779 @node Examples
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
780 @section Examples
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
781
14118
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
782 The following are examples of vectorization questions asked by actual
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
783 users of Octave and their solutions.
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
784
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
785 @c FIXME: We need a lot more examples here.
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
786
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
787 @itemize @bullet
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
788 @item
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
789 For a vector @code{A}, the following loop
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
790
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
791 @example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
792 @group
28487
a7fcdac012d8 doc: Fix incorrect example code in Vectorize chapter (bug #58607).
Rik <rik@octave.org>
parents: 28428
diff changeset
793 n = length (A) - 1;
14118
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
794 B = zeros (n, 2);
28487
a7fcdac012d8 doc: Fix incorrect example code in Vectorize chapter (bug #58607).
Rik <rik@octave.org>
parents: 28428
diff changeset
795 for i = 1:n
14118
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
796 ## this will be two columns, the first is the difference and
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
797 ## the second the mean of the two elements used for the diff.
18679
a142f35f3cb6 doc: Fix unbalanced parentheses in documentation.
Rik <rik@octave.org>
parents: 17744
diff changeset
798 B(i,:) = [A(i+1)-A(i), (A(i+1) + A(i))/2];
14123
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
799 endfor
14118
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
800 @end group
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
801 @end example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
802
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
803 @noindent
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
804 can be turned into the following one-liner:
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
805
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
806 @example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
807 B = [diff(A)(:), 0.5*(A(1:end-1)+A(2:end))(:)]
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
808 @end example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
809
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
810 Note the usage of colon indexing to flatten an intermediate result into
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
811 a column vector. This is a common vectorization trick.
14118
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
812
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
813 @end itemize