Mercurial > octave
annotate doc/interpreter/vectorize.txi @ 31247:3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
author | Arun Giridhar <arungiridhar@gmail.com> |
---|---|
date | Fri, 30 Sep 2022 06:38:59 -0400 |
parents | 43a6be589387 |
children | f957849b2ba5 |
rev | line source |
---|---|
30564
796f54d4ddbf
update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents:
30327
diff
changeset
|
1 @c Copyright (C) 2012-2022 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 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
46 * 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
|
47 * Examples:: |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
48 @end menu |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
49 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
50 @node Basic Vectorization |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
51 @section Basic Vectorization |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
52 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
53 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
|
54 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
|
55 trivial example, consider |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
56 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
57 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
58 @group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
59 for i = 1:n |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
60 for j = 1:m |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
61 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
|
62 endfor |
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 @end group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
65 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
66 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
67 @noindent |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
68 compared to the much simpler |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
69 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
70 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
71 c = a + b; |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
72 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
73 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
74 @noindent |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
75 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
|
76 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
|
77 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
|
78 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
|
79 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
|
80 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
|
81 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
|
82 |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
83 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
|
84 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
|
85 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
|
86 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
|
87 enclosing loop. |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
88 |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
89 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
|
90 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
91 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
92 @group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
93 for i = 1:n-1 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
94 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
|
95 endfor |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
96 @end group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
97 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
98 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
99 @noindent |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
100 write |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
101 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
102 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
103 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
|
104 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
105 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
106 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
|
107 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
|
108 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
|
109 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
|
110 instead of |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
111 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
112 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
113 @group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
114 for i = 1:n |
16934
48f5b993b819
doc: Use parentheses around if, switch conditions in documentation.
Rik <rik@octave.org>
parents:
16878
diff
changeset
|
115 if (a(i) > 5) |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
116 a(i) -= 20 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
117 endif |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
118 endfor |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
119 @end group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
120 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
121 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
122 @noindent |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
123 write |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
124 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
125 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
126 a(a>5) -= 20; |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
127 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
128 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
129 @noindent |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
130 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
|
131 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
132 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
|
133 (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
|
134 |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
135 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
|
136 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
|
137 @xref{Broadcasting}. |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
138 |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
139 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
|
140 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
|
141 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
|
142 future release. |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
143 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
144 For instance, even better than |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
145 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
146 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
147 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
|
148 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
149 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
150 @noindent |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
151 is |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
152 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
153 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
154 a = diff (b); |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
155 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
156 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
157 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
|
158 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
|
159 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
|
160 occur frequently in vectorized code: |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
161 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
162 @itemize @bullet |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
163 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
164 Index manipulation |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
165 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
166 @itemize |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
167 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
168 find |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
169 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
170 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
171 sub2ind |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
172 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
173 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
174 ind2sub |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
175 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
176 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
177 sort |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
178 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
179 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
180 unique |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
181 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
182 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
183 lookup |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
184 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
185 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
186 ifelse / merge |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
187 @end itemize |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
188 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
189 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
190 Repetition |
14853
72b8b39e12be
doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
191 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
192 @itemize |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
193 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
194 repmat |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
195 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
196 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
197 repelems |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
198 @end itemize |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
199 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
200 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
201 Vectorized arithmetic |
14853
72b8b39e12be
doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
202 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
203 @itemize |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
204 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
205 sum |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
206 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
207 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
208 prod |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
209 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
210 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
211 cumsum |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
212 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
213 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
214 cumprod |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
215 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
216 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
217 sumsq |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
218 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
219 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
220 diff |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
221 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
222 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
223 dot |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
224 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
225 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
226 cummax |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
227 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
228 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
229 cummin |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
230 @end itemize |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
231 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
232 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
233 Shape of higher dimensional arrays |
14853
72b8b39e12be
doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
234 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
235 @itemize |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
236 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
237 reshape |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
238 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
239 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
240 resize |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
241 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
242 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
243 permute |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
244 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
245 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
246 squeeze |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
247 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
248 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
249 deal |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
250 @end itemize |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
251 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
252 @end itemize |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
253 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
254 @node Broadcasting |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
255 @section Broadcasting |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
256 @cindex broadcast |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
257 @cindex broadcasting |
25003
2365c2661b3c
doc: Spellcheck documentation ahead of 4.4 release.
Rik <rik@octave.org>
parents:
24534
diff
changeset
|
258 @cindex @nospell{BSX} |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
259 @cindex recycling |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
260 @cindex SIMD |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
261 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
262 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
|
263 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
|
264 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
|
265 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
|
266 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
|
267 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
|
268 array dimensions must either |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
269 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
270 @enumerate |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
271 @item |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
272 be equal, or |
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
273 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
274 @item |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
275 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
|
276 @end enumerate |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
277 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
278 @noindent |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
279 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
|
280 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
|
281 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
|
282 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
|
283 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
|
284 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
|
285 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
286 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
287 @group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
288 x = [1 2 3; |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
289 4 5 6; |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
290 7 8 9]; |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
291 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
292 y = [10 20 30]; |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
293 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
294 x + y |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
295 @end group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
296 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
297 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
298 @noindent |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
299 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
|
300 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
|
301 operation were performed: |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
302 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
303 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
304 @group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
305 x = [1 2 3 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
306 4 5 6 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
307 7 8 9]; |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
308 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
309 y = [10 20 30 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
310 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 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
313 x + y |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
314 @result{} 11 22 33 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
315 14 25 36 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
316 17 28 39 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
317 @end group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
318 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
319 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
320 @noindent |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
321 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
|
322 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
|
323 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
|
324 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
|
325 effect without copying in memory. |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
326 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
327 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
|
328 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
|
329 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
330 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
331 @group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
332 y - y' |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
333 @result{} 0 10 20 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
334 -10 0 10 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
335 -20 -10 0 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
336 @end group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
337 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
338 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
339 @noindent |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
340 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
|
341 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
|
342 subtraction takes place. |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
343 |
14123
2f742be03f90
doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14119
diff
changeset
|
344 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
|
345 dimensions of the array being broadcast are 1, i.e., the array is a |
72b8b39e12be
doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
346 scalar. Thus for example, operations like @code{x - 42} and @code{max |
14123
2f742be03f90
doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14119
diff
changeset
|
347 (x, 2)} are basic examples of broadcasting. |
2f742be03f90
doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14119
diff
changeset
|
348 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
349 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
|
350 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
|
351 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
|
352 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
353 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
354 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
|
355 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
356 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
357 @noindent |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
358 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
|
359 @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
|
360 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
361 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
|
362 @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
|
363 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
364 @DOCSTRING(bsxfun) |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
365 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
366 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
|
367 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
|
368 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
|
369 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
370 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
371 @group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
372 x = [1 2 3 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
373 4 5 6]; |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
374 y = [10 20 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
375 30 40]; |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
376 x + y |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
377 @end group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
378 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
379 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
380 @noindent |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
381 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
|
382 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
383 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
|
384 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
|
385 is |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
386 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
387 @example |
30327
256fad4ac653
eiminate .+ and .- from documentation
John W. Eaton <jwe@octave.org>
parents:
30321
diff
changeset
|
388 plus + |
256fad4ac653
eiminate .+ and .- from documentation
John W. Eaton <jwe@octave.org>
parents:
30321
diff
changeset
|
389 minus - |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
390 times .* |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
391 rdivide ./ |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
392 ldivide .\ |
30321
2ba4758654ca
deprecate ** and .** operators (bug #60882)
John W. Eaton <jwe@octave.org>
parents:
29949
diff
changeset
|
393 power .^ |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
394 lt < |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
395 le <= |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
396 eq == |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
397 gt > |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
398 ge >= |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
399 ne != ~= |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
400 and & |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
401 or | |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
402 atan2 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
403 hypot |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
404 max |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
405 min |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
406 mod |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
407 rem |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
408 xor |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
409 |
30327
256fad4ac653
eiminate .+ and .- from documentation
John W. Eaton <jwe@octave.org>
parents:
30321
diff
changeset
|
410 += -= .*= ./= .\= .^= &= |= |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
411 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
412 |
30605
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
413 Here is a real example of the power of broadcasting. The Floyd-Warshall |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
414 algorithm is used to calculate the shortest path lengths between every pair of |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
415 vertices in a graph. A naive implementation for a graph adjacency matrix of |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
416 order @var{n} might look like this: |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
417 |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
418 @example |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
419 @group |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
420 for k = 1:n |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
421 for i = 1:n |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
422 for j = 1:n |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
423 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
|
424 endfor |
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 @end group |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
428 @end example |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
429 |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
430 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
|
431 |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
432 @example |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
433 @group |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
434 for k = 1:n |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
435 for i = 1:n |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
436 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
|
437 endfor |
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 @end group |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
440 @end example |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
441 |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
442 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
|
443 |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
444 @example |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
445 @group |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
446 for k = 1:n |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
447 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
|
448 endfor |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
449 @end group |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
450 @end example |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
451 |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
452 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
|
453 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
|
454 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
|
455 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
|
456 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
|
457 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
|
458 |
02e4fd516f0a
doc: add example about broadcasting and vectorization (bug #61601).
Arun Giridhar <arungiridhar@gmail.com>
parents:
30564
diff
changeset
|
459 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
|
460 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
|
461 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
462 @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
|
463 @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
|
464 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
465 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
466 @noindent |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
467 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
|
468 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
|
469 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
|
470 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
|
471 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
|
472 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
473 A note on terminology: ``broadcasting'' is the term popularized by the |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
474 Numpy numerical environment in the Python programming language. In other |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
475 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
|
476 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
|
477 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
|
478 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
|
479 or @emph{replication}. |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
480 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
481 @subsection Broadcasting and Legacy Code |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
482 |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
483 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
|
484 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
|
485 @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
|
486 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
|
487 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
488 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
489 @group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
490 try |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
491 c = a.*b; |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
492 catch |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
493 c = a.*a; |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
494 end_try_catch |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
495 @end group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
496 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
497 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
498 @noindent |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
499 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
|
500 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
|
501 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
|
502 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
503 @example |
20491
6ef177ddc1ee
doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents:
19836
diff
changeset
|
504 @group |
6ef177ddc1ee
doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents:
19836
diff
changeset
|
505 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
|
506 c = a .* b; |
6ef177ddc1ee
doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents:
19836
diff
changeset
|
507 else |
6ef177ddc1ee
doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents:
19836
diff
changeset
|
508 c = a .* a; |
6ef177ddc1ee
doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents:
19836
diff
changeset
|
509 endif |
6ef177ddc1ee
doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents:
19836
diff
changeset
|
510 @end group |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
511 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
512 |
14123
2f742be03f90
doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14119
diff
changeset
|
513 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
514 @node Function Application |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
515 @section Function Application |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
516 @cindex map |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
517 @cindex apply |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
518 @cindex function application |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
519 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
520 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
|
521 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
|
522 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
|
523 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
|
524 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
|
525 array, cell, or struct. |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
526 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
527 @DOCSTRING(arrayfun) |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
528 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
529 @DOCSTRING(spfun) |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
530 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
531 @DOCSTRING(cellfun) |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
532 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
533 @DOCSTRING(structfun) |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
534 |
19435
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
18815
diff
changeset
|
535 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
|
536 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
|
537 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
|
538 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
|
539 @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
|
540 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
|
541 @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
|
542 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
|
543 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
544 @node Accumulation |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
545 @section Accumulation |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
546 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
547 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
|
548 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
|
549 useful. |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
550 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
551 @DOCSTRING(accumarray) |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
552 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
553 @DOCSTRING(accumdim) |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
554 |
31246
43a6be589387
doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
30605
diff
changeset
|
555 @node Memoization |
43a6be589387
doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
30605
diff
changeset
|
556 @section Memoization Techniques |
43a6be589387
doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
30605
diff
changeset
|
557 |
31247
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
558 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
|
559 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
|
560 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
|
561 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
|
562 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
|
563 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
|
564 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
|
565 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
|
566 |
31247
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
567 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
|
568 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
|
569 |
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
570 @DOCSTRING(memoize) |
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
571 |
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
572 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
|
573 |
43a6be589387
doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
30605
diff
changeset
|
574 @example |
43a6be589387
doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
30605
diff
changeset
|
575 @group |
43a6be589387
doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
30605
diff
changeset
|
576 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
|
577 z = foo2 (x, y); |
43a6be589387
doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
30605
diff
changeset
|
578 @end group |
43a6be589387
doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
30605
diff
changeset
|
579 @end example |
43a6be589387
doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
30605
diff
changeset
|
580 |
31247
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
581 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
|
582 the function @code{foo}. For simple functions with only trivial wrapping, this |
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
583 line can also be shortened to |
31246
43a6be589387
doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
30605
diff
changeset
|
584 @example |
43a6be589387
doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
30605
diff
changeset
|
585 @group |
43a6be589387
doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
30605
diff
changeset
|
586 foo2 = memoize (@@foo); |
43a6be589387
doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
30605
diff
changeset
|
587 @end group |
43a6be589387
doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
30605
diff
changeset
|
588 @end example |
43a6be589387
doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
30605
diff
changeset
|
589 |
31247
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
590 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
|
591 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
|
592 and replace it with a looked-up value from a table if the inputs have occurred |
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
593 before, instead of evaluating the original function again. Note that this will |
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
594 not accelerate the @emph{first} call to the function but only subsequent calls. |
31246
43a6be589387
doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
30605
diff
changeset
|
595 |
31247
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
596 Note that due to the overhead incurred by @code{memoize} to create and manage |
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
597 the lookup tables for each function the user seeks to memoize, this technique |
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
598 is useful only for functions that take a significant time to execute, at least |
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
599 a few seconds. Such functions can be replaced by table lookups taking only a |
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
600 millisecond or less, but if the original function itself was taking only |
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
601 milliseconds or microseconds, memoizing it will not speed it up. |
31246
43a6be589387
doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
30605
diff
changeset
|
602 |
31247
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
603 Octave's memoization also allows the user to clear the cache of lookup values |
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
604 when it is no longer needed, using the function @code{clearAllMemoizedCaches}. |
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
605 |
3dae836c598c
doc: Expand and edit documentation for memoization (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
31246
diff
changeset
|
606 @DOCSTRING(clearAllMemoizedCaches) |
31246
43a6be589387
doc: New documentation for memoization techniques (bug #60860)
Arun Giridhar <arungiridhar@gmail.com>
parents:
30605
diff
changeset
|
607 |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
608 @node Miscellaneous Techniques |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
609 @section Miscellaneous Techniques |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
610 @cindex execution speed |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
611 @cindex speedups |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
612 @cindex optimization |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
613 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
614 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
|
615 programs. |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
616 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
617 @itemize @bullet |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
618 |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
619 @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
|
620 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
|
621 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
|
622 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
|
623 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
|
624 |
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17744
diff
changeset
|
625 @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
|
626 @cindex copy-on-write |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
627 @cindex COW |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
628 @cindex memory management |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
629 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
|
630 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
|
631 be modified. For example: |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
632 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
633 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
634 @group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
635 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
|
636 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
|
637 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
|
638 @end group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
639 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
640 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
641 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
|
642 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
|
643 elements). |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
644 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
645 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
|
646 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
|
647 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
648 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
649 @group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
650 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
|
651 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
|
652 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
|
653 @end group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
654 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
655 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
656 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
|
657 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
|
658 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
|
659 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
|
660 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
|
661 |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
662 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
|
663 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
|
664 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
|
665 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
|
666 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
|
667 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
|
668 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
|
669 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
670 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
671 @group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
672 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
|
673 b = a(:,10:100); # lazy slice |
17170
d6499c14021c
doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
674 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
|
675 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
|
676 @end group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
677 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
678 |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
679 @item Avoid deep recursion. |
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
680 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
|
681 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
|
682 of recursion is limited. |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
683 |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
684 @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
|
685 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
|
686 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
|
687 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
688 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
689 @group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
690 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
|
691 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
|
692 ridx = @dots{} |
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
693 cidx = @dots{} |
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
694 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
|
695 endfor |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
696 @end group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
697 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
698 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
699 @noindent |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
700 instead of |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
701 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
702 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
703 @group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
704 result = []; |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
705 for i = ever:and_ever |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
706 result = [ result, new_value() ]; |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
707 endfor |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
708 @end group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
709 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
710 |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
711 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
|
712 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
|
713 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
|
714 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
|
715 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
|
716 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
|
717 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
718 @example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
719 @group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
720 a = []; |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
721 while (condition) |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
722 @dots{} |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
723 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
|
724 @dots{} |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
725 a(end) = []; # "pop" operation |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
726 @dots{} |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
727 endwhile |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
728 @end group |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
729 @end example |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
730 |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
731 @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
|
732 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
|
733 relatively expensive operations. |
14116
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
734 |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
735 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
|
736 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
|
737 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
|
738 |
14119
94e2a76f1e5a
doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
14118
diff
changeset
|
739 @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
|
740 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
|
741 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
|
742 @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
|
743 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
|
744 @end itemize |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
745 |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
746 @node Examples |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
747 @section Examples |
951eacaf9381
Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff
changeset
|
748 |
14118
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
749 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
|
750 users of Octave and their solutions. |
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
751 |
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
752 @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
|
753 |
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
754 @itemize @bullet |
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
755 @item |
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
756 For a vector @code{A}, the following loop |
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
757 |
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
758 @example |
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
759 @group |
28487
a7fcdac012d8
doc: Fix incorrect example code in Vectorize chapter (bug #58607).
Rik <rik@octave.org>
parents:
28428
diff
changeset
|
760 n = length (A) - 1; |
14118
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
761 B = zeros (n, 2); |
28487
a7fcdac012d8
doc: Fix incorrect example code in Vectorize chapter (bug #58607).
Rik <rik@octave.org>
parents:
28428
diff
changeset
|
762 for i = 1:n |
14118
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
763 ## 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
|
764 ## 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
|
765 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
|
766 endfor |
14118
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
767 @end group |
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
768 @end example |
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
769 |
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
770 @noindent |
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
771 can be turned into the following one-liner: |
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
772 |
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
773 @example |
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
774 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
|
775 @end example |
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
776 |
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
777 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
|
778 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
|
779 |
ebe2e6b2ba52
Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14116
diff
changeset
|
780 @end itemize |