【Hackathon 6th No.16】为 Paddle 新增 LPPool1D / LPPool2D API (#6639)

* Add docs of lp pool * add data_format * update * update overview * remove empty line
PaddlePaddle · Jul 1, 2024 · 2785bd3 · 2785bd3
1 parent de7cf17
commit 2785bd3
Show file tree

Hide file tree

Showing 9 changed files with 196 additions and 4 deletions.
diff --git a/docs/api/paddle/nn/AvgPool1D_cn.rst b/docs/api/paddle/nn/AvgPool1D_cn.rst
@@ -18,7 +18,7 @@ AvgPool1D
 :::::::::
     - **kernel_size** (int|list|tuple) - 池化核的尺寸大小。如果 kernel_size 为 list 或 tuple 类型，其必须包含一个整数，最终池化核的大小为该数值。
     - **stride** (int|list|tuple，可选) - 池化操作步长。如果 stride 为 list 或 tuple 类型，其必须包含一个整数，最终池化操作的步长为该数值。默认值为 None，这时会使用 kernel_size 作为 stride。
-    - **padding** (str|int|list|tuple，可选) - 池化补零的方式。如果 padding 是一个字符串，则必须为 `SAME` 或者 `VALID`。如果是 turple 或者 list 类型，则应是 `[pad_left, pad_right]` 形式。如果 padding 是一个非 0 值，那么表示会在输入的两端都 padding 上同样长度的 0。默认值为 0。
+    - **padding** (str|int|list|tuple，可选) - 池化补零的方式。如果 padding 是一个字符串，则必须为 `SAME` 或者 `VALID`。如果是 tuple 或者 list 类型，若其长度为 1，则会在输入的两端都填充上长度为 padding[0] 的 0，若其长度为 2，则应是 `[pad_before, pad_after]` 形式。如果 padding 是一个非 0 整数，那么表示会在输入的两端都填充上同样长度的 0。如果 padding 是长度为 2 的序列组成的 list 或 tuple，则其中的每个元素表示在相应维度上的填充长度。注意：在 batch_size 维度和通道维度应该设置为 [0, 0] 或 (0, 0)。默认值为 0。
     - **exclusive** (bool，可选) - 是否用额外 padding 的值计算平均池化结果，默认为 True。
     - **ceil_mode** (bool，可选) - 是否用 ceil 函数计算输出的 height 和 width，如果设置为 False，则使用 floor 函数来计算，默认为 False。
     - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。

diff --git a/docs/api/paddle/nn/AvgPool2D_cn.rst b/docs/api/paddle/nn/AvgPool2D_cn.rst
@@ -31,7 +31,7 @@ AvgPool2D
 :::::::::
     - **kernel_size** (int|list|tuple)：池化核大小。如果它是一个元组或列表，它必须包含两个整数值，(pool_size_Height, pool_size_Width)。若为一个整数，则它的平方值将作为池化核大小，比如若 pool_size=2，则池化核大小为 2x2。
     - **stride** (int|list|tuple，可选)：池化层的步长。如果它是一个元组或列表，它将包含两个整数，(pool_stride_Height, pool_stride_Width)。若为一个整数，则表示 H 和 W 维度上 stride 均为该值。默认值为 None，这时会使用 kernel_size 作为 stride。
-    - **padding** (str|int|list|tuple，可选) 池化填充。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法，计算细节可参考上述 pool_padding = "SAME"或 pool_padding = "VALID" 时的计算公式。如果它是一个元组或列表，它可以有 3 种格式：(1)包含 2 个整数值：[pad_height, pad_width]；(2)包含 4 个整数值：[pad_height_top, pad_height_bottom, pad_width_left, pad_width_right]；(3)包含 4 个二元组：当 data_format 为"NCHW"时为 [[0,0], [0,0], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right]]，当 data_format 为"NHWC"时为[[0,0], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right], [0,0]]。若为一个整数，则表示 H 和 W 维度上均为该值。默认值：0。
+    - **padding** (str|int|list|tuple，可选) 池化填充。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法。如果它是一个元组或列表，它可以有 3 种格式：(1)包含 2 个整数值：[pad_height, pad_width]；(2)包含 4 个整数值：[pad_height_top, pad_height_bottom, pad_width_left, pad_width_right]；(3)包含 4 个二元组：当 data_format 为"NCHW"时为 [[0,0], [0,0], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right]]，当 data_format 为"NHWC"时为[[0,0], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right], [0,0]]。若为一个整数，则表示 H 和 W 维度上均为该值。默认值：0。
     - **ceil_mode** (bool，可选)：是否用 ceil 函数计算输出高度和宽度。如果是 True，则使用 `ceil` 计算输出形状的大小。默认为 False。
     - **exclusive** (bool，可选)：是否在平均池化模式忽略填充值，默认是 `True`。
     - **divisor_override** (int|float，可选)：如果指定，它将用作除数，否则根据`kernel_size`计算除数。默认`None`。

diff --git a/docs/api/paddle/nn/LPPool1D_cn.rst b/docs/api/paddle/nn/LPPool1D_cn.rst
@@ -0,0 +1,41 @@
+.. _cn_api_paddle_nn_LPPool1D:
+
+LPPool1D
+-------------------------------
+
+.. py:function:: paddle.nn.LPPool1D(norm_type, kernel_size, stride=None, padding=0, ceil_mode=False, data_format="NCL", name=None)
+
+根据输入 `x` , `kernel_size` 等参数对一个输入 Tensor 计算 1D 的幂平均池化。输入和输出都是 3-D Tensor，
+默认是以 `NCL` 格式表示的，其中 `N` 是 batch size, `C` 是通道数，`L` 是输入特征的长度。
+
+假设输入形状是(N, C, L)，输出形状是 (N, C, L_{out})，卷积核尺寸是 k, 1d 平均池化计算公式如下：
+
+.. math::
+
+    Output(N_i, C_i, l) = sum(Input[N_i, C_i, stride \times l:stride \times l+k]^{norm\_type})^{1/norm\_type}
+
+参数
+:::::::::
+    - **norm_type** (int|float)：幂平均池化的指数，不可以为 0。
+    - **kernel_size** (int|list|tuple) - 池化核的尺寸大小。如果 kernel_size 为 list 或 tuple 类型，其必须包含一个整数，最终池化核的大小为该数值。
+    - **stride** (int|list|tuple，可选) - 池化操作步长。如果 stride 为 list 或 tuple 类型，其必须包含一个整数，最终池化操作的步长为该数值。默认值为 None，这时会使用 kernel_size 作为 stride。
+    - **padding** (string|int|list|tuple) 池化填充。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法。如果它是一个元组或列表，它可以有 3 种格式：(1)包含 2 个整数值：[pad_height, pad_width]；(2)包含 4 个整数值：[pad_height_top, pad_height_bottom, pad_width_left, pad_width_right]；(3)包含 4 个二元组：当 data_format 为"NCHW"时为 [[0,0], [0,0], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right]]，当 data_format 为"NHWC"时为[[0,0], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right], [0,0]]。若为一个整数，则表示 H 和 W 维度上均为该值。默认值：0。
+    - **ceil_mode** (bool，可选) - 是否用 ceil 函数计算输出的 height 和 width，如果设置为 False，则使用 floor 函数来计算，默认为 False。
+    - **data_format** (str，可选)：输入和输出的数据格式，可以是"NCL"和"NLC"。N 是批尺寸，C 是通道数，L 是特征长度。默认值："NCL"
+    - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+
+
+形状
+:::::::::
+    - **x** (Tensor)：默认形状为（批大小，通道数，长度），即 NCL 格式的 3-D Tensor。其数据类型为 float32 或 float64。
+    - **output** (Tensor)：默认形状为（批大小，通道数，输出特征长度），即 NCL 格式的 3-D Tensor。其数据类型与输入 x 相同。
+
+返回
+:::::::::
+计算 LPPool1D 的可调用对象
+
+
+代码示例
+:::::::::
+
+COPY-FROM: paddle.nn.LPPool1D
diff --git a/docs/api/paddle/nn/LPPool2D_cn.rst b/docs/api/paddle/nn/LPPool2D_cn.rst
@@ -0,0 +1,57 @@
+.. _cn_api_paddle_nn_LPPool2D:
+
+LPPool2D
+-------------------------------
+
+.. py:function:: paddle.nn.LPPool2D(norm_type, kernel_size, stride=None, padding=0, ceil_mode=False, data_format="NCHW", name=None)
+构建 `LPPool2D` 类的一个可调用对象，其将构建一个二维幂平均池化层，根据输入参数 `kernel_size`, `stride`,
+`padding` 等参数对输入做平均池化操作。
+
+例如：
+
+输入：
+
+    X 形状：:math:`\left ( N,C,H_{in},W_{in} \right )`
+
+属性：
+
+    - kernel_size: :math:`ksize`
+    - stride: :math:`stride`
+    - norm_type: :math:`norm\_type`
+
+输出：
+
+    Out 形状：:math:`\left ( N,C,H_{out},W_{out} \right )`
+
+.. math::
+    out(N_i, C_j, h, w)  = (\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)^{norm\_type})^{1 / norm\_type}
+
+
+参数
+:::::::::
+    - **norm_type** (int|float)：幂平均池化的指数，不可以为 0。
+    - **kernel_size** (int|list|tuple)：池化核大小。如果它是一个元组或列表，它必须包含两个整数值，(pool_size_Height, pool_size_Width)。若为一个整数，则它的平方值将作为池化核大小，比如若 pool_size=2，则池化核大小为 2x2。
+    - **stride** (int|list|tuple，可选)：池化层的步长。如果它是一个元组或列表，它将包含两个整数，(pool_stride_Height, pool_stride_Width)。若为一个整数，则表示 H 和 W 维度上 stride 均为该值。默认值为 None，这时会使用 kernel_size 作为 stride。
+    - **padding** (str|int|list|tuple，可选) 池化填充。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法。如果它是一个元组或列表，它可以有 3 种格式：(1)包含 2 个整数值：[pad_height, pad_width]；(2)包含 4 个整数值：[pad_height_top, pad_height_bottom, pad_width_left, pad_width_right]；(3)包含 4 个二元组：当 data_format 为"NCHW"时为 [[0,0], [0,0], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right]]，当 data_format 为"NHWC"时为[[0,0], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right], [0,0]]。若为一个整数，则表示 H 和 W 维度上均为该值。默认值：0。
+    - **ceil_mode** (bool，可选)：是否用 ceil 函数计算输出高度和宽度。如果是 True，则使用 `ceil` 计算输出形状的大小。默认为 False。
+    - **data_format** (str，可选)：输入和输出的数据格式，可以是"NCHW"和"NHWC"。N 是批尺寸，C 是通道数，H 是特征高度，W 是特征宽度。默认值："NCHW"
+    - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+
+形状
+:::::::::
+    - **x** (Tensor)：默认形状为（批大小，通道数，高度，宽度），即 NCHW 格式的 4-D Tensor。其数据类型为 float16, float32, float64, int32 或 int64。
+    - **output** (Tensor)：默认形状为（批大小，通道数，输出特征高度，输出特征宽度），即 NCHW 格式的 4-D Tensor。其数据类型与输入相同。
+
+
+
+返回
+:::::::::
+计算 LPPool2D 的可调用对象
+
+
+
+代码示例
+:::::::::
+
+COPY-FROM: paddle.nn.LPPool2D
diff --git a/docs/api/paddle/nn/MaxPool1D_cn.rst b/docs/api/paddle/nn/MaxPool1D_cn.rst
@@ -17,7 +17,7 @@ MaxPool1D
 :::::::::
     - **kernel_size** (int|list|tuple) - 池化核的尺寸大小。如果 kernel_size 为 list 或 tuple 类型，其必须包含一个整数，最终池化核的大小为该数值。
     - **stride** (int|list|tuple，可选) - 池化操作步长。如果 stride 为 list 或 tuple 类型，其必须包含一个整数，最终池化操作的步长为该数值。默认值为 None，这时会使用 kernel_size 作为 stride。
-    - **padding** (str|int|list|tuple，可选) - 池化补零的方式。如果 padding 是一个字符串，则必须为 `SAME` 或者 `VALID`。如果是 turple 或者 list 类型，则应是 `[pad_left, pad_right]` 形式。如果 padding 是一个非 0 值，那么表示会在输入的两端都 padding 上同样长度的 0。
+    - **padding** (str|int|list|tuple，可选) - 池化补零的方式。如果 padding 是一个字符串，则必须为 `SAME` 或者 `VALID`。如果是 tuple 或者 list 类型，若其长度为 1，则会在输入的两端都填充上长度为 padding[0] 的 0，若其长度为 2，则应是 `[pad_before, pad_after]` 形式。如果 padding 是一个非 0 整数，那么表示会在输入的两端都填充上同样长度的 0。如果 padding 是长度为 2 的序列组成的 list 或 tuple，则其中的每个元素表示在相应维度上的填充长度。注意：在 batch_size 维度和通道维度应该设置为 [0, 0] 或 (0, 0)。默认值为 0。
     - **return_mask** (bool，可选) - 是否返回最大值的索引，默认为 False。
     - **ceil_mode** (bool，可选) - 是否用 ceil 函数计算输出的 height 和 width，如果设置为 False，则使用 floor 函数来计算，默认为 False。
     - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。

diff --git a/docs/api/paddle/nn/Overview_cn.rst b/docs/api/paddle/nn/Overview_cn.rst
@@ -95,6 +95,8 @@ pooling 层
     " :ref:`paddle.nn.MaxUnPool3D <cn_api_paddle_nn_MaxUnPool3D>` ", "三维最大反池化层"
     " :ref:`paddle.nn.FractionalMaxPool2D <cn_api_paddle_nn_FractionalMaxPool2D>` ", "二维分数阶最大值池化层"
     " :ref:`paddle.nn.FractionalMaxPool3D <cn_api_paddle_nn_FractionalMaxPool3D>` ", "三维分数阶最大值池化层"
+    " :ref:`paddle.nn.LPPool1D <cn_api_paddle_nn_LPPool1D>` ", "一维幂平均池化层"
+    " :ref:`paddle.nn.LPPool2D <cn_api_paddle_nn_LPPool2D>` ", "二维幂平均池化层"
 
 .. _padding_layers:
 
@@ -369,6 +371,8 @@ Pooling 相关函数
     " :ref:`paddle.nn.functional.max_unpool3d <cn_api_paddle_nn_functional_max_unpool3d>` ", "三维最大反池化层"
     " :ref:`paddle.nn.functional.fractional_max_pool2d <cn_api_paddle_nn_functional_fractional_max_pool2d>` ", "二维分数阶最大值池化"
     " :ref:`paddle.nn.functional.fractional_max_pool3d <cn_api_paddle_nn_functional_fractional_max_pool3d>` ", "三维分数阶最大值池化"
+    " :ref:`paddle.nn.functional.lp_pool1d <cn_api_paddle_nn_functional_lp_pool1d>` ", "一维平均幂池化"
+    " :ref:`paddle.nn.functional.lp_pool2d <cn_api_paddle_nn_functional_lp_pool2d>` ", "二维平均幂池化"
 
 .. _padding_functional:
 

diff --git a/docs/api/paddle/nn/functional/avg_pool2d_cn.rst b/docs/api/paddle/nn/functional/avg_pool2d_cn.rst
@@ -26,7 +26,7 @@ avg_pool2d
     - **x** (Tensor)：形状为 `[N,C,H,W]` 或 `[N,H,W,C]` 的 4-D Tensor，N 是批尺寸，C 是通道数，H 是特征高度，W 是特征宽度，数据类型为 float32 或 float64。
     - **kernel_size** (int|list|tuple)：池化核大小。如果它是一个元组或列表，它必须包含两个整数值，(pool_size_Height, pool_size_Width)。若为一个整数，则它的平方值将作为池化核大小，比如若 pool_size=2，则池化核大小为 2x2。
     - **stride** (int|list|tuple)：池化层的步长。如果它是一个元组或列表，它将包含两个整数，(pool_stride_Height, pool_stride_Width)。若为一个整数，则表示 H 和 W 维度上 stride 均为该值。默认值为 kernel_size。
-    - **padding** (string|int|list|tuple) 池化填充。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法，计算细节可参考上述 pool_padding = "SAME"或 pool_padding = "VALID" 时的计算公式。如果它是一个元组或列表，它可以有 3 种格式：(1)包含 2 个整数值：[pad_height, pad_width]；(2)包含 4 个整数值：[pad_height_top, pad_height_bottom, pad_width_left, pad_width_right]；(3)包含 4 个二元组：当 data_format 为"NCHW"时为 [[0,0], [0,0], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right]]，当 data_format 为"NHWC"时为[[0,0], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right], [0,0]]。若为一个整数，则表示 H 和 W 维度上均为该值。默认值：0。
+    - **padding** (str|int|list|tuple，可选) 池化填充。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法。如果它是一个元组或列表，它可以有 3 种格式：(1)包含 2 个整数值：[pad_height, pad_width]；(2)包含 4 个整数值：[pad_height_top, pad_height_bottom, pad_width_left, pad_width_right]；(3)包含 4 个二元组：当 data_format 为"NCHW"时为 [[0,0], [0,0], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right]]，当 data_format 为"NHWC"时为[[0,0], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right], [0,0]]。若为一个整数，则表示 H 和 W 维度上均为该值。默认值：0。
     - **ceil_mode** (bool)：是否用 ceil 函数计算输出高度和宽度。如果是 True，则使用 `ceil` 计算输出形状的大小。默认为 None
     - **exclusive** (bool)：是否在平均池化模式忽略填充值，默认是 `True`。
     - **divisor_override** (int|float)：如果指定，它将用作除数，否则根据`kernel_size`计算除数。默认`None`。

diff --git a/docs/api/paddle/nn/functional/lp_pool1d_cn.rst b/docs/api/paddle/nn/functional/lp_pool1d_cn.rst
@@ -0,0 +1,37 @@
+.. _cn_api_paddle_nn_functional_lp_pool1d:
+
+lp_pool1d
+-------------------------------
+
+.. py:function:: paddle.nn.functional.lp_pool1d(x, norm_type, kernel_size, stride=None, padding=0, ceil_mode=False, data_format="NCL", name=None)
+
+根据输入 `x` , `kernel_size` 等参数对一个输入 Tensor 计算 1D 的幂平均池化。输入和输出都是 3-D Tensor，
+默认是以 `NCL` 格式表示的，其中 `N` 是 batch size, `C` 是通道数，`L` 是输入特征的长度。
+
+.. note::
+   详细请参考对应的 `Class` 请参考：:ref:`cn_api_paddle_nn_LPPool1D` 。
+
+
+参数
+:::::::::
+    - **x** (Tensor)：当前算子的输入，其是一个形状为 `[N, C, L]` 的 3-D Tensor。其中 `N` 是 batch size, `C` 是通道数，`L` 是输入特征的长度。其数据类型为 float16、float32 和 float64。
+    - **norm_type** (int|float)：幂平均池化的指数，不可以为 0。
+    - **kernel_size** (int|list|tuple)：池化核的尺寸大小。如果 kernel_size 为 list 或 tuple 类型，其必须包含一个整数。
+    - **stride** (int|list|tuple)：池化操作步长。如果 stride 为 list 或 tuple 类型，其必须包含一个整数。
+    - **padding** (string|int|list|tuple)：池化补零的方式。如果 padding 是一个字符串，则必须为 `SAME` 或者 `VALID`。如果是 turple 或者 list 类型，则应是 `[pad_left, pad_right]` 形式。如果 padding 是一个非 0 值，那么表示会在输入的两端都 padding 上同样长度的 0。
+    - **ceil_mode** (bool)：是否用 ceil 函数计算输出的 height 和 width，如果设置为 False，则使用 floor 函数来计算，默认为 False。
+    - **data_format** (str)：输入和输出的数据格式，可以是"NCL"和"NLC"。N 是批尺寸，C 是通道数，L 是特征长度。默认值："NCL"
+    - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+
+
+
+返回
+:::::::::
+``Tensor``，输入 `x` 经过幂平均池化计算得到的目标 3-D Tensor，其数据类型与输入相同。
+
+
+
+代码示例
+:::::::::
+
+COPY-FROM: paddle.nn.functional.lp_pool1d