.. _sandbox_broadcasting:

============
Broadcasting
============

The following may go either in:
a) numpy refresher.
b) more details of broadcasting in the types section.



=== broadcastable ===

The {{{broadcastable}}} field of a {{{Tensor}}} must be a tuple of boolean values. Each value corresponds to a dimension of the {{{Tensor}}} and specifies whether the {{{Tensor}}} can be "broadcasted" along that dimension.

A value of {{{True}}} means two things:
  * The size of the corresponding dimension will necessarily be 1.
  * If needed, the {{{Tensor}}} can be ''broadcasted'' or ''replicated'' along the corresponding dimension to emulate a larger {{{Tensor}}}.

A value of {{{False}}} means that the corresponding dimension can take any nonnegative value and that the {{{Tensor}}} cannot be replicated along it (regardless of whether it is 1 or not).

Example: to define a ''row'' type, set broadcastable to {{{(True, False)}}}: this means the shape must be like {{{(1, n)}}}. If you add a row of shape {{{(1, n)}}} to a matrix of shape {{{(m, n)}}}, the row will be "broadcasted" or "replicated" {{{m}}} times along the first dimension, producing a virtual matrix of the correct size {{{(m, n)}}}. Therefore, adding a row to a matrix will add the row to each row of the matrix. If the value of {{{broadcastable}}} for the first dimension of the row was {{{False}}}, the operation would instead raise an exception complaining that the dimensions are not the same.

Similarly, the broadcastable pattern for a column is {{{(False, True)}}}: this means the shape must be like {{{(m, 1)}}}, therefore adding a column to a matrix will add that column to each column of the matrix. Several Ops, such as {{{DimShuffle}}}, can add or remove broadcastable dimensions.

The length of {{{broadcastable}}} is the number of dimensions of the {{{Tensor}}}.


