Mercurial > octave

annotate doc/interpreter/vectorize.txi @ 20491:6ef177ddc1ee stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: remove section about broadcasting warnings which no longer exists.
author Carnë Draug <carandraug@octave.org>
date Sat, 19 Sep 2015 02:34:45 +0100
parents 9cf91ecdc6f7
children 9fc91bb2aec3
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
19697
4197fc428c7d maint: Update copyright notices for 2015.
John W. Eaton <jwe@octave.org>
parents: 19596
diff changeset
1 @c Copyright (C) 2012-2015 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
16878
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
45 * JIT Compiler:: Just-In-Time Compiler for loops
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
46 * Miscellaneous Techniques:: Other techniques for speeding up code
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
47 * Examples::
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
48 @end menu
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
49
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
50 @node Basic Vectorization
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
51 @section Basic Vectorization
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
52
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
53 To a very good first approximation, the goal in vectorization is to
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
54 write code that avoids loops and uses whole-array operations. As a
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
55 trivial example, consider
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
56
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
57 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
58 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
59 for i = 1:n
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
60 for j = 1:m
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
61 c(i,j) = a(i,j) + b(i,j);
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
62 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
63 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
64 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
65 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
66
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
67 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
68 compared to the much simpler
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
69
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
70 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
71 c = a + b;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
72 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
73
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
74 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
75 This isn't merely easier to write; it is also internally much easier to
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
76 optimize. Octave delegates this operation to an underlying
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
77 implementation which, among other optimizations, may use special vector
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
78 hardware instructions or could conceivably even perform the additions in
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
79 parallel. In general, if the code is vectorized, the underlying
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
80 implementation has more freedom about the assumptions it can make
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
81 in order to achieve faster execution.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
82
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
83 This is especially important for loops with "cheap" bodies. Often it
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
84 suffices to vectorize just the innermost loop to get acceptable
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
85 performance. A general rule of thumb is that the "order" of the
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
86 vectorized body should be greater or equal to the "order" of the
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
87 enclosing loop.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
88
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
89 As a less trivial example, instead of
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
90
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
91 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
92 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
93 for i = 1:n-1
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
94 a(i) = b(i+1) - b(i);
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
95 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
96 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
97 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
98
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
99 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
100 write
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
101
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
102 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
103 a = b(2:n) - b(1:n-1);
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
104 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
105
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
106 This shows an important general concept about using arrays for indexing
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
107 instead of looping over an index variable. @xref{Index Expressions}.
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
108 Also use boolean indexing generously. If a condition needs to be tested,
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
109 this condition can also be written as a boolean index. For instance,
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
110 instead of
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
111
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
112 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
113 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
114 for i = 1:n
16934
48f5b993b819 doc: Use parentheses around if, switch conditions in documentation.
Rik <rik@octave.org>
parents: 16878
diff changeset
115 if (a(i) > 5)
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
116 a(i) -= 20
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
117 endif
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
118 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
119 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
120 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
121
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
122 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
123 write
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
124
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
125 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
126 a(a>5) -= 20;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
127 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
128
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
129 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
130 which exploits the fact that @code{a > 5} produces a boolean index.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
131
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
132 Use elementwise vector operators whenever possible to avoid looping
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
133 (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
134 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
135 automatically.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
136
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
137 @DOCSTRING(vectorize)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
138
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
139 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
140 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
141 @xref{Broadcasting}.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
142
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
143 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
144 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
145 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
146 future release.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
147
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
148 For instance, even better than
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
149
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
150 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
151 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
152 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
153
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
154 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
155 is
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
156
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
157 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
158 a = diff (b);
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
159 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
160
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
161 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
162 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
163 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
164 occur frequently in vectorized code:
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
165
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
166 @itemize @bullet
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
167 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
168 Index manipulation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
169
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
170 @itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
171 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
172 find
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
173
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
174 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
175 sub2ind
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
176
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
177 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
178 ind2sub
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
179
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
180 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
181 sort
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
182
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
183 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
184 unique
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
185
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
186 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
187 lookup
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
188
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
189 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
190 ifelse / merge
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
191 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
192
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
193 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
194 Repetition
14853
72b8b39e12be doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
195
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
196 @itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
197 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
198 repmat
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
199
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
200 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
201 repelems
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
202 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
203
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
204 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
205 Vectorized arithmetic
14853
72b8b39e12be doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
206
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
207 @itemize
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 sum
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 prod
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 cumsum
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 cumprod
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 sumsq
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 diff
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 dot
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 cummax
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
231
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
232 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
233 cummin
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
234 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
235
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 Shape of higher dimensional arrays
14853
72b8b39e12be doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
238
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
239 @itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
240 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
241 reshape
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
242
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
243 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
244 resize
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
245
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
246 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
247 permute
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
248
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
249 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
250 squeeze
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
251
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
252 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
253 deal
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
254 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
255
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
256 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
257
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
258 @node Broadcasting
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
259 @section Broadcasting
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
260 @cindex broadcast
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
261 @cindex broadcasting
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
262 @cindex BSX
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
263 @cindex recycling
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
264 @cindex SIMD
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
265
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
266 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
267 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
268 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
269 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
270 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
271 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
272 array dimensions must either
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
273
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
274 @enumerate
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
275 @item
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
276 be equal, or
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
277
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
278 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
279 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
280 @end enumerate
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
281
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
282 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
283 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
284 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
285 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
286 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
287 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
288 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
289
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
290 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
291 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
292 x = [1 2 3;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
293 4 5 6;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
294 7 8 9];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
295
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
296 y = [10 20 30];
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 x + y
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
299 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
300 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
301
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
302 @noindent
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
303 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
304 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
305 operation were performed:
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
306
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
307 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
308 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
309 x = [1 2 3
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
310 4 5 6
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
311 7 8 9];
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 y = [10 20 30
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
314 10 20 30
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
315 10 20 30];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
316
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
317 x + y
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
318 @result{} 11 22 33
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
319 14 25 36
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
320 17 28 39
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
321 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
322 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
323
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
324 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
325 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
326 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
327 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
328 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
329 effect without copying in memory.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
330
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
331 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
332 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
333
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
334 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
335 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
336 y - y'
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
337 @result{} 0 10 20
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
338 -10 0 10
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
339 -20 -10 0
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
340 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
341 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
342
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
343 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
344 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
345 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
346 subtraction takes place.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
347
14123
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
348 A special case of broadcasting that may be familiar is when all
14853
72b8b39e12be doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
349 dimensions of the array being broadcast are 1, i.e., the array is a
72b8b39e12be doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
350 scalar. Thus for example, operations like @code{x - 42} and @code{max
14123
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
351 (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
352
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
353 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
354 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
355 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
356
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
357 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
358 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
359 @end example
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 @noindent
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
362 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
363 @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
364
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
365 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
366 @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
367
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
368 @DOCSTRING(bsxfun)
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 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
371 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
372 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
373
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
374 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
375 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
376 x = [1 2 3
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
377 4 5 6];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
378 y = [10 20
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
379 30 40];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
380 x + y
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
381 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
382 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
383
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
384 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
385 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
386
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
387 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
388 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
389 is
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
390
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
391 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
392 plus + .+
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
393 minus - .-
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
394 times .*
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
395 rdivide ./
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
396 ldivide .\
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
397 power .^ .**
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
398 lt <
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
399 le <=
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
400 eq ==
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
401 gt >
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
402 ge >=
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
403 ne != ~=
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
404 and &
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
405 or |
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
406 atan2
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
407 hypot
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
408 max
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
409 min
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
410 mod
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
411 rem
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
412 xor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
413
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
414 += -= .+= .-= .*= ./= .\= .^= .**= &= |=
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
415 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
416
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
417 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
418 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
419
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
420 @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
421 @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
422 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
423
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
424 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
425 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
426 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
427 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
428 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
429 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
430
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
431 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
432 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
433 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
434 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
435 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
436 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
437 or @emph{replication}.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
438
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
439 @subsection Broadcasting and Legacy Code
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
440
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
441 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
442 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
443 @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
444 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
445
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
446 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
447 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
448 try
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
449 c = a.*b;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
450 catch
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
451 c = a.*a;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
452 end_try_catch
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
453 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
454 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
455
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
456 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
457 that may have relied on matrices of different size producing an error.
20491
6ef177ddc1ee doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents: 19836
diff changeset
458 Because such operation is now valid Octave syntax, this will no longer
6ef177ddc1ee doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents: 19836
diff changeset
459 produce an error. Instead, the following code should be used:
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
460
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
461 @example
20491
6ef177ddc1ee doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents: 19836
diff changeset
462 @group
6ef177ddc1ee doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents: 19836
diff changeset
463 if (isequal (size (a), size (b)))
6ef177ddc1ee doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents: 19836
diff changeset
464 c = a .* b;
6ef177ddc1ee doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents: 19836
diff changeset
465 else
6ef177ddc1ee doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents: 19836
diff changeset
466 c = a .* a;
6ef177ddc1ee doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents: 19836
diff changeset
467 endif
6ef177ddc1ee doc: remove section about broadcasting warnings which no longer exists.
Carnë Draug <carandraug@octave.org>
parents: 19836
diff changeset
468 @end group
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
469 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
470
14123
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
471
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
472 @node Function Application
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
473 @section Function Application
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
474 @cindex map
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
475 @cindex apply
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
476 @cindex function application
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
477
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
478 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
479 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
480 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
481 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
482 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
483 array, cell, or struct.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
484
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
485 @DOCSTRING(arrayfun)
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
486
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
487 @DOCSTRING(spfun)
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(cellfun)
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(structfun)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
492
19435
51a1d1164449 Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents: 18815
diff changeset
493 Consistent with earlier advice, seek to use Octave built-in functions whenever
51a1d1164449 Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents: 18815
diff changeset
494 possible for the best performance. This advice applies especially to the four
51a1d1164449 Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents: 18815
diff changeset
495 functions above. For example, when adding two arrays together
51a1d1164449 Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents: 18815
diff changeset
496 element-by-element one could use a handle to the built-in addition function
51a1d1164449 Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents: 18815
diff changeset
497 @code{@@plus} or define an anonymous function @code{@@(x,y) x + y}. But, the
51a1d1164449 Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents: 18815
diff changeset
498 anonymous function is 60% slower than the first method.
51a1d1164449 Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents: 18815
diff changeset
499 @xref{Operator Overloading}, for a list of basic functions which might be used
51a1d1164449 Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents: 18815
diff changeset
500 in place of anonymous ones.
51a1d1164449 Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents: 18815
diff changeset
501
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
502 @node Accumulation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
503 @section Accumulation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
504
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
505 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
506 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
507 useful.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
508
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
509 @DOCSTRING(accumarray)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
510
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
511 @DOCSTRING(accumdim)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
512
16878
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
513 @node JIT Compiler
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
514 @section JIT Compiler
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
515
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
516 Vectorization is the preferred technique for eliminating loops and speeding up
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
517 code. Nevertheless, it is not always possible to replace every loop. In such
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
518 situations it may be worth trying Octave's @strong{experimental} Just-In-Time
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
519 (JIT) compiler.
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
520
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
521 A JIT compiler works by analyzing the body of a loop, translating the Octave
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
522 statements into another language, compiling the new code segment into an
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
523 executable, and then running the executable and collecting any results. The
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
524 process is not simple and there is a significant amount of work to perform for
16941
e6ddaa65a777 Add new function jit_startcnt to control JIT acceleration.
Rik <rik@octave.org>
parents: 16934
diff changeset
525 each step. It can still make sense, however, if the number of loop iterations
e6ddaa65a777 Add new function jit_startcnt to control JIT acceleration.
Rik <rik@octave.org>
parents: 16934
diff changeset
526 is large. Because Octave is an interpreted language every time through a
16878
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
527 loop Octave must parse the statements in the loop body before executing them.
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
528 With a JIT compiler this is done just once when the body is translated to
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
529 another language.
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
530
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
531 The JIT compiler is a very new feature in Octave and not all valid Octave
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
532 statements can currently be accelerated. However, if no other technique
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
533 is available it may be worth benchmarking the code with JIT enabled. The
16941
e6ddaa65a777 Add new function jit_startcnt to control JIT acceleration.
Rik <rik@octave.org>
parents: 16934
diff changeset
534 function @code{jit_enable} is used to turn compilation on or off. The
e6ddaa65a777 Add new function jit_startcnt to control JIT acceleration.
Rik <rik@octave.org>
parents: 16934
diff changeset
535 function @code{jit_startcnt} sets the threshold for acceleration. Loops
e6ddaa65a777 Add new function jit_startcnt to control JIT acceleration.
Rik <rik@octave.org>
parents: 16934
diff changeset
536 with iteration counts above @code{jit_startcnt} will be accelerated. The
19836
9cf91ecdc6f7 Rename jit_failure_count() to jit_failcnt().
Rik <rik@octave.org>
parents: 19697
diff changeset
537 functions @code{jit_failcnt} and @code{debug_jit} are not likely to be of use
9cf91ecdc6f7 Rename jit_failure_count() to jit_failcnt().
Rik <rik@octave.org>
parents: 19697
diff changeset
538 to anyone not working directly on the implementation of the JIT compiler.
16878
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
539
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
540 @DOCSTRING(jit_enable)
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
541
16941
e6ddaa65a777 Add new function jit_startcnt to control JIT acceleration.
Rik <rik@octave.org>
parents: 16934
diff changeset
542 @DOCSTRING(jit_startcnt)
e6ddaa65a777 Add new function jit_startcnt to control JIT acceleration.
Rik <rik@octave.org>
parents: 16934
diff changeset
543
19836
9cf91ecdc6f7 Rename jit_failure_count() to jit_failcnt().
Rik <rik@octave.org>
parents: 19697
diff changeset
544 @DOCSTRING(jit_failcnt)
9cf91ecdc6f7 Rename jit_failure_count() to jit_failcnt().
Rik <rik@octave.org>
parents: 19697
diff changeset
545
16878
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
546 @DOCSTRING(debug_jit)
011119bf4868 doc: Add jit_enable() and debug_jit() to manual.
Rik <rik@octave.org>
parents: 16772
diff changeset
547
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
548 @node Miscellaneous Techniques
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
549 @section Miscellaneous Techniques
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
550 @cindex execution speed
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
551 @cindex speedups
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
552 @cindex optimization
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 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
555 programs.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
556
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
557 @itemize @bullet
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
558
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
559 @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
560 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
561 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
562 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
563 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
564
19593
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 17744
diff changeset
565 @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
566 @cindex copy-on-write
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
567 @cindex COW
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
568 @cindex memory management
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
569 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
570 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
571 be modified. For example:
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
572
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
573 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
574 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
575 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
576 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
577 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
578 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
579 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
580
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
581 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
582 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
583 elements).
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
584
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
585 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
586 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
587
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
588 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
589 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
590 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
591 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
592 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
593 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
594 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
595
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
596 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
597 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
598 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
599 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
600 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
601
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
602 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
603 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
604 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
605 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
606 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
607 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
608 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
609
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
610 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
611 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
612 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
613 b = a(:,10:100); # lazy slice
17170
d6499c14021c doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents: 17097
diff changeset
614 a = []; # the original "a" array is still allocated
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
615 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
616 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
617 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
618
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
619 @item Avoid deep recursion.
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
620 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
621 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
622 of recursion is limited.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
623
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
624 @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
625 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
626 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
627
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
628 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
629 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
630 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
631 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
632 ridx = @dots{}
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
633 cidx = @dots{}
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
634 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
635 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
636 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
637 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
638
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
639 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
640 instead of
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
641
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
642 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
643 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
644 result = [];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
645 for i = ever:and_ever
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
646 result = [ result, new_value() ];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
647 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
648 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
649 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
650
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
651 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
652 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
653 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
654 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
655 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
656 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
657
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
658 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
659 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
660 a = [];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
661 while (condition)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
662 @dots{}
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
663 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
664 @dots{}
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
665 a(end) = []; # "pop" operation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
666 @dots{}
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
667 endwhile
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
668 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
669 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
670
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
671 @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
672 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
673 relatively expensive operations.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
674
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
675 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
676 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
677 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
678
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
679 @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
680 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
681 during your run, set the variable @code{ignore_function_time_stamp} to
17281
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents: 17170
diff changeset
682 @qcode{"all"}. This will stop Octave from checking the time stamp of a function
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
683 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
684 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
685
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
686 @node Examples
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
687 @section Examples
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
688
14118
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
689 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
690 users of Octave and their solutions.
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
691
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
692 @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
693
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
694 @itemize @bullet
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
695 @item
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
696 For a vector @code{A}, the following loop
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
697
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
698 @example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
699 @group
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
700 n = length (A);
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
701 B = zeros (n, 2);
14856
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents: 14853
diff changeset
702 for i = 1:length (A)
14118
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
703 ## 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
704 ## the second the mean of the two elements used for the diff.
18679
a142f35f3cb6 doc: Fix unbalanced parentheses in documentation.
Rik <rik@octave.org>
parents: 17744
diff changeset
705 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
706 endfor
14118
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
707 @end group
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
708 @end example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
709
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
710 @noindent
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
711 can be turned into the following one-liner:
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
712
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
713 @example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
714 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
715 @end example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
716
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
717 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
718 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
719
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
720 @end itemize
18815
19a140e93b1f doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents: 18679
diff changeset
721