add DOCgit statusgit statusgit statusgit status!

doc/fluid/api_cn/nn_cn.rst

@@ -191,6 +191,9 @@ paddle.nn
     nn_cn/AdaptiveAvgPool3d_cn.rst
     nn_cn/AdaptiveAvgPool1d_cn.rst
     nn_cn/AdaptiveMaxPool1d_cn.rst
+    nn_cn/AdaptiveMaxPool2d_cn.rst
+    nn_cn/AdaptiveMaxPool3d_cn.rst
     nn_cn/AvgPool1d_cn.rst
     nn_cn/MaxPool1d_cn.rst
     nn_cn/Bilinear_cn.rst
+    nn_cn/PixelShuffle_cn.rst

doc/fluid/api_cn/nn_cn/AdaptiveMaxPool2d_cn.rst

+.. _cn_api_nn_AdaptiveMaxPool2d:
+
+
+AdaptiveMaxPool2d
+-------------------------------
+
+.. py:function:: paddle.nn.AdaptiveMaxPool2d(output_size, return_indices=False, name=None)
+
+该算子根据输入 `x` , `output_size` 等参数对一个输入Tensor计算2D的自适应平均池化。输入和输出都是4-D Tensor，
+默认是以 `NCHW` 格式表示的，其中 `N` 是 batch size, `C` 是通道数, `H` 是输入特征的高度, `W` 是输入特征的宽度.
+
+计算公式如下:
+
+..  math::
+
+    lstart &= floor(i * L_{in} / L_{out})
+
+    lend &= ceil((i + 1) * L_{in} / L_{out})
+
+    Output(i) &= max(Input[lstart:lend])
+
+    hstart &= floor(i * H_{in} / H_{out})
+    
+    hend &= ceil((i + 1) * H_{in} / H_{out})
+    
+    wstart &= floor(j * W_{in} / W_{out})
+    
+    wend &= ceil((j + 1) * W_{in} / W_{out})
+    
+    Output(i ,j) &= max(Input[hstart:hend, wstart:wend])
+
+参数
+:::::::::
+    - **output_size** (int|list|tuple): 算子输出特征图的高和宽大小，其数据类型为int,list或tuple。
+    - **return_indices** (bool): 如果设置为True，则会与输出一起返回最大值的索引，默认为False。
+    - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。
+
+形状
+:::::::::
+    - **x** (Tensor): 默认形状为（批大小，通道数，输出特征长度），即NCHW格式的4-D Tensor。 其数据类型为float32或者float64。
+    - **output** (Tensor): 默认形状为（批大小，通道数，输出特征长度），即NCHW格式的4-D Tensor。 其数据类型与输入x相同。
+
+返回
+:::::::::
+计算AdaptiveMaxPool2d的可调用对象
+
+抛出异常
+:::::::::
+    - ``ValueError`` - ``output_size`` 应是一个整数或长度为2的list，tuple
+
+代码示例
+:::::::::
+
+.. code-block:: python
+
+        # 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
+        paddle.disable_static()
+        input_data = np.random.rand(2, 3, 32, 32)
+        x = paddle.to_tensor(input_data)
+        adaptive_max_pool = paddle.nn.AdaptiveMaxPool2d(output_size=3, return_indices=True)
+        pool_out, indices = adaptive_max_pool(x = x)

doc/fluid/api_cn/nn_cn/AdaptiveMaxPool3d_cn.rst

+.. _cn_api_nn_AdaptiveMaxPool3d:
+
+
+AdaptiveMaxPool3d
+-------------------------------
+
+.. py:function:: paddle.nn.AdaptiveMaxPool3d(output_size, return_indices=False, name=None)
+
+该算子根据输入 `x` , `output_size` 等参数对一个输入Tensor计算3D的自适应平均池化。输入和输出都是5-D Tensor，
+默认是以 `NCDHW` 格式表示的，其中 `N` 是 batch size， `C` 是通道数， `D` ， `H` ， `W` 分别是输入特征的深度，高度，宽度.
+
+计算公式如下:
+
+..  math::
+
+    dstart &= floor(i * D_{in} / D_{out})
+    
+    dend &= ceil((i + 1) * D_{in} / D_{out})
+    
+    hstart &= floor(j * H_{in} / H_{out})
+    
+    hend &= ceil((j + 1) * H_{in} / H_{out})
+    
+    wstart &= floor(k * W_{in} / W_{out})
+    
+    wend &= ceil((k + 1) * W_{in} / W_{out})
+    
+    Output(i ,j, k) &= max(Input[dstart:dend, hstart:hend, wstart:wend])
+
+参数
+:::::::::
+    - **output_size** (int|list|tuple): 算子输出特征图的高宽长大小，其数据类型为int,list或tuple。
+    - **return_indices** (bool): 如果设置为True，则会与输出一起返回最大值的索引，默认为False。
+    - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。
+
+形状
+:::::::::
+    - **x** (Tensor): 默认形状为（批大小，通道数，输出特征长度），即NCDHW格式的5-D Tensor。 其数据类型为float32或者float64。
+    - **output** (Tensor): 默认形状为（批大小，通道数，输出特征长度），即NCDHW格式的5-D Tensor。 其数据类型与输入x相同。
+
+返回
+:::::::::
+计算AdaptiveMaxPool3d的可调用对象
+
+抛出异常
+:::::::::
+    - ``ValueError`` - ``output_size`` 应是一个整数或长度为3的list，tuple
+
+代码示例
+:::::::::
+
+.. code-block:: python
+
+        # 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
+        paddle.disable_static()
+        input_data = np.random.rand(2, 3, 8, 32, 32)
+        x = paddle.to_tensor(input_data)
+        pool = paddle.nn.AdaptiveMaxPool3d(output_size=4)
+        out = pool(x)
+        # out shape: [2, 3, 4, 4, 4]
+        pool, indices = paddle.nn.AdaptiveMaxPool3d(output_size=3, return_indices=True)
+        out = pool(x)
+        # out shape: [2, 3, 4, 4, 4], indices shape: [2, 3, 4, 4, 4]

doc/fluid/api_cn/nn_cn/PixelShuffle_cn.rst

+.. _cn_api_nn_PixelShuffle:
+
+PixelShuffle
+-------------------------------
+
+.. py:function:: paddle.nn.PixelShuffle(upscale_factor, data_format="NCHW", name=None)
+
+该算子将一个形为[N, C, H, W]或是[N, H, W, C]的Tensor重新排列成形为 [N, C/r**2, H*r, W*r]或 [N, H*r, W*r, C/r**2]  的Tensor。这样做有利于实现步长（stride）为1/r的高效sub-pixel（亚像素）卷积。详见Shi等人在2016年发表的论文 `Real Time Single Image and Video Super Resolution Using an Efficient Sub Pixel Convolutional Neural Network <https://arxiv.org/abs/1609.05158v2>`_ 。
+
+.. code-block:: text
+
+    给定一个形为  x.shape = [1, 9, 4, 4]  的4-D张量
+    设定：upscale_factor=3
+    那么输出张量的形为：[1, 1, 12, 12]
+
+参数
+:::::::::
+    - **upscale_factor** （int):增大空间分辨率的增大因子
+    - **data_format** (str，可选): 数据格式，可选："NCHW"或"NHWC"，默认:"NCHW"
+    - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。
+
+形状
+:::::::::
+    - **x** (Tensor): 默认形状为（批大小，通道数，高度，宽度），即NCHW格式的4-D Tensor或NHWC格式的4-DTensor。 其数据类型为float32, float64.
+    - **output** (Tensor): 默认形状为（批大小，通道数，输出特征高度，输出特征宽度），即NCHW格式或NHWC的4-D Tensor。 其数据类型与输入相同。
+
+返回
+:::::::::
+计算PixelShuffle的可调用对象
+
+抛出异常
+:::::::::
+    - ``ValueError`` - 如果 ``data_format`` 既不是"NCHW"也不是"NHWC"。
+
+代码示例
+:::::::::
+.. code-block:: python
+
+        import paddle
+        import paddle.nn as nn
+        import numpy as np
+        paddle.disable_static()
+        x = np.random.randn(2, 9, 4, 4).astype(np.float32)
+        x_var = paddle.to_tensor(x)
+        pixel_shuffle = nn.PixelShuffle(3)
+        out_var = pixel_shuffle(x_var)
+        out = out_var.numpy()
+        print(out.shape) 
+        # (2, 1, 12, 12)

doc/fluid/api_cn/nn_cn/functional_cn.rst

@@ -26,7 +26,10 @@ functional
     functional_cn/sigmoid_cn.rst
     functional_cn/adaptive_avg_pool1d_cn.rst
     functional_cn/adaptive_max_pool1d_cn.rst
+    functional_cn/adaptive_max_pool2d_cn.rst
+    functional_cn/adaptive_max_pool3d_cn.rst
     functional_cn/avg_pool1d_cn.rst
     functional_cn/max_pool1d_cn.rst
     functional_cn/cross_entropy_loss_cn.rst
     functional_cn/bilinear_cn.rst
+    functional_cn/pixel_shuffle_cn.rst

doc/fluid/api_cn/nn_cn/functional_cn/adaptive_max_pool2d_cn.rst

+.. _cn_api_nn_functional_adaptive_max_pool2d:
+
+
+adaptive_max_pool2d
+-------------------------------
+
+.. py:function:: paddle.nn.functional.adaptive_max_pool2d(x, output_size, return_indices=False, name=None)
+
+该算子根据输入 `x` , `output_size` 等参数对一个输入Tensor计算2D的自适应最大值池化。输入和输出都是4-D Tensor，
+默认是以 `NCHW` 格式表示的，其中 `N` 是 batch size, `C` 是通道数, `H` 是输入特征的高度， `W` 是输入特征的宽度。
+
+.. note::
+   详细请参考对应的 `Class` 请参考: :ref:`cn_api_nn_AdaptiveMaxPool2d` 。
+
+
+参数
+:::::::::
+    - **x** (Tensor): 当前算子的输入, 其是一个形状为 `[N, C, H, W]` 的4-D Tensor。其中 `N` 是batch size, `C` 是通道数, `H` 是输入特征的高度, `W` 是输入特征的宽度。 其数据类型为float32或者float64。
+    - **output_size** (int|list|tuple): 算子输出特征图的长度，其数据类型为int或list，tuple。
+    - **return_indices** (bool): 如果设置为True，则会与输出一起返回最大值的索引，默认为False。
+    - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。
+
+返回
+:::::::::
+``Tensor``, 输入 `x` 经过自适应池化计算得到的目标4-D Tensor，其数据类型与输入相同。
+
+抛出异常
+:::::::::
+    - ``ValueError`` - 如果 ``output_size`` 不是int类型值。
+
+代码示例
+:::::::::
+
+.. code-block:: python
+
+        # 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
+        paddle.disable_static()
+        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]
+

doc/fluid/api_cn/nn_cn/functional_cn/adaptive_max_pool3d_cn.rst

+.. _cn_api_nn_functional_adaptive_max_pool3d:
+
+
+adaptive_max_pool3d
+-------------------------------
+
+.. py:function:: paddle.nn.functional.adaptive_max_pool3d(x, output_size, return_indices=False, name=None)
+
+该算子根据输入 `x` , `output_size` 等参数对一个输入Tensor计算3D的自适应最大值池化。输入和输出都是5-D Tensor，
+默认是以 `NCDHW` 格式表示的，其中 `N` 是 batch size, `C` 是通道数, `D` , `H` , `W` 是输入特征的深度，高度，宽度.
+
+.. note::
+   详细请参考对应的 `Class` 请参考: :ref:`cn_api_nn_AdaptiveMaxPool3d` 。
+
+
+参数
+:::::::::
+    - **x** (Tensor): 当前算子的输入, 其是一个形状为 `[N, C, D, H, W]` 的5-D Tensor。其中 `N` 是batch size, `C` 是通道数, `D` , `H` , `W` 是输入特征的深度，高度，宽度。 其数据类型为float32或者float64。
+    - **output_size** (int|list|tuple): 算子输出特征图的长度，其数据类型为int或list，tuple。
+    - **return_indices** (bool): 如果设置为True，则会与输出一起返回最大值的索引，默认为False。
+    - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。
+
+返回
+:::::::::
+``Tensor``, 输入 `x` 经过自适应池化计算得到的目标5-D Tensor，其数据类型与输入相同。
+
+抛出异常
+:::::::::
+    - ``ValueError`` - 如果 ``output_size`` 不是int类型值。
+
+代码示例
+:::::::::
+
+.. code-block:: python
+
+        # 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
+        paddle.disable_static()
+        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]

doc/fluid/api_cn/nn_cn/functional_cn/pixel_shuffle_cn.rst

+.. _cn_api_nn_functional_pixel_shuffle:
+
+
+pixel_shuffle
+-------------------------------
+
+.. py:function:: paddle.nn.functional.pixel_shuffle(x, upscale_factor, data_format="NCHW", name=None)
+
+该算子将一个形为[N, C, H, W]或是[N, H, W, C]的Tensor重新排列成形为 [N, C/r**2, H*r, W*r]或 [N, H*r, W*r, C/r**2]  的Tensor。这样做有利于实现步长（stride）为1/r的高效sub-pixel（亚像素）卷积。详见Shi等人在2016年发表的论文 `Real Time Single Image and Video Super Resolution Using an Efficient Sub Pixel Convolutional Neural Network <https://arxiv.org/abs/1609.05158v2>`_ 。
+
+.. note::
+   详细请参考对应的 `Class` 请参考: :ref:`cn_api_nn_PixelShuffle` 。
+
+参数
+:::::::::
+    - **x** (Tensor): 当前算子的输入, 其是一个形状为 `[N, C, H, W]` 的4-D Tensor。其中 `N` 是batch size, `C` 是通道数, `H` 是输入特征的高度, `W` 是输入特征的宽度。 其数据类型为float32或者float64。
+    - **upscale_factor** （int):增大空间分辨率的增大因子
+    - **data_format** (str，可选): 数据格式，可选："NCHW"或"NHWC"，默认:"NCHW"
+    - **name** (str，可选): 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。
+
+返回
+:::::::::
+``Tensor``, 输出Tensor, 其数据类型与输入相同。
+
+抛出异常
+:::::::::
+    - ``ValueError`` - 如果 ``data_format`` 既不是"NCHW"也不是"NHWC"。
+
+代码示例
+:::::::::
+.. code-block:: python
+        
+        import paddle
+        import paddle.nn.functional as F
+        import numpy as np
+        x = np.random.randn(2, 9, 4, 4).astype(np.float32)
+        paddle.disable_static()
+        x_var = paddle.to_tensor(x)
+        out_var = F.pixel_shuffle(x_var, 3)
+        out = out_var.numpy()
+        print(out.shape) 
+        # (2, 1, 12, 12)

doc/fluid/api_cn/nn_cn/pixel_shuffle_cn.rst

-.. _cn_api_nn_cn_pixel_shuffle:
-
-pixel_shuffle
--------------------------------
-:doc_source: paddle.fluid.layers.pixel_shuffle
-
-