Merge pull request Theano#3872 from SinaHonari/issue3681

deconvolution interface

theano/tensor/nnet/abstract_conv.py

@@ -118,6 +118,195 @@ def conv2d(input,
     return conv_op(input, filters)
 
 
+def conv2d_grad_wrt_inputs(output_grad,
+                           filters,
+                           output_grad_shape=None,
+                           input_shape=None,
+                           filter_shape=None,
+                           border_mode='valid',
+                           subsample=(1, 1),
+                           filter_flip=True):
+    """This function builds the symbolic graph for getting the
+    gradient of the output of a convolution (namely output_grad)
+    w.r.t the input of the convolution, given a set of 2D filters
+    used by the convolution, such that the output_grad is upsampled
+    to the input shape.
+
+    :type output_grad: symbolic 4D tensor.
+    :param output_grad: mini-batch of feature map stacks, of shape
+        (batch size, input channels, input rows, input columns).
+        This is the tensor that will be upsampled or the output
+        gradient of the convolution whose gradient will be taken
+        with respect to the input of the convolution.
+        See the optional parameter ``output_grad_shape``.
+
+    :type filters: symbolic 4D tensor.
+    :param filters: set of filters used in CNN layer of shape
+        (output channels, input channels, filter rows, filter columns).
+        See the optional parameter ``filter_shape``.
+
+    :type output_grad_shape: None, tuple/list of len 4 of int or
+        Constant variable.
+    :param output_grad_shape: The shape of the output_grad parameter.
+        Optional, possibly used to choose an optimal implementation.
+        You can give ``None`` for any element of the list to specify that this
+        element is not known at compile time.
+
+    :type input_shape: tuple/list of len 2 of int or Constant variable.
+    :param input_shape: The shape (row and column size) of the
+        input (upsampled) parameter.
+        Not Optional, since given the output_grad_shape and the subsample values,
+        multiple input_shape may be plausible.
+
+    :type filter_shape: None, tuple/list of len 4 of int or Constant variable
+    :param filter_shape: The shape of the filters parameter.
+        Optional, possibly used to choose an optimal implementation.
+        You can give ``None`` for any element of the list to specify that this
+        element is not known at compile time.
+
+    :type border_mode: str, int or tuple of two int
+    :param border_mode: Either of the following:
+        * ``'valid'``: apply filter wherever it completely overlaps with the
+          input. Generates output of shape: input shape - filter shape + 1
+        * ``'full'``: apply filter wherever it partly overlaps with the input.
+          Generates output of shape: input shape + filter shape - 1
+        * ``'half'``: pad input with a symmetric border of ``filter rows // 2``
+          rows and ``filter columns // 2`` columns, then perform a valid
+          convolution. For filters with an odd number of rows and columns, this
+          leads to the output shape being equal to the input shape.
+        * ``int``: pad input with a symmetric border of zeros of the given
+          width, then perform a valid convolution.
+        * ``(int1, int2)``: pad input with a symmetric border of ``int1`` rows
+          and ``int2`` columns, then perform a valid convolution.
+
+    :type subsample: tuple of len 2, the subsampling used in the forward pass
+        of the convolutional operation.
+    :param subsample: factor by which to subsample the output.
+        Also called strides elsewhere.
+
+    :type filter_flip: bool
+    :param filter_flip: If ``True``, will flip the filter rows and columns
+        before sliding them over the input. This operation is normally referred
+        to as a convolution, and this is the default. If ``False``, the filters
+        are not flipped and the operation is referred to as a
+        cross-correlation.
+
+    :rtype: symbolic 4D tensor.
+    :return: set of feature maps generated by convolutional layer. Tensor is
+        of shape (batch size, output channels, output rows, output columns)
+
+    :note: If CuDNN is available, it will be used on the
+        GPU. Otherwise, it is the *CorrMM* convolution that will be used
+        "caffe style convolution".
+
+    :note: This is only supported in Theano 0.8 or the development
+        version until it is released.
+
+    """
+
+    grad_input_op = AbstractConv2d_gradInputs(imshp=input_shape,
+                                              kshp=filter_shape,
+                                              border_mode=border_mode,
+                                              subsample=subsample,
+                                              filter_flip=filter_flip)
+
+    return grad_input_op(filters, input, output_grad_shape)
+
+
+def conv2d_grad_wrt_weights(input,
+                            output_grad,
+                            input_shape=None,
+                            output_grad_shape=None,
+                            filter_shape=None,
+                            border_mode='valid',
+                            subsample=(1, 1),
+                            filter_flip=True):
+    """This function will build the symbolic graph for getting the
+    gradient of the output of a convolution (output_grad) w.r.t its wights.
+
+    :type input: symbolic 4D tensor.
+    :param input: mini-batch of feature map stacks, of shape
+        (batch size, input channels, input rows, input columns).
+        This is the input of the convolution in the forward pass.
+
+    :type output_grad: symbolic 4D tensor.
+    :param output_grad: mini-batch of feature map stacks, of shape
+        (batch size, input channels, input rows, input columns).
+        This is the gradient of the output of convolution.
+
+    :type filters: symbolic 4D tensor.
+    :param filters: set of filters used in CNN layer of shape
+        (output channels, input channels, filter rows, filter columns).
+        See the optional parameter ``filter_shape``.
+
+    :type output_grad_shape: None, tuple/list of len 4 of int
+        or Constant variable.
+    :param output_grad_shape: The shape of the input parameter.
+        Optional, possibly used to choose an optimal implementation.
+        You can give ``None`` for any element of the list to specify that this
+        element is not known at compile time.
+
+    :type input_shape: tuple/list of len 2 of int or Constant variable.
+    :param input_shape: The shape of the input parameter.
+        This parameter indicates the row and column size of the input
+        in the forward pass.
+        Optional, possibly used to choose an optimal implementation.
+        You can give ``None`` for any element of the list to specify that this
+        element is not known at compile time.
+
+    :type filter_shape: None, tuple/list of len 4 of int or Constant variable.
+    :param filter_shape: The shape of the filters parameter.
+        Not Optional, since given the output_grad_shape and the input_shape,
+        multiple filter_shape may be plausible.
+
+    :type border_mode: str, int or tuple of two int
+    :param border_mode: Either of the following:
+        * ``'valid'``: apply filter wherever it completely overlaps with the
+          input. Generates output of shape: input shape - filter shape + 1
+        * ``'full'``: apply filter wherever it partly overlaps with the input.
+          Generates output of shape: input shape + filter shape - 1
+        * ``'half'``: pad input with a symmetric border of ``filter rows // 2``
+          rows and ``filter columns // 2`` columns, then perform a valid
+          convolution. For filters with an odd number of rows and columns, this
+          leads to the output shape being equal to the input shape.
+        * ``int``: pad input with a symmetric border of zeros of the given
+          width, then perform a valid convolution.
+        * ``(int1, int2)``: pad input with a symmetric border of ``int1`` rows
+          and ``int2`` columns, then perform a valid convolution.
+
+    :type subsample: tuple of len 2, the subsampling used in the forward pass
+        of the convolutional operation.
+    :param subsample: factor by which to subsample the output.
+        Also called strides elsewhere.
+
+    :type filter_flip: bool
+    :param filter_flip: If ``True``, will flip the filter rows and columns
+        before sliding them over the input. This operation is normally referred
+        to as a convolution, and this is the default. If ``False``, the filters
+        are not flipped and the operation is referred to as a
+        cross-correlation.
+
+    :rtype: symbolic 4D tensor.
+    :return: set of feature maps generated by convolutional layer. Tensor is
+        of shape (batch size, output channels, output rows, output columns)
+
+    :note: If CuDNN is available, it will be used on the
+        GPU. Otherwise, it is the *CorrMM* convolution that will be used
+        "caffe style convolution".
+
+    :note: This is only supported in Theano 0.8 or the development
+        version until it is released.
+
+    """
+    gradWeight_op = AbstractConv2d_gradWeights(imshp=input_shape,
+                                               kshp=filter_shape,
+                                               border_mode=border_mode,
+                                               subsample=subsample,
+                                               filter_flip=filter_flip)
+
+    return gradWeight_op(input, output_grad, input_shape)
+
+
 class BaseAbstractConv2d(Op):
     """Base class for AbstractConv