[API-Compat] Multiple changes: (#7433)

- Adjust `put_along_axis`, `take_along_axis`
- Add new compatible upgrade info for `scatter`, `scatter_`, `gather`
- Add `compat.pad`
- Deleted `scatter` related API difference doc

Author: Enigmatisms

docs/api/paddle/compat/Overview_cn.rst

@@ -15,12 +15,13 @@ PyTorch 兼容函数
     :widths: 10, 30
 
     " :ref:`max <cn_api_paddle_compat_max>` ", "包含 `amax`、同时返回 values 及 indices 的轴向最大值、`maximum` 三种功能"
+    " :ref:`median <cn_api_paddle_compat_median>` ", "兼容版中位数，支持 dim/keepdim/out 签名"
     " :ref:`min <cn_api_paddle_compat_min>` ", "包含 `amin`、同时返回 values 及 indices 的轴向最小值、`minimum` 三种功能"
+    " :ref:`nanmedian <cn_api_paddle_compat_nanmedian>` ", "忽略 NaN 的兼容版中位数，支持 dim/keepdim/out 签名"
+    " :ref:`pad <cn_api_paddle_compat_pad>` ", "从最后一维度开始进行 padding、padding 正确兼容转换的填充函数"
     " :ref:`softmax <cn_api_paddle_compat_softmax>` ", "softmax 函数"
     " :ref:`sort <cn_api_paddle_compat_sort>` ", "同时返回 values 及 indices 的排序"
     " :ref:`split <cn_api_paddle_compat_split>` ", "允许非整除块大小输入的 Tensor 轴向切分"
-    " :ref:`median <cn_api_paddle_compat_median>` ", "兼容版中位数，支持 dim/keepdim/out 签名"
-    " :ref:`nanmedian <cn_api_paddle_compat_nanmedian>` ", "忽略 NaN 的兼容版中位数，支持 dim/keepdim/out 签名"
 
 
 .. _about_compat_class:

docs/api/paddle/compat/pad_cn.rst

@@ -0,0 +1,46 @@
+.. _cn_api_paddle_compat_pad:
+
+pad
+-------------------------------
+
+.. py:function:: paddle.compat.pad(input, pad, mode='constant', value=0.0)
+
+PyTorch 兼容的 :ref:`cn_api_paddle_nn_functional_pad` 版本
+
+使用前请详细参考：`【paddle 参数更多】torch.nn.functional.pad`_ 以确定是否使用此模块。
+
+.. _【paddle 参数更多】torch.nn.functional.pad: https://www.paddlepaddle.org.cn/documentation/docs/en/guides/model_convert/convert_from_pytorch/api_difference/functional/torch.nn.functional.pad.html
+
+根据 ``'pad'`` 和 ``'mode'`` 对输入张量进行 padding 操作。所有操作都是从 **最右侧的维度** （最后一个维度）开始。
+
+.. note::
+    此 API 遵循 ``torch.nn.functional.pad`` 的函数签名和行为以实现 PyTorch 兼容。
+    如需使用 Paddle 原生实现，请参考 :ref:`cn_api_paddle_nn_functional_pad`
+
+参数
+:::::::::
+       - **input** (Tensor) - 输入 N 维 Tensor，支持 float32、float64、int32、int64、complex64、complex128
+       - **pad** (Tensor|list[int]|tuple[int]) - 填充大小，基本数据类型是 ``int32``。
+       - **mode** (str, 可选) - - padding 的四种模式，分别为 ``'constant'``、``'reflect'``、``'replicate'`` 和 ``'circular'``，默认值为 ``constant``
+
+         - ``'constant'`` 表示填充常数 ``value``；
+         - ``'reflect'`` 表示填充以 ``input`` 边界值为轴的映射；
+         - ``'replicate'`` 表示填充 ``input`` 边界值；
+         - ``'circular'`` 为循环填充 ``input``。
+
+       - **value** (float, 可选) - 以 ``'constant'`` 模式填充区域时填充的值，使用其他模式时此值不被使用。默认值为 :math:`0.0`。
+
+.. note::
+
+    对于非 ``'constant'``, ``pad`` 的尺寸不能超过 ``min(2 * input.ndim - 2, 6)``。
+    此外非 ``'constant'`` 中只有 2D、3D、4D 以及 5D 张量受到支持，且至多仅能操作最后三个维度（当 ``ndim>=3`` 时）。
+
+返回
+:::::::::
+Tensor，对 ``input`` 进行 ``'pad'`` 的结果，数据类型和 ``input`` 相同。
+
+
+代码示例
+:::::::::
+
+COPY-FROM: paddle.compat.pad

docs/api/paddle/gather_cn.rst

@@ -3,6 +3,14 @@
 gather
 -------------------------------
 
+.. caution::
+
+    本接口根据输入参数的不同，包含两种不同的功能。
+
+    下面列举的两种功能参数输入方式 **互斥**，混用非公共的参数输入方法将会导致报错，请谨慎使用。
+
+=====
+
 .. py:function:: paddle.gather(x, index, axis=None, name=None)
 
 根据索引 index 获取输入 ``x`` 的指定 ``axis`` 维度的条目，并将它们拼接在一起。
@@ -46,3 +54,34 @@ Tensor，当 index 为一维 Tensor 时，返回和输入 Tensor 的形状相同
 ::::::::::::
 
 COPY-FROM: paddle.gather
+
+=====
+
+.. py:function:: paddle.gather(input, dim, index, out=None)
+
+PyTorch 兼容的 ``gather`` 操作：根据索引 index 获取输入 ``input`` 的指定 ``dim`` 维度的条目，并将它们拼接在一起。行为与 ``cn_api_paddle_take_along_axis`` 在 ``broadcast=False`` 情况下一致。
+
+接口对比可见 `【torch 参数更多】torch.gather`_ 。
+
+.. _【torch 参数更多】torch.gather: https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/model_convert/convert_from_pytorch/api_difference/torch/torch.gather.html
+
+参数
+::::::::::::
+        - **input** (Tensor) - 输入 Tensor，支持的数据类型包括 int32、int64、float32、float64、int16、uint8、float16（GPU）以及 bfloat16（GPU） 。
+        - **dim** (int) - 指定 index 获取输入的维度，``dim`` 的类型可以是 int 或者。
+        - **index** (Tensor) - 索引 Tensor，``index`` 张量的各维度需要小于等于 ``input`` 张量的各维度（除 ``dim`` 维度外），且值需要在 ``input.shape[dim]`` 范围内。数据类型为 int32 或 int64。
+        - **out** (Tensor，可选) - 用于引用式传入输出值，注意：动态图下 out 可以是任意 Tensor，默认值为 None。
+
+.. caution::
+
+        本接口没有实现 PyTorch 的 ``sparse_grad`` 参数！梯度默认是稠密的，等效于 ``sparse_grad=False``。
+
+
+返回
+::::::::::::
+Tensor，与 input 有数据类型，与 ``index`` 有相同的形状。
+
+代码示例
+:::::::::
+
+见 :ref:`cn_api_paddle_take_along_axis` 的代码示例。

docs/api/paddle/put_along_axis_cn.rst

@@ -4,14 +4,15 @@ put_along_axis
 -------------------------------
 
 .. py:function:: paddle.put_along_axis(arr, indices, values, axis, reduce='assign', include_self=True, broadcast=True)
+
 基于输入 index 矩阵，将输入 value 沿着指定 axis 放置入 arr 矩阵。索引矩阵和 value 必须和 arr 矩阵有相同的维度，需要能够 broadcast 与 arr 矩阵对齐。
 
 参数
 :::::::::
 
-    - **arr**  (Tensor) - 输入的 Tensor 作为目标矩阵，数据类型为：bfloat16、float16、float32、float64、int32、int64、uint8。
-    - **indices**  (Tensor) - 索引矩阵，包含沿轴提取 1d 切片的下标，必须和 arr 矩阵有相同的维度，需要能够 broadcast 与 arr 矩阵对齐，数据类型为：int32、int64。
-    - **values** （float）- 需要插入的值，形状和维度需要能够被 broadcast 与 indices 矩阵匹配，数据类型为：bfloat16、float16、float32、float64、int32、int64、uint8。
+    - **arr**  (Tensor) - 输入的 Tensor 作为目标矩阵，数据类型为：bfloat16、float16、float32、float64、int32、int64、uint8、int16。
+    - **indices**  (Tensor) - 索引矩阵，包含沿轴提取 1d 切片的下标，必须和 arr 矩阵有相同的维度。当 ``broadcast`` 为 ``True`` 时，需要能够 broadcast 与 arr 矩阵对齐，否则除 ``axis`` 维度，其他维度都需要小于等于 ``arr`` 与 ``values`` 的对应维度。数据类型为：int32、int64。
+    - **values** (float) - 需要插入的值，当 ``broadcast`` 为 ``True`` 时，形状和维度需要能够被 broadcast 与 indices 矩阵匹配，否则各维度需大于等于 ``indices`` 的各维度。数据类型为：bfloat16、float16、float32、float64、int32、int64、uint8、int16。
     - **axis**  (int) - 指定沿着哪个维度获取对应的值，数据类型为：int。
     - **reduce** (str，可选) - 归约操作类型，默认为 ``assign``，可选为 ``add``、 ``multiple``、 ``mean``、 ``amin``、 ``amax``。不同的规约操作插入值 value 对于输入矩阵 arr 会有不同的行为，如为 ``assgin`` 则覆盖输入矩阵， ``add`` 则累加至输入矩阵， ``mean`` 则计算累计平均值至输入矩阵， ``multiple`` 则累乘至输入矩阵， ``amin`` 则计算累计最小值至输入矩阵， ``amax`` 则计算累计最大值至输入矩阵。
     - **include_self** (bool，可选) - 规约时是否包含 arr 的元素，默认为 ``True``。

docs/api/paddle/scatter__cn.rst

@@ -2,10 +2,26 @@
 
 scatter\_
 -------------------------------
+
+.. caution::
+
+    本接口根据输入参数的不同，包含两种不同的功能。
+
+    下面列举的两种功能参数输入方式 **互斥**，混用非公共的参数输入方法将会导致报错，请谨慎使用。
+
+=====
+
 .. py:function:: paddle.scatter_(x, index, updates, overwrite=True, name=None)
 
 Inplace 版本的 :ref:`cn_api_paddle_scatter` API，对输入 `x` 采用 Inplace 策略。
 
+=====
+
+.. py:function:: paddle.scatter_(input, dim, index, src, reduce=None, out=None)
+
+PyTorch 兼容 Inplace 版本的 :ref:`cn_api_paddle_scatter` API，对输入 `input` 采用 Inplace 策略。
+
+
 更多关于 inplace 操作的介绍请参考 `3.1.3 原位（Inplace）操作和非原位操作的区别`_ 了解详情。
 
 .. _3.1.3 原位（Inplace）操作和非原位操作的区别: https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/beginner/tensor_cn.html#id3

docs/api/paddle/scatter_cn.rst

@@ -2,6 +2,16 @@
 
 scatter
 -------------------------------
+
+.. caution::
+
+    本接口根据输入参数的不同，包含两种不同的功能。
+
+    下面列举的两种功能参数输入方式 **互斥**，混用非公共的参数输入方法将会导致报错，请谨慎使用。
+
+
+=====
+
 .. py:function:: paddle.scatter(x, index, updates, overwrite=True, name=None)
 
 
@@ -20,11 +30,11 @@ COPY-FROM: paddle.scatter:scatter-example-1
 
 参数
 :::::::::
-    - **x** (Tensor) - ndim> = 1 的输入 N-D Tensor。数据类型可以是 float32，float64。
+    - **x** （Tensor） - ``ndim>= 1`` 的输入 N-D Tensor。数据类型可以是 float32，float64。
     - **index** （Tensor）- 一维或者零维 Tensor。数据类型可以是 int32，int64。 ``index`` 的长度不能超过 ``updates`` 的长度，并且 ``index`` 中的值不能超过输入的长度。
-    - **updates** （Tensor）- 根据 ``index`` 使用 ``update`` 参数更新输入 ``x``。当 ``index`` 为一维 tensor 时，``updates`` 形状应与输入 ``x`` 相同，并且 dim>1 的 dim 值应与输入 ``x`` 相同。当 ``index`` 为零维 tensor 时，``updates`` 应该是一个 (N-1)-D 的 Tensor，并且 ``updates`` 的第 i 个维度应该与 ``x`` 的 i+1 个维度相同。
+    - **updates** （Tensor）- 根据 ``index`` 使用 ``update`` 参数更新输入 ``x``。当 ``index`` 为一维 tensor 时，``updates`` 形状应与输入 ``x`` 相同，并且 ``dim>1`` 的 dim 值应与输入 ``x`` 相同。当 ``index`` 为零维 tensor 时，``updates`` 应该是一个 ``(N-1)-D`` 的 Tensor，并且 ``updates`` 的第 i 个维度应该与 ``x`` 的 ``i+1`` 个维度相同。
     - **overwrite** （bool，可选）- 指定索引 ``index`` 相同时，更新输出的方式。如果为 True，则使用覆盖模式更新相同索引的输出，如果为 False，则使用累加模式更新相同索引的输出。默认值为 True。
-    - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+    - **name** （str，可选） - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
 
 返回
 :::::::::
@@ -35,3 +45,28 @@ Tensor，与 x 有相同形状和数据类型。
 :::::::::
 
 COPY-FROM: paddle.scatter:scatter-example-2
+
+
+=====
+
+.. py:function:: paddle.scatter(input, dim, index, src, reduce=None, out=None)
+
+PyTorch 兼容的 scatter 函数。基于 :ref:`cn_api_paddle_put_along_axis` 实现，等效于 ``paddle.put_along_axis(..., broadcast=False)``。详细的用法见 :ref:`cn_api_paddle_put_along_axis`。
+
+参数
+:::::::::
+    - **input** （Tensor） - 输入 N-D Tensor。数据类型可以是 float32，float64，float16，bfloat16，int32，int64，int16，uint8。
+    - **dim** （int） - 进行 scatter 操作的维度，范围为 ``[-input.ndim, input.ndim)``。
+    - **index** （Tensor）- 索引矩阵，包含沿轴提取 1d 切片的下标，必须和 arr 矩阵有相同的维度。注意，除了 ``dim`` 维度外， ``index`` 张量的各维度大小应该小于等于 ``input`` 以及 ``src`` 张量。内部的值应该在 ``input.shape[dim]`` 范围内。数据类型可以是 int32，int64。
+    - **src** （Tensor）- 需要插入的值。``src`` 是张量时，各维度大小需要至少大于等于 ``index`` 各维度。不受到 ``input`` 的各维度约束。当为标量值时，会自动广播大小到 ``index``。数据类型为：bfloat16、float16、float32、float64、int32、int64、uint8、int16。本参数有一个互斥的别名 ``value``。
+    - **reduce** （str，可选）- 指定 scatter 的归约方式。默认值为 None，等效为 ``assign``。可选为 ``add``、 ``multiple``、 ``mean``、 ``amin``、 ``amax``。不同的规约操作插入值 src 对于输入矩阵 arr 会有不同的行为，如为 ``assgin`` 则覆盖输入矩阵， ``add`` 则累加至输入矩阵， ``mean`` 则计算累计平均值至输入矩阵， ``multiple`` 则累乘至输入矩阵， ``amin`` 则计算累计最小值至输入矩阵， ``amax`` 则计算累计最大值至输入矩阵。
+    - **out** (Tensor，可选) - 用于引用式传入输出值，注意：动态图下 out 可以是任意 Tensor，默认值为 None。
+
+返回
+:::::::::
+Tensor，与 input 有相同形状和数据类型。
+
+代码示例
+:::::::::
+
+见 :ref:`cn_api_paddle_put_along_axis` 的代码示例。

docs/api/paddle/take_along_axis_cn.rst

@@ -4,6 +4,7 @@ take_along_axis
 -------------------------------
 
 .. py:function:: paddle.take_along_axis(arr, indices, axis, broadcast=True)
+
 基于输入索引矩阵，沿着指定 axis 从 arr 矩阵里选取 1d 切片。索引矩阵必须和 arr 矩阵有相同的维度，需要能够 broadcast 与 arr 矩阵对齐。
 
 .. note::
@@ -12,9 +13,9 @@ take_along_axis
 参数
 :::::::::
 
-    - **arr**  (Tensor) - 输入的 Tensor 作为源矩阵，数据类型为：bfloat16、float16、float32、float64、int32、int64、uint8。
+    - **arr**  (Tensor) - 输入的 Tensor 作为源矩阵，数据类型为：bfloat16、float16、float32、float64、int32、int64、uint8、int16。
       别名： ``input``
-    - **indices**  (Tensor) - 索引矩阵，包含沿轴提取 1d 切片的下标，必须和 arr 矩阵有相同的维度，需要能够 broadcast 与 arr 矩阵对齐，数据类型为：int32、int64。
+    - **indices**  (Tensor) - 索引矩阵，包含沿轴提取 1d 切片的下标，必须和 arr 矩阵有相同的维度，当 ``broadcast`` 为 ``True`` 时，需要能够 broadcast 与 arr 矩阵对齐，否则除 ``axis`` 维度，其他维度都需要小于等于 ``arr`` 的对应维度，数据类型为：int32、int64。
     - **axis**  (int) - 指定沿着哪个维度获取对应的值，数据类型为：int。
       别名： ``dim``
     - **broadcast** (bool，可选) - 是否广播 ``index`` 矩阵，默认为 ``True``。