/usr/share/doc/octave/octave.html/Broadcasting.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Broadcasting (GNU Octave)</title>

<meta name="description" content="Broadcasting (GNU Octave)">
<meta name="keywords" content="Broadcasting (GNU Octave)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Vectorization-and-Faster-Code-Execution.html#Vectorization-and-Faster-Code-Execution" rel="up" title="Vectorization and Faster Code Execution">
<link href="Function-Application.html#Function-Application" rel="next" title="Function Application">
<link href="Basic-Vectorization.html#Basic-Vectorization" rel="prev" title="Basic Vectorization">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">


</head>

<body lang="en">
<a name="Broadcasting"></a>
<div class="header">
<p>
Next: <a href="Function-Application.html#Function-Application" accesskey="n" rel="next">Function Application</a>, Previous: <a href="Basic-Vectorization.html#Basic-Vectorization" accesskey="p" rel="prev">Basic Vectorization</a>, Up: <a href="Vectorization-and-Faster-Code-Execution.html#Vectorization-and-Faster-Code-Execution" accesskey="u" rel="up">Vectorization and Faster Code Execution</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Broadcasting-1"></a>
<h3 class="section">19.2 Broadcasting</h3>
<a name="index-broadcast"></a>
<a name="index-broadcasting"></a>
<a name="index-BSX"></a>
<a name="index-recycling"></a>
<a name="index-SIMD"></a>

<p>Broadcasting refers to how Octave binary operators and functions behave
when their matrix or array operands or arguments differ in size.  Since
version 3.6.0, Octave now automatically broadcasts vectors, matrices,
and arrays when using elementwise binary operators and functions.
Broadly speaking, smaller arrays are &ldquo;broadcast&rdquo; across the larger
one, until they have a compatible shape.  The rule is that corresponding
array dimensions must either
</p>
<ol>
<li> be equal, or

</li><li> one of them must be 1.
</li></ol>

<p>In case all dimensions are equal, no broadcasting occurs and ordinary
element-by-element arithmetic takes place.  For arrays of higher
dimensions, if the number of dimensions isn&rsquo;t the same, then missing
trailing dimensions are treated as 1.  When one of the dimensions is 1,
the array with that singleton dimension gets copied along that dimension
until it matches the dimension of the other array.  For example, consider
</p>
<div class="example">
<pre class="example">x = [1 2 3;
     4 5 6;
     7 8 9];

y = [10 20 30];

x + y
</pre></div>

<p>Without broadcasting, <code>x + y</code> would be an error because the dimensions
do not agree.  However, with broadcasting it is as if the following
operation were performed:
</p>
<div class="example">
<pre class="example">x = [1 2 3
     4 5 6
     7 8 9];

y = [10 20 30
     10 20 30
     10 20 30];

x + y
&rArr;    11   22   33
      14   25   36
      17   28   39
</pre></div>

<p>That is, the smaller array of size <code>[1 3]</code> gets copied along the
singleton dimension (the number of rows) until it is <code>[3 3]</code>.  No
actual copying takes place, however.  The internal implementation reuses
elements along the necessary dimension in order to achieve the desired
effect without copying in memory.
</p>
<p>Both arrays can be broadcast across each other, for example, all
pairwise differences of the elements of a vector with itself:
</p>
<div class="example">
<pre class="example">y - y'
&rArr;    0   10   20
    -10    0   10
    -20  -10    0
</pre></div>

<p>Here the vectors of size <code>[1 3]</code> and <code>[3 1]</code> both get
broadcast into matrices of size <code>[3 3]</code> before ordinary matrix
subtraction takes place.
</p>
<p>A special case of broadcasting that may be familiar is when all
dimensions of the array being broadcast are 1, i.e., the array is a
scalar.  Thus for example, operations like <code>x - 42</code> and <code>max
(x, 2)</code> are basic examples of broadcasting.
</p>
<p>For a higher-dimensional example, suppose <code>img</code> is an RGB image of
size <code>[m n 3]</code> and we wish to multiply each color by a different
scalar.  The following code accomplishes this with broadcasting,
</p>
<div class="example">
<pre class="example">img .*= permute ([0.8, 0.9, 1.2], [1, 3, 2]);
</pre></div>

<p>Note the usage of permute to match the dimensions of the
<code>[0.8, 0.9, 1.2]</code> vector with <code>img</code>.
</p>
<p>For functions that are not written with broadcasting semantics,
<code>bsxfun</code> can be useful for coercing them to broadcast.
</p>
<a name="XREFbsxfun"></a><dl>
<dt><a name="index-bsxfun"></a>: <em></em> <strong>bsxfun</strong> <em>(<var>f</var>, <var>A</var>, <var>B</var>)</em></dt>
<dd><p>The binary singleton expansion function performs broadcasting,
that is, it applies a binary function <var>f</var> element-by-element to two
array arguments <var>A</var> and <var>B</var>, and expands as necessary
singleton dimensions in either input argument.
</p>
<p><var>f</var> is a function handle, inline function, or string containing the name
of the function to evaluate.  The function <var>f</var> must be capable of
accepting two column-vector arguments of equal length, or one column vector
argument and a scalar.
</p>
<p>The dimensions of <var>A</var> and <var>B</var> must be equal or singleton.  The
singleton dimensions of the arrays will be expanded to the same
dimensionality as the other array.
</p>
<p><strong>See also:</strong> <a href="Function-Application.html#XREFarrayfun">arrayfun</a>, <a href="Function-Application.html#XREFcellfun">cellfun</a>.
</p></dd></dl>


<p>Broadcasting is only applied if either of the two broadcasting
conditions hold.  As usual, however, broadcasting does not apply when two
dimensions differ and neither is 1:
</p>
<div class="example">
<pre class="example">x = [1 2 3
     4 5 6];
y = [10 20
     30 40];
x + y
</pre></div>

<p>This will produce an error about nonconformant arguments.
</p>
<p>Besides common arithmetic operations, several functions of two arguments
also broadcast.  The full list of functions and operators that broadcast
is
</p>
<div class="example">
<pre class="example">      plus      +  .+
      minus     -  .-
      times     .*
      rdivide   ./
      ldivide   .\
      power     .^  .**
      lt        &lt;
      le        &lt;=
      eq        ==
      gt        &gt;
      ge        &gt;=
      ne        !=  ~=
      and       &amp;
      or        |
      atan2
      hypot
      max
      min
      mod
      rem
      xor

      +=  -=  .+=  .-=  .*=  ./=  .\=  .^=  .**=  &amp;=  |=
</pre></div>

<p>Beware of resorting to broadcasting if a simpler operation will suffice.
For matrices <var>a</var> and <var>b</var>, consider the following:
</p>
<div class="example">
<pre class="example"><var>c</var> = sum (permute (<var>a</var>, [1, 3, 2]) .* permute (<var>b</var>, [3, 2, 1]), 3);
</pre></div>

<p>This operation broadcasts the two matrices with permuted dimensions
across each other during elementwise multiplication in order to obtain a
larger 3-D array, and this array is then summed along the third dimension.
A moment of thought will prove that this operation is simply the much
faster ordinary matrix multiplication, <code><var>c</var> = <var>a</var>*<var>b</var>;</code>.
</p>
<p>A note on terminology: &ldquo;broadcasting&rdquo; is the term popularized by the
Numpy numerical environment in the Python programming language.  In other
programming languages and environments, broadcasting may also be known
as <em>binary singleton expansion</em> (BSX, in <small>MATLAB</small>, and the
origin of the name of the <code>bsxfun</code> function), <em>recycling</em> (R
programming language), <em>single-instruction multiple data</em> (SIMD),
or <em>replication</em>.
</p>
<a name="Broadcasting-and-Legacy-Code"></a>
<h4 class="subsection">19.2.1 Broadcasting and Legacy Code</h4>

<p>The new broadcasting semantics almost never affect code that worked
in previous versions of Octave.  Consequently, all code inherited from
<small>MATLAB</small> that worked in previous versions of Octave should still work
without change in Octave.  The only exception is code such as
</p>
<div class="example">
<pre class="example">try
  c = a.*b;
catch
  c = a.*a;
end_try_catch
</pre></div>

<p>that may have relied on matrices of different size producing an error.
Because such operation is now valid Octave syntax, this will no longer
produce an error.  Instead, the following code should be used:
</p>
<div class="example">
<pre class="example">if (isequal (size (a), size (b)))
  c = a .* b;
else
  c = a .* a;
endif
</pre></div>


<hr>
<div class="header">
<p>
Next: <a href="Function-Application.html#Function-Application" accesskey="n" rel="next">Function Application</a>, Previous: <a href="Basic-Vectorization.html#Basic-Vectorization" accesskey="p" rel="prev">Basic Vectorization</a>, Up: <a href="Vectorization-and-Faster-Code-Execution.html#Vectorization-and-Faster-Code-Execution" accesskey="u" rel="up">Vectorization and Faster Code Execution</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
octave-doc 4.2.2-1ubuntu1 / usr / share / doc / octave / octave.html / Broadcasting.html
