doc/tutorial/broadcasting.txt contains the information about broadcasting and…

doc/tutorial/broadcasting.txt

@@ -10,57 +10,65 @@ 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.
+Broadcasting is the mechanism by which a scalar
+may be added to a matrix, a vector to a matrix or a scalar to
+a vector.
 
-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).
+.. figure:: bcast.png
 
-The length of ``broadcastable`` is the number of dimensions of the ``Tensor``.
+Broadcasting a row matrix. T and F respectively stand for
+True and False and indicate along which dimensions we allow
+broadcasting.
 
-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.
+If the second argument were a vector, its shape would be
+``(2,)`` and its broadcastable pattern ``(False,)``. They would
+be automatically expanded to the **left** to match the
+dimensions of the matrix (adding ``1`` to the shape and ``True``
+to the pattern), resulting in ``(1, 2)`` and ``(True, False)``.
+It would then behave just like the example above.
 
-.. 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.
+Unlike numpy which does broadcasting dynamically, Theano needs
+to know, for any operation which supports broadcasting, which
+dimensions will need to be broadcasted. When applicable, this
+information is given in the :ref:`type` of a *Variable*.
 
 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
+>>> r = T.row()
+>>> r.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
+>>> f_row = theano.function([r, mtr], [r + 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)
+>>> f_row(R, M)
 [array([[  0.,   2.,   4.],
        [  3.,   5.,   7.],
-       [  6.,   8.,  10.]]), array([[  0.,   1.,   2.],
+       [  6.,   8.,  10.]])]
+>>> c = T.col()
+>>> c.broadcastable
+(False, True)
+>>> f_col = theano.function([c, mtr], [c + mtr])
+>>> C = np.arange(3).reshape(3, 1)
+>>> C
+array([[0],
+       [1],
+       [2]])
+>>> M = np.arange(9).reshape(3, 3)
+>>> f_col(C, M)
+[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.
+In these examples, 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: