Mercurial > octave-nkf

annotate doc/interpreter/vectorize.txi @ 15684:ddc651eecf7a stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix Info index for language statements (bug #37787) * dynamic.txi, errors.txi, stmt.txi, vectorize.txi: Remove @code from all node names, menus, and cross-references. * octave.texi: Remove @code from menu for statements. * ov-oncleanup.cc(Foncleanup): Remove @code from cross-reference in docstring.
author Rik <rik@octave.org>
date Wed, 28 Nov 2012 09:13:56 -0800
parents 72c96de7a403
children 18f8f2987205
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
14138
72c96de7a403 maint: update copyright notices for 2012
John W. Eaton <jwe@octave.org>
parents: 14123
diff changeset
1 @c Copyright (C) 2012 Jordi Gutiérrez Hermoso
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
2 @c
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
3 @c This file is part of Octave.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
4 @c
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
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
25 instead of element-by-element loop-based operations. Besides frequently
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
26 producing more succinct Octave code, vectorization also allows for better
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
27 optimization in the subsequent implementation. The optimizations may occur
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
28 either in Octave's own Fortran, C, or C++ internal implementation, or even at a
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
29 lower level depending on the compiler and external numerical libraries used to
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
30 build Octave. The ultimate goal is to make use of your hardware's vector
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
31 instructions if possible or to perform other optimizations in software.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
32
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
33 Vectorization is not a concept unique to Octave, but it is particularly
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
34 important because Octave is a matrix-oriented language. Vectorized
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
35 Octave code will see a dramatic speed up (10X--100X) in most cases.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
36
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
37 This chapter discusses vectorization and other techniques for writing faster
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
38 code.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
39
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
40 @menu
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
41 * Basic Vectorization:: Basic techniques for code optimization
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
42 * Broadcasting:: Broadcasting operations
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
43 * Function Application:: Applying functions to arrays, cells, and structs
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
44 * Accumulation:: Accumulation functions
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
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
53 write code that avoids loops and uses whole-array operations. As a
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
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
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
75 optimize. Octave delegates this operation to an underlying
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
76 implementation which, among other optimizations, may use special vector
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
77 hardware instructions or could conceivably even perform the additions in
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
78 parallel. In general, if the code is vectorized, the underlying
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
79 implementation has more freedom about the assumptions it can make
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
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
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
82 This is especially important for loops with "cheap" bodies. Often it
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
83 suffices to vectorize just the innermost loop to get acceptable
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
84 performance. A general rule of thumb is that the "order" of the
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
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
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
88 As a less trivial example, instead of
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
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
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
106 instead of looping over an index variable. @xref{Index Expressions}.
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
107 Also use boolean indexing generously. If a condition needs to be tested,
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
108 this condition can also be written as a boolean index. For instance,
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
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
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
132 (operators like @code{.*} and @code{.^}). @xref{Arithmetic Ops}. For
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
133 simple inline functions, the @code{vectorize} function can do this
14116
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
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
138 Also exploit broadcasting in these elementwise operators both to avoid
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
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
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
142 Use built-in and library functions if possible. Built-in and compiled
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
143 functions are very fast. Even with an m-file library function, chances
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
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
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
161 mind. If you find yourself writing a loop with a very simple operation,
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
162 chances are that such a function already exists. The following functions
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
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
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
172
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
173 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
174 sub2ind
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
175
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
176 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
177 ind2sub
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
178
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
179 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
180 sort
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
181
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
182 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
183 unique
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
184
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
185 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
186 lookup
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
187
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
188 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
189 ifelse / merge
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
190 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
191
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
192 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
193 Repetition
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
194 @itemize
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 repmat
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
197
14116
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 repelems
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
200 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
201
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 Vectorized arithmetic
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
204 @itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
205 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
206 sum
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
207
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
208 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
209 prod
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
210
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
211 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
212 cumsum
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
213
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
214 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
215 cumprod
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
216
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
217 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
218 sumsq
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
219
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
220 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
221 diff
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
222
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
223 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
224 dot
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
225
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
226 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
227 cummax
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
228
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
229 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
230 cummin
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
231 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
232
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
233 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
234 Shape of higher dimensional arrays
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
235 @itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
236 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
237 reshape
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
238
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
239 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
240 resize
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
241
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
242 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
243 permute
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
244
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
245 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
246 squeeze
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
247
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
248 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
249 deal
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
250 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
251
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
252 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
253
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
254 @node Broadcasting
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
255 @section Broadcasting
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
256 @cindex broadcast
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
257 @cindex broadcasting
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
258 @cindex BSX
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
259 @cindex recycling
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
260 @cindex SIMD
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
261
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
262 Broadcasting refers to how Octave binary operators and functions behave
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
263 when their matrix or array operands or arguments differ in size. Since
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
264 version 3.6.0, Octave now automatically broadcasts vectors, matrices,
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
265 and arrays when using elementwise binary operators and functions.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
266 Broadly speaking, smaller arrays are ``broadcast'' across the larger
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
267 one, until they have a compatible shape. The rule is that corresponding
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
268 array dimensions must either
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
269
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
270 @enumerate
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
271 @item
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
272 be equal, or
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
273
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
274 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
275 one of them must be 1.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
276 @end enumerate
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
277
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
278 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
279 In case all dimensions are equal, no broadcasting occurs and ordinary
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
280 element-by-element arithmetic takes place. For arrays of higher
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
281 dimensions, if the number of dimensions isn't the same, then missing
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
282 trailing dimensions are treated as 1. When one of the dimensions is 1,
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
283 the array with that singleton dimension gets copied along that dimension
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
284 until it matches the dimension of the other array. For example, consider
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
285
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
286 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
287 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
288 x = [1 2 3;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
289 4 5 6;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
290 7 8 9];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
291
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
292 y = [10 20 30];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
293
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
294 x + y
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
295 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
296 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
297
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
298 @noindent
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
299 Without broadcasting, @code{x + y} would be an error because the dimensions
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
300 do not agree. However, with broadcasting it is as if the following
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
301 operation were performed:
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
302
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
303 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
304 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
305 x = [1 2 3
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
306 4 5 6
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
307 7 8 9];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
308
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
309 y = [10 20 30
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
310 10 20 30
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
311 10 20 30];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
312
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
313 x + y
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
314 @result{} 11 22 33
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
315 14 25 36
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
316 17 28 39
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
317 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
318 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
319
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
320 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
321 That is, the smaller array of size @code{[1 3]} gets copied along the
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
322 singleton dimension (the number of rows) until it is @code{[3 3]}. No
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
323 actual copying takes place, however. The internal implementation reuses
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
324 elements along the necessary dimension in order to achieve the desired
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
325 effect without copying in memory.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
326
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
327 Both arrays can be broadcast across each other, for example, all
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
328 pairwise differences of the elements of a vector with itself:
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
329
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
330 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
331 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
332 y - y'
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
333 @result{} 0 10 20
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
334 -10 0 10
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
335 -20 -10 0
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
336 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
337 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
338
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
339 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
340 Here the vectors of size @code{[1 3]} and @code{[3 1]} both get
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
341 broadcast into matrices of size @code{[3 3]} before ordinary matrix
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
342 subtraction takes place.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
343
14123
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
344 A special case of broadcasting that may be familiar is when all
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
345 dimensions of the array being broadcast are 1, i.e. the array is a
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
346 scalar. Thus for example, operations like @code{x - 42} and @code{max
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
347 (x, 2)} are basic examples of broadcasting.
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
348
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
349 For a higher-dimensional example, suppose @code{img} is an RGB image of
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
350 size @code{[m n 3]} and we wish to multiply each color by a different
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
351 scalar. The following code accomplishes this with broadcasting,
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
352
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
353 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
354 img .*= permute ([0.8, 0.9, 1.2], [1, 3, 2]);
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
355 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
356
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
357 @noindent
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
358 Note the usage of permute to match the dimensions of the
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
359 @code{[0.8, 0.9, 1.2]} vector with @code{img}.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
360
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
361 For functions that are not written with broadcasting semantics,
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
362 @code{bsxfun} can be useful for coercing them to broadcast.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
363
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
364 @DOCSTRING(bsxfun)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
365
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
366 Broadcasting is only applied if either of the two broadcasting
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
367 conditions hold. As usual, however, broadcasting does not apply when two
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
368 dimensions differ and neither is 1:
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
369
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
370 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
371 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
372 x = [1 2 3
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
373 4 5 6];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
374 y = [10 20
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
375 30 40];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
376 x + y
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
377 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
378 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
379
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
380 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
381 This will produce an error about nonconformant arguments.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
382
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
383 Besides common arithmetic operations, several functions of two arguments
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
384 also broadcast. The full list of functions and operators that broadcast
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
385 is
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
386
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
387 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
388 plus + .+
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
389 minus - .-
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
390 times .*
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
391 rdivide ./
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
392 ldivide .\
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
393 power .^ .**
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
394 lt <
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
395 le <=
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
396 eq ==
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
397 gt >
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
398 ge >=
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
399 ne != ~=
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
400 and &
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
401 or |
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
402 atan2
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
403 hypot
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
404 max
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
405 min
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
406 mod
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
407 rem
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
408 xor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
409
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
410 += -= .+= .-= .*= ./= .\= .^= .**= &= |=
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
411 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
412
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
413 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
414 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
415
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
416 @example
14123
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
417 @var{c} = sum (permute (@var{a}, [1, 3, 2]) .* permute (@var{b}, [3, 2, 1]), 3);
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
418 @end example
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 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
421 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
422 across each other during elementwise multiplication in order to obtain a
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
423 larger 3-D array, and this array is then summed along the third dimension.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
424 A moment of thought will prove that this operation is simply the much
14123
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
425 faster ordinary matrix multiplication, @code{@var{c} = @var{a}*@var{b};}.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
426
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
427 A note on terminology: ``broadcasting'' is the term popularized by the
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
428 Numpy numerical environment in the Python programming language. In other
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
429 programming languages and environments, broadcasting may also be known
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
430 as @emph{binary singleton expansion} (BSX, in @sc{matlab}, and the
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
431 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
432 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
433 or @emph{replication}.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
434
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
435 @subsection Broadcasting and Legacy Code
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
436
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
437 The new broadcasting semantics almost never affect code that worked
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
438 in previous versions of Octave. Consequently, all code inherited from
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
439 @sc{matlab} that worked in previous versions of Octave should still work
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
440 without change in Octave. The only exception is code such as
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
441
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
442 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
443 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
444 try
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
445 c = a.*b;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
446 catch
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
447 c = a.*a;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
448 end_try_catch
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
449 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
450 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
451
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
452 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
453 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
454 Due to how broadcasting changes semantics with older versions of Octave,
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
455 by default Octave warns if a broadcasting operation is performed. To
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
456 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
457
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
458 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
459 warning ("off", "Octave:broadcast");
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
460 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
461
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
462 @noindent
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
463 If you want to recover the old behavior and produce an error, turn this
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
464 warning into an error:
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 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
467 warning ("error", "Octave:broadcast");
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
468 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
469
14123
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
470 @noindent
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
471 For broadcasting on scalars that worked in previous versions of Octave,
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
472 this warning will not be emitted.
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
473
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
474 @node Function Application
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
475 @section Function Application
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
476 @cindex map
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
477 @cindex apply
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
478 @cindex function application
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
479
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
480 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
481 arguments in mind and should consider whole matrix operations in a
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
482 vectorized manner. Sometimes, writing functions in this way appears
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
483 difficult or impossible for various reasons. For those situations,
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
484 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
485 array, cell, or struct.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
486
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
487 @DOCSTRING(arrayfun)
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
488
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
489 @DOCSTRING(spfun)
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
490
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
491 @DOCSTRING(cellfun)
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
492
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
493 @DOCSTRING(structfun)
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 @node Accumulation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
496 @section Accumulation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
497
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
498 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
499 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
500 useful.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
501
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
502 @DOCSTRING(accumarray)
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 @DOCSTRING(accumdim)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
505
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
506 @node Miscellaneous Techniques
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
507 @section Miscellaneous Techniques
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
508 @cindex execution speed
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
509 @cindex speedups
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
510 @cindex optimization
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 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
513 programs.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
514
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
515 @itemize @bullet
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
516
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
517 @item Avoid computing costly intermediate results multiple times.
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
518 Octave currently does not eliminate common subexpressions. Also, certain
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
519 internal computation results are cached for variables. For instance, if
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
520 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
521 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
522
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
523 @item Be aware of lazy copies (copy-on-write).
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
524 @cindex copy-on-write
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
525 @cindex COW
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
526 @cindex memory management
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
527 When a copy of an object is created, the data is not immediately copied, but
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
528 rather shared. The actual copying is postponed until the copied data needs to
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
529 be modified. For example:
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
530
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
531 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
532 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
533 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
534 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
535 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
536 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
537 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
538
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
539 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
540 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
541 elements).
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
542
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
543 Additionally, index expressions also use lazy copying when Octave can
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
544 determine that the indexed portion is contiguous in memory. For example:
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
545
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
546 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
547 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
548 a = zeros (1000); # create a 1000x1000 matrix
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
549 b = a(:,10:100); # no copying done here
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
550 b = a(10:100,:); # copying done here
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
551 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
552 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
553
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
554 This applies to arrays (matrices), cell arrays, and structs indexed
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
555 using @samp{()}. Index expressions generating comma-separated lists can also
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
556 benefit from shallow copying in some cases. In particular, when @var{a} is a
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
557 struct array, expressions like @code{@{a.x@}, @{a(:,2).x@}} will use lazy
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
558 copying, so that data can be shared between a struct array and a cell array.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
559
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
560 Most indexing expressions do not live longer than their parent
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
561 objects. In rare cases, however, a lazily copied slice outlasts its
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
562 parent, in which case it becomes orphaned, still occupying unnecessarily
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
563 more memory than needed. To provide a remedy working in most real cases,
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
564 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
565 value is stored into a "permanent" location, such as a named variable or
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
566 cell or struct element, and possibly economizes them. For example:
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
567
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
568 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
569 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
570 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
571 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
572 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
573 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
574 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
575 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
576
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
577 @item Avoid deep recursion.
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
578 Function calls to m-file functions carry a relatively significant overhead, so
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
579 rewriting a recursion as a loop often helps. Also, note that the maximum level
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
580 of recursion is limited.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
581
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
582 @item Avoid resizing matrices unnecessarily.
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
583 When building a single result matrix from a series of calculations, set the
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
584 size of the result matrix first, then insert values into it. Write
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
585
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
586 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
587 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
588 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
589 for i = over:and_over
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
590 ridx = @dots{}
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
591 cidx = @dots{}
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
592 result(ridx, cidx) = new_value ();
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
593 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
594 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
595 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
596
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
597 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
598 instead of
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
599
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
600 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
601 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
602 result = [];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
603 for i = ever:and_ever
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
604 result = [ result, new_value() ];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
605 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
606 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
607 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
608
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
609 Sometimes the number of items can not be computed in advance, and
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
610 stack-like operations are needed. When elements are being repeatedly
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
611 inserted or removed from the end of an array, Octave detects it as stack
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
612 usage and attempts to use a smarter memory management strategy by
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
613 pre-allocating the array in bigger chunks. This strategy is also applied
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
614 to cell and struct arrays.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
615
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
616 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
617 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
618 a = [];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
619 while (condition)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
620 @dots{}
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
621 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
622 @dots{}
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
623 a(end) = []; # "pop" operation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
624 @dots{}
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
625 endwhile
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
626 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
627 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
628
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
629 @item Avoid calling @code{eval} or @code{feval} excessively.
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
630 Parsing input or looking up the name of a function in the symbol table are
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
631 relatively expensive operations.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
632
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
633 If you are using @code{eval} merely as an exception handling mechanism, and not
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
634 because you need to execute some arbitrary text, use the @code{try}
15684
ddc651eecf7a Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents: 14138
diff changeset
635 statement instead. @xref{The try Statement}.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
636
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
637 @item Use @code{ignore_function_time_stamp} when appropriate.
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
638 If you are calling lots of functions, and none of them will need to change
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
639 during your run, set the variable @code{ignore_function_time_stamp} to
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
640 @code{"all"}. This will stop Octave from checking the time stamp of a function
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
641 file to see if it has been updated while the program is being run.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
642 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
643
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
644 @node Examples
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
645 @section Examples
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
646
14118
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
647 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
648 users of Octave and their solutions.
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
649
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
650 @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
651
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
652 @itemize @bullet
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
653 @item
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
654 For a vector @code{A}, the following loop
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
655
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
656 @example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
657 @group
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
658 n = length (A);
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
659 B = zeros (n, 2);
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
660 for i = 1:length(A)
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
661 ## 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
662 ## 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
663 B(i,:) = [A(i+1)-A(i), (A(i+1) + A(i))/2)];
14123
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
664 endfor
14118
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
665 @end group
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
666 @end example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
667
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
668 @noindent
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
669 can be turned into the following one-liner:
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
670
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
671 @example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
672 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
673 @end example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
674
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
675 Note the usage of colon indexing to flatten an intermediate result into
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
676 a column vector. This is a common vectorization trick.
14118
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
677
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
678 @end itemize