More details about the 'f' option for Dimshuffle

doc/library/tensor/basic.txt

@@ -450,6 +450,13 @@ TensorVariable
         Returns a view of this tensor with permuted dimensions.  Typically the
         pattern will include the integers 0, 1, ... ndim-1, and any number of
         'x' characters in dimensions where this tensor should be broadcasted.
+        Beside 'x' you can also use 'f' for dimension of length 1 which (from
+        the point of view of Theano) are not broadcastable. Note that for
+        Numpy, a dimension of length 1 is implicitly broadcastable, therefore 
+        the same will be true for dimension marked with 'f' of the value of
+        the symbolic variable. Nonetheless, when you try to compile/write your
+        symbolic expression that tries to broadcast the dimension marked with
+        'f', Theano will catch it and will trow on exception.
 
         See :func:`dimshuffle`.
 

theano/tensor/basic.py

@@ -904,15 +904,18 @@ class _tensor_py_operators:
     def dimshuffle(self, *pattern):
         """Reorder the dimensions of this variable, optionally inserting broadcasted dimensions.
 
-        :param pattern: list/tuple of int mixed with 'x' for broadcastable dimensions
+        :param pattern: list/tuple of int mixed with 'x' for broadcastable dimensions and 'f' for 
+        non-broadcastable dimensions
 
         For example, to create a 3D view of a [2D] matrix, call ``dimshuffle([0,'x',1])``.  This
         will create a 3D view such that the middle dimension is an implicit broadcasted
         dimension.  To do the same thing on the transpose of that matrix, call ``dimshuffle([1,
-        'x', 0])``.
+        'x', 0])``. 'f' behaves exactly like 'x' (i.e. adds a 1-length dimension at that position) 
+        just that from the viewpoint of Theano this dimension is not broadcastable.
 
         This function supports the pattern passed as a tuple, or as a variable-length argument (e.g. ``a.dimshuffle(pattern)`` is equivalent to ``a.dimshuffle(*pattern)`` where ``pattern`` is a list/tuple of ints mixed with 'x' characters).
 
+
         For more information, see `DimShuffle`.
         """
         if (len(pattern) == 1) and (isinstance(pattern[0], (list, tuple))):

theano/tensor/elemwise.py

@@ -43,9 +43,16 @@ class DimShuffle(Op):
     dimension and a numerical index represents the dimension of the same
     rank in the tensor passed to perform.
 
-    Note 2.04.2010 RP Added 'f' - means that we insert a non-broadcastable
-    dimension; 'f' behaves exactly like 'x', just that the new dimension is
-    not broadcastable
+    Note (2.04.2010 RP) Added 'f' - means that we insert a non-broadcastable
+    dimension; 'f'. This is useful because Theano in some cases is strongly
+    typed, and will not allow you to replace (in an optimization for example),
+    identical tensors, where the broadcastable patterns differ. Note that numpy
+    does not offer this option (from what I have researched), a dimension of 1
+    means automatically that it is broadcastable. This will be true for the 
+    value of the Theano variable as well on the fixed dimension (the one with 'f').
+    However, when you express your computation symbolically Theano should catch 
+    the fact that you will try to broadcast an unbroadcastable dimension and will
+    not allow you (throw an exception ..).
 
     Examples:
       DimShuffle((False, False, False), ['x', 2, 'x', 0, 1])
@@ -95,6 +102,9 @@ class DimShuffle(Op):
         If new_order[i] is 'x', the output's ith dimension will
           be 1 and Broadcast operations will be allowed to do broadcasting
           over that dimension.
+        if new_order[i] is 'f' the outputs's ith dimension will 
+          be 1 and Broadcast operations will not be allowed to do broadcasting
+          over that dimension.
 
         If input.broadcastable[i] == False then i must be found in new_order.
         Broadcastable dimensions, on the other hand, can be discarded.