numpydoc for theano/tensor/elemwise.py

theano/tensor/elemwise.py

@@ -62,7 +62,30 @@ class DimShuffle(Op):
     dimension and a numerical index represents the dimension of the same
     rank in the tensor passed to perform.
 
-    Examples:
+    Parameters
+    ----------
+    input_broadcastable
+        The expected broadcastable pattern of the input
+    new_order
+        A list representing the relationship between the input's
+        dimensions and the output's dimensions. Each element of the
+        list can either be an index or 'x'. Indices must be encoded
+        as python integers, not theano symbolic integers.
+    inplace : bool, optional
+        If True, the output will be a view of the input.
+        If False (default), the output will be a copy of the input.
+
+    If j = new_order[i] is an index, the output's ith dimension
+    will be the input's jth dimension.
+    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 input.broadcastable[i] == False then i must be found in new_order.
+    Broadcastable dimensions, on the other hand, can be discarded.
+
+    Examples
+    --------
     DimShuffle((False, False, False), ['x', 2, 'x', 0, 1])
 
     This op will only work on 3d tensors with no broadcastable
@@ -81,7 +104,7 @@ class DimShuffle(Op):
     If the tensor has shape (1, 20), the resulting tensor will have shape
     (20, ).
 
-    More examples:
+    More examples :
     DimShuffle((), ['x']) -> make a 0d (scalar) into a 1d vector
     DimShuffle((False, False), [0, 1]) -> identity
     DimShuffle((False, False), [1, 0]) -> inverts the 1st and 2nd dimensions
@@ -96,33 +119,13 @@ class DimShuffle(Op):
     The reordering of the dimensions can be done in numpy with the
     transpose function.
     Adding, subtracting dimensions can be done with reshape.
+
     """
+
     _f16_ok = True
     check_input = False
 
     def __init__(self, input_broadcastable, new_order, inplace=False):
-        """
-        Usage: DimShuffle(input_broadcastable, new_order, inplace = False)
-
-        - input_broadcastable: the expected broadcastable pattern of the
-                               input
-        - new_order: a list representing the relationship between the
-                     input's dimensions and the output's dimensions. Each
-                     element of the list can either be an index or 'x'.
-                     Indices must be encoded as python integers, not
-                     theano symbolic integers.
-        - inplace: if True, the output will be a view of the input.
-                   If False, the output will be a copy of the input.
-
-        If j = new_order[i] is an index, the output's ith dimension
-          will be the input's jth dimension.
-        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 input.broadcastable[i] == False then i must be found in new_order.
-        Broadcastable dimensions, on the other hand, can be discarded.
-        """
         input_broadcastable = tuple(input_broadcastable)
         self.input_broadcastable = input_broadcastable
         new_order = tuple(new_order)
@@ -456,7 +459,26 @@ class Elemwise(OpenMPOp):
     be the same as the corresponding input type (see the doc of
     scalar.ScalarOp to get help about controlling the output type)
 
-    Examples:
+    Parameteres
+    -----------
+    scalar_op
+        An instance of a subclass of scalar.ScalarOp which works uniquely
+        on scalars.
+    inplace_pattern
+        A dictionary that maps the index of an output to the
+        index of an input so the output is calculated inplace using
+        the input's storage. (Just like destroymap, but without the lists.)
+    nfunc_spec
+        Either None or a tuple of three elements,
+        (nfunc_name, nin, nout) such that getattr(numpy, nfunc_name)
+        implements this operation, takes nin inputs and nout outputs.
+        Note that nin cannot always be inferred from the scalar op's
+        own nin field because that value is sometimes 0 (meaning a
+        variable number of inputs), whereas the numpy function may
+        not have varargs.
+
+    Examples
+    --------
     Elemwise(add) # represents + on tensors (x + y)
     Elemwise(add, {0 : 0}) # represents the += operation (x += y)
     Elemwise(add, {0 : 1}) # represents += on the second argument (y += x)
@@ -466,26 +488,11 @@ class Elemwise(OpenMPOp):
     # second dimension
     Elemwise(int_div)(rand(1, 5), rand(10, 1)) # the output has size (10, 5)
     Elemwise(log)(rand(3, 4, 5))
+
     """
 
     def __init__(self, scalar_op, inplace_pattern=None, name=None,
                  nfunc_spec=None, openmp=None):
-        """
-        Usage: Elemwise(scalar_op, inplace_pattern = {})
-
-        * scalar_op: an instance of a subclass of scalar.ScalarOp which works
-            uniquely on scalars
-        * inplace_pattern: a dictionary that maps the index of an output to the
-            index of an input so the output is calculated inplace using
-            the input's storage. (Just like destroymap, but without the lists.)
-        * nfunc_spec: either None or a tuple of three elements,
-            (nfunc_name, nin, nout) such that getattr(numpy, nfunc_name)
-            implements this operation, takes nin inputs and nout outputs.
-            Note that nin cannot always be inferred from the scalar op's
-            own nin field because that value is sometimes 0 (meaning a
-            variable number of inputs), whereas the numpy function may
-            not have varargs.
-        """
         if inplace_pattern is None:
             inplace_pattern = {}
         self.name = name
@@ -1252,7 +1259,18 @@ class CAReduce(Op):
     dimensions. It will contain the variable of accumulating all values
     over the reduced dimensions using the specified scalar op.
 
-    Examples:
+    Parameters
+    ----------
+    scalar_op
+        A binary scalar op with only one output.
+        It must be commutative and associative.
+    axis
+        - The dimension along which we want to reduce
+        - List of dimensions that we want to reduce
+        - If None, all dimensions are reduced
+
+    Examples
+    --------
     CAReduce(add) -> sum (ie, acts like the numpy sum operation)
     CAReduce(mul) -> product
     CAReduce(maximum) -> max
@@ -1270,18 +1288,10 @@ class CAReduce(Op):
     operation represented by the reduction must be both commutative
     and associative (eg add, multiply, maximum, binary or/and/xor - but not
     subtract, divide or power).
-    """
 
-    def __init__(self, scalar_op, axis=None):
     """
-        Usage: CAReduce(scalar_op, axis = None)
 
-        * scalar_op: a binary scalar op with only one output.
-                     It must be commutative and associative.
-        * axis: - the dimension along which we want to reduce
-                - list of dimensions that we want to reduce
-                - if None, all dimensions are reduced
-        """
+    def __init__(self, scalar_op, axis=None):
         if scalar_op.nin not in [-1, 2] or scalar_op.nout != 1:
             raise NotImplementedError((
                 "CAReduce only supports binary functions with a single "
@@ -1656,8 +1666,10 @@ class All(CAReduce):
     """ Applies `bitwise and` to all the values of a tensor along the
     specified axis(es).
 
-    Equivalent to CAReduce(scalar.and_, axis=axis)
+    Equivalent to CAReduce(scalar.and_, axis=axis).
+
     """
+
     def __init__(self, axis=None):
         CAReduce.__init__(self, scalar.and_, axis)
 
@@ -1686,8 +1698,10 @@ class Any(CAReduce):
     """ Applies `bitwise or` to all the values of a tensor along the
     specified axis(es).
 
-    Equivalent to CAReduce(scalar.or_, axis=axis)
+    Equivalent to CAReduce(scalar.or_, axis=axis).
+
     """
+
     def __init__(self, axis=None):
         CAReduce.__init__(self, scalar.or_, axis)
 
@@ -1727,22 +1741,21 @@ class CAReduceDtype(CAReduce):
 
     If no dtype is provided, one will be inferred so as not to lose
     too much precision.
-    """
 
-    def __init__(self, scalar_op, axis=None, dtype=None, acc_dtype=None):
-        """
-        Usage: CAReduceDtype(scalar_op, axis=None, dtype=None, acc_dtype=None)
-
-        :param scalar_op: a binary scalar op with only one output.
+    Parameters
+    ----------
+    scalar_op
+        A binary scalar op with only one output.
         It must be commutative and associative.
 
-        :param axis: - the dimension along which we want to reduce
+    axis
+        - the dimension along which we want to reduce
         - list of dimensions that we want to reduce
         - if None, all dimensions are reduced
 
-        :param dtype: The dtype of the returned
-            tensor. If None, then we use the default dtype which is the same
-            as the input tensor's dtype except when:
+    dtype
+        The dtype of the returned tensor. If None, then we use the default
+        dtype which is the same as the input tensor's dtype except when:
         - the input dtype is a signed integer of precision < 64 bit, in
         which case we use int64
         - the input dtype is an unsigned integer of precision < 64 bit, in
@@ -1752,7 +1765,8 @@ class CAReduceDtype(CAReduce):
         uses the default machine integer while we always use 64 bit
         integers to avoid platform-dependent behavior).
 
-        :param acc_dtype: The dtype of the internal accumulator.
+    acc_dtype
+        The dtype of the internal accumulator.
         If None (default), we use the dtype in the list below,
         or the input dtype if its precision is higher:
         - for int dtypes, we use at least int64;
@@ -1761,6 +1775,8 @@ class CAReduceDtype(CAReduce):
         - for complex dtypes, we use at least complex128.
 
     """
+
+    def __init__(self, scalar_op, axis=None, dtype=None, acc_dtype=None):
         CAReduce.__init__(self, scalar_op, axis=axis)
         self.dtype = dtype
         self.acc_dtype = acc_dtype
@@ -1888,17 +1904,16 @@ class Sum(CAReduceDtype):
     Equivalent to CAReduceDtype(scalar.add, axis=axis, dtype=dtype),
     with the difference that this defines the gradient of sum wrt its
     tensor input.
-    """
-
-    def __init__(self, axis=None, dtype=None, acc_dtype=None):
-        """
-        Constructor.
 
-        :param axis: Axis(es) along which the tensor should be summed
+    Parameters
+    ----------
+    axis
+        Axis(es) along which the tensor should be summed
         (use None to sum over all axes, and a list or tuple to sum along more
         than one axis).
 
-        :param dtype: The dtype of the internal accumulator and returned
+    dtype
+        The dtype of the internal accumulator and returned
         tensor. If None, then we use the default dtype which is the same as the
         input tensor's dtype except when:
         - the input dtype is a signed integer of precision < 64 bit, in
@@ -1907,14 +1922,18 @@ class Sum(CAReduceDtype):
         which case we use uint64
         This value does not depend on the value of "acc_dtype".
 
-        :param acc_dtype: The dtype of the internal accumulator.
+    acc_dtype
+        The dtype of the internal accumulator.
         If None (default), we use the dtype in the list below,
         or the input dtype if its precision is higher:
         - for int dtypes, we use at least int64;
         - for uint dtypes, we use at least uint64;
         - for float dtypes, we use at least float64;
         - for complex dtypes, we use at least complex128.
+
     """
+
+    def __init__(self, axis=None, dtype=None, acc_dtype=None):
         CAReduceDtype.__init__(self, scalar.add, axis=axis,
                                dtype=dtype, acc_dtype=acc_dtype)
 
@@ -1960,7 +1979,9 @@ class Prod(CAReduceDtype):
     Equivalent to CAReduce(scalar.prod, axis = axis), with the
     difference that this defines the gradient of prod wrt its tensor
     input.
+
     """
+
     def __init__(self, axis=None, dtype=None, acc_dtype=None,
                  no_zeros_in_input=False):
         CAReduceDtype.__init__(self, scalar.mul, axis=axis,
@@ -1982,7 +2003,7 @@ class Prod(CAReduceDtype):
                 hash(self.no_zeros_in_input))
 
     def grad(self, inp, grads):
-        '''
+        """
         The grad of this Op could be very easy, if it is was not for the case
         where zeros are present in a given "group" (ie. elements reduced
         together to form the product).
@@ -2026,7 +2047,8 @@ class Prod(CAReduceDtype):
         I do this by first counting the number of zeros in each group (see
         the "T.eq()" bits), then taking this or that behavior (see T.switch)
         based on the result of this count.
-        '''
+
+        """
         prod_in, = inp
         gz, = grads