Add docs for amax/amin (PaddlePaddle#4162)

* copy code example for max and min

* add amax/amin

doc/fluid/api_cn/tensor_cn/amax_cn.rst

@@ -0,0 +1,31 @@
+.. _cn_api_paddle_tensor_amax:
+
+amax
+-------------------------------
+
+.. py:function:: paddle.tensor.amax(x, axis=None, keepdim=False, name=None)
+
+:alias_main: paddle.amax
+:alias: paddle.amax,paddle.tensor.amax,paddle.tensor.math.amax
+
+该OP是对指定维度上的Tensor元素求最大值运算，并输出相应的计算结果。
+
+.. note::
+
+    对输入有多个最大值的情况下，max 将梯度完整传回到最大值对应的位置，amax 会将梯度平均传回到最大值对应的位置
+
+参数
+:::::::::
+   - **x** （Tensor）- Tensor，支持数据类型为float32，float64，int32，int64。
+   - **axis** （list | int ，可选）- 求最大值运算的维度。如果为None，则计算所有元素的最大值并返回包含单个元素的Tensor变量，否则必须在  :math:`[-x.ndim, x.ndim]` 范围内。如果 :math:`axis[i] <0` ，则维度将变为 :math:`x.ndim+axis[i]` ，默认值为None。
+   - **keepdim** （bool）- 是否在输出Tensor中保留减小的维度。如果keepdim 为 False，结果张量的维度将比输入张量的小，默认值为False。
+   - **name** （str， 可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
+
+返回
+:::::::::
+   Tensor, 在指定axis上进行求最大值运算的Tensor，数据类型和输入数据类型一致。
+
+
+代码示例
+::::::::::
+COPY-FROM: paddle.amax

doc/fluid/api_cn/tensor_cn/amin_cn.rst

@@ -0,0 +1,31 @@
+.. _cn_api_paddle_tensor_amin:
+
+amin
+-------------------------------
+
+.. py:function:: paddle.tensor.amin(x, axis=None, keepdim=False, name=None)
+
+:alias_main: paddle.amin
+:alias: paddle.amin,paddle.tensor.amin,paddle.tensor.math.amin
+
+该OP是对指定维度上的Tensor元素求最小值运算，并输出相应的计算结果。
+
+.. note::
+
+    对输入有多个最小值的情况下，min 将梯度完整传回到最小值对应的位置，amin 会将梯度平均传回到最小值对应的位置
+
+参数
+:::::::::
+   - **x** （Tensor）- Tensor，支持数据类型为float32，float64，int32，int64。
+   - **axis** （list | int ，可选）- 求最小值运算的维度。如果为None，则计算所有元素的最小值并返回包含单个元素的Tensor变量，否则必须在  :math:`[−x.ndim, x.ndim]` 范围内。如果 :math:`axis[i] < 0` ，则维度将变为 :math:`x.ndim+axis[i]` ，默认值为None。
+   - **keepdim** （bool）- 是否在输出Tensor中保留减小的维度。如果keepdim 为False，结果张量的维度将比输入张量的小，默认值为False。
+   - **name** （str， 可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
+
+返回
+:::::::::
+   Tensor，在指定axis上进行求最小值运算的Tensor，数据类型和输入数据类型一致。
+
+
+代码示例
+::::::::::
+COPY-FROM: paddle.amin

doc/fluid/api_cn/tensor_cn/max_cn.rst

@@ -10,6 +10,10 @@ max
 
 该OP是对指定维度上的Tensor元素求最大值运算，并输出相应的计算结果。
 
+.. note::
+
+    对输入有多个最大值的情况下，max 将梯度完整传回到最大值对应的位置，amax 会将梯度平均传回到最大值对应的位置
+
 参数
 :::::::::
    - **x** （Tensor）- Tensor，支持数据类型为float32，float64，int32，int64。
@@ -24,39 +28,4 @@ max
 
 代码示例
 ::::::::::
-
-..  code-block:: python
-
-    import numpy as np
-    import paddle
-
-    paddle.disable_static()
-
-    # data_x is a variable with shape [2, 4]
-    # the axis is a int element
-    x = paddle.to_tensor([[0.2, 0.3, 0.5, 0.9],
-                          [0.1, 0.2, 0.6, 0.7]])
-    result1 = paddle.max(x)
-    print(result1.numpy())
-    #[0.9]
-    result2 = paddle.max(x, axis=0)
-    print(result2.numpy()) 
-    #[0.2 0.3 0.6 0.9]
-    result3 = paddle.max(x, axis=-1)
-    print(result3.numpy())
-    #[0.9 0.7]
-    result4 = paddle.max(x, axis=1, keepdim=True)
-    print(result4.numpy())
-    #[[0.9]
-    # [0.7]]
-
-    # data_y is a variable with shape [2, 2, 2]
-    # the axis is list 
-    y = paddle.to_tensor([[[1.0, 2.0], [3.0, 4.0]],
-                          [[5.0, 6.0], [7.0, 8.0]]])
-    result5 = paddle.max(y, axis=[1, 2])
-    print(result5.numpy())
-    #[4. 8.]
-    result6 = paddle.max(y, axis=[0, 1])
-    print(result6.numpy())
-    #[7. 8.]
+COPY-FROM: paddle.max

doc/fluid/api_cn/tensor_cn/min_cn.rst

@@ -10,6 +10,10 @@ min
 
 该OP是对指定维度上的Tensor元素求最小值运算，并输出相应的计算结果。
 
+.. note::
+
+    对输入有多个最小值的情况下，min 将梯度完整传回到最小值对应的位置，amin 会将梯度平均传回到最小值对应的位置
+
 参数
 :::::::::
    - **x** （Tensor）- Tensor，支持数据类型为float32，float64，int32，int64。
@@ -24,34 +28,4 @@ min
 
 代码示例
 ::::::::::
-..  code-block:: python
-
-    import paddle
-    paddle.disable_static()
-
-    # the axis is a int element
-    x = paddle.to_tensor([[0.2, 0.3, 0.5, 0.9],
-                          [0.1, 0.2, 0.6, 0.7]])
-    result1 = paddle.min(x)
-    print(result1.numpy())
-    #[0.1]
-    result2 = paddle.min(x, axis=0)
-    print(result2.numpy())
-    #[0.1 0.2 0.5 0.7]
-    result3 = paddle.min(x, axis=-1)
-    print(result3.numpy()) 
-    #[0.2 0.1]
-    result4 = paddle.min(x, axis=1, keepdim=True)
-    print(result4.numpy())
-    #[[0.2]
-    # [0.1]]
-
-    # the axis is list 
-    y = paddle.to_tensor([[[1.0, 2.0], [3.0, 4.0]],
-                          [[5.0, 6.0], [7.0, 8.0]]])
-    result5 = paddle.min(y, axis=[1, 2])
-    print(result5.numpy()) 
-    #[1. 5.]
-    result6 = paddle.min(y, axis=[0, 1])
-    print(result6.numpy())
-    #[1. 2.]
+COPY-FROM: paddle.min

docs/api/paddle/Overview_cn.rst

@@ -81,10 +81,12 @@ tensor数学操作
     " :ref:`paddle.bitwise_xor <cn_api_tensor_bitwise_xor>` ", "逐元素的对 X 和 Y 进行按位异或运算"
     " :ref:`paddle.logsumexp <cn_api_paddle_tensor_math_logsumexp>` ", "沿着 axis 计算 x 的以e为底的指数的和的自然对数"
     " :ref:`paddle.max <cn_api_paddle_tensor_max>` ", "对指定维度上的Tensor元素求最大值运算"
+    " :ref:`paddle.amax <cn_api_paddle_tensor_max>` ", "对指定维度上的Tensor元素求最大值运算"
     " :ref:`paddle.maximum <cn_api_paddle_tensor_maximum>` ", "逐元素对比输入的两个Tensor，并且把各个位置更大的元素保存到返回结果中"
     " :ref:`paddle.mean <cn_api_tensor_cn_mean>` ", "沿 axis 计算 x 的平均值"
     " :ref:`paddle.median <cn_api_tensor_cn_median>` ", "沿给定的轴 axis 计算 x 中元素的中位数"
     " :ref:`paddle.min <cn_api_paddle_tensor_min>` ", "对指定维度上的Tensor元素求最小值运算"
+    " :ref:`paddle.amin <cn_api_paddle_tensor_min>` ", "对指定维度上的Tensor元素求最小值运算"
     " :ref:`paddle.minimum <cn_api_paddle_tensor_minimum>` ", "逐元素对比输入的两个Tensor，并且把各个位置更小的元素保存到返回结果中"
     " :ref:`paddle.mm <cn_api_tensor_mm>` ", "用于两个输入矩阵的相乘"
     " :ref:`paddle.multiplex <cn_api_fluid_layers_multiplex>` ", "从每个输入Tensor中选择特定行构造输出Tensor"   

docs/api/paddle/Tensor_cn.rst

@@ -1415,6 +1415,15 @@ max(axis=None, keepdim=False, name=None)
 
 请参考 :ref:`cn_api_paddle_tensor_max`
 
+amax(axis=None, keepdim=False, name=None)
+:::::::::
+
+返回：计算后的Tensor
+
+返回类型：Tensor
+
+请参考 :ref:`cn_api_paddle_tensor_amax`
+
 maximum(y, axis=-1, name=None)
 :::::::::
 
@@ -1451,6 +1460,15 @@ min(axis=None, keepdim=False, name=None)
 
 请参考 :ref:`cn_api_paddle_tensor_min`
 
+amin(axis=None, keepdim=False, name=None)
+:::::::::
+
+返回：计算后的Tensor
+
+返回类型：Tensor
+
+请参考 :ref:`cn_api_paddle_tensor_amin`
+
 minimum(y, axis=-1, name=None)
 :::::::::
 

docs/api/paddle/amax_cn.rst

@@ -0,0 +1,29 @@
+.. _cn_api_paddle_tensor_amax:
+
+amax
+-------------------------------
+
+.. py:function:: paddle.amax(x, axis=None, keepdim=False, name=None)
+
+
+该OP是对指定维度上的Tensor元素求最大值运算，并输出相应的计算结果。
+
+.. note::
+
+    对输入有多个最大值的情况下，max 将梯度完整传回到最大值对应的位置，amax 会将梯度平均传回到最大值对应的位置
+
+参数
+:::::::::
+   - **x** （Tensor）- Tensor，支持数据类型为float32，float64，int32，int64。
+   - **axis** （list | int ，可选）- 求最大值运算的维度。如果为None，则计算所有元素的最大值并返回包含单个元素的Tensor变量，否则必须在  :math:`[-x.ndim, x.ndim]` 范围内。如果 :math:`axis[i] <0` ，则维度将变为 :math:`x.ndim+axis[i]` ，默认值为None。
+   - **keepdim** （bool）- 是否在输出Tensor中保留减小的维度。如果keepdim 为 False，结果张量的维度将比输入张量的小，默认值为False。
+   - **name** （str， 可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
+
+返回
+:::::::::
+   Tensor, 在指定axis上进行求最大值运算的Tensor，数据类型和输入数据类型一致。
+
+
+代码示例
+::::::::::
+COPY-FROM: paddle.amax

docs/api/paddle/amin_cn.rst

@@ -0,0 +1,29 @@
+.. _cn_api_paddle_tensor_amin:
+
+amin
+-------------------------------
+
+.. py:function:: paddle.amin(x, axis=None, keepdim=False, name=None)
+
+
+该OP是对指定维度上的Tensor元素求最小值运算，并输出相应的计算结果。
+
+.. note::
+
+    对输入有多个最小值的情况下，min 将梯度完整传回到最小值对应的位置，amin 会将梯度平均传回到最小值对应的位置
+
+参数
+:::::::::
+   - **x** （Tensor）- Tensor，支持数据类型为float32，float64，int32，int64。
+   - **axis** （list | int ，可选）- 求最小值运算的维度。如果为None，则计算所有元素的最小值并返回包含单个元素的Tensor变量，否则必须在  :math:`[−x.ndim, x.ndim]` 范围内。如果 :math:`axis[i] < 0` ，则维度将变为 :math:`x.ndim+axis[i]` ，默认值为None。
+   - **keepdim** （bool）- 是否在输出Tensor中保留减小的维度。如果keepdim 为False，结果张量的维度将比输入张量的小，默认值为False。
+   - **name** （str， 可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
+
+返回
+:::::::::
+   Tensor，在指定axis上进行求最小值运算的Tensor，数据类型和输入数据类型一致。
+
+
+代码示例
+::::::::::
+COPY-FROM: paddle.amin

docs/api/paddle/max_cn.rst

@@ -8,6 +8,10 @@ max
 
 该OP是对指定维度上的Tensor元素求最大值运算，并输出相应的计算结果。
 
+.. note::
+
+    对输入有多个最大值的情况下，max 将梯度完整传回到最大值对应的位置，amax 会将梯度平均传回到最大值对应的位置
+
 参数
 :::::::::
    - **x** （Tensor）- Tensor，支持数据类型为float32，float64，int32，int64。
@@ -22,34 +26,4 @@ max
 
 代码示例
 ::::::::::
-
-..  code-block:: python
-
-    import paddle
-
-    # the axis is a int element
-    x = paddle.to_tensor([[0.2, 0.3, 0.5, 0.9],
-                          [0.1, 0.2, 0.6, 0.7]])
-    result1 = paddle.max(x)
-    print(result1)
-    #[0.9]
-    result2 = paddle.max(x, axis=0)
-    print(result2) 
-    #[0.2 0.3 0.6 0.9]
-    result3 = paddle.max(x, axis=-1)
-    print(result3)
-    #[0.9 0.7]
-    result4 = paddle.max(x, axis=1, keepdim=True)
-    print(result4)
-    #[[0.9]
-    # [0.7]]
-
-    # the axis is list 
-    y = paddle.to_tensor([[[1.0, 2.0], [3.0, 4.0]],
-                           [[5.0, 6.0], [7.0, 8.0]]])
-    result5 = paddle.max(y, axis=[1, 2])
-    print(result5)
-    #[4. 8.]
-    result6 = paddle.max(y, axis=[0, 1])
-    print(result6)
-    #[7. 8.]
+COPY-FROM: paddle.max

docs/api/paddle/min_cn.rst

@@ -8,6 +8,10 @@ min
 
 该OP是对指定维度上的Tensor元素求最小值运算，并输出相应的计算结果。
 
+.. note::
+
+    对输入有多个最小值的情况下，min 将梯度完整传回到最小值对应的位置，amin 会将梯度平均传回到最小值对应的位置
+
 参数
 :::::::::
    - **x** （Tensor）- Tensor，支持数据类型为float32，float64，int32，int64。
@@ -22,33 +26,4 @@ min
 
 代码示例
 ::::::::::
-..  code-block:: python
-
-    import paddle
-
-    # the axis is a int element
-    x = paddle.to_tensor([[0.2, 0.3, 0.5, 0.9],
-                          [0.1, 0.2, 0.6, 0.7]])
-    result1 = paddle.min(x)
-    print(result1)
-    #[0.1]
-    result2 = paddle.min(x, axis=0)
-    print(result2)
-    #[0.1 0.2 0.5 0.7]
-    result3 = paddle.min(x, axis=-1)
-    print(result3) 
-    #[0.2 0.1]
-    result4 = paddle.min(x, axis=1, keepdim=True)
-    print(result4)
-    #[[0.2]
-    # [0.1]]
-
-    # the axis is list 
-    y = paddle.to_tensor([[[1.0, 2.0], [3.0, 4.0]],
-                           [[5.0, 6.0], [7.0, 8.0]]])
-    result5 = paddle.min(y, axis=[1, 2])
-    print(result5) 
-    #[1. 5.]
-    result6 = paddle.min(y, axis=[0, 1])
-    print(result6)
-    #[1. 2.]
+COPY-FROM: paddle.min