pooling.py 57.4 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
#   Copyright (c) 2020 PaddlePaddle Authors. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

from ...fluid.layer_helper import LayerHelper
from .. import functional as F
Z
zhiboniu 已提交
17
from .. import Layer
18

19 20
__all__ = []

21

Z
zhiboniu 已提交
22
class AvgPool1D(Layer):
W
Wei Shengyu 已提交
23
    r"""
24
    This operation applies a 1D average pooling over an input signal composed
25
    of several input planes, based on the input, output_size, return_mask parameters.
26 27 28 29 30
    Input(X) and output(Out) are in NCL format, where N is batch
    size, C is the number of channels, L is the length of the feature.
    The output tensor shape will be [N, C, output_size].

    The output value of the layer with input size (N, C, L),
W
Wei Shengyu 已提交
31
    output (N, C, :math:`L_{out}`) and kernel_size ksize can be precisely described as
32 33 34 35
    For average pool1d:

    ..  math::

W
Wei Shengyu 已提交
36
        Output(N_i, C_i, l) = \frac{Input[N_i, C_i, stride \times l:stride \times l+k]}{ksize}
37

W
Wei Shengyu 已提交
38 39
    Parameters:
        kernel_size(int|list|tuple): The pool kernel size. If pool kernel size is a tuple or list,
40
            it must contain an integer.
W
Wei Shengyu 已提交
41 42 43
        stride(int|list|tuple, optional): The pool stride size. If pool stride size is a tuple or list,
            it must contain an integer. Default None, then stride will be equal to the kernel_size.
        padding(str|int|list|tuple, optional): The padding size. Padding could be in one of the following forms.
44 45 46 47 48 49
            1. A string in ['valid', 'same'].
            2. An int, which means the feature map is zero padded by size of `padding` on every sides.
            3. A list[int] or tuple(int) whose length is 1, which means the feature map is zero padded by the size of `padding[0]` on every sides.
            4. A list[int] or tuple(int) whose length is 2. It has the form [pad_before, pad_after].
            5. A list or tuple of pairs of integers. It has the form [[pad_before, pad_after], [pad_before, pad_after], ...]. Note that, the batch dimension and channel dimension should be [0,0] or (0,0).
            The default value is 0.
W
Wei Shengyu 已提交
50 51 52 53 54
        exclusive(bool, optional): Whether to exclude padding points in average pooling mode, default is `True`.
        ceil_mode(bool, optional): ${ceil_mode_comment}Whether to use the ceil function to calculate output height
            and width. If it is set to False, the floor function will be used. The default value is False.
        name(str, optional): For eed to detailed information, please refer to :ref:`api_guide_Name`.
            Usually name is no nset and None by default.
55 56

    Returns:
W
Wei Shengyu 已提交
57
        A callable object of AvgPool1D.
58 59 60 61 62

    Raises:
        ValueError: If `padding` is a string, but not "SAME" or "VALID".
        ValueError: If `padding` is "VALID", but `ceil_mode` is True.
        ValueError: If `padding` is a list or tuple but its length greater than 1.
63
        ShapeError: If the input is not a 3-D tensor.
64 65
        ShapeError: If the output's shape calculated is not greater than 0.

66
    Shape:
W
Wei Shengyu 已提交
67 68 69 70
        - x(Tensor): The input tensor of avg pool1d operator, which is a 3-D tensor.
          The data type can be float32, float64.
        - output(Tensor): The output tensor of avg pool1d  operator, which is a 3-D tensor.
          The data type is same as input x.
71

72 73 74
    Examples:

        .. code-block:: python
75

W
Wei Shengyu 已提交
76 77 78
            import paddle
            import paddle.nn as nn
            import numpy as np
79

W
Wei Shengyu 已提交
80 81 82 83
            data = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32]).astype(np.float32))
            AvgPool1D = nn.AvgPool1D(kernel_size=2, stride=2, padding=0)
            pool_out = AvgPool1D(data)
            # pool_out shape: [1, 3, 16]
84 85 86 87 88 89 90

    """

    def __init__(self,
                 kernel_size,
                 stride=None,
                 padding=0,
91
                 exclusive=True,
92 93
                 ceil_mode=False,
                 name=None):
C
cnn 已提交
94
        super(AvgPool1D, self).__init__()
95 96 97 98
        self.kernel_size = kernel_size
        self.stride = stride
        self.padding = padding
        self.ceil_mode = ceil_mode
99
        self.exclusive = exclusive
100 101 102 103
        self.name = name

    def forward(self, x):
        out = F.avg_pool1d(x, self.kernel_size, self.stride, self.padding,
104
                           self.exclusive, self.ceil_mode, self.name)
105 106
        return out

107 108 109 110
    def extra_repr(self):
        return 'kernel_size={kernel_size}, stride={stride}, padding={padding}'.format(
            **self.__dict__)

111

Z
zhiboniu 已提交
112
class AvgPool2D(Layer):
113
    r"""
114 115 116 117
    This operation applies 2D average pooling over input features based on the input,
    and kernel_size, stride, padding parameters. Input(X) and Output(Out) are
    in NCHW format, where N is batch size, C is the number of channels,
    H is the height of the feature, and W is the width of the feature.
118

119
    Example:
W
Wei Shengyu 已提交
120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
        Input:
            X shape: :math:`(N, C, :math:`H_{in}`, :math:`W_{in}`)`
        Attr:
            kernel_size: ksize

        Output:
            Out shape: :math:`(N, C, :math:`H_{out}`, :math:`W_{out}`)`

        ..  math::

            Output(N_i, C_j, h, w)  = \frac{\sum_{m=0}^{ksize[0]-1} \sum_{n=0}^{ksize[1]-1}
                Input(N_i, C_j, stride[0] \times h + m, stride[1] \times w + n)}{ksize[0] * ksize[1]}

    Parameters:
        kernel_size(int|list|tuple): The pool kernel size. If pool kernel size is a tuple or list,
135 136
            it must contain two integers, (pool_size_Height, pool_size_Width).
            Otherwise, the pool kernel size will be a square of an int.
W
Wei Shengyu 已提交
137
        stride(int|list|tuple, optional): The pool stride size. If pool stride size is a tuple or list,
138 139
            it must contain two integers, (pool_stride_Height, pool_stride_Width).
            Otherwise, the pool stride size will be a square of an int.
W
Wei Shengyu 已提交
140 141
            Default None, then stride will be equal to the kernel_size.
        padding(str|int|list|tuple, optional): The padding size. Padding could be in one of the following forms.
142 143 144 145 146 147
            1. A string in ['valid', 'same'].
            2. An int, which means the feature map is zero padded by size of `padding` on every sides.
            3. A list[int] or tuple(int) whose length is 2, [pad_height, pad_weight] whose value means the padding size of each dimension.
            4. A list[int] or tuple(int) whose length is 4. [pad_height_top, pad_height_bottom, pad_width_left, pad_width_right] whose value means the padding size of each side.
            5. A list or tuple of pairs of integers. It has the form [[pad_before, pad_after], [pad_before, pad_after], ...]. Note that, the batch dimension and channel dimension should be [0,0] or (0,0).
            The default value is 0.
W
Wei Shengyu 已提交
148 149 150 151 152 153 154 155 156 157
        ceil_mode(bool, optional): When True, will use `ceil` instead of `floor` to compute the output shape.
        exclusive(bool, optional): Whether to exclude padding points in average pooling
            mode, default is `true`.
        divisor_override(float, optional): If specified, it will be used as divisor, otherwise kernel_size will be
            used. Default None.
        data_format(str, optional): The data format of the input and output data. An optional string from: `"NCHW"`,
            `"NDHW"`. The default is `"NCHW"`. When it is `"NCHW"`, the data is stored in the order of:
            `[batch_size, input_channels, input_height, input_width]`.
        name(str, optional): For detailed information, please refer to :ref:`api_guide_Name`.
            Usually name is no need to set and None by default.
158

159
    Shape:
W
Wei Shengyu 已提交
160 161 162 163
        - x(Tensor): The input tensor of avg pool2d operator, which is a 4-D tensor.
          The data type can be float32, float64.
        - output(Tensor): The output tensor of avg pool2d  operator, which is a 4-D tensor.
          The data type is same as input x.
164

W
Wei Shengyu 已提交
165 166
    Returns:
        A callable object of AvgPool2D.
167 168 169 170 171 172
    Raises:
        ValueError: If `padding` is a string, but not "SAME" or "VALID".
        ValueError: If `padding` is "VALID", but `ceil_mode` is True.
        ShapeError: If the output's shape calculated is not greater than 0.
    Examples:
        .. code-block:: python
173

W
Wei Shengyu 已提交
174 175 176
            import paddle
            import paddle.nn as nn
            import numpy as np
177

W
Wei Shengyu 已提交
178 179 180
            # max pool2d
            input = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32, 32]).astype(np.float32))
            AvgPool2D = nn.AvgPool2D(kernel_size=2,
181
                                stride=2, padding=0)
W
Wei Shengyu 已提交
182 183
            output = AvgPool2D(input)
            # output.shape [1, 3, 16, 16]
184 185 186 187 188 189 190 191

    """

    def __init__(self,
                 kernel_size,
                 stride=None,
                 padding=0,
                 ceil_mode=False,
192
                 exclusive=True,
193 194
                 divisor_override=None,
                 data_format="NCHW",
195
                 name=None):
C
cnn 已提交
196
        super(AvgPool2D, self).__init__()
197
        self.ksize = kernel_size
198 199 200
        self.stride = stride
        self.padding = padding
        self.ceil_mode = ceil_mode
201
        self.exclusive = exclusive
202 203
        self.divisor = divisor_override
        self.data_format = data_format
204 205
        self.name = name

206 207 208 209 210 211 212
    def forward(self, x):
        return F.avg_pool2d(
            x,
            kernel_size=self.ksize,
            stride=self.stride,
            padding=self.padding,
            ceil_mode=self.ceil_mode,
213
            exclusive=self.exclusive,
214 215 216
            divisor_override=self.divisor,
            data_format=self.data_format,
            name=self.name)
217

218 219 220 221
    def extra_repr(self):
        return 'kernel_size={ksize}, stride={stride}, padding={padding}'.format(
            **self.__dict__)

222

Z
zhiboniu 已提交
223
class AvgPool3D(Layer):
224
    """
225 226 227 228
    This operation applies 3D max pooling over input features based on the input,
    and kernel_size, stride, padding parameters. Input(X) and Output(Out) are
    in NCDHW format, where N is batch size, C is the number of channels,
    H is the height of the feature,  D is the depth of the feature, and W is the width of the feature.
229

W
Wei Shengyu 已提交
230 231
    Parameters:
        kernel_size(int|list|tuple): The pool kernel size. If pool kernel size
232 233 234
            is a tuple or list, it must contain three integers,
            (kernel_size_Depth, kernel_size_Height, kernel_size_Width).
            Otherwise, the pool kernel size will be the cube of an int.
W
Wei Shengyu 已提交
235
        stride(int|list|tuple, optional): The pool stride size. If pool stride size is a tuple or list,
236 237
            it must contain three integers, [stride_Depth, stride_Height, stride_Width).
            Otherwise, the pool stride size will be a cube of an int.
W
Wei Shengyu 已提交
238 239
            Default None, then stride will be equal to the kernel_size.
        padding(str|int|list|tuple, optional): The padding size. Padding could be in one of the following forms.
240 241 242 243 244 245
            1. A string in ['valid', 'same'].
            2. An int, which means the feature map is zero padded by size of `padding` on every sides.
            3. A list[int] or tuple(int) whose length is 3, [pad_depth, pad_height, pad_weight] whose value means the padding size of each dimension.
            4. A list[int] or tuple(int) whose length is 6. [pad_depth_front, pad_depth_back, pad_height_top, pad_height_bottom, pad_width_left, pad_width_right] whose value means the padding size of each side.
            5. A list or tuple of pairs of integers. It has the form [[pad_before, pad_after], [pad_before, pad_after], ...]. Note that, the batch dimension and channel dimension should be [0,0] or (0,0).
            The default value is 0.
W
Wei Shengyu 已提交
246 247 248 249 250 251 252
        ceil_mode(bool, optional): ${ceil_mode_comment}
        exclusive(bool, optional): Whether to exclude padding points in average pooling mode, default is True.
        divisor_override(int|float, optional): if specified, it will be used as divisor, otherwise kernel_size will
            be used. Default None.
        data_format(str, optional): The data format of the input and output data. An optional string from: `"NCDHW"`,
             `"NDHWC"`. The default is `"NCDHW"`. When it is `"NCDHW"`, the data is stored in the order of:
             `[batch_size, input_channels, input_depth, input_height, input_width]`.
253
        name(str, optional): For detailed information, please refer
W
Wei Shengyu 已提交
254 255
             to :ref:`api_guide_Name`. Usually name is no need to set and
             None by default.
256

W
Wei Shengyu 已提交
257 258
    Returns:
        A callable object of AvgPool3D.
259
    Raises:
260 261 262 263 264
        ValueError: If `padding` is a string, but not "SAME" or "VALID".
        ValueError: If `padding` is "VALID", but `ceil_mode` is True.
        ShapeError: If the output's shape calculated is not greater than 0.

    Shape:
W
Wei Shengyu 已提交
265 266 267 268
        - x(Tensor): The input tensor of avg pool3d operator, which is a 5-D tensor.
          The data type can be float32, float64.
        - output(Tensor): The output tensor of avg pool3d  operator, which is a 5-D tensor.
          The data type is same as input x.
269 270
    Examples:
        .. code-block:: python
271

W
Wei Shengyu 已提交
272 273 274
            import paddle
            import paddle.nn as nn
            import numpy as np
275

W
Wei Shengyu 已提交
276 277 278
            # avg pool3d
            input = paddle.to_tensor(np.random.uniform(-1, 1, [1, 2, 3, 32, 32]).astype(np.float32))
            AvgPool3D = nn.AvgPool3D(kernel_size=2,
279
                                   stride=2, padding=0)
W
Wei Shengyu 已提交
280 281
            output = AvgPool3D(input)
            # output.shape [1, 2, 3, 16, 16]
282

283 284
    """

285 286
    def __init__(self,
                 kernel_size,
W
Wei Shengyu 已提交
287
                 stride=None,
288 289
                 padding=0,
                 ceil_mode=False,
290
                 exclusive=True,
291 292 293
                 divisor_override=None,
                 data_format="NCDHW",
                 name=None):
C
cnn 已提交
294
        super(AvgPool3D, self).__init__()
295 296 297 298
        self.ksize = kernel_size
        self.stride = stride
        self.padding = padding
        self.ceil_mode = ceil_mode
299
        self.exclusive = exclusive
300 301
        self.divisor = divisor_override
        self.data_format = data_format
302 303
        self.name = name

304 305 306 307 308 309 310
    def forward(self, x):
        return F.avg_pool3d(
            x,
            kernel_size=self.ksize,
            stride=self.stride,
            padding=self.padding,
            ceil_mode=self.ceil_mode,
311
            exclusive=self.exclusive,
312 313 314
            divisor_override=self.divisor,
            data_format=self.data_format,
            name=self.name)
315

316 317 318 319
    def extra_repr(self):
        return 'kernel_size={ksize}, stride={stride}, padding={padding}'.format(
            **self.__dict__)

320

Z
zhiboniu 已提交
321
class MaxPool1D(Layer):
322
    """
W
Wei Shengyu 已提交
323 324 325 326 327
    This operation applies 1D max pooling over input signal
    composed of several input planes based on the input,
    and kernel_size, stride, padding parameters. Input(X) and Output(Out) are
    in NCL format, where N is batch size, C is the number of channels,
    L is the length of the feature.
328

329 330 331
    The output value of the layer with input size (N, C, L),
    output (N, C, L_{out}) and kernel_size k can be precisely described as
    For average pool1d:
332 333 334

    ..  math::

W
Wei Shengyu 已提交
335
        Output(N_i, C_i, l) =  max(Input[N_i, C_i, stride \times l:stride \times l+k])
336

W
Wei Shengyu 已提交
337 338
    Parameters:
        kernel_size(int|list|tuple): The pool kernel size. If pool kernel size is a tuple or list,
339
            it must contain an integer.
W
Wei Shengyu 已提交
340 341 342
        stride(int|list|tuple, optional): The pool stride size. If pool stride size is a tuple or list,
            it must contain an integer. Default None, then stride will be equal to the kernel_size.
        padding(str|int|list|tuple, optional): The padding size. Padding could be in one of the following forms.
343 344 345
            1. A string in ['valid', 'same'].
            2. An integer, which means the feature map is zero padded by size of `padding` on every sides.
            3. A list[int] or tuple(int) whose length is 1, which means the feature map is zero padded by the size of `padding[0]` on every sides.
W
Wei Shengyu 已提交
346 347
            4. A list[int] or tuple(int) whose length is 2, It has the form [pad_before, pad_after].
            5. A list or tuple of pairs of integers. It has the form [[pad_before, pad_after], [pad_before, pad_after], ...]. Note that, the batch dimension and channel dimension should be [0,0] or(0,0).
348
            The default value is 0.
W
Wei Shengyu 已提交
349 350 351 352 353
        return_mask(bool, optional): Whether return the max indices along with the outputs. default is `False`.
        ceil_mode(bool, optional): Whether to use the ceil function to calculate output height and width.
            False is the default. If it is set to False, the floor function will be used. Default False.
        name(str, optional): For detailed information, please refer to :ref:`api_guide_Name`.
            Usually name is no need to set and None by default.
354
    Returns:
W
Wei Shengyu 已提交
355
        A callable object of MaxPool1D.
356 357

    Raises:
358 359 360 361 362 363 364 365
        ValueError: If `padding` is a string, but not "SAME" or "VALID".
        ValueError: If `padding` is "VALID", but `ceil_mode` is True.
        ValueError: If `padding` is a list or tuple but its length greater than 1.
        ShapeError: If the input is not a 3-D.
        ShapeError: If the output's shape calculated is not greater than 0.


    Shape:
W
Wei Shengyu 已提交
366 367 368 369
        - x(Tensor): The input tensor of max pool1d operator, which is a 3-D tensor.
          The data type can be float32, float64.
        - output(Tensor): The output tensor of max pool1d  operator, which is a 3-D tensor.
          The data type is same as input x.
370 371

    Examples:
372

373 374
        .. code-block:: python

W
Wei Shengyu 已提交
375 376 377
            import paddle
            import paddle.nn as nn
            import numpy as np
378

W
Wei Shengyu 已提交
379 380 381 382
            data = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32]).astype(np.float32))
            MaxPool1D = nn.MaxPool1D(kernel_size=2, stride=2, padding=0)
            pool_out = MaxPool1D(data)
            # pool_out shape: [1, 3, 16]
383

W
Wei Shengyu 已提交
384 385 386
            MaxPool1D = nn.MaxPool1D(kernel_size=2, stride=2, padding=0, return_mask=True)
            pool_out, indices = MaxPool1D(data)
            # pool_out shape: [1, 3, 16], indices shape: [1, 3, 16]
387 388 389

    """

390 391 392 393
    def __init__(self,
                 kernel_size,
                 stride=None,
                 padding=0,
394
                 return_mask=False,
395 396
                 ceil_mode=False,
                 name=None):
C
cnn 已提交
397
        super(MaxPool1D, self).__init__()
398 399 400 401
        self.kernel_size = kernel_size
        self.stride = stride
        self.padding = padding
        self.ceil_mode = ceil_mode
402
        self.return_mask = return_mask
403 404 405
        self.name = name

    def forward(self, input):
406
        out = F.max_pool1d(input, self.kernel_size, self.stride, self.padding,
407
                           self.return_mask, self.ceil_mode, self.name)
408
        return out
409

410 411 412 413
    def extra_repr(self):
        return 'kernel_size={kernel_size}, stride={stride}, padding={padding}'.format(
            **self.__dict__)

414

Z
zhiboniu 已提交
415
class MaxPool2D(Layer):
416
    r"""
417
    This operation applies 2D max pooling over input feature based on the input,
418 419 420 421 422
    and kernel_size, stride, padding parameters. Input(X) and Output(Out) are
    in NCHW format, where N is batch size, C is the number of channels,
    H is the height of the feature, and W is the width of the feature.

    Example:
W
Wei Shengyu 已提交
423 424 425 426 427 428 429 430 431 432 433 434 435 436 437
        - Input:
            X shape: :math:`(N, C, H_{in}, W_{in})`
        - Attr:
            kernel_size: ksize

        - Output:
            Out shape: :math:`(N, C, H_{out}, W_{out})`

        ..  math::

            Output(N_i, C_j, h, w) = \max_{m=0, \ldots, ksize[0] -1} \max_{n=0, \ldots, ksize[1]-1}
                Input(N_i, C_j, stride[0] \times h + m, stride[1] \times w + n)

    Parameters:
        kernel_size(int|list|tuple): The pool kernel size. If pool kernel size is a tuple or list,
438 439
            it must contain two integers, (pool_size_Height, pool_size_Width).
            Otherwise, the pool kernel size will be a square of an int.
W
Wei Shengyu 已提交
440
        stride(int|list|tuple, optional): The pool stride size. If pool stride size is a tuple or list,
441
            it must contain two integers, (pool_stride_Height, pool_stride_Width).
442
            Otherwise, the pool stride size will be a square of an int.
W
Wei Shengyu 已提交
443 444
            Default None, then stride will be equal to the kernel_size.
        padding(str|int|list|tuple, optional): The padding size. Padding could be in one of the following forms.
445 446 447
            1. A string in ['valid', 'same'].
            2. An int, which means the feature map is zero padded by size of `padding` on every sides.
            3. A list[int] or tuple(int) whose length is 2, [pad_height, pad_weight] whose value means the padding size of each dimension.
W
Wei Shengyu 已提交
448
            4. A list[int] or tuple(int) whose length is \4. [pad_height_top, pad_height_bottom, pad_width_left, pad_width_right] whose value means the padding size of each side.
449 450
            5. A list or tuple of pairs of integers. It has the form [[pad_before, pad_after], [pad_before, pad_after], ...]. Note that, the batch dimension and channel dimension should be [0,0] or (0,0).
            The default value is 0.
W
Wei Shengyu 已提交
451 452 453 454 455 456 457
        ceil_mode(bool, optional): when True, will use `ceil` instead of `floor` to compute the output shape
        return_mask(bool, optional): Whether to return the max indices along with the outputs.
        data_format(str, optional): The data format of the input and output data. An optional string from: `"NCHW"`, `"NDHW"`.
            The default is `"NCHW"`. When it is `"NCHW"`, the data is stored in the order of:
            `[batch_size, input_channels, input_height, input_width]`.
        name(str, optional): For detailed information, please refer to :ref:`api_guide_Name`.
            Usually name is no need to set and None by default.
458

W
Wei Shengyu 已提交
459 460
    Returns:
        A callable object of MaxPool2D.
461 462 463 464
    Raises:
        ValueError: If `padding` is a string, but not "SAME" or "VALID".
        ValueError: If `padding` is "VALID", but `ceil_mode` is True.
        ShapeError: If the output's shape calculated is not greater than 0.
465 466

    Shape:
W
Wei Shengyu 已提交
467 468 469 470
        - x(Tensor): The input tensor of max pool2d operator, which is a 4-D tensor.
          The data type can be float32, float64.
        - output(Tensor): The output tensor of max pool2d  operator, which is a 4-D tensor.
          The data type is same as input x.
471

472 473
    Examples:
        .. code-block:: python
474

W
Wei Shengyu 已提交
475 476 477
            import paddle
            import paddle.nn as nn
            import numpy as np
478

W
Wei Shengyu 已提交
479 480 481
            # max pool2d
            input = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32, 32]).astype(np.float32))
            MaxPool2D = nn.MaxPool2D(kernel_size=2,
482
                                   stride=2, padding=0)
W
Wei Shengyu 已提交
483 484
            output = MaxPool2D(input)
            # output.shape [1, 3, 16, 16]
485

W
Wei Shengyu 已提交
486 487 488 489
            # for return_mask=True
            MaxPool2D = nn.MaxPool2D(kernel_size=2, stride=2, padding=0, return_mask=True)
            output, max_indices = MaxPool2D(input)
            # output.shape [1, 3, 16, 16], max_indices.shape [1, 3, 16, 16],
490 491 492 493 494 495
    """

    def __init__(self,
                 kernel_size,
                 stride=None,
                 padding=0,
496
                 return_mask=False,
497 498 499
                 ceil_mode=False,
                 data_format="NCHW",
                 name=None):
C
cnn 已提交
500
        super(MaxPool2D, self).__init__()
501 502 503
        self.ksize = kernel_size
        self.stride = stride
        self.padding = padding
504
        self.return_mask = return_mask
505 506 507 508 509
        self.ceil_mode = ceil_mode
        self.data_format = data_format
        self.name = name

    def forward(self, x):
510
        return F.max_pool2d(
511 512 513 514
            x,
            kernel_size=self.ksize,
            stride=self.stride,
            padding=self.padding,
515
            return_mask=self.return_mask,
D
Double_V 已提交
516
            ceil_mode=self.ceil_mode,
517 518 519
            data_format=self.data_format,
            name=self.name)

520 521 522 523
    def extra_repr(self):
        return 'kernel_size={ksize}, stride={stride}, padding={padding}'.format(
            **self.__dict__)

524

Z
zhiboniu 已提交
525
class MaxPool3D(Layer):
526
    """
527
    This operation applies 3D max pooling over input features based on the input,
528
    and kernel_size, stride, padding parameters. Input(X) and Output(Out) are
529 530
    in NCDHW format, where N is batch size, C is the number of channels,
    H is the height of the feature,  D is the depth of the feature, and W is the width of the feature.
531

W
Wei Shengyu 已提交
532 533
    Parameters:
        kernel_size(int|list|tuple): The pool kernel size. If the kernel size
534
            is a tuple or list, it must contain three integers,
535
            (kernel_size_Depth, kernel_size_Height, kernel_size_Width).
536
            Otherwise, the pool kernel size will be the cube of an int.
W
Wei Shengyu 已提交
537
        stride(int|list|tuple, optional): The pool stride size. If pool stride size is a tuple or list,
538 539
            it must contain three integers, [stride_Depth, stride_Height, stride_Width).
            Otherwise, the pool stride size will be a cube of an int.
W
Wei Shengyu 已提交
540 541
            Default None, then stride will be equal to the kernel_size.
        padding(str|int|list|tuple, optional): The padding size. Padding could be in one of the following forms.
542 543 544
            1. A string in ['valid', 'same'].
            2. An int, which means the feature map is zero padded by size of `padding` on every sides.
            3. A list[int] or tuple(int) whose length is 3, [pad_depth, pad_height, pad_weight] whose value means the padding size of each dimension.
W
Wei Shengyu 已提交
545
            4. A list[int] or tuple(int) whose length is \6. [pad_depth_front, pad_depth_back, pad_height_top, pad_height_bottom, pad_width_left, pad_width_right] whose value means the padding size of each side.
546 547
            5. A list or tuple of pairs of integers. It has the form [[pad_before, pad_after], [pad_before, pad_after], ...]. Note that, the batch dimension and channel dimension should be [0,0] or (0,0).
            The default value is 0.
W
Wei Shengyu 已提交
548 549 550 551 552 553 554
        ceil_mode(bool, optional): ${ceil_mode_comment}
        return_mask(bool, optional): Whether to return the max indices along with the outputs.
        data_format(str, optional): The data format of the input and output data. An optional string from: `"NCDHW"`,
            `"NDHWC"`. The default is `"NCDHW"`. When it is `"NCDHW"`, the data is stored in the order of:
            `[batch_size, input_channels, input_depth, input_height, input_width]`.
        name(str, optional): For detailed information, please refer to :ref:`api_guide_Name`.
            Usually name is no need to set and None by default.
555 556


W
Wei Shengyu 已提交
557 558
    Returns:
        A callable object of MaxPool3D.
559 560 561 562
    Raises:
        ValueError: If `padding` is a string, but not "SAME" or "VALID".
        ValueError: If `padding` is "VALID", but `ceil_mode` is True.
        ShapeError: If the output's shape calculated is not greater than 0.
563 564

    Shape:
W
Wei Shengyu 已提交
565 566 567 568
        - x(Tensor): The input tensor of max pool3d operator, which is a 5-D tensor.
          The data type can be float32, float64.
        - output(Tensor): The output tensor of max pool3d  operator, which is a 5-D tensor.
          The data type is same as input x.
569

570 571
    Examples:
        .. code-block:: python
572

W
Wei Shengyu 已提交
573 574 575
            import paddle
            import paddle.nn as nn
            import numpy as np
576

W
Wei Shengyu 已提交
577 578 579
            # max pool3d
            input = paddle.to_tensor(np.random.uniform(-1, 1, [1, 2, 3, 32, 32]).astype(np.float32))
            MaxPool3D = nn.MaxPool3D(kernel_size=2,
580
                                   stride=2, padding=0)
W
Wei Shengyu 已提交
581 582
            output = MaxPool3D(input)
            # output.shape [1, 2, 3, 16, 16]
583

W
Wei Shengyu 已提交
584 585 586 587
            # for return_mask=True
            MaxPool3D = nn.MaxPool3D(kernel_size=2, stride=2, padding=0, return_mask=True)
            output, max_indices = MaxPool3D(input)
            # output.shape [1, 2, 3, 16, 16], max_indices.shape [1, 2, 3, 16, 16],
588 589 590 591
    """

    def __init__(self,
                 kernel_size,
P
parap1uie-s 已提交
592 593
                 stride=None,
                 padding=0,
594
                 return_mask=False,
595 596 597
                 ceil_mode=False,
                 data_format="NCDHW",
                 name=None):
C
cnn 已提交
598
        super(MaxPool3D, self).__init__()
599 600 601
        self.ksize = kernel_size
        self.stride = stride
        self.padding = padding
602
        self.return_mask = return_mask
603 604 605 606 607 608 609 610 611 612
        self.ceil_mode = ceil_mode
        self.data_format = data_format
        self.name = name

    def forward(self, x):
        return F.max_pool3d(
            x,
            kernel_size=self.ksize,
            stride=self.stride,
            padding=self.padding,
613
            return_mask=self.return_mask,
D
Double_V 已提交
614
            ceil_mode=self.ceil_mode,
615 616 617
            data_format=self.data_format,
            name=self.name)

618 619 620 621
    def extra_repr(self):
        return 'kernel_size={ksize}, stride={stride}, padding={padding}'.format(
            **self.__dict__)

622

Z
zhiboniu 已提交
623
class AdaptiveAvgPool1D(Layer):
624
    r"""
625 626

    This operation applies a 1D adaptive average pooling over an input signal composed
627
    of several input planes, based on the input, output_size, return_mask parameters.
628 629 630 631 632 633 634 635
    Input(X) and output(Out) are in NCL format, where N is batch
    size, C is the number of channels, L is the length of the feature.
    The output tensor shape will be [N, C, output_size].

    For average adaptive pool1d:

    ..  math::

W
Wei Shengyu 已提交
636
        lstart &= floor(i * L_{in} / L_{out})
637

W
Wei Shengyu 已提交
638
        lend &= ceil((i + 1) * L_{in} / L_{out})
639

W
Wei Shengyu 已提交
640
        Output(i) &= \frac{ \sum Input[lstart:lend]}{lend - lstart}
641

W
Wei Shengyu 已提交
642 643 644 645
    Parameters:
        output_size(int): The target output size. It must be an integer.
        name(str, optional): For detailed information, please refer to :ref:`api_guide_Name`.
            Usually name is no need to set and None by default.
646

647
    Returns:
W
Wei Shengyu 已提交
648
        A callable object of AdaptiveAvgPool1D.
649

650
    Raises:
651
        ValueError: 'output_size' should be an integer.
652 653

    Shape:
W
Wei Shengyu 已提交
654 655 656 657
        - x(Tensor): 3-D tensor. The input tensor of adaptive avg pool1d operator, which is a 3-D tensor.
          The data type can be float32, float64.
        - output(Tensor): 3-D tensor. The output tensor of adaptive avg pool1d operator, which is a 3-D tensor.
          The data type is same as input x.
658

659 660
    Examples:
        .. code-block:: python
661

W
Wei Shengyu 已提交
662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681
            # average adaptive pool1d
            # suppose input data in shape of [N, C, L], `output_size` is m or [m],
            # output shape is [N, C, m], adaptive pool divide L dimension
            # of input data into m grids averagely and performs poolings in each
            # grid to get output.
            # adaptive max pool performs calculations as follow:
            #
            #     for i in range(m):
            #         lstart = floor(i * L / m)
            #         lend = ceil((i + 1) * L / m)
            #         output[:, :, i] = sum(input[:, :, lstart: lend])/(lend - lstart)
            #
            import paddle
            import paddle.nn as nn
            import numpy as np

            data = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32]).astype(np.float32))
            AdaptiveAvgPool1D = nn.AdaptiveAvgPool1D(output_size=16)
            pool_out = AdaptiveAvgPool1D(data)
            # pool_out shape: [1, 3, 16]
682 683
    """

684
    def __init__(self, output_size, name=None):
C
cnn 已提交
685
        super(AdaptiveAvgPool1D, self).__init__()
686
        self.output_size = output_size
687 688
        self.name = name

689 690 691
    def forward(self, input):
        return F.adaptive_avg_pool1d(input, self.output_size, self.name)

692 693 694
    def extra_repr(self):
        return 'output_size={}'.format(self.output_size)

695

Z
zhiboniu 已提交
696
class AdaptiveAvgPool2D(Layer):
697
    r"""
698 699 700 701 702 703 704 705

    This operation applies 2D adaptive avg pooling on input tensor. The h and w dimensions
    of the output tensor are determined by the parameter output_size.

    For avg adaptive pool2d:

    ..  math::

W
Wei Shengyu 已提交
706
        hstart &= floor(i * H_{in} / H_{out})
707

W
Wei Shengyu 已提交
708
        hend &= ceil((i + 1) * H_{in} / H_{out})
709

W
Wei Shengyu 已提交
710
        wstart &= floor(j * W_{in} / W_{out})
711

W
Wei Shengyu 已提交
712
        wend &= ceil((j + 1) * W_{in} / W_{out})
713

W
Wei Shengyu 已提交
714
        Output(i ,j) &= \frac{\sum Input[hstart:hend, wstart:wend]}{(hend - hstart) * (wend - wstart)}
715 716 717


    Parameters:
W
Wei Shengyu 已提交
718
        output_size(int|list|tuple): The pool kernel size. If pool kernel size is a tuple or list,
719 720
            it must contain two element, (H, W). H and W can be either a int, or None which means
            the size will be the same as that of the input.
W
Wei Shengyu 已提交
721
        data_format(str, optional): The data format of the input and output data. An optional string
722 723
            from: "NCHW", "NHWC". The default is "NCHW". When it is "NCHW", the data is stored in
            the order of: [batch_size, input_channels, input_height, input_width].
W
Wei Shengyu 已提交
724 725
        name(str, optional): For detailed information, please refer to :ref:`api_guide_Name`.
            Usually name is no need to set and None by default.
726 727

    Shape:
W
Wei Shengyu 已提交
728 729 730 731
        - x(Tensor): The input tensor of adaptive avg pool2d operator, which is a 4-D tensor.
          The data type can be float32, float64.
        - output(Tensor): The output tensor of adaptive avg pool2d operator, which is a 4-D tensor.
          The data type is same as input x.
732 733

    Returns:
C
cnn 已提交
734
        A callable object of AdaptiveAvgPool2D.
735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755

    Examples:
        .. code-block:: python

            # adaptive avg pool2d
            # suppose input data in shape of [N, C, H, W], `output_size` is [m, n],
            # output shape is [N, C, m, n], adaptive pool divide H and W dimensions
            # of input data into m * n grids averagely and performs poolings in each
            # grid to get output.
            # adaptive avg pool performs calculations as follow:
            #
            #     for i in range(m):
            #         for j in range(n):
            #             hstart = floor(i * H / m)
            #             hend = ceil((i + 1) * H / m)
            #             wstart = floor(i * W / n)
            #             wend = ceil((i + 1) * W / n)
            #             output[:, :, i, j] = avg(input[:, :, hstart: hend, wstart: wend])
            #
            import paddle
            import numpy as np
756

757 758 759
            input_data = np.random.rand(2, 3, 32, 32)
            x = paddle.to_tensor(input_data)
            # x.shape is [2, 3, 32, 32]
C
cnn 已提交
760
            adaptive_avg_pool = paddle.nn.AdaptiveAvgPool2D(output_size=3)
761 762 763 764 765
            pool_out = adaptive_avg_pool(x = x)
            # pool_out.shape is [2, 3, 3, 3]
    """

    def __init__(self, output_size, data_format="NCHW", name=None):
C
cnn 已提交
766
        super(AdaptiveAvgPool2D, self).__init__()
767 768 769 770 771 772 773 774 775 776 777
        self._output_size = output_size
        self._data_format = data_format
        self._name = name

    def forward(self, x):
        return F.adaptive_avg_pool2d(
            x,
            output_size=self._output_size,
            data_format=self._data_format,
            name=self._name)

778 779 780
    def extra_repr(self):
        return 'output_size={}'.format(self._output_size)

781

Z
zhiboniu 已提交
782
class AdaptiveAvgPool3D(Layer):
783
    r"""
784 785 786 787 788 789 790 791

    This operation applies 3D adaptive avg pooling on input tensor. The h and w dimensions
    of the output tensor are determined by the parameter output_size.

    For avg adaptive pool3d:

    ..  math::

W
Wei Shengyu 已提交
792
        dstart &= floor(i * D_{in} / D_{out})
793

W
Wei Shengyu 已提交
794
        dend &= ceil((i + 1) * D_{in} / D_{out})
795

W
Wei Shengyu 已提交
796
        hstart &= floor(j * H_{in} / H_{out})
797

W
Wei Shengyu 已提交
798
        hend &= ceil((j + 1) * H_{in} / H_{out})
799

W
Wei Shengyu 已提交
800
        wstart &= floor(k * W_{in} / W_{out})
801

W
Wei Shengyu 已提交
802
        wend &= ceil((k + 1) * W_{in} / W_{out})
803

W
Wei Shengyu 已提交
804 805
        Output(i ,j, k) &= \frac{\sum Input[dstart:dend, hstart:hend, wstart:wend]}
            {(dend - dstart) * (hend - hstart) * (wend - wstart)}
806 807 808


    Parameters:
W
Wei Shengyu 已提交
809
        output_size(int|list|tuple): The pool kernel size. If pool kernel size is a tuple or list,
810 811
            it must contain three elements, (D, H, W). D, H and W can be either a int, or None which means
            the size will be the same as that of the input.
W
Wei Shengyu 已提交
812
        data_format(str, optional): The data format of the input and output data. An optional string
813 814
            from: "NCDHW", "NDHWC". The default is "NCDHW". When it is "NCDHW", the data is stored in
            the order of: [batch_size, input_channels, input_depth, input_height, input_width].
W
Wei Shengyu 已提交
815 816
        name(str, optional): For detailed information, please refer to :ref:`api_guide_Name`.
            Usually name is no need to set and None by default.
817
    Shape:
W
Wei Shengyu 已提交
818 819 820 821
        - x(Tensor): The input tensor of adaptive avg pool3d operator, which is a 5-D tensor.
          The data type can be float32, float64\.
        - output(Tensor): The output tensor of adaptive avg pool3d operator, which is a 5-D tensor.
          The data type is same as input x.
822 823

    Returns:
C
cnn 已提交
824
        A callable object of AdaptiveAvgPool3D.
825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848

    Examples:
        .. code-block:: python

            # adaptive avg pool3d
            # suppose input data in shape of [N, C, D, H, W], `output_size` is [l, m, n],
            # output shape is [N, C, l, m, n], adaptive pool divide D, H and W dimensions
            # of input data into l * m * n grids averagely and performs poolings in each
            # grid to get output.
            # adaptive avg pool performs calculations as follow:
            #
            #     for i in range(l):
            #         for j in range(m):
            #             for k in range(n):
            #                 dstart = floor(i * D / l)
            #                 dend = ceil((i + 1) * D / l)
            #                 hstart = floor(j * H / m)
            #                 hend = ceil((j + 1) * H / m)
            #                 wstart = floor(k * W / n)
            #                 wend = ceil((k + 1) * W / n)
            #                 output[:, :, i, j, k] =
            #                     avg(input[:, :, dstart:dend, hstart: hend, wstart: wend])
            import paddle
            import numpy as np
849

850 851 852
            input_data = np.random.rand(2, 3, 8, 32, 32)
            x = paddle.to_tensor(input_data)
            # x.shape is [2, 3, 8, 32, 32]
C
cnn 已提交
853
            adaptive_avg_pool = paddle.nn.AdaptiveAvgPool3D(output_size=3)
854 855 856 857 858
            pool_out = adaptive_avg_pool(x = x)
            # pool_out = [2, 3, 3, 3, 3]
    """

    def __init__(self, output_size, data_format="NCDHW", name=None):
C
cnn 已提交
859
        super(AdaptiveAvgPool3D, self).__init__()
860 861 862 863 864 865 866 867 868 869 870
        self._output_size = output_size
        self._data_format = data_format
        self._name = name

    def forward(self, x):
        return F.adaptive_avg_pool3d(
            x,
            output_size=self._output_size,
            data_format=self._data_format,
            name=self._name)

871 872 873
    def extra_repr(self):
        return 'output_size={}'.format(self._output_size)

874

Z
zhiboniu 已提交
875
class AdaptiveMaxPool1D(Layer):
876 877 878
    """

    This operation applies a 1D adaptive max pooling over an input signal composed
879
    of several input planes, based on the input, output_size, return_mask parameters.
880 881 882 883 884 885 886 887
    Input(X) and output(Out) are in NCL format, where N is batch
    size, C is the number of channels, L is the length of the feature.
    The output tensor shape will be [N, C, output_size].

    For max adaptive pool1d:

    ..  math::

W
Wei Shengyu 已提交
888
        lstart &= floor(i * L_{in} / L_{out})
889

W
Wei Shengyu 已提交
890
        lend &= ceil((i + 1) * L_{in} / L_{out})
891

W
Wei Shengyu 已提交
892
        Output(i) &= max(Input[lstart:lend])
893

W
Wei Shengyu 已提交
894 895 896 897
    Parameters:
        output_size(int|list|tuple): The pool kernel size. If pool kernel size is a tuple or list,
            it must contain one int.
        return_mask(bool, optional): If true, the index of max pooling point will be returned along
898
            with outputs. It cannot be set in average pooling type. Default False.
W
Wei Shengyu 已提交
899 900
        name(str, optional): For detailed information, please refer to :ref:`api_guide_Name`.
            Usually name is no need to set and None by default.
901
    Returns:
W
Wei Shengyu 已提交
902
        A callable object of AdaptiveMaxPool1D.
903 904 905 906 907

    Raises:
        ValueError: 'pool_size' should be a integer or list or tuple with length as 1.

    Shape:
W
Wei Shengyu 已提交
908 909 910 911
        - x(Tensor): The input tensor of adaptive max pool1d operator, which is a 3-D tensor.
          The data type can be float32, float64.
        - output(Tensor): The output tensor of adaptive max pool1d operator, which is a 3-D tensor.
          The data type is same as input x.
912 913 914 915

    Examples:
        .. code-block:: python

W
Wei Shengyu 已提交
916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940
            # max adaptive pool1d
            # suppose input data in shape of [N, C, L], `output_size` is m or [m],
            # output shape is [N, C, m], adaptive pool divide L dimension
            # of input data into m grids averagely and performs poolings in each
            # grid to get output.
            # adaptive max pool performs calculations as follow:
            #
            #     for i in range(m):
            #         lstart = floor(i * L / m)
            #         lend = ceil((i + 1) * L / m)
            #         output[:, :, i] = max(input[:, :, lstart: lend])
            #
            import paddle
            import paddle.nn as nn
            import numpy as np

            data = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32]).astype(np.float32))
            AdaptiveMaxPool1D = nn.AdaptiveMaxPool1D(output_size=16)
            pool_out = AdaptiveMaxPool1D(data)
            # pool_out shape: [1, 3, 16]

            # for return_mask = true
            AdaptiveMaxPool1D = nn.AdaptiveMaxPool1D(output_size=16, return_mask=True)
            pool_out, indices = AdaptiveMaxPool1D(data)
            # pool_out shape: [1, 3, 16], indices shape: [1, 3, 16]
941 942 943

    """

944
    def __init__(self, output_size, return_mask=False, name=None):
C
cnn 已提交
945
        super(AdaptiveMaxPool1D, self).__init__()
946
        self.output_size = output_size
947
        self.return_mask = return_mask
948 949 950
        self.name = name

    def forward(self, input):
951 952
        return F.adaptive_max_pool1d(input, self.output_size, self.return_mask,
                                     self.name)
953

954 955 956 957
    def extra_repr(self):
        return 'output_size={}, return_mask={}'.format(self.output_size,
                                                       self.return_mask)

958

Z
zhiboniu 已提交
959
class AdaptiveMaxPool2D(Layer):
960 961
    """
    This operation applies 2D adaptive max pooling on input tensor. The h and w dimensions
W
Wei Shengyu 已提交
962 963
    of the output tensor are determined by the parameter output_size. The difference between adaptive pooling and
    pooling is adaptive one focus on the output size.
964

965
    For adaptive max pool2d:
966

967
    ..  math::
968

W
Wei Shengyu 已提交
969
        hstart &= floor(i * H_{in} / H_{out})
970

W
Wei Shengyu 已提交
971
        hend &= ceil((i + 1) * H_{in} / H_{out})
972

W
Wei Shengyu 已提交
973
        wstart &= floor(j * W_{in} / W_{out})
974

W
Wei Shengyu 已提交
975
        wend &= ceil((j + 1) * W_{in} / W_{out})
976

W
Wei Shengyu 已提交
977
        Output(i ,j) &= max(Input[hstart:hend, wstart:wend])
978

979
    Parameters:
W
Wei Shengyu 已提交
980 981 982 983 984 985 986
        output_size(int|list|tuple): The pool kernel size. If pool kernel size is a tuple or list, it must contain
            two element, (H, W). H and W can be either a int, or None which means the size will be the same as that of
            the input.
        return_mask(bool, optional): If true, the index of max pooling point will be returned along with outputs.
            It cannot be set in average pooling type. Default False.
        name(str, optional): For detailed information, please refer to :ref:`api_guide_Name`.
            Usually name is no need to set and None by default.
987
    Shape:
W
Wei Shengyu 已提交
988 989 990 991
        - x(Tensor): The input tensor of adaptive max pool2d operator, which is a 4-D tensor.
          The data type can be float32, float64.
        - output(Tensor): The output tensor of adaptive max pool2d operator, which is a 4-D tensor.
          The data type is same as input x.
D
Double_V 已提交
992

993
    Returns:
C
cnn 已提交
994
        A callable object of AdaptiveMaxPool2D.
995 996
    Examples:
        .. code-block:: python
997

998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014
            # adaptive max pool2d
            # suppose input data in shape of [N, C, H, W], `output_size` is [m, n],
            # output shape is [N, C, m, n], adaptive pool divide H and W dimensions
            # of input data into m * n grids averagely and performs poolings in each
            # grid to get output.
            # adaptive max pool performs calculations as follow:
            #
            #     for i in range(m):
            #         for j in range(n):
            #             hstart = floor(i * H / m)
            #             hend = ceil((i + 1) * H / m)
            #             wstart = floor(i * W / n)
            #             wend = ceil((i + 1) * W / n)
            #             output[:, :, i, j] = max(input[:, :, hstart: hend, wstart: wend])
            #
            import paddle
            import numpy as np
1015

1016 1017
            input_data = np.random.rand(2, 3, 32, 32)
            x = paddle.to_tensor(input_data)
1018
            adaptive_max_pool = paddle.nn.AdaptiveMaxPool2D(output_size=3, return_mask=True)
1019 1020 1021
            pool_out, indices = adaptive_max_pool(x = x)
    """

1022
    def __init__(self, output_size, return_mask=False, name=None):
C
cnn 已提交
1023
        super(AdaptiveMaxPool2D, self).__init__()
1024
        self._output_size = output_size
1025
        self._return_mask = return_mask
1026 1027 1028 1029 1030 1031
        self._name = name

    def forward(self, x):
        return F.adaptive_max_pool2d(
            x,
            output_size=self._output_size,
1032
            return_mask=self._return_mask,
1033 1034
            name=self._name)

1035 1036 1037 1038
    def extra_repr(self):
        return 'output_size={}, return_mask={}'.format(self._output_size,
                                                       self._return_mask)

1039

Z
zhiboniu 已提交
1040
class AdaptiveMaxPool3D(Layer):
1041
    """
W
Wei Shengyu 已提交
1042 1043 1044
    This operation applies 3D adaptive max pooling on input tensor. The h and w dimensions of the output tensor are
    determined by the parameter output_size. The difference between adaptive pooling and pooling is adaptive one focus
    on the output size.
1045

1046
    For adaptive max pool3d:
1047

1048
    ..  math::
1049

W
Wei Shengyu 已提交
1050
        dstart &= floor(i * D_{in} / D_{out})
1051

W
Wei Shengyu 已提交
1052
        dend &= ceil((i + 1) * D_{in} / D_{out})
1053

W
Wei Shengyu 已提交
1054
        hstart &= floor(j * H_{in} / H_{out})
1055

W
Wei Shengyu 已提交
1056
        hend &= ceil((j + 1) * H_{in} / H_{out})
1057

W
Wei Shengyu 已提交
1058
        wstart &= floor(k * W_{in} / W_{out})
1059

W
Wei Shengyu 已提交
1060
        wend &= ceil((k + 1) * W_{in} / W_{out})
1061

W
Wei Shengyu 已提交
1062
        Output(i ,j, k) &= max(Input[dstart:dend, hstart:hend, wstart:wend])
1063

1064
    Parameters:
W
Wei Shengyu 已提交
1065 1066 1067 1068 1069 1070 1071
        output_size(int|list|tuple): The pool kernel size. If pool kernel size is a tuple or list, it must contain
            three elements, (D, H, W). D, H and W can be either a int, or None which means the size will be the same as
            that of the input.
        return_mask(bool, optional): If true, the index of max pooling point will be returned along with outputs.
            Default False.
        name(str, optional): For detailed information, please refer to :ref:`api_guide_Name`.
            Usually name is no need to set and None by default.
1072
    Shape:
W
Wei Shengyu 已提交
1073 1074 1075 1076 1077
        - x(Tensor): The input tensor of adaptive max pool3d operator, which is a 5-D tensor.
          The data type can be float32, float64.
        - output(Tensor): The output tensor of adaptive max pool3d operator, which is a 5-D tensor.
          The data type is same as input x.

1078
    Returns:
C
cnn 已提交
1079
        A callable object of AdaptiveMaxPool3D.
1080 1081
    Examples:
        .. code-block:: python
1082

1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102
            # adaptive max pool3d
            # suppose input data in shape of [N, C, D, H, W], `output_size` is [l, m, n],
            # output shape is [N, C, l, m, n], adaptive pool divide D, H and W dimensions
            # of input data into l * m * n grids averagely and performs poolings in each
            # grid to get output.
            # adaptive max pool performs calculations as follow:
            #
            #     for i in range(l):
            #         for j in range(m):
            #             for k in range(n):
            #                 dstart = floor(i * D / l)
            #                 dend = ceil((i + 1) * D / l)
            #                 hstart = floor(j * H / m)
            #                 hend = ceil((j + 1) * H / m)
            #                 wstart = floor(k * W / n)
            #                 wend = ceil((k + 1) * W / n)
            #                 output[:, :, i, j, k] =
            #                     max(input[:, :, dstart:dend, hstart: hend, wstart: wend])
            import paddle
            import numpy as np
1103

1104 1105
            input_data = np.random.rand(2, 3, 8, 32, 32)
            x = paddle.to_tensor(input_data)
C
cnn 已提交
1106
            pool = paddle.nn.AdaptiveMaxPool3D(output_size=4)
1107 1108
            out = pool(x)
            # out shape: [2, 3, 4, 4, 4]
1109
            pool = paddle.nn.AdaptiveMaxPool3D(output_size=3, return_mask=True)
1110
            out, indices = pool(x)
1111
            # out shape: [2, 3, 4, 4, 4], indices shape: [2, 3, 4, 4, 4]
D
Double_V 已提交
1112

1113 1114
    """

1115
    def __init__(self, output_size, return_mask=False, name=None):
C
cnn 已提交
1116
        super(AdaptiveMaxPool3D, self).__init__()
1117
        self._output_size = output_size
1118
        self._return_mask = return_mask
1119 1120 1121 1122 1123 1124
        self._name = name

    def forward(self, x):
        return F.adaptive_max_pool3d(
            x,
            output_size=self._output_size,
1125
            return_mask=self._return_mask,
1126
            name=self._name)
1127 1128 1129 1130

    def extra_repr(self):
        return 'output_size={}, return_mask={}'.format(self._output_size,
                                                       self._return_mask)
1131 1132


1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214
class MaxUnPool1D(Layer):
    """
    This API implements max unpooling 1d opereation.

    `max_unpool1d` accepts the output of `max_pool1d` as input, 
    including the indices of the maximum value and calculate the partial inverse. 
    All non-maximum values ​​are set to zero.

    - Input: :math:`(N, C, L_{in})`
    - Output: :math:`(N, C, L_{out})`, where
    
    .. math::
        L_{out} = (L_{in} - 1) * stride - 2 * padding + kernel\_size

    or as given by :attr:`output_size` in the call operator.
    
    Parameters:
        kernel_size (int|list|tuple): The unpool kernel size. If unpool kernel size is a tuple or list,
            it must contain an integer.
        stride (int|list|tuple): The unpool stride size. If unpool stride size is a tuple or list,
            it must contain an integer.
        padding (int | tuple): Padding that was added to the input.
        output_size(list|tuple, optional): The target output size. If output_size is not specified, 
                           the actual output shape will be automatically calculated by (input_shape,
                           kernel_size, stride, padding).
        data_format (string): The data format of the input and output data.
                        The default is `"NCL"`. When it is `"NCL"`, the data is stored in the order of:
                        `[batch_size, input_channels, input_length]`.
        name(str, optional): For detailed information, please refer
                             to :ref:`api_guide_Name`. Usually name is no need to set and
                             None by default.


    Returns:
        A callable object of MaxUnPool1D.

    Examples:
        .. code-block:: python
        
            import paddle
            import paddle.nn.functional as F
            import numpy as np

            data = paddle.rand(shape=[1, 3, 16])
            pool_out, indices = F.max_pool1d(data, kernel_size=2, stride=2, padding=0, return_mask=True)
            # pool_out shape: [1, 3, 8],  indices shape: [1, 3, 8]
            Unpool1D = paddle.nn.MaxUnPool1D(kernel_size=2, padding=0)
            unpool_out = Unpool1D(pool_out, indices)
            # unpool_out shape: [1, 3, 16]

    """

    def __init__(self,
                 kernel_size,
                 stride=None,
                 padding=0,
                 data_format="NCL",
                 output_size=None,
                 name=None):
        super(MaxUnPool1D, self).__init__()
        self.ksize = kernel_size
        self.stride = stride
        self.padding = padding
        self.data_format = data_format
        self.output_size = output_size
        self.name = name

    def forward(self, x, indices):
        return F.max_unpool1d(
            x,
            indices,
            kernel_size=self.ksize,
            stride=self.stride,
            padding=self.padding,
            data_format=self.data_format,
            output_size=self.output_size,
            name=self.name)

    def extra_repr(self):
        return 'output_size={}'.format(self.output_size)


1215 1216 1217 1218
class MaxUnPool2D(Layer):
    """
    This API implements max unpooling 2d opereation.

1219 1220 1221
    'max_unpool2d' accepts the output of 'max_unpool2d' as input
    Including the indices of the maximum value and calculating the partial inverse
    All non-maximum values ​​are set to zero.
1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261
    

    Parameters:
        kernel_size (int|list|tuple): The unpool kernel size. If unpool kernel size is a tuple or list,
            it must contain an integer.
        stride (int|list|tuple): The unpool stride size. If unpool stride size is a tuple or list,
            it must contain an integer.
        kernel_size (int|tuple): Size of the max unpooling window.
        padding (int | tuple): Padding that was added to the input.
        output_size(list|tuple, optional): The target output size. If output_size is not specified, 
                           the actual output shape will be automatically calculated by (input_shape,
                           kernel_size, padding).
        name(str, optional): For detailed information, please refer
                             to :ref:`api_guide_Name`. Usually name is no need to set and
                             None by default.


        - Input: :math:`(N, C, H_{in}, W_{in})`
        - Output: :math:`(N, C, H_{out}, W_{out})`, where

          .. math::
            H_{out} = (H_{in} - 1) \times \text{stride[0]} - 2 \times \text{padding[0]} + \text{kernel\_size[0]}

          .. math::
            W_{out} = (W_{in} - 1) \times \text{stride[1]} - 2 \times \text{padding[1]} + \text{kernel\_size[1]}

          or as given by :attr:`output_size` in the call operator

    Returns:
        A callable object of MaxUnPool2D.

            

    Examples:
        .. code-block:: python
        
        import paddle
        import paddle.nn.functional as F
        import numpy as np

1262
        data = paddle.rand(shape=[1,1,7,7])
1263 1264 1265
        pool_out, indices = F.max_pool2d(data, kernel_size=2, stride=2, padding=0, return_mask=True)
        # pool_out shape: [1, 1, 3, 3],  indices shape: [1, 1, 3, 3]
        Unpool2D = paddle.nn.MaxUnPool2D(kernel_size=2, padding=0)
X
xiaoting 已提交
1266
        unpool_out = Unpool2D(pool_out, indices)
1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298
        # unpool_out shape: [1, 1, 6, 6]

    """

    def __init__(self,
                 kernel_size,
                 stride=None,
                 padding=0,
                 data_format="NCHW",
                 output_size=None,
                 name=None):
        super(MaxUnPool2D, self).__init__()
        self.ksize = kernel_size
        self.stride = stride
        self.padding = padding
        self.data_format = data_format
        self.output_size = output_size
        self.name = name

    def forward(self, x, indices):
        return F.max_unpool2d(
            x,
            indices,
            kernel_size=self.ksize,
            stride=self.stride,
            padding=self.padding,
            data_format=self.data_format,
            output_size=self.output_size,
            name=self.name)

    def extra_repr(self):
        return 'output_size={}'.format(self.output_size)
1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387


class MaxUnPool3D(Layer):
    """
    This API implements max unpooling 3d opereation.

    `max_unpool3d` accepts the output of `max_pool3d` as input, 
    including the indices of the maximum value and calculate the partial inverse. 
    All non-maximum values ​​are set to zero.

    - Input: :math:`(N, C, D_{in}, H_{in}, W_{in})`
    - Output: :math:`(N, C, D_{out}, H_{out}, W_{out})`, where
    
    .. math::
        D_{out} = (D_{in} - 1) * stride[0] - 2 * padding[0] + kernel\_size[0]

    .. math::
        H_{out} = (H_{in} - 1) * stride[1] - 2 * padding[1] + kernel\_size[1]

    .. math::
        W_{out} = (W_{in} - 1) * stride[2] - 2 * padding[2] + kernel\_size[2]

    or as given by :attr:`output_size` in the call operator

    
    Parameters:
        kernel_size (int|list|tuple): The unpool kernel size. If unpool kernel size is a tuple or list,
            it must contain an integer.
        stride (int|list|tuple): The unpool stride size. If unpool stride size is a tuple or list,
            it must contain an integer.
        padding (int | tuple): Padding that was added to the input.
        output_size(list|tuple, optional): The target output size. If output_size is not specified, 
                           the actual output shape will be automatically calculated by (input_shape,
                           kernel_size, stride, padding).
        data_format (string): The data format of the input and output data.
                        The default is `"NCDHW"`. When it is `"NCDHW"`, the data is stored in the order of:
                        `[batch_size, input_channels, input_depth, input_height, input_width]`.
        name(str, optional): For detailed information, please refer
                             to :ref:`api_guide_Name`. Usually name is no need to set and
                             None by default.


    Returns:
        A callable object of MaxUnPool3D.

    Examples:
        .. code-block:: python
        
            import paddle
            import paddle.nn.functional as F
            import numpy as np

            data = paddle.rand(shape=[1, 1, 4, 4, 6])
            pool_out, indices = F.max_pool3d(data, kernel_size=2, stride=2, padding=0, return_mask=True)
            # pool_out shape: [1, 1, 2, 2, 3],  indices shape: [1, 1, 2, 2, 3]
            Unpool3D = paddle.nn.MaxUnPool3D(kernel_size=2, padding=0)
            unpool_out = Unpool3D(pool_out, indices)
            # unpool_out shape: [1, 1, 4, 4, 6]

    """

    def __init__(self,
                 kernel_size,
                 stride=None,
                 padding=0,
                 data_format="NCDHW",
                 output_size=None,
                 name=None):
        super(MaxUnPool3D, self).__init__()
        self.ksize = kernel_size
        self.stride = stride
        self.padding = padding
        self.data_format = data_format
        self.output_size = output_size
        self.name = name

    def forward(self, x, indices):
        return F.max_unpool3d(
            x,
            indices,
            kernel_size=self.ksize,
            stride=self.stride,
            padding=self.padding,
            data_format=self.data_format,
            output_size=self.output_size,
            name=self.name)

    def extra_repr(self):
        return 'output_size={}'.format(self.output_size)