Mercurial > octave-nkf

annotate doc/interpreter/vectorize.txi @ 16772:7eff3032d144

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix seealso HTML links when using Texinfo 4.X (bug #38862). Use the prefix 'docX' instead of 'doc-' for Texinfo references. * doc/interpreter/arith.txi, doc/interpreter/basics.txi, doc/interpreter/container.txi, doc/interpreter/func.txi, doc/interpreter/java.txi, doc/interpreter/matrix.txi, doc/interpreter/munge-texi.pl, doc/interpreter/package.txi, doc/interpreter/plot.txi, doc/interpreter/stats.txi, doc/interpreter/strings.txi, doc/interpreter/system.txi, doc/interpreter/var.txi, doc/interpreter/vectorize.txi, libinterp/corefcn/qz.cc, libinterp/corefcn/regexp.cc, libinterp/interpfcn/error.cc, scripts/general/accumarray.m, scripts/general/structfun.m, scripts/miscellaneous/setfield.m, scripts/optimization/fminbnd.m, scripts/optimization/fzero.m, scripts/optimization/lsqnonneg.m: Use the prefix 'docX' instead of 'doc-' for Texinfo references.
author Rik <rik@octave.org>
date Tue, 18 Jun 2013 20:35:12 -0700
parents 18f8f2987205
children 011119bf4868
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
14138
72c96de7a403 maint: update copyright notices for 2012
John W. Eaton <jwe@octave.org>
parents: 14123
diff changeset
1 @c Copyright (C) 2012 Jordi Gutiérrez Hermoso
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
2 @c
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
3 @c This file is part of Octave.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
4 @c
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
5 @c Octave is free software; you can redistribute it and/or modify it
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
6 @c under the terms of the GNU General Public License as published by the
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
7 @c Free Software Foundation; either version 3 of the License, or (at
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
8 @c your option) any later version.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
9 @c
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
10 @c Octave is distributed in the hope that it will be useful, but WITHOUT
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
11 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
12 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
13 @c for more details.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
14 @c
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
15 @c You should have received a copy of the GNU General Public License
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
16 @c along with Octave; see the file COPYING. If not, see
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
17 @c <http://www.gnu.org/licenses/>.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
18
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
19 @node Vectorization and Faster Code Execution
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
20 @chapter Vectorization and Faster Code Execution
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
21 @cindex vectorization
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
22 @cindex vectorize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
23
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
24 Vectorization is a programming technique that uses vector operations
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
25 instead of element-by-element loop-based operations. Besides frequently
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
26 producing more succinct Octave code, vectorization also allows for better
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
27 optimization in the subsequent implementation. The optimizations may occur
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
28 either in Octave's own Fortran, C, or C++ internal implementation, or even at a
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
29 lower level depending on the compiler and external numerical libraries used to
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
30 build Octave. The ultimate goal is to make use of your hardware's vector
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
31 instructions if possible or to perform other optimizations in software.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
32
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
33 Vectorization is not a concept unique to Octave, but it is particularly
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
34 important because Octave is a matrix-oriented language. Vectorized
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
35 Octave code will see a dramatic speed up (10X--100X) in most cases.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
36
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
37 This chapter discusses vectorization and other techniques for writing faster
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
38 code.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
39
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
40 @menu
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
41 * Basic Vectorization:: Basic techniques for code optimization
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
42 * Broadcasting:: Broadcasting operations
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
43 * Function Application:: Applying functions to arrays, cells, and structs
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
44 * Accumulation:: Accumulation functions
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
45 * Miscellaneous Techniques:: Other techniques for speeding up code
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
46 * Examples::
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
47 @end menu
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
48
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
49 @node Basic Vectorization
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
50 @section Basic Vectorization
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
51
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
52 To a very good first approximation, the goal in vectorization is to
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
53 write code that avoids loops and uses whole-array operations. As a
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
54 trivial example, consider
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
55
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
56 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
57 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
58 for i = 1:n
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
59 for j = 1:m
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
60 c(i,j) = a(i,j) + b(i,j);
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
61 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
62 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
63 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
64 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
65
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
66 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
67 compared to the much simpler
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
68
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
69 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
70 c = a + b;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
71 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
72
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
73 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
74 This isn't merely easier to write; it is also internally much easier to
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
75 optimize. Octave delegates this operation to an underlying
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
76 implementation which, among other optimizations, may use special vector
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
77 hardware instructions or could conceivably even perform the additions in
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
78 parallel. In general, if the code is vectorized, the underlying
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
79 implementation has more freedom about the assumptions it can make
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
80 in order to achieve faster execution.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
81
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
82 This is especially important for loops with "cheap" bodies. Often it
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
83 suffices to vectorize just the innermost loop to get acceptable
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
84 performance. A general rule of thumb is that the "order" of the
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
85 vectorized body should be greater or equal to the "order" of the
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
86 enclosing loop.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
87
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
88 As a less trivial example, instead of
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
89
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
90 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
91 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
92 for i = 1:n-1
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
93 a(i) = b(i+1) - b(i);
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
94 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
95 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
96 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
97
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
98 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
99 write
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
100
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
101 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
102 a = b(2:n) - b(1:n-1);
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
103 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
104
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
105 This shows an important general concept about using arrays for indexing
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
106 instead of looping over an index variable. @xref{Index Expressions}.
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
107 Also use boolean indexing generously. If a condition needs to be tested,
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
108 this condition can also be written as a boolean index. For instance,
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
109 instead of
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
110
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
111 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
112 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
113 for i = 1:n
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
114 if a(i) > 5
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
115 a(i) -= 20
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
116 endif
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
117 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
118 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
119 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
120
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
121 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
122 write
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
123
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
124 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
125 a(a>5) -= 20;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
126 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
127
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
128 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
129 which exploits the fact that @code{a > 5} produces a boolean index.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
130
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
131 Use elementwise vector operators whenever possible to avoid looping
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
132 (operators like @code{.*} and @code{.^}). @xref{Arithmetic Ops}. For
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
133 simple inline functions, the @code{vectorize} function can do this
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
134 automatically.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
135
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
136 @DOCSTRING(vectorize)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
137
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
138 Also exploit broadcasting in these elementwise operators both to avoid
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
139 looping and unnecessary intermediate memory allocations.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
140 @xref{Broadcasting}.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
141
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
142 Use built-in and library functions if possible. Built-in and compiled
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
143 functions are very fast. Even with an m-file library function, chances
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
144 are good that it is already optimized, or will be optimized more in a
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
145 future release.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
146
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
147 For instance, even better than
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
148
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
149 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
150 a = b(2:n) - b(1:n-1);
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
151 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
152
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
153 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
154 is
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
155
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
156 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
157 a = diff (b);
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
158 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
159
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
160 Most Octave functions are written with vector and array arguments in
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
161 mind. If you find yourself writing a loop with a very simple operation,
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
162 chances are that such a function already exists. The following functions
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
163 occur frequently in vectorized code:
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
164
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
165 @itemize @bullet
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
166 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
167 Index manipulation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
168
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
169 @itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
170 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
171 find
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
172
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
173 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
174 sub2ind
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
175
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
176 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
177 ind2sub
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
178
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
179 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
180 sort
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
181
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
182 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
183 unique
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
184
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
185 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
186 lookup
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
187
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
188 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
189 ifelse / merge
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
190 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
191
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
192 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
193 Repetition
14853
72b8b39e12be doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
194
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
195 @itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
196 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
197 repmat
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
198
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
199 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
200 repelems
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
201 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
202
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
203 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
204 Vectorized arithmetic
14853
72b8b39e12be doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
205
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
206 @itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
207 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
208 sum
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
209
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
210 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
211 prod
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
212
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
213 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
214 cumsum
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
215
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
216 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
217 cumprod
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
218
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
219 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
220 sumsq
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
221
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
222 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
223 diff
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
224
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
225 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
226 dot
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
227
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
228 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
229 cummax
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
230
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
231 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
232 cummin
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
233 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
234
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
235 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
236 Shape of higher dimensional arrays
14853
72b8b39e12be doc: Periodic grammarcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
237
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
238 @itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
239 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
240 reshape
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
241
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
242 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
243 resize
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
244
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
245 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
246 permute
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
247
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
248 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
249 squeeze
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
250
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
251 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
252 deal
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
253 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
254
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
255 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
256
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
257 @node Broadcasting
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
258 @section Broadcasting
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
259 @cindex broadcast
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
260 @cindex broadcasting
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
261 @cindex BSX
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
262 @cindex recycling
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
263 @cindex SIMD
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
264
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
265 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
266 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
267 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
268 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
269 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
270 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
271 array dimensions must either
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
272
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
273 @enumerate
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
274 @item
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
275 be equal, or
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
276
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
277 @item
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
278 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
279 @end enumerate
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
280
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
281 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
282 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
283 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
284 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
285 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
286 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
287 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
288
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
289 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
290 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
291 x = [1 2 3;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
292 4 5 6;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
293 7 8 9];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
294
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
295 y = [10 20 30];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
296
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
297 x + y
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
298 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
299 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
300
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
301 @noindent
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
302 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
303 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
304 operation were performed:
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
305
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
306 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
307 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
308 x = [1 2 3
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
309 4 5 6
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
310 7 8 9];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
311
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
312 y = [10 20 30
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
313 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
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
316 x + y
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
317 @result{} 11 22 33
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
318 14 25 36
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
319 17 28 39
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
320 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
321 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
322
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
323 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
324 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
325 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
326 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
327 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
328 effect without copying in memory.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
329
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
330 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
331 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
332
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
333 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
334 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
335 y - y'
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
336 @result{} 0 10 20
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
337 -10 0 10
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
338 -20 -10 0
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
339 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
340 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
341
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
342 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
343 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
344 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
345 subtraction takes place.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
346
14123
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
347 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
348 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
349 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
350 (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
351
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
352 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
353 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
354 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
355
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
356 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
357 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
358 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
359
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
360 @noindent
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
361 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
362 @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
363
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
364 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
365 @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
366
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
367 @DOCSTRING(bsxfun)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
368
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
369 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
370 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
371 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
372
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
373 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
374 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
375 x = [1 2 3
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
376 4 5 6];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
377 y = [10 20
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
378 30 40];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
379 x + y
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
380 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
381 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
382
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
383 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
384 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
385
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
386 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
387 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
388 is
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
389
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
390 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
391 plus + .+
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
392 minus - .-
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
393 times .*
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
394 rdivide ./
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
395 ldivide .\
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
396 power .^ .**
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
397 lt <
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
398 le <=
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
399 eq ==
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
400 gt >
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
401 ge >=
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
402 ne != ~=
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
403 and &
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
404 or |
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
405 atan2
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
406 hypot
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
407 max
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
408 min
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
409 mod
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
410 rem
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
411 xor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
412
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
413 += -= .+= .-= .*= ./= .\= .^= .**= &= |=
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
414 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
415
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
416 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
417 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
418
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
419 @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
420 @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
421 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
422
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
423 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
424 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
425 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
426 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
427 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
428 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
429
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
430 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
431 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
432 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
433 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
434 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
435 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
436 or @emph{replication}.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
437
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
438 @subsection Broadcasting and Legacy Code
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
439
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
440 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
441 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
442 @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
443 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
444
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
445 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
446 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
447 try
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
448 c = a.*b;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
449 catch
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
450 c = a.*a;
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
451 end_try_catch
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
452 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
453 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
454
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
455 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
456 that may have relied on matrices of different size producing an error.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
457 Due to how broadcasting changes semantics with older versions of Octave,
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
458 by default Octave warns if a broadcasting operation is performed. To
16772
7eff3032d144 Fix seealso HTML links when using Texinfo 4.X (bug #38862).
Rik <rik@octave.org>
parents: 15685
diff changeset
459 disable this warning, refer to its ID (@pxref{docXwarning_ids}):
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
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
462 warning ("off", "Octave:broadcast");
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
463 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
464
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
465 @noindent
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
466 If you want to recover the old behavior and produce an error, turn this
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
467 warning into an error:
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
468
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
469 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
470 warning ("error", "Octave:broadcast");
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
471 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
472
14123
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
473 @noindent
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
474 For broadcasting on scalars that worked in previous versions of Octave,
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
475 this warning will not be emitted.
2f742be03f90 doc: mention how scalar broadcasting is a special case of broadcasting
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14119
diff changeset
476
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
477 @node Function Application
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
478 @section Function Application
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
479 @cindex map
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
480 @cindex apply
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
481 @cindex function application
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
482
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
483 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
484 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
485 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
486 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
487 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
488 array, cell, or struct.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
489
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
490 @DOCSTRING(arrayfun)
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
491
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
492 @DOCSTRING(spfun)
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
493
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
494 @DOCSTRING(cellfun)
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
495
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
496 @DOCSTRING(structfun)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
497
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
498 @node Accumulation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
499 @section Accumulation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
500
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
501 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
502 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
503 useful.
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 @DOCSTRING(accumarray)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
506
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
507 @DOCSTRING(accumdim)
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 @node Miscellaneous Techniques
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
510 @section Miscellaneous Techniques
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
511 @cindex execution speed
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
512 @cindex speedups
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
513 @cindex optimization
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
514
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
515 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
516 programs.
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
517
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
518 @itemize @bullet
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
519
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
520 @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
521 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
522 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
523 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
524 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
525
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
526 @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
527 @cindex copy-on-write
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
528 @cindex COW
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
529 @cindex memory management
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
530 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
531 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
532 be modified. For example:
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
533
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
534 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
535 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
536 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
537 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
538 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
539 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
540 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
541
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
542 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
543 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
544 elements).
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
545
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
546 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
547 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
548
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
549 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
550 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
551 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
552 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
553 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
554 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
555 @end example
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 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
558 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
559 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
560 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
561 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
562
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
563 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
564 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
565 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
566 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
567 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
568 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
569 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
570
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
571 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
572 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
573 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
574 b = a(:,10:100); # lazy slice
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
575 a = []; # the original a array is still allocated
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
576 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
577 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
578 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
579
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
580 @item Avoid deep recursion.
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
581 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
582 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
583 of recursion is limited.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
584
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
585 @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
586 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
587 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
588
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
589 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
590 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
591 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
592 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
593 ridx = @dots{}
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
594 cidx = @dots{}
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
595 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
596 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
597 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
598 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
599
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
600 @noindent
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
601 instead of
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
602
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
603 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
604 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
605 result = [];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
606 for i = ever:and_ever
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
607 result = [ result, new_value() ];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
608 endfor
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
609 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
610 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
611
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
612 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
613 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
614 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
615 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
616 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
617 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
618
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
619 @example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
620 @group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
621 a = [];
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
622 while (condition)
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
623 @dots{}
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
624 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
625 @dots{}
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
626 a(end) = []; # "pop" operation
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
627 @dots{}
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
628 endwhile
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
629 @end group
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
630 @end example
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
631
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
632 @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
633 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
634 relatively expensive operations.
14116
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
635
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
636 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
637 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
638 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
639
14119
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
640 @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
641 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
642 during your run, set the variable @code{ignore_function_time_stamp} to
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
643 @code{"all"}. This will stop Octave from checking the time stamp of a function
94e2a76f1e5a doc: Final grammarcheck and spellcheck before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 14118
diff changeset
644 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
645 @end itemize
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
646
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
647 @node Examples
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
648 @section Examples
951eacaf9381 Initial documentation for broadcasting and general vectorization guidelines
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
649
14118
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
650 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
651 users of Octave and their solutions.
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
652
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
653 @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
654
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
655 @itemize @bullet
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
656 @item
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
657 For a vector @code{A}, the following loop
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
658
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
659 @example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
660 @group
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
661 n = length (A);
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
662 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
663 for i = 1:length (A)
14118
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
664 ## 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
665 ## the second the mean of the two elements used for the diff.
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
666 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
667 endfor
14118
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
668 @end group
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
669 @end example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
670
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
671 @noindent
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
672 can be turned into the following one-liner:
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
673
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
674 @example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
675 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
676 @end example
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
677
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
678 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
679 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
680
ebe2e6b2ba52 Start adding vectorization examples
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14116
diff changeset
681 @end itemize