doc/tutorial/broadcasting.txt has been added to the tutorial folder and contains…

doc/tutorial/broadcasting.txt

+.. _tutbroadcasting:
+
+
+============
+Broadcasting
+============
+
+Broadcasting is a mechanism which allows tensors with
+different numbers of dimensions to be added or multiplied
+together by (virtually) replicating the smaller tensor along
+the dimensions that it is lacking.
+
+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.
+ * The ``Tensor`` cannot be replicated along it (regardless of whether it is 1 or not).
+
+The length of ``broadcastable`` is the number of dimensions of the ``Tensor``.
+
+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.
+
+.. figure:: bcast.png
+
+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 following code illustrates how rows and columns are broadcasted in order to perform an addition operation with a matrix:
+
+>>> import numpy as np
+>>> import theano
+>>> import theano.tensor as T
+>>> rowvec = T.row()
+>>> rowvec.broadcastable
+(True, False)
+>>> colvec = rowvec.dimshuffle(1,0)
+>>> colvec.broadcastable
+(False, True)
+>>> mtr = T.matrix()
+>>> mtr.broadcastable
+(False, False)
+>>> f = theano.function([rowvec, mtr], [rowvec + mtr, colvec + mtr])
+>>> r = np.arange(3).reshape(1, 3)
+>>> r
+array([[0, 1, 2]])
+>>> M = np.arange(9).reshape(3, 3)
+>>> M
+array([[0, 1, 2],
+       [3, 4, 5],
+       [6, 7, 8]])
+>>> f(r, M)
+[array([[  0.,   2.,   4.],
+       [  3.,   5.,   7.],
+       [  6.,   8.,  10.]]), array([[  0.,   1.,   2.],
+       [  4.,   5.,   6.],
+       [  8.,   9.,  10.]])]
+
+In this example, we can see that both the row vector and the column vector are broadcasted in order to be be added to the matrix.
+
+See also:
+
+* `SciPy documentation about numpy's broadcasting <http://www.scipy.org/EricsBroadcastingDoc>`_
+
+* `OnLamp article about numpy's broadcasting <http://www.onlamp.com/pub/a/python/2000/09/27/numerically.html>`_
+