【PaddlePaddle Hackathon 2】29、为 Paddle 新增 PixelUnshuffle 组网 API (#4523)

* Create PixelUnshuffle_cn.rst

* Create pixel_unshuffle_cn.rst

* add PixelUnshuffle

* add pixel_unshuffle

* Update PixelUnshuffle_cn.rst

* Update PixelUnshuffle_cn.rst

* Update pixel_unshuffle_cn.rst

* Update pixel_unshuffle_cn.rst

docs/api/paddle/nn/Overview_cn.rst

@@ -268,6 +268,7 @@ Vision层
 
     " :ref:`paddle.nn.ChannelShuffle <cn_api_nn_ChannelShuffle>` ", "将一个形为[N, C, H, W]或是[N, H, W, C]的Tensor按通道分成g组，得到形为[N, g, C/g, H, W]或[N, H, W, g, C/g]的Tensor，然后转置为[N, C/g, g, H, W]或[N, H, W, C/g, g]的形状，最后重新排列为原来的形状"
     " :ref:`paddle.nn.PixelShuffle <cn_api_nn_PixelShuffle>` ", "将一个形为[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"
+    " :ref:`paddle.nn.PixelUnshuffle <cn_api_nn_PixelUnshuffle>` ", "PixelShuffle的逆操作，将一个形为[N, C, H, W]或是[N, H, W, C]的Tensor重新排列成形为 [N, C*r*r, H/r, W/r] 或 [N, H/r, W/r, C*r*r] 的Tensor"
     " :ref:`paddle.nn.Upsample <cn_api_paddle_nn_Upsample>` ", "用于调整一个batch中图片的大小"
     " :ref:`paddle.nn.UpsamplingBilinear2D <cn_api_paddle_nn_UpsamplingBilinear2D>` ", "用于调整一个batch中图片的大小（使用双线性插值方法）"
     " :ref:`paddle.nn.UpsamplingNearest2D <cn_api_paddle_nn_UpsamplingNearest2D>` ", "用于调整一个batch中图片的大小（使用最近邻插值方法）"
@@ -491,6 +492,7 @@ Embedding相关函数
     " :ref:`paddle.nn.functional.label_smooth <cn_api_paddle_nn_functional_common_label_smooth>` ", "标签平滑"
     " :ref:`paddle.nn.functional.one_hot <cn_api_nn_functional_one_hot>` ", "将输入'x'中的每个id转换为一个one-hot向量"
     " :ref:`paddle.nn.functional.pixel_shuffle <cn_api_nn_functional_pixel_shuffle>` ", "将Tensor重新排列"
+    " :ref:`paddle.nn.functional.pixel_unshuffle <cn_api_nn_functional_pixel_unshuffle>` ", "将Tensor重新排列，是pixel_shuffle的逆操作"
     " :ref:`paddle.nn.functional.square_error_cost <cn_api_fluid_layers_square_error_cost>` ", "用于计算预测值和目标值的方差估计"
     " :ref:`paddle.nn.functional.unfold <cn_api_fluid_layers_unfold>` ", "对每一个卷积核覆盖下的区域，将元素重新排成一列"
     " :ref:`paddle.nn.functional.fold <cn_api_nn_functional_fold>` ", "该Op用于将一个滑动局部块组合成一个大的张量,通常也被称为col2im。"

docs/api/paddle/nn/PixelUnshuffle_cn.rst

@@ -0,0 +1,28 @@
+.. _cn_api_nn_PixelUnshuffle:
+
+PixelUnshuffle
+-------------------------------
+
+.. py:function:: paddle.nn.PixelUnshuffle(downscale_factor, data_format="NCHW", name=None)
+该算子将一个形为 :math:`[N, C, H, W]` 或是 :math:`[N, H, W, C]` 的 Tensor 重新排列成形为 :math:`[N, r^2C, H/r, W/r]` 或 :math:`[N, H/r, W/r, r^2C]` 的 Tensor，这里 :math:`r` 是减小空间分辨率的减小因子。这个算子是 PixelShuffle 算子（请参考：:ref:`cn_api_nn_PixelShuffle`）的逆算子。详见施闻哲等人在 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, 1, 12, 12] 的 4-D 张量
+    设定 downscale_factor = 3
+    那么输出张量的形为 [1, 9, 4, 4]
+
+参数
+:::::::::
+    - **downscale_factor** (int) – 减小空间分辨率的减小因子。
+    - **data_format** (str，可选) – 数据格式，可选 NCHW 或 NHWC，默认为 NCHW，即（批大小，通道数，高度，宽度）的格式。
+    - **name** (str，可选) – 操作的名称（可选，默认值为 None），大多数情况下不需要设置此属性。更多信息请参见 :ref:`api_guide_Name`。
+
+形状
+:::::::::
+    - **x** (Tensor) – 形状为 :math:`[N, C, H, W]` 或 :math:`[N, C, H, W]` 的 4-D Tensor。
+    - **out** (Tensor) – 形状为 :math:`[N, r^2C, H/r, W/r]` 或 :math:`[N, H/r, W/r, r^2C]` 的 4-D Tensor，这里 :math:`r` 就是 :attr:`downscale_factor`。
+
+代码示例
+:::::::::
+COPY-FROM: paddle.nn.PixelUnshuffle:PixelUnshuffle-example

docs/api/paddle/nn/functional/pixel_unshuffle_cn.rst

@@ -0,0 +1,26 @@
+.. _cn_api_nn_functional_pixel_unshuffle:
+
+
+pixel_unshuffle
+-------------------------------
+
+.. py:function:: paddle.nn.functional.pixel_unshuffle(x, downscale_factor, data_format="NCHW", name=None)
+该算子将一个形为 :math:`[N, C, H, W]` 或 :math:`[N, H, W, C]` 的 Tensor 重新排列成形为 :math:`[N, r^2C, H/r, W/r]` 或 :math:`[N, H/r, W/r, r^2C]` 的 Tensor，这里 :math:`r` 是减小空间分辨率的减小因子。这个算子是 pixel_shuffle 算子（请参考：:ref:`cn_api_nn_functional_pixel_shuffle`）的逆算子。详见施闻哲等人在 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_PixelUnshuffle` 。
+
+参数
+:::::::::
+    - **x** (Tensor) – 当前算子的输入，其是一个形状为 :math:`[N, C, H, W]` 或 :math:`[N, H, W, C]` 的 4-D Tensor。其中 :math:`N` 是批大小，:math:`C` 是通道数，:math:`H` 是输入特征的高度，:math:`W` 是输入特征的宽度。其数据类型为 float32 或 float64。
+    - **downscale_factor** (int) – 减小空间分辨率的减小因子。
+    - **data_format** (str，可选) – 数据格式，可选 NCHW 或 NHWC，默认为 NCHW，即（批大小，通道数，高度，宽度）的格式。
+    - **name** (str，可选) – 操作的名称（可选，默认值为 None），大多数情况下不需要设置此属性。更多信息请参见 :ref:`cn_api_guide_Name`。
+
+返回
+:::::::::
+``Tensor``，重新排列过的 Tensor，其数据类型与输入相同。
+
+代码示例
+:::::::::
+COPY-FROM: paddle.nn.functional.pixel_unshuffle:pixel_unshuffle-example