【Hackathon 5th No.6】 为 Paddle 增强put_along_axis API

docs/api/paddle/Tensor_cn.rst

@@ -2597,7 +2597,7 @@ is_integer()
 
 请参考 :ref:`cn_api_paddle_is_integer`
 
-take_along_axis(arr, indices, axis)
+take_along_axis(arr, indices, axis, broadcast=True)
 :::::::::
 
 基于输入索引矩阵，沿着指定 axis 从 arr 矩阵里选取 1d 切片。索引矩阵必须和 arr 矩阵有相同的维度，需要能够 broadcast 与 arr 矩阵对齐。
@@ -2608,10 +2608,10 @@ take_along_axis(arr, indices, axis)
 
 请参考 :ref:`cn_api_paddle_take_along_axis`
 
-put_along_axis(arr, indices, value, axis, reduce="assign")
+put_along_axis(arr, indices, value, axis, reduce="assign", include_self=True, broadcast=True)
 :::::::::
 
-基于输入 indices 矩阵，将输入 value 沿着指定 axis 放置入 arr 矩阵。索引矩阵和 value 必须和 arr 矩阵有相同的维度，需要能够 broadcast 与 arr 矩阵对齐。
+基于输入 indices 矩阵，将输入 value 沿着指定 axis 放置入 arr 矩阵。索引矩阵和 value 必须和 arr 矩阵有相同的维度，如果 ``broadcast`` 为 ``True``，则需要能够 broadcast 与 arr 矩阵对齐。
 
 返回：计算后的 Tensor
 

docs/api/paddle/put_along_axis__cn.rst

@@ -3,7 +3,7 @@
 put_along_axis\_
 -------------------------------
 
-.. py:function:: paddle.put_along_axis_(indices, value, axis, reduce)
+.. py:function:: paddle.put_along_axis_(indices, value, axis, reduce, include_self)
 
 Inplace 版本的 :ref:`cn_api_paddle_put_along_axis` API，对输入 `x` 采用 Inplace 策略。
 

docs/api/paddle/put_along_axis_cn.rst

@@ -3,7 +3,7 @@
 put_along_axis
 -------------------------------
 
-.. py:function:: paddle.put_along_axis(arr, indices, values, axis, reduce='assign')
+.. 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 矩阵对齐。
 
 参数
@@ -13,7 +13,9 @@ put_along_axis
 - **indices**  (Tensor) - 索引矩阵，包含沿轴提取 1d 切片的下标，必须和 arr 矩阵有相同的维度，需要能够 broadcast 与 arr 矩阵对齐，数据类型为：int、int64。
 - **value** （float）- 需要插入的值，形状和维度需要能够被 broadcast 与 indices 矩阵匹配，数据类型为：float32、float64。
 - **axis**  (int) - 指定沿着哪个维度获取对应的值，数据类型为：int。
-- **reduce** (str，可选) - 归约操作类型，默认为 ``assign``，可选为 ``add`` 或 ``multiple``。不同的规约操作插入值 value 对于输入矩阵 arr 会有不同的行为，如为 ``assgin`` 则覆盖输入矩阵，``add`` 则累加至输入矩阵，``multiple`` 则累乘至输入矩阵。
+- **reduce** (str，可选) - 归约操作类型，默认为 ``assign``，可选为 ``add``、 ``multiple``、 ``mean``、 ``amin``、 ``amax``。不同的规约操作插入值 value 对于输入矩阵 arr 会有不同的行为，如为 ``assgin`` 则覆盖输入矩阵， ``add`` 则累加至输入矩阵， ``mean`` 则计算累计平均值至输入矩阵， ``multiple`` 则累乘至输入矩阵， ``amin`` 则计算累计最小值至输入矩阵， ``amax`` 则计算累计最大值至输入矩阵。
+- **include_self** (bool，可选) - 规约时是否包含 arr 的元素，默认为 ``True``。
+- **broadcast** (bool，可选) - 是否广播 ``index`` 矩阵，默认为 ``True``。
 
 返回
 :::::::::

docs/api/paddle/take_along_axis_cn.rst

@@ -3,7 +3,7 @@
 take_along_axis
 -------------------------------
 
-.. py:function:: paddle.take_along_axis(arr, indices, axis)
+.. py:function:: paddle.take_along_axis(arr, indices, axis, broadcast=True)
 基于输入索引矩阵，沿着指定 axis 从 arr 矩阵里选取 1d 切片。索引矩阵必须和 arr 矩阵有相同的维度，需要能够 broadcast 与 arr 矩阵对齐。
 
 参数
@@ -12,6 +12,7 @@ take_along_axis
 - **arr**  (Tensor) - 输入的 Tensor 作为源矩阵，数据类型为：float32、float64。
 - **indices**  (Tensor) - 索引矩阵，包含沿轴提取 1d 切片的下标，必须和 arr 矩阵有相同的维度，需要能够 broadcast 与 arr 矩阵对齐，数据类型为：int、int64。
 - **axis**  (int) - 指定沿着哪个维度获取对应的值，数据类型为：int。
+- **broadcast** (bool，可选) - 是否广播 ``index`` 矩阵，默认为 ``True``。
 
 返回
 :::::::::

docs/guides/custom_op/new_cpp_op_cn.md

@@ -327,7 +327,7 @@ PADDLE_API Tensor ones(const IntArray& shape, DataType dtype = DataType::FLOAT32
 PADDLE_API Tensor overlap_add(const Tensor& x, int hop_length, int axis = -1);
 PADDLE_API Tensor pixel_shuffle(const Tensor& x, int upscale_factor, const std::string& data_format);
 PADDLE_API Tensor poisson(const Tensor& x);
-PADDLE_API Tensor put_along_axis(const Tensor& arr, const Tensor& indices, const Tensor& values, int axis, const std::string& reduce = "assign");
+PADDLE_API Tensor put_along_axis(const Tensor& arr, const Tensor& indices, const Tensor& values, int axis, const std::string& reduce = "assign", include_self = true);
 PADDLE_API std::tuple<Tensor,Tensor> qr(const Tensor& x, const std::string& mode);
 PADDLE_API Tensor real(const Tensor& x);
 PADDLE_API Tensor reciprocal(const Tensor& x);

docs/guides/model_convert/convert_from_pytorch/api_difference/Tensor/torch.Tensor.gather.md

@@ -9,7 +9,7 @@ torch.Tensor.gather(dim, index)
 ### [paddle.Tensor.take_along_axis](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/Tensor_cn.html#take-along-axis-arr-index-axis)
 
 ```python
-paddle.Tensor.take_along_axis(index, axis)
+paddle.Tensor.take_along_axis(index, axis, broadcast=True)
 ```
 
 两者功能一致且参数用法一致，仅参数名不一致，具体如下：

docs/guides/model_convert/convert_from_pytorch/api_difference/Tensor/torch.Tensor.scatter.md

@@ -9,7 +9,7 @@ torch.Tensor.scatter(dim, index, src, reduce=None)
 ### [paddle.Tensor.put_along_axis](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/Tensor_cn.html#put-along-axis-arr-index-value-axis-reduce-assign)
 
 ```python
-paddle.Tensor.put_along_axis(indices, values, axis, reduce="assign")
+paddle.Tensor.put_along_axis(indices, values, axis, reduce="assign", include_self=True, broadcast=True)
 
 ```
 
@@ -22,3 +22,5 @@ paddle.Tensor.put_along_axis(indices, values, axis, reduce="assign")
 | index   | indices        | 表示输入的索引张量，仅参数名不一致。 |
 | src     | values        | 表示需要插入的值，仅参数名不一致。 |
 | reduce       | reduce       | 归约操作类型 。 |
+| -            | include_self | 表示插入 values 时是否包含 arr 中的元素，PyTorch 无此参数。|
+| -            | broadcast   | 表示是否需要广播 indices 矩阵，PyTorch 无此参数。 |

docs/guides/model_convert/convert_from_pytorch/api_difference/Tensor/torch.Tensor.scatter_.md

@@ -9,7 +9,7 @@ torch.Tensor.scatter_(dim, index, src)
 ### [paddle.Tensor.put_along_axis_](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/put_along_axis__cn.html#put-along-axis)
 
 ```python
-paddle.Tensor.put_along_axis_(index, value, axis, reduce="assign")
+paddle.Tensor.put_along_axis_(index, value, axis, reduce="assign", include_self=True)
 
 ```
 

docs/guides/model_convert/convert_from_pytorch/api_difference/Tensor/torch.Tensor.scatter_add.md

@@ -12,7 +12,9 @@ torch.Tensor.scatter_add(dim, index, src)
 paddle.Tensor.put_along_axis(indices,
                               values,
                               axis,
-                              reduce='assign')
+                              reduce='assign',
+                              include_self=True,
+                              broadcast=True)
 ```
 
 其中 Paddle 相比 Pytorch 支持更多其他参数，具体如下：
@@ -24,3 +26,5 @@ paddle.Tensor.put_along_axis(indices,
 | index         | indices     | 表示输入的索引张量，仅参数名不一致。                   |
 | src           | values      | 表示需要插入的值，仅参数名不一致。                   |
 | -             | reduce      | 表示对输出 Tensor 的计算方式， PyTorch 无此参数, Paddle 应设置为 'add' 。  |
+| -            | include_self | 表示插入 values 时是否包含 arr 中的元素，PyTorch 无此参数，Paddle 应设置为 'True' 。 |
+| -            | broadcast   | 表示是否需要广播 indices 矩阵，PyTorch 无此参数，Paddle 应设置为 'False' 结果才与 pytorch 一致。 |

docs/guides/model_convert/convert_from_pytorch/api_difference/Tensor/torch.Tensor.scatter_add_.md

@@ -14,7 +14,8 @@ torch.Tensor.scatter_add_(dim,
 paddle.Tensor.put_along_axis_(indices,
                               values,
                               axis,
-                              reduce='assign')
+                              reduce='assign'，
+                              include_self=True)
 ```
 
 其中 Paddle 相比 Pytorch 支持更多其他参数，具体如下：
@@ -26,3 +27,4 @@ paddle.Tensor.put_along_axis_(indices,
 | index         | indices     | 表示输入的索引张量，仅参数名不一致。                   |
 | src           | values      | 表示需要插入的值，仅参数名不一致。                   |
 | -             | reduce      | 表示对输出 Tensor 的计算方式， PyTorch 无此参数, Paddle 应设置为 'add' 。  |
+| -            | include_self | 表示插入 values 时是否包含 arr 中的元素，PyTorch 无此参数，Paddle 应设置为 'True' 。 |

docs/guides/model_convert/convert_from_pytorch/api_difference/Tensor/torch.Tensor.take_along_dim.md

@@ -10,7 +10,8 @@ torch.Tensor.take_along_dim(indices,
 
 ```python
 paddle.Tensor.take_along_axis(indices,
-                    axis)
+                    axis,
+                    broadcast=True)
 ```
 
 两者功能一致，参数名不一致，具体如下：

docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.gather.md

@@ -15,7 +15,8 @@ torch.gather(input,
 ```python
 paddle.take_along_axis(arr,
                        indices,
-                       axis)
+                       axis,
+                       broadcast=True)
 ```
 
 Pytorch 相比 Paddle 支持更多其他参数，具体如下：

docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.scatter.md

@@ -9,7 +9,7 @@ torch.scatter(input,dim, index, src, reduce=None,out=None)
 ### [paddle.put_along_axis](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/put_along_axis_cn.html#cn-api-paddle-tensor-put-along-axis)
 
 ```python
-paddle.put_along_axis(arr,indices, values, axis, reduce="assign")
+paddle.put_along_axis(arr,indices, values, axis, reduce="assign", include_self=True, broadcast=True)
 
 ```
 
@@ -22,8 +22,10 @@ paddle.put_along_axis(arr,indices, values, axis, reduce="assign")
 | dim     | axis         | 表示在哪一个维度 scatter ，仅参数名不一致。 |
 | index   | indices        | 表示输入的索引张量，仅参数名不一致。 |
 | src     | values        | 表示需要插入的值，仅参数名不一致。 |
-| reduce       | reduce       | 归约操作类型 。 |
-| out       | -       | 表示输出的 Tensor，Paddle 无此参数，需要转写。 |
+| reduce  | reduce       | 归约操作类型 。 |
+| -       | include_self | 表示插入 values 时是否包含 arr 中的元素，PyTorch 无此参数|
+| -       | broadcast   | 表示是否需要广播 indices 矩阵，PyTorch 无此参数，Paddle 应设置为 'False' 结果才与 pytorch 一致。 |
+| out     | -       | 表示输出的 Tensor，Paddle 无此参数，需要转写。 |
 
 
 ### 转写示例

docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.scatter_add.md

@@ -16,7 +16,9 @@ paddle.put_along_axis(arr,
                       indices,
                       values,
                       axis,
-                      reduce='assign')
+                      reduce='assign',
+                      include_self=True,
+                      broadcast=True)
 ```
 
 其中 Paddle 相比 Pytorch 支持更多其他参数，具体如下：
@@ -28,4 +30,6 @@ paddle.put_along_axis(arr,
 | dim          | axis        | 表示在哪一个维度 scatter ，仅参数名不一致。                             |
 | index        | indices     | 表示输入的索引张量，仅参数名不一致。                                    |
 | src          | values      | 表示需要插入的值，仅参数名不一致。                                      |
-| -            | reduce      | 表示插入 values 时的计算方式，PyTorch 无此参数，Paddle 应设置为 'add' 。|
+| -            | reduce      | 表示插入 values 时的计算方式，PyTorch 无此参数，Paddle 应设置为 'add' 。 |
+| -            | include_self | 表示插入 values 时是否包含 arr 中的元素，PyTorch 无此参数，Paddle 应设置为 'True' 。 |
+| -            | broadcast   | 表示是否需要广播 indices 矩阵，PyTorch 无此参数，Paddle 应设置为 'False' 结果才与 pytorch 一致。 |

docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.take_along_dim.md

@@ -14,7 +14,8 @@ torch.take_along_dim(input,
 ```python
 paddle.take_along_axis(arr,
                        indices,
-                       axis)
+                       axis,
+                       broadcast=True)
 ```
 
 Pytorch 相比 Paddle 支持更多其他参数，具体如下：