Mercurial > octave

annotate doc/interpreter/vectorize.txi @ 14118:ebe2e6b2ba52 stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Start adding vectorization examples
author Jordi Gutiérrez Hermoso <jordigh@octave.org>
date Tue, 27 Dec 2011 19:06:37 -0500
parents 951eacaf9381
children 94e2a76f1e5a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
1 @c Copyright (C) 2011 Jordi Gutiérrez Hermoso
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
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
5 @c Octave is free software; you can redistribute it and/or modify it
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
6 @c under the terms of the GNU General Public License as published by the
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
7 @c Free Software Foundation; either version 3 of the License, or (at
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
8 @c your option) any later version.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
9 @c
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
10 @c Octave is distributed in the hope that it will be useful, but WITHOUT
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
11 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
12 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
13 @c for more details.
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
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
16 @c along with Octave; see the file COPYING. If not, see
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
17 @c <http://www.gnu.org/licenses/>.
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
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
25 instead of element-by-element loop-based operations. Besides frequently
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
26 writing more succinct code, vectorization also allows for better
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
27 optimization of the code. The optimizations may occur either in Octave's
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
28 own Fortran, C, or C++ internal implementation, or even at a lower level
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
29 depending on the compiler and external numerical libraries used to
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
30 build Octave. The ultimate goal is to make use of your hardware's vector
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
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
33 Vectorization is not a concept unique to Octave, but is particularly
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
34 important because Octave is a matrix-oriented language. Vectorized
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
35 Octave code will see a dramatic speed up in most cases.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
36
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
37 This chapter discusses vectorization and other techniques for faster
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
38 code execution.
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
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
45 * 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
46 * Examples::
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
47 @end menu
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
48
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
49 @node Basic Vectorization
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
50 @section Basic Vectorization
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
51
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
52 To a very good first approximation, the goal in vectorization is to
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
53 write code that avoids loops and uses whole-array operations. As a
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
54 trivial example, consider
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
55
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
56 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
57 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
58 for i = 1:n
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
59 for j = 1:m
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
60 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
61 endfor
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 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
64 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
65
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
66 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
67 compared to the much simpler
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
68
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
69 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
70 c = a + b;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
71 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
72
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
73 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
74 This isn't merely easier to write; it is also internally much easier to
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
75 optimize. Octave delegates this operation to an underlying
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
76 implementation which among other optimizations may use special vector
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
77 hardware instructions or could conceivably even perform the additions in
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
78 parallel. In general, if the code is vectorized, the underlying
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
79 implementation has much more freedom about the assumptions it can make
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
80 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
81
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
82 This is especially important for loops with "cheap" bodies. Often it
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
83 suffices to vectorize just the innermost loop to get acceptable
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
84 performance. A general rule of thumb is that the "order" of the
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
85 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
86 enclosing loop.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
87
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
88 As a less trivial example, rather than
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
89
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
90 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
91 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
92 for i = 1:n-1
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
93 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
94 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
95 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
96 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
97
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
98 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
99 write
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
100
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
101 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
102 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
103 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
104
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
105 This shows an important general concept about using arrays for indexing
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
106 instead of looping over an index variable. @xref{Index Expressions}.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
107 Also use boolean indexing generously. If a condition needs to be tested,
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
108 this condition can also be written as a boolean index. For instance,
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
109 instead of
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
110
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
111 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
112 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
113 for i = 1:n
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
114 if a(i) > 5
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
115 a(i) -= 20
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
116 endif
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
117 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
118 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
119 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
120
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
121 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
122 write
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
123
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
124 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
125 a(a>5) -= 20;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
126 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
127
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
128 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
129 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
130
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
131 Use elementwise vector operators whenever possible to avoid looping
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
132 (operators like @code{.*} and @code{.^}). @xref{Arithmetic Ops}. For
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
133 simple in-line functions, the @code{vectorize} function can do this
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
134 automatically.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
135
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
136 @DOCSTRING(vectorize)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
137
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
138 Also exploit broadcasting in these elementise operators both to avoid
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
139 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
140 @xref{Broadcasting}.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
141
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
142 Use built-in and library functions if possible. Built-in and compiled
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
143 functions are very fast. Even with a m-file library function, chances
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
144 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
145 future release.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
146
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
147 For instance, even better than
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
148
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
149 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
150 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
151 @end example
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 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
154 is
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
155
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
156 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
157 a = diff (b);
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
158 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
159
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
160 Most Octave functions are written with vector and array arguments in
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
161 mind. If you find yourself writing a loop with a very simple operation,
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
162 chances are that such a function already exists. The following functions
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
163 occur frequently in vectorized code:
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
164
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
165 @itemize @bullet
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
166 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
167 Index manipulation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
168
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
169 @itemize
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 find
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
172 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
173 sub2ind
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
174 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
175 ind2sub
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
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
178 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
179 unique
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
180 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
181 lookup
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 ifelse / merge
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
184 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
185
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
186 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
187 Repetition
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
188 @itemize
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 repmat
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
191 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
192 repelems
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
193 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
194
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
195 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
196 Vectorized arithmetic
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
197 @itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
198 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
199 sum
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 prod
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
202 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
203 cumsum
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 cumprod
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
206 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
207 sumsq
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
208 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
209 diff
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 dot
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
212 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
213 cummax
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
214 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
215 cummin
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
216 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
217
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
218 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
219 Shape of higher dimensional arrays
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
220 @itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
221 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
222 reshape
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
223 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
224 resize
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 permute
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
227 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
228 squeeze
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
229 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
230 deal
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
231 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
232
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
233 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
234
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
235 @node Broadcasting
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
236 @section Broadcasting
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
237 @cindex broadcast
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
238 @cindex broadcasting
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
239 @cindex BSX
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
240 @cindex recycling
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
241 @cindex SIMD
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
242
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
243 Broadcasting refers to how Octave binary operators and functions behave
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
244 when their matrix or array operands or arguments differ in size. Since
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
245 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
246 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
247 Broadly speaking, smaller arrays are ``broadcast'' across the larger
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
248 one, until they have a compatible shape. The rule is that corresponding
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
249 array dimensions must either
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
250
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
251 @enumerate
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
252 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
253 be equal or,
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
254 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
255 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
256 @end enumerate
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
257
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
258 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
259 In case all dimensions are equal, no broadcasting occurs and ordinary
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
260 element-by-element arithmetic takes place. For arrays of higher
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
261 dimensions, if the number of dimensions isn't the same, then missing
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
262 trailing dimensions are treated as 1. When one of the dimensions is 1,
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
263 the array with that singleton dimension gets copied along that dimension
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
264 until it matches the dimension of the other array. For example, consider
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
265
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
266 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
267 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
268 x = [1 2 3;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
269 4 5 6;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
270 7 8 9];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
271
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
272 y = [10 20 30];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
273
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
274 x + y
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
275 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
276 @end example
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 Without broadcasting, @code{x + y} would be an error because dimensions
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
280 do not agree. However, with broadcasting it is as if the following
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
281 operation were performed:
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
282
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
283 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
284 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
285 x = [1 2 3
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
286 4 5 6
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
287 7 8 9];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
288
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
289 y = [10 20 30
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
290 10 20 30
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
291 10 20 30];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
292
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
293 x + y
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
294 @result{} 11 22 33
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
295 14 25 36
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
296 17 28 39
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
297 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
298 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
299
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
300 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
301 That is, the smaller array of size @code{[1 3]} gets copied along the
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
302 singleton dimension (the number of rows) until it is @code{[3 3]}. No
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
303 actual copying takes place, however. The internal implementation reuses
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
304 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
305 effect without copying in memory.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
306
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
307 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
308 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
309
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
310 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
311 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
312 y - y'
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
313 @result{} 0 10 20
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
314 -10 0 10
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
315 -20 -10 0
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
316 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
317 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
318
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
319 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
320 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
321 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
322 subtraction takes place.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
323
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
324 For a higher-dimensional example, suppose @code{img} is an RGB image of
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
325 size @code{[m n 3]} and we wish to multiply each colour by a different
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
326 scalar. The following code accomplishes this with broadcasting,
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
327
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
328 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
329 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
330 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
331
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
332 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
333 Note the usage of permute to match the dimensions of the @code{[0.8,
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
334 0.9, 1.2]} vector with @code{img}.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
335
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
336 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
337 @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
338
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
339 @DOCSTRING(bsxfun)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
340
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
341 Broadcasting is only applied if either of the two broadcasting
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
342 conditions hold. As usual, however, broadcasting does not apply when two
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
343 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
344
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
345 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
346 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
347 x = [1 2 3
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
348 4 5 6];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
349 y = [10 20
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
350 30 40];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
351 x + y
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
352 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
353 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
354
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
355 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
356 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
357
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
358 Besides common arithmetic operations, several functions of two arguments
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
359 also broadcast. The full list of functions and operators that broadcast
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
360 is
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
361
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
362 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
363 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
364 plus + .+
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
365 minus - .-
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
366 times .*
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
367 rdivide ./
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
368 ldivide .\
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
369 power .^ .**
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
370 lt <
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
371 le <=
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
372 eq ==
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
373 gt >
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
374 ge >=
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
375 ne != ~=
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
376 and &
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
377 or |
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
378 atan2
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
379 hypot
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
380 max
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
381 min
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
382 mod
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
383 rem
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
384 xor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
385
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 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
388 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
389
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
390 Beware of resorting to broadcasting if a simpler operation will suffice.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
391 For matrices @var{a} and @var{b}, consider the following:
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
392
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
393 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
394 c = sum (permute (a, [1, 3, 2]) .* permute (b, [3, 2, 1]), 3);
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
395 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
396
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
397 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
398 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
399 across each other during elementwise multiplication in order to obtain a
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
400 larger 3d array, and this array is the summed along the third dimension.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
401 A moment of thought will prove that this operation is simply the much
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
402 faster ordinary matrix multiplication, @code{c = a*b;}.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
403
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
404 A note on terminology: ``broadcasting'' is the term popularized by the
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
405 Numpy numerical environment in the Python programming language. In other
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
406 programming languages and environments, broadcasting may also be known
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
407 as @emph{binary singleton expansion} (BSX, in @sc{Matlab}, and the
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
408 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
409 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
410 or @emph{replication}.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
411
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
412 @subsection Broadcasting and Legacy Code
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
413
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
414 The new broadcasting semantics do not affect almost any code that worked
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
415 in previous versions of Octave without error. Thus for example all code
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
416 inherited from @sc{Matlab} that worked in previous versions of Octave
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
417 should still work without change in Octave. The only exception is code
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
418 such as
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
419
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
420 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
421 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
422 try
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
423 c = a.*b;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
424 catch
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
425 c = a.*a;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
426 end_try_catch
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
427 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
428 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
429
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
430 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
431 that may have relied on matrices of different size producing an error.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
432 Due to how broadcasting changes semantics with older versions of Octave,
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
433 by default Octave warns if a broadcasting operation is performed. To
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
434 disable this warning, refer to its ID (@pxref{doc-warning_ids}):
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
435
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
436 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
437 warning ("off", "Octave:broadcast");
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
438 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
439
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
440 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
441 If you want to recover the old behaviour and produce an error, turn this
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
442 warning into an error:
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
443
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
444 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
445 warning ("error", "Octave:broadcast");
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
446 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
447
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
448 @node Function Application
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
449 @section Function Application
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
450 @cindex map
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
451 @cindex apply
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
452 @cindex function application
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
453
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
454 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
455 arguments in mind and should consider whole matrix operations in a
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
456 vectorized manner. Sometimes, writing functions in this way appears
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
457 difficult or impossible for various reasons. For those situations,
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
458 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
459 array, cell, or struct.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
460
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
461 @DOCSTRING(arrayfun)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
462 @DOCSTRING(spfun)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
463 @DOCSTRING(cellfun)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
464 @DOCSTRING(structfun)
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 @node Accumulation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
467 @section Accumulation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
468
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
469 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
470 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
471 useful.
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 @DOCSTRING(accumarray)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
474
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
475 @DOCSTRING(accumdim)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
476
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
477 @node Miscellaneous Techniques
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
478 @section Miscellaneous Techniques
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
479 @cindex execution speed
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
480 @cindex speedups
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
481 @cindex optimization
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
482
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
483 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
484 programs.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
485
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
486 @itemize @bullet
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 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
489 Avoid computing costly intermediate results multiple times. Octave
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
490 currently does not eliminate common subexpressions. Also, certain
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
491 internal computation results are cached for variables. For instance, if
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
492 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
493 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
494
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
495 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
496 @cindex copy-on-write
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
497 @cindex COW
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
498 @cindex memory management
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
499 Be aware of lazy copies (copy-on-write). When a copy of an object is
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
500 created, the data is not immediately copied, but rather shared. The
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
501 actual copying is postponed until the copied data needs to be modified.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
502 For example:
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
503
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
504 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
505 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
506 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
507 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
508 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
509 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
510 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
511
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
512 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
513 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
514 elements).
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
515
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
516 Additionally, index expressions also use lazy copying when Octave can
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
517 determine that the indexed portion is contiguous in memory. For example:
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
518
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
519 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
520 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
521 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
522 b = a(:,10:100); # no copying done here
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
523 b = a(10:100,:); # copying done here
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
524 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
525 @end example
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 This applies to arrays (matrices), cell arrays, and structs indexed
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
528 using (). Index expressions generating cs-lists can also benefit of
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
529 shallow copying in some cases. In particular, when @var{a} is a struct
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
530 array, expressions like @code{@{a.x@}, @{a(:,2).x@}} will use lazy
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
531 copying, so that data can be shared between a struct array and a cell
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
532 array.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
533
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
534 Most indexing expressions do not live longer than their `parent'
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
535 objects. In rare cases, however, a lazily copied slice outlasts its
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
536 parent, in which case it becomes orphaned, still occupying unnecessarily
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
537 more memory than needed. To provide a remedy working in most real cases,
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
538 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
539 value is stored into a "permanent" location, such as a named variable or
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
540 cell or struct element, and possibly economizes them. For example:
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
541
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
542 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
543 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
544 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
545 b = a(:,10:100); # lazy slice
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
546 a = []; # the original a array is still allocated
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
547 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
548 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
549 @end example
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 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
552 Avoid deep recursion. Function calls to m-file functions carry a
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
553 relatively significant overhead, so rewriting a recursion as a loop
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
554 often helps. Also, note that the maximum level of recursion is limited.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
555
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
556 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
557 Avoid resizing matrices unnecessarily. When building a single result
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
558 matrix from a series of calculations, set the size of the result matrix
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
559 first, then insert values into it. Write
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
560
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
561 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
562 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
563 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
564 for i = over:and_over
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
565 r1 = @dots{}
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
566 r2 = @dots{}
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
567 result (r1, r2) = new_value ();
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
568 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
569 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
570 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
571
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
572 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
573 instead of
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
574
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
575 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
576 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
577 result = [];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
578 for i = ever:and_ever
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
579 result = [ result, new_value() ];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
580 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
581 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
582 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
583
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
584 Sometimes the number of items can't be computed in advance, and
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
585 stack-like operations are needed. When elements are being repeatedly
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
586 inserted at/removed from the end of an array, Octave detects it as stack
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
587 usage and attempts to use a smarter memory management strategy
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
588 pre-allocating the array in bigger chunks. Likewise works for cell and
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
589 struct arrays.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
590
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
591 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
592 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
593 a = [];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
594 while (condition)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
595 @dots{}
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
596 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
597 @dots{}
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
598 a(end) = []; # "pop" operation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
599 @dots{}
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
600 endwhile
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
601 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
602 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
603
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
604 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
605 Avoid calling @code{eval} or @code{feval} excessively, because
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
606 they require Octave to parse input or look up the name of a function in
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
607 the symbol table.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
608
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
609 If you are using @code{eval} as an exception handling mechanism and not
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
610 because you need to execute some arbitrary text, use the @code{try}
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
611 statement instead. @xref{The @code{try} Statement}.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
612
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
613 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
614 If you are calling lots of functions but none of them will need to
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
615 change during your run, set the variable
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
616 @code{ignore_function_time_stamp} to @code{"all"} so that Octave doesn't
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
617 waste a lot of time checking to see if you have updated your function
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
618 files.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
619 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
620
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
621 @node Examples
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
622 @section Examples
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
623
14118
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
624 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
625 users of Octave and their solutions.
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
626
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
627 @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
628
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
629 @itemize @bullet
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
630 @item
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
631 For a vector @code{A}, the following loop
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
632
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
633 @example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
634 @group
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
635 n = length (A);
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
636 B = zeros (n, 2);
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
637 for i = 1:length(A)
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
638 ## 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
639 ## the second the mean of the two elements used for the diff.
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
640 B(i,:) = [A(i+1)-A(i), (A(i+1) + A(i))/2)];
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
641 end
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
642 @end group
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
643 @end example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
644
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
645 @noindent
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
646 can be turned into the following one-liner:
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
647
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
648 @example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
649 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
650 @end example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
651
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
652 Note the usage of colon indexing to flatten an intermediate result into
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
653 a column vector. This is a common vectorization trick.
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
654
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
655 @end itemize