deconvolution interface

theano/tensor/nnet/abstract_conv.py

@@ -177,6 +177,187 @@ def conv2d(input,
     return conv_op(input, filters)
 
 
+def deconv(input,
+           filters,
+           input_shape=None,
+           output_shape=None,
+           filter_shape=None,
+           border_mode='valid',
+           subsample=(1, 1),
+           filter_flip=True):
+    """This function will build the symbolic graph for deconvoloving a
+    mini-batch of a stack of 2D inputs with a set of 2D filters (using
+    gradient of convolution), such that it upsamples the input to the
+    desired output resolution.
+
+    :type input: symbolic 4D tensor to be upsampled
+    :param input: mini-batch of feature map stacks, of shape
+        (batch size, input channels, input rows, input columns).
+        See the optional parameter ``input_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 input_shape: None, tuple/list of len 4 of int or Constant variable
+        indicating the shape to be upsampled or whose gradient should be taken.
+    :param input_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 output_shape: tuple/list of len 2 of int or Constant variable
+        indicating the row and column size of the output (upsampled) features.
+    :param output_shape: The shape of the input parameter.
+        Not Optional, since given the input_shape and the subsample values,
+        multiple output_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.
+
+    """
+
+    deconv_op = AbstractConv2d_gradInputs(imshp=output_shape,
+                              kshp=filter_shape,
+                              border_mode=border_mode,
+                              subsample=subsample,
+                              filter_flip=filter_flip)
+
+    return deconv_op(filters, input, output_shape)
+
+
+def gradWeights(input,
+           output,
+           input_shape=None,
+           output_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 layer w.r.t its wights.
+
+    :type input: symbolic 4D tensor as in the input in the forward pass
+    :param input: mini-batch of feature map stacks, of shape
+        (batch size, input channels, input rows, input columns).
+
+    :type output: symbolic 4D tensor as in the output in the forward pass
+    :param output: mini-batch of feature map stacks, of shape
+        (batch size, input channels, input rows, input columns).
+
+    :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_shape: None, tuple/list of len 4 of int or Constant variable
+    :param output_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
+        indicating the row and column size of the input in the forward pass.
+    :param input_shape: The shape of the input parameter.
+        Not Optional, since given the input_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.
+
+    """
+    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, input_shape)
+
+
 class BaseAbstractConv2d(Op):
     """Base class for AbstractConv