1from __future__ import absolute_import, print_function, division
2from .nnet import (
3    CrossentropyCategorical1Hot, CrossentropyCategorical1HotGrad,
4    CrossentropySoftmax1HotWithBiasDx, CrossentropySoftmaxArgmax1HotWithBias,
5    LogSoftmax, Prepend_scalar_constant_to_each_row,
6    Prepend_scalar_to_each_row, Softmax,
7    SoftmaxGrad, SoftmaxWithBias,
8    binary_crossentropy, sigmoid_binary_crossentropy,
9    categorical_crossentropy, crossentropy_categorical_1hot,
10    crossentropy_categorical_1hot_grad, crossentropy_softmax_1hot,
11    crossentropy_softmax_1hot_with_bias,
12    crossentropy_softmax_1hot_with_bias_dx,
13    crossentropy_softmax_argmax_1hot_with_bias,
14    crossentropy_softmax_max_and_argmax_1hot,
15    crossentropy_softmax_max_and_argmax_1hot_with_bias,
16    crossentropy_to_crossentropy_with_softmax,
17    crossentropy_to_crossentropy_with_softmax_with_bias,
18    graph_merge_softmax_with_crossentropy_softmax, h_softmax,
19    logsoftmax, logsoftmax_op, prepend_0_to_each_row, prepend_1_to_each_row,
20    prepend_scalar_to_each_row, relu, softmax, softmax_grad, softmax_graph,
21    softmax_op, softmax_simplifier, softmax_with_bias, elu, selu,
22    confusion_matrix, softsign)
23from . import opt
24from .conv import ConvOp
25from .sigm import (softplus, sigmoid, sigmoid_inplace,
26                   scalar_sigmoid, ultra_fast_sigmoid,
27                   hard_sigmoid)
28from .bn import batch_normalization
29
30
31import warnings
32from .abstract_conv import conv2d as abstract_conv2d
33from .abstract_conv import conv2d_grad_wrt_inputs
34from .abstract_conv import conv3d
35from .abstract_conv import separable_conv2d
36
37
38def conv2d(input, filters, input_shape=None, filter_shape=None,
39           border_mode='valid', subsample=(1, 1), filter_flip=True,
40           image_shape=None, filter_dilation=(1, 1), num_groups=1, unshared=False, **kwargs):
41    """
42    This function will build the symbolic graph for convolving a mini-batch of a
43    stack of 2D inputs with a set of 2D filters. The implementation is modelled
44    after Convolutional Neural Networks (CNN).
45
46
47    Parameters
48    ----------
49    input: symbolic 4D tensor
50        Mini-batch of feature map stacks, of shape
51        (batch size, input channels, input rows, input columns).
52        See the optional parameter ``input_shape``.
53
54    filters: symbolic 4D or 6D tensor
55        Set of filters used in CNN layer of shape
56        (output channels, input channels, filter rows, filter columns)
57        for normal convolution and
58        (output channels, output rows, output columns, input channels,
59        filter rows, filter columns)
60        for unshared convolution.
61        See the optional parameter ``filter_shape``.
62
63    input_shape: None, tuple/list of len 4 or 6 of int or Constant variable
64        The shape of the input parameter.
65        Optional, possibly used to choose an optimal implementation.
66        You can give ``None`` for any element of the list to specify that this
67        element is not known at compile time.
68
69    filter_shape: None, tuple/list of len 4 or 6 of int or Constant variable
70        The shape of the filters parameter.
71        Optional, possibly used to choose an optimal implementation.
72        You can give ``None`` for any element of the list to specify that this
73        element is not known at compile time.
74
75    border_mode: str, int or a tuple of two ints or pairs of ints
76        Either of the following:
77
78        ``'valid'``: apply filter wherever it completely overlaps with the
79            input. Generates output of shape: input shape - filter shape + 1
80        ``'full'``: apply filter wherever it partly overlaps with the input.
81            Generates output of shape: input shape + filter shape - 1
82        ``'half'``: pad input with a symmetric border of ``filter rows // 2``
83            rows and ``filter columns // 2`` columns, then perform a valid
84            convolution. For filters with an odd number of rows and columns, this
85            leads to the output shape being equal to the input shape.
86        ``int``: pad input with a symmetric border of zeros of the given
87            width, then perform a valid convolution.
88        ``(int1, int2)``: (for 2D) pad input with a symmetric border of ``int1``,
89            ``int2``, then perform a valid convolution.
90        ``(int1, (int2, int3))`` or ``((int1, int2), int3)``: (for 2D)
91            pad input with one symmetric border of `int1`` or ``int3``, and
92            one asymmetric border of ``(int2, int3)`` or ``(int1, int2)``.
93
94    subsample: tuple of len 2
95        Factor by which to subsample the output.
96        Also called strides elsewhere.
97
98    filter_flip: bool
99        If ``True``, will flip the filter rows and columns
100        before sliding them over the input. This operation is normally referred
101        to as a convolution, and this is the default. If ``False``, the filters
102        are not flipped and the operation is referred to as a cross-correlation.
103
104    image_shape: None, tuple/list of len 4 of int or Constant variable
105        Deprecated alias for input_shape.
106
107    filter_dilation: tuple of len 2
108        Factor by which to subsample (stride) the input.
109        Also called dilation elsewhere.
110
111    num_groups : int
112        Divides the image, kernel and output tensors into num_groups
113        separate groups. Each which carry out convolutions separately
114
115    unshared: bool
116        If true, then unshared or 'locally connected' convolution will be
117        performed. A different filter will be used for each region of the
118        input.
119
120    kwargs: Any other keyword arguments are accepted for backwards
121            compatibility, but will be ignored.
122
123    Returns
124    -------
125    Symbolic 4D tensor
126        Set of feature maps generated by convolutional layer. Tensor is
127        of shape (batch size, output channels, output rows, output columns)
128
129    Notes
130    -----
131        If cuDNN is available, it will be used on the
132        GPU. Otherwise, it is the *CorrMM* convolution that will be used
133        "caffe style convolution".
134
135        This is only supported in Theano 0.8 or the development
136        version until it is released.
137
138        The parameter filter_dilation is an implementation of `dilated
139        convolution <https://arxiv.org/pdf/1511.07122v3.pdf>`_.
140
141    """
142
143    if 'imshp_logical' in kwargs or 'kshp_logical' in kwargs:
144        raise ValueError(
145            "Keyword arguments 'imshp_logical' and 'kshp_logical' for conv2d "
146            "are not supported anymore (and have not been a reliable way to "
147            "perform upsampling). That feature is still available by calling "
148            "theano.tensor.nnet.conv.conv2d() for the time being.")
149    if len(kwargs.keys()) > 0:
150        warnings.warn(str(kwargs.keys()) +
151                      " are now deprecated in "
152                      "`tensor.nnet.abstract_conv.conv2d` interface"
153                      " and will be ignored.",
154                      stacklevel=2)
155
156    if image_shape is not None:
157        warnings.warn("The `image_shape` keyword argument to "
158                      "`tensor.nnet.conv2d` is deprecated, it has been "
159                      "renamed to `input_shape`.",
160                      stacklevel=2)
161        if input_shape is None:
162            input_shape = image_shape
163        else:
164            raise ValueError("input_shape and image_shape should not"
165                             " be provided at the same time.")
166
167    return abstract_conv2d(input, filters, input_shape, filter_shape,
168                           border_mode, subsample, filter_flip,
169                           filter_dilation, num_groups, unshared)
170
171
172def conv2d_transpose(input, filters, output_shape, filter_shape=None,
173                     border_mode='valid', input_dilation=(1, 1),
174                     filter_flip=True, filter_dilation=(1, 1), num_groups=1, unshared=False):
175    """
176    This function will build the symbolic graph for applying a transposed
177    convolution over a mini-batch of a stack of 2D inputs with a set of 2D
178    filters.
179
180
181    Parameters
182    ----------
183    input: symbolic 4D tensor
184        Mini-batch of feature map stacks, of shape
185        (batch size, input channels, input rows, input columns).
186        See the optional parameter ``input_shape``.
187
188    filters: symbolic 4D tensor
189        Set of filters used in CNN layer of shape
190        (input channels, output channels, filter rows, filter columns).
191        See the optional parameter ``filter_shape``. **Note: the order for
192        ``output_channels`` and ``input_channels`` is reversed with respect to
193        ``conv2d``.**
194
195    output_shape: tuple/list of len 4 of int or Constant variable
196        The shape of the output of ``conv2d_transpose``. The last two elements
197        are allowed to be ``tensor.scalar`` variables.
198
199    filter_shape: None, tuple/list of len 4 of int or Constant variable
200        The shape of the filters parameter.
201        Optional, possibly used to choose an optimal implementation.
202        You can give ``None`` for any element of the list to specify that this
203        element is not known at compile time.
204
205    border_mode: str, int or tuple of two int
206        Refers to the ``border_mode`` argument of the corresponding forward
207        (non-transposed) convolution. See the argument description in
208        ``conv2d``.  What was ``padding`` for the forward convolution means
209        ``cropping`` the output of the transposed one. ``valid`` corresponds to
210        no cropping, ``full`` to maximal cropping.
211
212    input_dilation: tuple of len 2
213        Corresponds to ``subsample`` (also called strides elsewhere) in the
214        non-transposed convolution.
215
216    filter_flip: bool
217        If ``True``, will flip the filter rows and columns
218        before sliding them over the input. This operation is normally referred
219        to as a convolution, and this is the default. If ``False``, the filters
220        are not flipped and the operation is referred to as a cross-correlation.
221
222    filter_dilation: tuple of len 2
223        Factor by which to subsample (stride) the input.
224        Also called dilation elsewhere.
225
226    num_groups : int
227        Divides the image, kernel and output tensors into num_groups
228        separate groups. Each which carry out convolutions separately
229
230    unshared: bool
231        If true, then unshared or 'locally connected' convolution will be
232        performed. A different filter will be used for each region of the
233        input.
234        Grouped unshared convolution is supported.
235
236    Returns
237    -------
238    Symbolic 4D tensor
239        Set of feature maps generated by the transposed convolution. Tensor is
240        of shape (batch size, output channels, output rows, output columns)
241
242    Notes
243    -----
244        If cuDNN is available, it will be used on the
245        GPU. Otherwise, it is the *CorrMM* convolution that will be used
246        "caffe style convolution".
247
248        This operation is also sometimes called "deconvolution".
249
250        The parameter filter_dilation is an implementation of `dilated
251        convolution <https://arxiv.org/pdf/1511.07122v3.pdf>`_.
252
253    """
254
255    return conv2d_grad_wrt_inputs(output_grad=input,
256                                  filters=filters,
257                                  input_shape=output_shape,
258                                  filter_shape=filter_shape,
259                                  border_mode=border_mode,
260                                  subsample=input_dilation,
261                                  filter_flip=filter_flip,
262                                  filter_dilation=filter_dilation,
263                                  num_groups=num_groups,
264                                  unshared=unshared)
265