pooling.py 62.9 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
#   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.

# TODO: define pooling functions
16
from ...fluid import core
17 18 19
from ...fluid.framework import in_dygraph_mode
from ...fluid.layers import utils, LayerHelper, unsqueeze, squeeze
from ...fluid.data_feeder import check_type, check_variable_and_dtype
20

21
__all__ = [
22
    'avg_pool1d',
23 24
    'avg_pool2d',
    'avg_pool3d',
25
    'max_pool1d',
26 27
    'max_pool2d',
    'max_pool3d',
28 29 30
    'adaptive_avg_pool1d',
    'adaptive_avg_pool2d',
    'adaptive_avg_pool3d',
31 32 33
    'adaptive_max_pool1d',
    'adaptive_max_pool2d',
    'adaptive_max_pool3d',
34 35 36
]


37 38 39 40 41
def _is_list_or_tuple(input):
    return isinstance(input, (list, tuple))


def _check_input(x, dimension):
42
    if len(x.shape) != dimension:
43 44 45
        raise ValueError(
            "Excepted Input X is {}-D tensor, but received {}-D {}".format(
                dimension, len(x.shape), type(x)))
46 47


48
def _check_instance(x, x_name, types=(int, float)):
49 50 51 52 53 54

    if not isinstance(x, types):
        raise ValueError("Excepted {} type for {} but received type: {}. ".
                         format(types, x_name, type(x)))


55 56 57
def _zero_padding_in_batch_and_channel(padding, channel_last):
    if channel_last:
        return list(padding[0]) == [0, 0] and list(padding[-1]) == [0, 0]
58
    else:
59
        return list(padding[0]) == [0, 0] and list(padding[1]) == [0, 0]
60 61


62 63 64 65
def _exclude_padding_in_batch_and_channel(padding, channel_last):
    padding_ = padding[1:-1] if channel_last else padding[2:]
    padding_ = [elem for pad_a_dim in padding_ for elem in pad_a_dim]
    return padding_
66 67


68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89
def _channel_last(data_format, num_dims):
    if num_dims == 1:
        if data_format not in ['NCL', 'NLC']:
            raise ValueError(
                "Attr(data_format) should be 'NCL' or 'NLC'. Received "
                "Attr(data_format): %s" % str(data_format))
        else:
            return True if data_format == "NLC" else False
    if num_dims == 2:
        if data_format not in ['NCHW', 'NHWC']:
            raise ValueError(
                "Attr(data_format) should be 'NCHW' or 'NHWC'. Received "
                "Attr(data_format): %s" % str(data_format))
        else:
            return True if data_format == "NHWC" else False
    if num_dims == 3:
        if data_format not in ['NCDHW', 'NDHWC']:
            raise ValueError(
                "Attr(data_format) should be 'NCDHW' or 'NDHWC'. Received "
                "Attr(data_format): %s" % str(data_format))
        else:
            return True if data_format == "NDHWC" else False
90 91


92 93 94 95 96 97 98 99 100
def _update_padding_nd(padding, num_dims, channel_last=False, ceil_mode=False):
    if isinstance(padding, str):
        padding = padding.upper()
        if padding not in ["SAME", "VALID"]:
            raise ValueError(
                "Unknown padding: '{}'. It can only be 'SAME' or 'VALID'.".
                format(padding))
        if padding == "VALID":
            if ceil_mode != False:
101
                raise ValueError(
102 103 104 105 106 107 108 109 110 111 112 113 114 115
                    "When Attr(padding) is \"VALID\", Attr(ceil_mode) must be False. "
                    "Received ceil_mode: True.")

            padding_algorithm = "VALID"
            padding = [0] * num_dims
        else:
            padding_algorithm = "SAME"
            padding = [0] * num_dims
    elif _is_list_or_tuple(padding):
        # for padding like
        # [(pad_before, pad_after), (pad_before, pad_after), ...]
        # padding for batch_dim and channel_dim included
        if len(padding) == 2 + num_dims and _is_list_or_tuple(padding[0]):
            if not _zero_padding_in_batch_and_channel(padding, channel_last):
116
                raise ValueError(
117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136
                    "Non-zero padding({}) in the batch or channel dimensions "
                    "is not supported.".format(padding))
            padding_algorithm = "EXPLICIT"
            padding = _exclude_padding_in_batch_and_channel(padding,
                                                            channel_last)
            if utils._is_symmetric_padding(padding, num_dims):
                padding = padding[0::2]
        # for padding like [pad_before, pad_after, pad_before, pad_after, ...]
        elif len(padding) == 2 * num_dims and isinstance(padding[0], int):
            padding_algorithm = "EXPLICIT"
            padding = utils.convert_to_list(padding, 2 * num_dims, 'padding')
            if utils._is_symmetric_padding(padding, num_dims):
                padding = padding[0::2]
        # for padding like [pad_d1, pad_d2, ...]
        elif len(padding) == num_dims and isinstance(padding[0], int):
            padding_algorithm = "EXPLICIT"
            padding = utils.convert_to_list(padding, num_dims, 'padding')
        else:
            raise ValueError("Invalid padding: {}".format(padding))
    # for integer padding
137
    else:
138 139 140 141
        padding_algorithm = "EXPLICIT"
        padding = utils.convert_to_list(padding, num_dims, 'padding')
    return padding, padding_algorithm

142

143 144 145 146 147 148 149 150 151 152
def _expand_low_nd_padding(padding):
    #1d to 2d fake input
    if len(padding) == 2:
        padding = [0] * 2 + padding
    elif len(padding) == 1:
        padding = [0] + padding
    else:
        raise ValueError(
            "The size of padding's dimmention should be 1 or 2. But got padding={}".
            format(padding))
153 154 155 156 157 158 159
    return padding


def avg_pool1d(x,
               kernel_size,
               stride=None,
               padding=0,
160
               exclusive=True,
161 162
               ceil_mode=False,
               name=None):
D
Double_V 已提交
163
    """
164 165
    This API implements average pooling 1d operation,
    See more details in :ref:`api_nn_pooling_AvgPool1d` .
166 167 168 169

    Args:
        x (Tensor): The input tensor of pooling operator which is a 3-D tensor with
                          shape [N, C, L]. where `N` is batch size, `C` is the number of channels,
170
                          `L` is the length of the feature. The data type is float32 or float64.
171
        kernel_size (int|list|tuple): The pool kernel size. If pool kernel size is a tuple or list,
172
            it must contain an integer.
173
        stride (int|list|tuple): The pool stride size. If pool stride size is a tuple or list,
174 175 176 177 178 179 180 181
            it must contain an integer.
        padding (string|int|list|tuple): The padding size. Padding could be in one of the following forms.
            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.
182
        exclusive (bool): Whether to exclude padding points in average pooling
183
                          mode, default is `True`.
184
        ceil_mode (bool): ${ceil_mode_comment}Whether to use the ceil function to calculate output height and width.
185
            If it is set to False, the floor function will be used. The default value is False.
186 187 188 189 190 191 192 193 194
        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:
        Tensor: The output tensor of pooling result. The data type is same as input tensor.

    Raises:
        ValueError: If `padding` is a string, but not "SAME" or "VALID".
        ValueError: If `padding` is "VALID", but `ceil_mode` is True.
195 196
        ValueError: If `padding` is a list or tuple but its length is greater than 1.
        ShapeError: If the input is not a 3-D tensor.
197 198 199 200 201 202 203
        ShapeError: If the output's shape calculated is not greater than 0.

    Examples:
        .. code-block:: python
          import paddle
          import paddle.nn.functional as F
          data = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32]).astype(np.float32))
204 205
          out = F.avg_pool1d(data, kernel_size=2, stride=2, padding=0)
          # out shape: [1, 3, 16]
206 207 208
    """
    """NCL to NCHW"""
    data_format = "NCHW"
209 210
    check_variable_and_dtype(x, 'x', ['float32', 'float64'], 'avg_pool1d')
    _check_input(x, 3)
211
    x = unsqueeze(x, [2])
212
    kernel_size = utils.convert_to_list(kernel_size, 1, 'kernel_size')
213 214 215 216 217 218 219
    kernel_size = [1] + kernel_size
    if stride is None:
        stride = kernel_size
    else:
        stride = utils.convert_to_list(stride, 1, 'pool_stride')
        stride = [1] + stride

220 221 222
    channel_last = _channel_last("NCL", 1)
    padding, padding_algorithm = _update_padding_nd(
        padding, 1, channel_last=channel_last, ceil_mode=ceil_mode)
223

224 225
    # use 2d to implenment 1d should expand padding in advance.
    padding = _expand_low_nd_padding(padding)
226 227 228 229 230

    if in_dygraph_mode():
        output = core.ops.pool2d(
            x, 'pooling_type', 'avg', 'ksize', kernel_size, 'global_pooling',
            False, 'strides', stride, 'paddings', padding, 'padding_algorithm',
231
            padding_algorithm, 'use_cudnn', True, 'ceil_mode', ceil_mode,
D
Double_V 已提交
232
            'use_mkldnn', False, 'exclusive', exclusive, 'data_format',
233
            data_format)
234 235 236 237
        return squeeze(output, [2])

    op_type = 'pool2d'
    helper = LayerHelper(op_type, **locals())
238
    dtype = helper.input_dtype(input_param_name='x')
239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254
    pool_out = helper.create_variable_for_type_inference(dtype)

    helper.append_op(
        type=op_type,
        inputs={"X": x},
        outputs={"Out": pool_out},
        attrs={
            "pooling_type": 'avg',
            "ksize": kernel_size,
            "global_pooling": False,
            "strides": stride,
            "paddings": padding,
            "padding_algorithm": padding_algorithm,
            "use_cudnn": True,
            "ceil_mode": ceil_mode,
            "use_mkldnn": False,
255
            "exclusive": exclusive,
256 257 258 259 260 261
            "data_format": data_format,
        })

    return squeeze(pool_out, [2])


262
def avg_pool2d(x,
263 264 265 266
               kernel_size,
               stride=None,
               padding=0,
               ceil_mode=False,
267
               exclusive=True,
268 269
               divisor_override=None,
               data_format="NCHW",
270 271
               name=None):
    """
272 273
    This API implements average pooling 2d operation.
    See more details in :ref:`api_nn_pooling_AvgPool2d` .
D
Double_V 已提交
274

275
    Args:
276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295
        x (Tensor): The input tensor of pooling operator which is a 4-D tensor with
                          shape [N, C, H, W]. The format of input tensor is `"NCHW"` or
                          `"NHWC"`, 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. The data type if float32 or float64.
        kernel_size (int|list|tuple): The pool kernel size. If it is a tuple or list,
            it must contain two integers, (kernel_size_Height, kernel_size_Width).
            Otherwise, the pool kernel size will be a square of an int.
        stride (int|list|tuple): The stride size. If it is a tuple or list,
            it must contain two integers, (stride_Height, stride_Width).
            Otherwise, the stride size will be a square of an int.

        padding (string|int|list|tuple): The padding size. Padding could be in one of the following forms.
            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.
        ceil_mode (bool): when True, will use `ceil` instead of `floor` to compute the output shape
296
        exclusive (bool): Whether to exclude padding points in average pooling
297 298 299 300 301
                          mode, default is `true`.
        divisor_override (float): if specified, it will be used as divisor, otherwise kernel_size will be used. Default None.
        data_format (string): The data format of the input and output data. An optional string 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]`.
302 303 304 305 306 307 308 309 310 311 312 313 314
        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:
        Tensor: The output tensor of pooling result. The data type is same as input tensor.
    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
          import paddle
          import paddle.nn.functional as F
315 316 317 318 319 320 321
          import numpy as np
          # avg pool2d
          x = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32, 32]).astype(np.float32))
          out = F.avg_pool2d(x,
                                kernel_size=2,
                                stride=2, padding=0)
          # out.shape [1, 3, 16, 16]
322
    """
323 324
    check_variable_and_dtype(x, 'x', ['float32', 'float64'], 'avg_pool2d')
    kernel_size = utils.convert_to_list(kernel_size, 2, 'pool_size')
325 326 327
    if stride is None:
        stride = kernel_size
    else:
328
        stride = utils.convert_to_list(stride, 2, 'pool_stride')
329

330 331 332
    channel_last = _channel_last(data_format, 2)
    padding, padding_algorithm = _update_padding_nd(
        padding, 2, channel_last, ceil_mode=ceil_mode)
333 334

    if in_dygraph_mode():
335 336 337 338
        output = core.ops.pool2d(
            x, 'pooling_type', 'avg', 'ksize', kernel_size, 'global_pooling',
            False, 'padding_algorithm', padding_algorithm, 'strides', stride,
            'paddings', padding, 'use_cudnn', True, 'ceil_mode', ceil_mode,
D
Double_V 已提交
339
            'use_mkldnn', False, 'exclusive', exclusive, 'data_format',
340
            data_format)
341 342 343 344 345
        if divisor_override is None:
            return output
        else:
            _check_instance(divisor_override, "divisor_override")
            return output * (kernel_size[0] * kernel_size[1]) / divisor_override
346

347
    op_type = 'pool2d'
348
    helper = LayerHelper(op_type, **locals())
349
    dtype = helper.input_dtype(input_param_name='x')
350 351 352 353 354
    pool_out = helper.create_variable_for_type_inference(dtype)

    helper.append_op(
        type=op_type,
        inputs={"X": x},
355
        outputs={"Out": pool_out},
356
        attrs={
357
            "pooling_type": "avg",
358 359 360 361 362 363 364 365
            "ksize": kernel_size,
            "global_pooling": False,
            "strides": stride,
            "paddings": padding,
            "padding_algorithm": padding_algorithm,
            "use_cudnn": True,
            "ceil_mode": ceil_mode,
            "use_mkldnn": False,
366
            "exclusive": exclusive,
367 368 369
            "data_format": data_format,
        })

370 371 372 373 374
    if divisor_override is None:
        return pool_out
    else:
        _check_instance(divisor_override, "divisor_override")
        return pool_out * (kernel_size[0] * kernel_size[1]) / divisor_override
375 376


377 378 379 380 381
def avg_pool3d(x,
               kernel_size,
               stride=None,
               padding=0,
               ceil_mode=False,
382
               exclusive=True,
383 384 385
               divisor_override=None,
               data_format="NCDHW",
               name=None):
386
    """
387 388
    This API implements average pooling 3d operation.
    See more details in :ref:`api_nn_pooling_AvgPool3d` .
389 390

    Args:
391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408
        x (Tensor): The input tensor of pooling operator, which is a 5-D tensor with
                          shape [N, C, D, H, W], where `N` represents the batch size, `C` represents
                          the number of channels, `D`, `H` and `W` represent the depth, height and width of the feature respectively.
        kernel_size (int|list|tuple): The pool kernel size. If pool kernel size
            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.
        stride (int|list|tuple): The pool stride size. If pool stride size is a tuple or list,
            it must contain three integers, [stride_Depth, stride_Height, stride_Width).
            Otherwise, the pool stride size will be a cube of an int.
        padding (string|int|list|tuple): The padding size. Padding could be in one of the following forms.
            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.
        ceil_mode (bool): ${ceil_mode_comment}
409
        exclusive (bool): Whether to exclude padding points in average pooling
410 411 412 413 414
                          mode, default is True.
        divisor_override (int|float) if specified, it will be used as divisor, otherwise kernel_size will be used. Default None.
        data_format (string): 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]`.
415
        name(str, optional): For detailed information, please refer
416 417
                             to :ref:`api_guide_Name`. Usually name is no need to set and
                             None by default.
418
    Returns:
419
        Tensor: The output tensor of pooling result. The data type is same as input tensor.
420
    Raises:
421 422 423
        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.
424 425
    Examples:
        .. code-block:: python
426 427 428 429 430 431 432 433 434 435
          import paddle.fluid as fluid
          import paddle
          x = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32, 32, 32]).astype(np.float32))
          # avg pool3d
          out = paddle.nn.functional.avg_pool3d(
                                            x,
                                            kernel_size = 2,
                                            stride = 2,
                                            padding=0)
          # out.shape: [1, 3, 16, 16, 16]
436
    """
437 438 439 440 441 442
    check_variable_and_dtype(x, 'x', ['float32', 'float64'], 'max_pool3d')
    kernel_size = utils.convert_to_list(kernel_size, 3, 'pool_size')
    if stride is None:
        stride = kernel_size
    else:
        stride = utils.convert_to_list(stride, 3, 'pool_stride')
443

444 445 446
    channel_last = _channel_last(data_format, 3)
    padding, padding_algorithm = _update_padding_nd(
        padding, 3, channel_last=channel_last, ceil_mode=ceil_mode)
447 448

    if in_dygraph_mode():
449 450 451 452
        output = core.ops.pool3d(
            x, 'pooling_type', 'avg', 'ksize', kernel_size, 'strides', stride,
            'paddings', padding, 'global_pooling', False, 'padding_algorithm',
            padding_algorithm, 'use_cudnn', True, 'ceil_mode', ceil_mode,
D
Double_V 已提交
453
            'use_mkldnn', False, 'exclusive', exclusive, 'data_format',
454
            data_format)
455 456 457 458 459 460
        if divisor_override is None:
            return output
        else:
            _check_instance(divisor_override, "divisor_override")
            return output * (kernel_size[0] * kernel_size[1] *
                             kernel_size[2]) / divisor_override
461

462 463
    op_type = "pool3d"
    helper = LayerHelper(op_type, **locals())
464
    dtype = helper.input_dtype(input_param_name='x')
465 466
    pool_out = helper.create_variable_for_type_inference(dtype)
    outputs = {"Out": pool_out}
467 468

    helper.append_op(
469
        type=op_type,
470 471 472
        inputs={"X": x},
        outputs=outputs,
        attrs={
473 474 475 476 477 478 479 480 481
            "pooling_type": 'avg',
            "ksize": kernel_size,
            "global_pooling": False,
            "strides": stride,
            "paddings": padding,
            "padding_algorithm": padding_algorithm,
            "use_cudnn": True,
            "ceil_mode": ceil_mode,
            "use_mkldnn": False,
482
            "exclusive": exclusive,
483
            "data_format": data_format,
484 485
        })

486 487 488 489 490 491
    if divisor_override is None:
        return pool_out
    else:
        _check_instance(divisor_override, "divisor_override")
        return pool_out * (kernel_size[0] * kernel_size[1] *
                           kernel_size[2]) / divisor_override
492 493


494
def max_pool1d(x,
495 496 497
               kernel_size,
               stride=None,
               padding=0,
498
               return_mask=False,
499 500 501
               ceil_mode=False,
               name=None):
    """
502 503
    This API implements max pooling 1d opereation.
    See more details in :ref:`api_nn_pooling_MaxPool1d` .
504 505

    Args:
506 507 508
        x (Tensor): The input tensor of pooling operator which is a 3-D tensor with
                          shape [N, C, L], where `N` is batch size, `C` is the number of channels,
                          `L` is the length of the feature. The data type if float32 or float64.
509
        kernel_size (int|list|tuple): The pool kernel size. If pool kernel size is a tuple or list,
510
            it must contain an integer.
511
        stride (int|list|tuple): The pool stride size. If pool stride size is a tuple or list,
512 513 514 515 516 517 518 519
            it must contain an integer.
        padding (string|int|list|tuple): The padding size. Padding could be in one of the following forms.
            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.
            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.
520
        return_mask (bool): Whether return the max indices along with the outputs. default is `False`.
521 522
        ceil_mode (bool): 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.
523 524 525 526 527
        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:
        Tensor: The output tensor of pooling result. The data type is same as input tensor.
528

529 530 531
    Raises:
        ValueError: If `padding` is a string, but not "SAME" or "VALID".
        ValueError: If `padding` is "VALID", but `ceil_mode` is True.
532
        ShapeError: If the input is not a 3-D tensor.
533
        ShapeError: If the output's shape calculated is not greater than 0.
534

535 536
    Examples:
        .. code-block:: python
537

538 539
          import paddle
          import paddle.nn.functional as F
540 541 542
          data = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32]).astype(np.float32))
          pool_out = F.max_pool1d(data, kernel_size=2, stride=2, padding=0)
          # pool_out shape: [1, 3, 16]
543
          pool_out, indices = F.max_pool1d(data, kernel_size=2, stride=2, padding=0, return_mask=True)
544
          # pool_out shape: [1, 3, 16],  indices shape: [1, 3, 16]
545
    """
546 547 548 549 550 551
    """NCL to NCHW"""
    data_format = "NCHW"
    check_variable_and_dtype(x, 'x', ['float32', 'float64'], 'max_pool1d')
    _check_input(x, 3)
    x = unsqueeze(x, [2])
    kernel_size = [1] + utils.convert_to_list(kernel_size, 1, 'pool_size')
552 553 554
    if stride is None:
        stride = kernel_size
    else:
555
        stride = [1] + utils.convert_to_list(stride, 1, 'pool_stride')
556

557 558
    padding, padding_algorithm = _update_padding_nd(
        padding, 1, ceil_mode=ceil_mode)
559

560 561
    # use 2d to implenment 1d should expand padding in advance.
    padding = _expand_low_nd_padding(padding)
562 563

    if in_dygraph_mode():
564
        if return_mask:
D
Double_V 已提交
565 566 567 568 569 570
            pool_out = core.ops.max_pool2d_with_index(
                x, 'ksize', kernel_size, 'global_pooling', False, 'strides',
                stride, 'paddings', padding, 'padding_algorithm',
                padding_algorithm, 'use_cudnn', True, 'ceil_mode', ceil_mode,
                'use_mkldnn', False, 'exclusive', True, 'data_format',
                data_format)
571 572 573
            return (squeeze(pool_out[0], [2]),
                    squeeze(pool_out[1],
                            [2])) if return_mask else squeeze(pool_out[0], [2])
D
Double_V 已提交
574 575 576 577 578 579 580 581 582
        else:
            pool_out = core.ops.pool2d(
                x, 'pooling_type', 'max', 'ksize', kernel_size,
                'global_pooling', False, 'padding_algorithm', padding_algorithm,
                'strides', stride, 'paddings', padding, 'use_cudnn', True,
                'ceil_mode', ceil_mode, 'use_mkldnn', False, 'exclusive', True,
                'data_format', data_format)
            return squeeze(pool_out, [2])

583
    op_type = 'max_pool2d_with_index' if return_mask else "pool2d"
584
    helper = LayerHelper(op_type, **locals())
585
    dtype = helper.input_dtype(input_param_name='x')
586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607
    pool_out = helper.create_variable_for_type_inference(dtype)
    mask = helper.create_variable_for_type_inference(dtype)
    outputs = {"Out": pool_out, "Mask": mask}

    helper.append_op(
        type=op_type,
        inputs={"X": x},
        outputs=outputs,
        attrs={
            "pooling_type": 'max',
            "ksize": kernel_size,
            "global_pooling": False,
            "strides": stride,
            "paddings": padding,
            "padding_algorithm": padding_algorithm,
            "use_cudnn": True,
            "ceil_mode": ceil_mode,
            "use_mkldnn": False,
            "exclusive": True,
            "data_format": data_format,
        })

608
    return (squeeze(pool_out, [2]),
609
            squeeze(mask, [2])) if return_mask else squeeze(pool_out, [2])
610 611


612
def max_pool2d(x,
613 614 615
               kernel_size,
               stride=None,
               padding=0,
616
               return_mask=False,
617 618 619 620
               ceil_mode=False,
               data_format="NCHW",
               name=None):
    """
621 622
    This API implements max pooling 2d operation.
    See more details in :ref:`api_nn_pooling_MaxPool2d` .
623 624 625 626 627 628 629 630

    Args:
        x (Tensor): The input tensor of pooling operator which is a 4-D tensor with
                          shape [N, C, H, W]. The format of input tensor is `"NCHW"` or
                          `"NHWC"`, 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. The data type if float32 or float64.
        kernel_size (int|list|tuple): The pool kernel size. If pool kernel size is a tuple or list,
631
            it must contain two integers, (kernel_size_Height, kernel_size_Width).
632 633
            Otherwise, the pool kernel size will be a square of an int.
        stride (int|list|tuple): The pool stride size. If pool stride size is a tuple or list,
634
            it must contain two integers, (stride_Height, stride_Width).
635
            Otherwise, the pool stride size will be a square of an int.
636 637 638 639 640 641 642
        padding (string|int|list|tuple): The padding size. Padding could be in one of the following forms.
            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.
643
        ceil_mode (bool): when True, will use `ceil` instead of `floor` to compute the output shape
644
        return_mask (bool): Whether to return the max indices along with the outputs. Default False, only support `"NCHW"` data format
645
        data_format (string): The data format of the input and output data. An optional string from: `"NCHW"`, `"NHWC"`.
646 647 648 649 650 651 652 653 654 655 656 657 658
                        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.
    Returns:
        Tensor: The output tensor of pooling result. The data type is same as input tensor.
    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
659

660 661 662
          import paddle
          import paddle.nn.functional as F
          import numpy as np
663 664 665
          # max pool2d
          x = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32, 32]).astype(np.float32))
          out = F.max_pool2d(x,
666 667 668
                                kernel_size=2,
                                stride=2, padding=0)
          # output.shape [1, 3, 16, 16]
669
          # for return_mask=True
670 671 672 673
          out, max_indices = F.max_pool2d(x,
                                             kernel_size=2,
                                             stride=2,
                                             padding=0,
674
                                             return_mask=True)
675
          # out.shape [1, 3, 16, 16], max_indices.shape [1, 3, 16, 16],
676
    """
677
    check_variable_and_dtype(x, 'x', ['float32', 'float64'], 'max_pool2d')
678 679 680 681 682 683 684 685 686 687
    kernel_size = utils.convert_to_list(kernel_size, 2, 'pool_size')
    if stride is None:
        stride = kernel_size
    else:
        stride = utils.convert_to_list(stride, 2, 'pool_stride')

    if data_format not in ["NCHW", "NHWC"]:
        raise ValueError(
            "Attr(data_format) should be 'NCHW' or 'NHWC'. Received "
            "Attr(data_format): %s." % str(data_format))
688 689 690 691 692

    channel_last = True if data_format == "NHWC" else False

    padding, padding_algorithm = _update_padding_nd(
        padding, num_dims=2, channel_last=channel_last, ceil_mode=ceil_mode)
693

694
    if data_format == "NHWC" and return_mask:
D
Double_V 已提交
695
        raise ValueError(
696
            "When setting return_mask to true, data_format must be set to NCHW in API:max_pool2d"
D
Double_V 已提交
697 698
        )

699
    if in_dygraph_mode():
700
        if return_mask:
D
Double_V 已提交
701 702 703 704 705 706
            output = core.ops.max_pool2d_with_index(
                x, 'ksize', kernel_size, 'global_pooling', False, 'strides',
                stride, 'paddings', padding, 'padding_algorithm',
                padding_algorithm, 'use_cudnn', True, 'ceil_mode', ceil_mode,
                'use_mkldnn', False, 'exclusive', True, 'data_format',
                data_format)
707
            return output if return_mask else output[0]
D
Double_V 已提交
708
        else:
D
Double_V 已提交
709 710 711 712 713 714 715
            output = core.ops.pool2d(
                x, 'pooling_type', 'max', 'ksize', kernel_size,
                'global_pooling', False, 'padding_algorithm', padding_algorithm,
                'strides', stride, 'paddings', padding, 'use_cudnn', True,
                'ceil_mode', ceil_mode, 'use_mkldnn', False, 'exclusive', True,
                'data_format', data_format)
            return output
716

717
    op_type = 'max_pool2d_with_index' if return_mask else "pool2d"
718
    helper = LayerHelper(op_type, **locals())
719
    dtype = helper.input_dtype(input_param_name='x')
720
    pool_out = helper.create_variable_for_type_inference(dtype)
721 722
    mask = helper.create_variable_for_type_inference(dtype)
    outputs = {"Out": pool_out, "Mask": mask}
723 724 725 726

    helper.append_op(
        type=op_type,
        inputs={"X": x},
727
        outputs=outputs,
728
        attrs={
729
            "pooling_type": 'max',
730 731 732
            "ksize": kernel_size,
            "global_pooling": False,
            "strides": stride,
733
            "paddings": padding,
734 735 736 737
            "padding_algorithm": padding_algorithm,
            "use_cudnn": True,
            "ceil_mode": ceil_mode,
            "use_mkldnn": False,
738
            "exclusive": True,
739 740 741
            "data_format": data_format,
        })

742
    return (pool_out, mask) if return_mask else pool_out
743 744 745 746 747 748


def max_pool3d(x,
               kernel_size,
               stride=None,
               padding=0,
749
               return_mask=False,
750 751 752 753
               ceil_mode=False,
               data_format="NCDHW",
               name=None):
    """
754 755
    This API implements max pooling 2d operation.
    See more details in :ref:`api_nn_pooling_MaxPool3d` .
756 757
    Args:
        x (Tensor): The input tensor of pooling operator, which is a 5-D tensor with
D
Double_V 已提交
758
                          shape [N, C, D, H, W]. The format of input tensor is `"NCDHW"` or `"NDHWC"`, where N represents batch size, C represents the number of channels, D, H and W represent the depth, height and width of the feature respectively.
759
        kernel_size (int|list|tuple): The pool kernel size. If the kernel size
760
            is a tuple or list, it must contain three integers,
761
            (kernel_size_Depth, kernel_size_Height, kernel_size_Width).
762
            Otherwise, the pool kernel size will be the cube of an int.
763 764
        stride (int|list|tuple): The pool stride size. If pool stride size is a tuple or list,
            it must contain three integers, [stride_Depth, stride_Height, stride_Width).
765
            Otherwise, the pool stride size will be a cube of an int.
766 767 768 769 770 771 772
        padding (string|int|list|tuple): The padding size. Padding could be in one of the following forms.
            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.
773
        ceil_mode (bool): ${ceil_mode_comment}
774
        return_mask (bool): Whether to return the max indices along with the outputs. Default False. Only support "NDCHW" data_format.
775 776 777 778 779 780 781 782 783 784 785 786 787 788
        data_format (string): 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.
    Returns:
        Tensor: The output tensor of pooling result. The data type is same as input tensor.
    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
789

790 791 792
          import paddle
          import paddle.nn.functional as F
          import numpy as np
793

794
          # max pool3d
795 796
          x = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32, 32, 32]).astype(np.float32))
          output = F.max_pool2d(x,
797 798 799
                                kernel_size=2,
                                stride=2, padding=0)
          output.shape [1, 3, 16, 16, 16]
800
          # for return_mask=True
801 802
          x = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32, 32, 32]).astype(np.float32))
          output, max_indices = paddle.nn.functional.max_pool3d(x,
803 804 805
                                        kernel_size = 2,
                                        stride = 2,
                                        padding=0,
806
                                        return_mask=True)
807 808 809 810 811 812 813 814 815
          # output.shape [None, 3, 16, 16, 16], max_indices.shape [None, 3, 16, 16, 16],
    """
    check_variable_and_dtype(x, 'x', ['float32', 'float64'], 'max_pool3d')
    kernel_size = utils.convert_to_list(kernel_size, 3, 'pool_size')
    if stride is None:
        stride = kernel_size
    else:
        stride = utils.convert_to_list(stride, 3, 'pool_stride')

816
    channel_last = _channel_last(data_format, 3)
817

818 819
    padding, padding_algorithm = _update_padding_nd(
        padding, 3, channel_last=channel_last, ceil_mode=ceil_mode)
820

821
    if data_format == "NDHWC" and return_mask:
D
Double_V 已提交
822
        raise ValueError(
823
            "When setting return_mask to true, data_format must be set to NCDHW in API:max_pool3d"
D
Double_V 已提交
824 825
        )

826
    if in_dygraph_mode():
827
        if return_mask:
D
Double_V 已提交
828 829 830 831 832 833
            output = core.ops.max_pool3d_with_index(
                x, 'pooling_type', 'max', 'ksize', kernel_size, 'strides',
                stride, 'paddings', padding, 'global_pooling', False,
                'padding_algorithm', padding_algorithm, 'use_cudnn', True,
                'ceil_mode', ceil_mode, 'use_mkldnn', False, 'exclusive', True,
                'data_format', data_format)
834
            return output if return_mask else output[0]
D
Double_V 已提交
835
        else:
D
Double_V 已提交
836 837 838 839 840 841 842
            output = core.ops.pool3d(
                x, 'pooling_type', 'max', 'ksize', kernel_size,
                'global_pooling', False, 'padding_algorithm', padding_algorithm,
                'strides', stride, 'paddings', padding, 'use_cudnn', True,
                'ceil_mode', ceil_mode, 'use_mkldnn', False, 'exclusive', True,
                'data_format', data_format)
            return output
843

844
    op_type = "max_pool3d_with_index" if return_mask else "pool3d"
845
    helper = LayerHelper(op_type, **locals())
846
    dtype = helper.input_dtype(input_param_name='x')
847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868
    pool_out = helper.create_variable_for_type_inference(dtype)
    mask = helper.create_variable_for_type_inference(dtype)
    outputs = {"Out": pool_out, "Mask": mask}

    helper.append_op(
        type=op_type,
        inputs={"X": x},
        outputs=outputs,
        attrs={
            "pooling_type": 'max',
            "ksize": kernel_size,
            "global_pooling": False,
            "strides": stride,
            "paddings": padding,
            "padding_algorithm": padding_algorithm,
            "use_cudnn": True,
            "ceil_mode": ceil_mode,
            "use_mkldnn": False,
            "exclusive": False,
            "data_format": data_format,
        })

869
    return (pool_out, mask) if return_mask else pool_out
870 871


872
def adaptive_avg_pool1d(x, output_size, name=None):
873
    """
874 875
    This API implements adaptive average pooling 1d operation.
    See more details in :ref:`api_nn_pooling_AdaptiveAvgPool1d` .
D
Double_V 已提交
876

877
    Args:
878 879 880 881
        x (Tensor): The input tensor of pooling operator, which is a 3-D tensor
                              with shape [N, C, L].  The format of input tensor is NCL,
                              where N is batch size, C is the number of channels, L is the
                              length of the feature. The data type is float32 or float64.
882
        output_size (int): The target output size. It must be an integer.
883
        name(str, optional): For detailed information, please refer
884 885
                                 to :ref:`api_guide_Name`. Usually name is no need to set and
                                 None by default.
886
    Returns:
887 888
            Tensor: The output tensor of adaptive average pooling result. The data type is same
                      as input tensor.
889
    Raises:
890
            ValueError: 'output_size' should be an integer.
891 892
    Examples:
        .. code-block:: python
B
Bai Yifan 已提交
893

894 895 896 897 898 899 900 901 902 903 904 905 906 907
              # 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])/(lstart - lend)
              #
              import paddle
              import paddle.nn.functional as F
908

909 910 911 912 913 914 915 916
              data = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32]).astype(np.float32))
              pool_out = F.adaptive_average_pool1d(data, output_size=16)
              # pool_out shape: [1, 3, 16])
    """
    pool_type = 'avg'
    check_variable_and_dtype(x, 'x', ['float32', 'float64'], 'adaptive_pool2d')
    _check_input(x, 3)
    check_type(output_size, 'pool_size', (int), 'adaptive_pool1d')
917

918
    pool_size = [1] + utils.convert_to_list(output_size, 1, 'pool_size')
919

920 921
    l_type = "pool2d"
    x = unsqueeze(x, [2])
922
    if in_dygraph_mode():
923 924 925
        pool_out = core.ops.pool2d(x, 'pooling_type', pool_type, 'ksize',
                                   pool_size, 'adaptive', True)
        return squeeze(pool_out, [2])
926

927
    helper = LayerHelper(l_type, **locals())
928
    dtype = helper.input_dtype(input_param_name='x')
929 930
    pool_out = helper.create_variable_for_type_inference(dtype)

931
    outputs = {"Out": pool_out}
932
    helper.append_op(
933
        type=l_type,
934 935 936
        inputs={"X": x},
        outputs=outputs,
        attrs={
937 938 939
            "pooling_type": pool_type,
            "ksize": pool_size,
            "adaptive": True,
940 941
        })

942
    return squeeze(pool_out, [2])
943 944


945 946
def adaptive_avg_pool2d(x, output_size, data_format='NCHW', name=None):
    """
947 948
    This API implements adaptive average pooling 2d operation.
    See more details in :ref:`api_nn_pooling_AdaptiveAvgPool2d` .
949 950 951

    Args:
        x (Tensor): The input tensor of adaptive avg pool2d operator, which is a 4-D tensor.
952
                          The data type can be float32 or float64.
953 954 955 956 957 958 959 960 961 962 963 964 965 966 967
        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.
        data_format (str): The data format of the input and output data. An optional string
            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].
        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:
        Tensor: The output tensor of avg adaptive pool2d result. The data type is same as input tensor.
    Raises:
        ValueError: If `data_format` is not "NCHW" or "NHWC".
    Examples:
        .. code-block:: python
B
Bai Yifan 已提交
968

969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985
            # 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
986

987 988 989
            input_data = np.random.rand(2, 3, 32, 32)
            x = paddle.to_tensor(input_data)
            # x.shape is [2, 3, 32, 32]
990
            out = paddle.nn.functional.adaptive_avg_pool2d(
991 992
                            x = x,
                            output_size=[3, 3])
993
            # out.shape is [2, 3, 3, 3]
994 995
    """
    if not in_dygraph_mode():
996 997
        check_variable_and_dtype(x, 'x', ['float32', 'float64'],
                                 'adaptive_avg_pool2d')
998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012
    check_type(data_format, 'data_format', str, 'adaptive_avg_pool2d')

    if data_format not in ["NCHW", "NHWC"]:
        raise ValueError(
            "Attr(data_format) should be 'NCHW' or 'NHWC'. Received "
            "Attr(data_format): %s." % str(data_format))

    if data_format == "NCHW":
        in_h, in_w = x.shape[2:4]
    else:
        in_h, in_w = x.shape[1:3]

    if isinstance(output_size, int):
        output_size = utils.convert_to_list(output_size, 2, 'output_size')
    else:
1013
        output_size = list(output_size)
1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027
        if output_size[0] == None:
            output_size[0] = in_h
        if output_size[1] == None:
            output_size[1] = in_w

    if in_dygraph_mode():
        output = core.ops.pool2d(x, 'pooling_type', 'avg', 'ksize', output_size,
                                 'global_pooling', False, 'adaptive', True,
                                 'data_format', data_format)
        return output

    l_type = 'pool2d'

    helper = LayerHelper(l_type, **locals())
1028
    dtype = helper.input_dtype(input_param_name='x')
1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048
    pool_out = helper.create_variable_for_type_inference(dtype)

    outputs = {"Out": pool_out}

    helper.append_op(
        type=l_type,
        inputs={"X": x},
        outputs=outputs,
        attrs={
            "pooling_type": "avg",
            "ksize": output_size,
            "adaptive": True,
            "data_format": data_format,
        })

    return pool_out


def adaptive_avg_pool3d(x, output_size, data_format='NCDHW', name=None):
    """
1049 1050
    This API implements adaptive average pooling 3d operation.
    See more details in :ref:`api_nn_pooling_AdaptiveAvgPool3d` .
1051 1052 1053

    Args:
        x (Tensor): The input tensor of adaptive avg pool3d operator, which is a 5-D tensor.
1054
                          The data type can be float32, float64.
1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069
        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.
        data_format (str): 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.
    Returns:
        Tensor: The output tensor of avg adaptive pool3d result. The data type is same as input tensor.
    Raises:
        ValueError: If `data_format` is not "NCDHW" or "NDHWC".
    Examples:
        .. code-block:: python
B
Bai Yifan 已提交
1070

1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093
            # 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
            input_data = np.random.rand(2, 3, 8, 32, 32)
            x = paddle.to_tensor(input_data)
            # x.shape is [2, 3, 8, 32, 32]
1094
            out = paddle.nn.functional.adaptive_avg_pool3d(
1095 1096
                            x = x,
                            output_size=[3, 3, 3])
1097
            # out.shape is [2, 3, 3, 3, 3]
1098 1099
    """
    if not in_dygraph_mode():
1100 1101
        check_variable_and_dtype(x, 'x', ['float32', 'float64'],
                                 'adaptive_avg_pool3d')
1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116
    check_type(data_format, 'data_format', str, 'adaptive_avg_pool3d')

    if data_format not in ["NCDHW", "NDHWC"]:
        raise ValueError(
            "Attr(data_format) should be 'NCDHW' or 'NDHWC'. Received "
            "Attr(data_format): %s." % str(data_format))

    if data_format == "NCDHW":
        in_l, in_h, in_w = x.shape[2:5]
    else:
        in_l, in_h, in_w = x.shape[1:4]

    if isinstance(output_size, int):
        output_size = utils.convert_to_list(output_size, 3, 'output_size')
    else:
1117
        output_size = list(output_size)
1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133
        if output_size[0] == None:
            output_size[0] = in_l
        if output_size[1] == None:
            output_size[1] = in_h
        if output_size[2] == None:
            output_size[2] = in_w

    if in_dygraph_mode():
        output = core.ops.pool3d(x, 'pooling_type', 'avg', 'ksize', output_size,
                                 'global_pooling', False, 'adaptive', True,
                                 'data_format', data_format)
        return output

    l_type = 'pool3d'

    helper = LayerHelper(l_type, **locals())
1134
    dtype = helper.input_dtype(input_param_name='x')
1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149
    pool_out = helper.create_variable_for_type_inference(dtype)
    outputs = {"Out": pool_out}

    helper.append_op(
        type=l_type,
        inputs={"X": x},
        outputs=outputs,
        attrs={
            "pooling_type": "avg",
            "ksize": output_size,
            "adaptive": True,
            "data_format": data_format,
        })

    return pool_out
1150 1151


1152
def adaptive_max_pool1d(x, output_size, return_mask=False, name=None):
1153 1154 1155 1156 1157 1158 1159 1160 1161
    """
    This API implements adaptive max pooling 1d operation.
    See more details in :ref:`api_nn_pooling_AdaptiveMaxPool1d` .

    Args:
        x (Tensor): The input tensor of pooling operator, which is a 3-D tensor
                              with shape [N, C, L].  The format of input tensor is NCL,
                              where N is batch size, C is the number of channels, L is the
                              length of the feature. The data type is float32 or float64.
1162
        output_size (int): The pool kernel size. The value should be an integer.
1163
        return_mask (bool): If true, the index of max pooling point will be returned along
1164 1165 1166 1167 1168 1169 1170 1171
                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.
    Returns:
            Tensor: The output tensor of adaptive pooling result. The data type is same
                      as input tensor.
    Raises:
1172
            ValueError: 'output_size' should be an integer.
1173 1174
    Examples:
        .. code-block:: python
1175

1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189
              # 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.functional as F
1190

1191 1192 1193
              data = paddle.to_tensor(np.random.uniform(-1, 1, [1, 3, 32]).astype(np.float32))
              pool_out = F.adaptive_max_pool1d(data, output_size=16)
              # pool_out shape: [1, 3, 16])
1194
              pool_out, indices = F.adaptive_max_pool1d(data, output_size=16, return_mask=True)
1195 1196 1197 1198 1199 1200
              # pool_out shape: [1, 3, 16] indices  shape: [1, 3, 16]
    """
    pool_type = 'max'
    check_variable_and_dtype(x, 'x', ['float32', 'float64'],
                             'adaptive_max_pool1d')
    _check_input(x, 3)
1201
    check_type(output_size, 'pool_size', int, 'adaptive_max_pool1d')
1202
    check_type(return_mask, 'return_mask', bool, 'adaptive_max_pool1d')
1203 1204 1205 1206 1207 1208 1209 1210 1211 1212

    pool_size = [1] + utils.convert_to_list(output_size, 1, 'pool_size')

    l_type = 'max_pool2d_with_index'

    x = unsqueeze(x, [2])
    if in_dygraph_mode():
        pool_out = core.ops.max_pool2d_with_index(
            x, 'pooling_type', pool_type, 'ksize', pool_size, 'adaptive', True)
        return (squeeze(pool_out[0], [2]), squeeze(
1213
            pool_out[1], [2])) if return_mask else squeeze(pool_out[0], [2])
1214 1215

    helper = LayerHelper(l_type, **locals())
1216
    dtype = helper.input_dtype(input_param_name='x')
1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232
    pool_out = helper.create_variable_for_type_inference(dtype)

    mask = helper.create_variable_for_type_inference(dtype)
    outputs = {"Out": pool_out, "Mask": mask}

    helper.append_op(
        type=l_type,
        inputs={"X": x},
        outputs=outputs,
        attrs={
            "pooling_type": pool_type,
            "ksize": pool_size,
            "adaptive": True,
        })

    return (squeeze(pool_out, [2]),
1233
            squeeze(mask, [2])) if return_mask else squeeze(pool_out, [2])
1234 1235


1236
def adaptive_max_pool2d(x, output_size, return_mask=False, name=None):
1237 1238 1239
    """
        This operation applies a 2D adaptive max pooling on input tensor.
        See more details in :ref:`api_nn_pooling_AdaptiveMaxPool2d` .
1240

1241 1242 1243
        Args:
            x (Tensor): The input tensor of adaptive max pool2d operator, which is a 4-D tensor. The data type can be float16, float32, float64, int32 or int64.
            output_size (int|list|tuple): The pool kernel size. If pool kernel size is a tuple or list, it must contain two elements, (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.
1244
            return_mask (bool): If true, the index of max pooling point will be returned along with outputs. Default False.
1245
            name(str, optional): For detailed information, please refer to :ref:`api_guide_Name`. Usually name is no need to set and None by default.
1246

1247 1248
        Returns:
            Tensor: The output tensor of adaptive max pool2d result. The data type is same as input tensor.
1249

1250 1251
        Examples:
            .. code-block:: python
1252

1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269
              # max adaptive pool2d
              # suppose input data in the 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
1270

1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283
              input_data = np.random.rand(2, 3, 32, 32)
              x = paddle.to_tensor(input_data)
              # x.shape is [2, 3, 32, 32]
              out = paddle.nn.functional.adaptive_max_pool2d(
                            x = x,
                            output_size=[3, 3])
              # out.shape is [2, 3, 3, 3]
    """
    if not in_dygraph_mode():
        check_variable_and_dtype(x, 'x', ['float32', 'float64'],
                                 'adaptive_max_pool2d')
    _check_input(x, 4)
    #check_type(output_size, 'pool_size', (int), 'adaptive_max_pool2d')
1284
    check_type(return_mask, 'return_mask', bool, 'adaptive_max_pool2d')
1285 1286 1287 1288 1289

    in_h, in_w = x.shape[2:4]
    if isinstance(output_size, int):
        output_size = utils.convert_to_list(output_size, 2, 'output_size')
    else:
1290
        output_size = list(output_size)
1291 1292 1293 1294 1295 1296 1297 1298
        if output_size[0] == None:
            output_size[0] = in_h
        if output_size[1] == None:
            output_size[1] = in_w

    if in_dygraph_mode():
        pool_out = core.ops.max_pool2d_with_index(
            x, 'pooling_type', 'max', 'ksize', output_size, 'adaptive', True)
1299
        return pool_out if return_mask else pool_out[0]
1300 1301 1302 1303

    l_type = 'max_pool2d_with_index'

    helper = LayerHelper(l_type, **locals())
1304
    dtype = helper.input_dtype(input_param_name='x')
1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318
    pool_out = helper.create_variable_for_type_inference(dtype)

    mask = helper.create_variable_for_type_inference(dtype)
    outputs = {"Out": pool_out, "Mask": mask}

    helper.append_op(
        type=l_type,
        inputs={"X": x},
        outputs=outputs,
        attrs={
            "pooling_type": 'max',
            "ksize": output_size,
            "adaptive": True,
        })
1319
    #return (pool_out, mask) if return_mask else pool_out
1320 1321 1322
    return pool_out


1323
def adaptive_max_pool3d(x, output_size, return_mask=False, name=None):
1324 1325 1326
    """
        This operation applies a 3D adaptive max pooling on input tensor.
        See more details in :ref:`api_nn_pooling_AdaptiveMaxPool3d` .
1327

1328 1329 1330
        Args:
            x (Tensor): The input tensor of adaptive max pool3d operator, which is a 5-D tensor. The data type can be float32, float64.
            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.
1331
            return_mask (bool): If true, the index of max pooling point will be returned along with outputs. Default False.
1332
            name(str, optional): For detailed information, please refer to :ref:`api_guide_Name`. Usually name is no need to set and None by default.
1333

1334 1335
        Returns:
            Tensor: The output tensor of adaptive max pool3d result. The data type is same as input tensor.
1336

1337 1338
        Examples:
            .. code-block:: python
1339

1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359
              # adaptive max pool3d
              # suppose input data in the 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 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(i * H / m)
              #                 hend = ceil((i + 1) * H / m)
              #                 wstart = floor(i * W / n)
              #                 wend = ceil((i + 1) * W / n)
              #             output[:, :, i, j, k] = max(input[:, :, dstart: dend, hstart: hend, wstart: wend])
              #
              import paddle
              import numpy as np
1360

1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374
              input_data = np.random.rand(2, 3, 8, 32, 32)
              x = paddle.to_tensor(input_data)
              # x.shape is [2, 3, 8, 32, 32]
              out = paddle.nn.functional.adaptive_max_pool3d(
                            x = x,
                            output_size=[3, 3, 3])
              # out.shape is [2, 3, 3, 3, 3]
    """

    if not in_dygraph_mode():
        check_variable_and_dtype(x, 'x', ['float32', 'float64'],
                                 'adaptive_max_pool3d')
    _check_input(x, 5)
    #check_type(output_size, 'pool_size', (int), 'adaptive_max_pool3d')
1375
    check_type(return_mask, 'return_mask', bool, 'adaptive_max_pool3d')
1376 1377 1378 1379 1380

    in_l, in_h, in_w = x.shape[2:5]
    if isinstance(output_size, int):
        output_size = utils.convert_to_list(output_size, 3, 'output_size')
    else:
1381
        output_size = list(output_size)
1382 1383 1384 1385 1386 1387 1388 1389 1390 1391
        if output_size[0] == None:
            output_size[0] = in_l
        if output_size[1] == None:
            output_size[1] = in_h
        if output_size[2] == None:
            output_size[2] = in_w

    if in_dygraph_mode():
        pool_out = core.ops.max_pool3d_with_index(
            x, 'pooling_type', 'max', 'ksize', output_size, 'adaptive', True)
1392
        return pool_out if return_mask else pool_out[0]
1393 1394 1395 1396

    l_type = 'max_pool3d_with_index'

    helper = LayerHelper(l_type, **locals())
1397
    dtype = helper.input_dtype(input_param_name='x')
1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412
    pool_out = helper.create_variable_for_type_inference(dtype)

    mask = helper.create_variable_for_type_inference(dtype)
    outputs = {"Out": pool_out, "Mask": mask}

    helper.append_op(
        type=l_type,
        inputs={"X": x},
        outputs=outputs,
        attrs={
            "pooling_type": 'max',
            "ksize": output_size,
            "adaptive": True,
        })

1413
    return (pool_out, mask) if return_mask else pool_out