Polish elementwise_add/sub/mul/div documents (#1312)

Polish elementwise_add/sub/mul/div documents

doc/fluid/api_cn/layers_cn/elementwise_add_cn.rst

@@ -5,21 +5,22 @@ elementwise_add
 
 .. py:function:: paddle.fluid.layers.elementwise_add(x, y, axis=-1, act=None, name=None)
 
-逐元素相加算子
+该OP是逐元素相加算子，输入 ``x`` 与输入 ``y`` 逐元素相加，并将各个位置的输出元素保存到返回结果中。
 
 等式为：
 
 .. math::
         Out = X + Y
 
-- :math:`X` ：任意维度的张量（Tensor）.
-- :math:`Y` ：一个维度必须小于等于X维度的张量（Tensor）。
+- :math:`X` ：多维Tensor。
+- :math:`Y` ：维度必须小于等于X维度的Tensor。
+
 对于这个运算算子有2种情况：
-        1. :math:`Y` 的形状（shape）与 :math:`X` 相同。
-        2. :math:`Y` 的形状（shape）是 :math:`X` 的连续子序列。
+        1. :math:`Y` 的 ``shape`` 与 :math:`X` 相同。
+        2. :math:`Y` 的 ``shape`` 是 :math:`X` 的连续子序列。
 
 对于情况2:
-        1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），则 ``axis`` 为 :math:`Y` 传到 :math:`X` 上的起始维度索引。
+        1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 是 :math:`Y` 在 :math:`X` 上的起始维度的位置。
         2. 如果 ``axis`` 为-1（默认值），则 :math:`axis= rank(X)-rank(Y)` 。
         3. 考虑到子序列， :math:`Y` 的大小为1的尾部维度将被忽略，例如shape（Y）=（2,1）=>（2）。
 
@@ -34,52 +35,77 @@ elementwise_add
         shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0
         shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0
 
-输入 :math:`X` 和 :math:`Y` 可以携带不同的LoD信息。但输出仅与输入 :math:`X` 共享LoD信息。
-
 参数：
-        - **x** （Tensor）- 第一个输入张量（Tensor）。
-        - **y** （Tensor）- 第二个输入张量（Tensor）。
-        - **axis** （INT）- （int，默认-1）。将Y传到X上的起始维度索引。
-        - **act** （basestring | None）- 激活函数名称，应用于输出。
-        - **name** （basestring | None）- 输出的名称。
+        - **x** （Variable）- 多维 ``Tensor`` 或 ``LoDTensor`` 。数据类型为 ``float32`` 、 ``float64`` 、 ``int32`` 或  ``int64``。
+        - **y** （Variable）- 多维 ``Tensor`` 或 ``LoDTensor`` 。数据类型为 ``float32`` 、 ``float64`` 、 ``int32`` 或  ``int64``。
+        - **axis** （int32，可选）-  ``y`` 的维度对应到 ``x`` 维度上时的索引。默认值为 -1。
+        - **act** （str，可选）- 激活函数名称，作用于输出上。默认值为None。详细请参考 :ref:`api_guide_activations` ， 常见的激活函数有: ``relu`` ``tanh`` ``sigmoid`` 等。
+        - **name** （str，可选）- 输出的名字。默认值为None。该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` 。
+
 
-返回：        元素运算的输出。
+返回：        维度与 ``x`` 相同的 ``Tensor`` 或 ``LoDTensor`` ，数据类型与 ``x`` 相同。
 
-**代码示例**
+返回类型：        Variable。
+
+**代码示例 1**
 
 ..  code-block:: python
 
     import paddle.fluid as fluid
-    # 例1: shape(x) = (2, 3, 4, 5), shape(y) = (2, 3, 4, 5)
-    x0 = fluid.layers.data(name="x0", shape=[2, 3, 4, 5], dtype='float32')
-    y0 = fluid.layers.data(name="y0", shape=[2, 3, 4, 5], dtype='float32')
-    z0 = fluid.layers.elementwise_add(x0, y0)
-     
-    # 例2: shape(X) = (2, 3, 4, 5), shape(Y) = (5)
-    x1 = fluid.layers.data(name="x1", shape=[2, 3, 4, 5], dtype='float32')
-    y1 = fluid.layers.data(name="y1", shape=[5], dtype='float32')
-    z1 = fluid.layers.elementwise_add(x1, y1)
-     
-    # 例3: shape(X) = (2, 3, 4, 5), shape(Y) = (4, 5), with axis=-1(default) or axis=2
-    x2 = fluid.layers.data(name="x2", shape=[2, 3, 4, 5], dtype='float32')
-    y2 = fluid.layers.data(name="y2", shape=[4, 5], dtype='float32')
-    z2 = fluid.layers.elementwise_add(x2, y2, axis=2)
-     
-    # 例4: shape(X) = (2, 3, 4, 5), shape(Y) = (3, 4), with axis=1
-    x3 = fluid.layers.data(name="x3", shape=[2, 3, 4, 5], dtype='float32')
-    y3 = fluid.layers.data(name="y3", shape=[3, 4], dtype='float32')
-    z3 = fluid.layers.elementwise_add(x3, y3, axis=1)
-     
-    # 例5: shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0
-    x4 = fluid.layers.data(name="x4", shape=[2, 3, 4, 5], dtype='float32')
-    y4 = fluid.layers.data(name="y4", shape=[2], dtype='float32')
-    z4 = fluid.layers.elementwise_add(x4, y4, axis=0)
-     
-    # 例6: shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0
-    x5 = fluid.layers.data(name="x5", shape=[2, 3, 4, 5], dtype='float32')
-    y5 = fluid.layers.data(name="y5", shape=[2], dtype='float32')
-    z5 = fluid.layers.elementwise_add(x5, y5, axis=0)
+    import numpy as np
+    def gen_data():
+        return {
+            "x": np.array([2, 3, 4]),
+            "y": np.array([1, 5, 2])
+        }
+    x = fluid.layers.data(name="x", shape=[3], dtype='float32')
+    y = fluid.layers.data(name="y", shape=[3], dtype='float32')
+    z = fluid.layers.elementwise_add(x, y)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    z_value = exe.run(feed=gen_data(),
+                        fetch_list=[z.name])
+    print(z_value) #[3., 8., 6.]
+
+**代码示例 2**
+
+..  code-block:: python
 
+    import paddle.fluid as fluid
+    import numpy as np
+    def gen_data():
+        return {
+            "x": np.random.randint(1, 5, size=[2, 3, 4, 5]).astype('float32'),
+            "y": np.random.randint(1, 5, size=[3, 4]).astype('float32')
+        }
+    x = fluid.layers.data(name="x", shape=[2,3,4,5], dtype='float32')
+    y = fluid.layers.data(name="y", shape=[3,4], dtype='float32')
+    z = fluid.layers.elementwise_add(x, y, axis=1)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    z_value = exe.run(feed=gen_data(),
+                        fetch_list=[z.name])
+    print(z_value) # z.shape=[2,3,4,5]
+
+**代码示例 3**
+
+..  code-block:: python
+
+    import paddle.fluid as fluid
+    import numpy as np
+    def gen_data():
+        return {
+            "x": np.random.randint(1, 5, size=[2, 3, 4, 5]).astype('float32'),
+            "y": np.random.randint(1, 5, size=[5]).astype('float32')
+        }
+    x = fluid.layers.data(name="x", shape=[2,3,4,5], dtype='float32')
+    y = fluid.layers.data(name="y", shape=[3,4], dtype='float32')
+    z = fluid.layers.elementwise_add(x, y, axis=3)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    z_value = exe.run(feed=gen_data(),
+                        fetch_list=[z.name])
+    print(z_value) # z.shape=[2,3,4,5]
 
 
 

doc/fluid/api_cn/layers_cn/elementwise_div_cn.rst

@@ -5,23 +5,23 @@ elementwise_div
 
 .. py:function:: paddle.fluid.layers.elementwise_div(x, y, axis=-1, act=None, name=None)
 
-逐元素相除算子
+该OP是逐元素相除算子，输入 ``x`` 与输入 ``y`` 逐元素相除，并将各个位置的输出元素保存到返回结果中。
 
 等式是：
 
 .. math::
         Out = X / Y
 
-- :math:`X` ：任何维度的张量（Tensor）。
-- :math:`Y` ：维度必须小于或等于X维度的张量（Tensor）。
+- :math:`X` ：多维Tensor。
+- :math:`Y` ：维度必须小于等于X维度的Tensor。
 
-此运算算子有两种情况：
-        1. :math:`Y` 的形状（shape）与 :math:`X` 相同。
-        2. :math:`Y` 的形状（shape）是 :math:`X` 的连续子序列。
+对于这个运算算子有2种情况：
+        1. :math:`Y` 的 ``shape`` 与 :math:`X` 相同。
+        2. :math:`Y` 的 ``shape`` 是 :math:`X` 的连续子序列。
 
-对于情况2：
-        1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 将是 :math:`Y` 传到 :math:`X` 上的起始维度索引。
-        2. 如果 ``axis`` 为-1（默认值），则 :math:`axis = rank（X）-rank（Y）` 。
+对于情况2:
+        1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 是 :math:`Y` 在 :math:`X` 上的起始维度的位置。
+        2. 如果 ``axis`` 为-1（默认值），则 :math:`axis= rank(X)-rank(Y)` 。
         3. 考虑到子序列， :math:`Y` 的大小为1的尾部维度将被忽略，例如shape（Y）=（2,1）=>（2）。
 
 例如：
@@ -35,61 +35,77 @@ elementwise_div
         shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0
         shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0
 
-输入 :math:`X` 和 :math:`Y` 可以携带不同的LoD信息。但输出仅与输入 :math:`X` 共享LoD信息。
-
 参数：
-        - **x** （Tensor）- 第一个输入张量（Tensor）。
-        - **y** （Tensor）- 第二个输入张量（Tensor）。
-        - **axis** （INT）- （int，默认-1）。将Y传到X上的起始维度索引。
-        - **act** （basestring | None）- 激活函数名称，应用于输出。
-        - **name** （basestring | None）- 输出的名称。
-
-返回：        元素运算的输出。
-
-**代码示例**
-
-..  code-block:: python
-
-    import paddle.fluid as fluid
-    # 例1: shape(x) = (2, 3, 4, 5), shape(y) = (2, 3, 4, 5)
-    x0 = fluid.layers.data(name="x0", shape=[2, 3, 4, 5], dtype='float32')
-    y0 = fluid.layers.data(name="y0", shape=[2, 3, 4, 5], dtype='float32')
-    z0 = fluid.layers.elementwise_div(x0, y0)
-     
-    # 例2: shape(X) = (2, 3, 4, 5), shape(Y) = (5)
-    x1 = fluid.layers.data(name="x1", shape=[2, 3, 4, 5], dtype='float32')
-    y1 = fluid.layers.data(name="y1", shape=[5], dtype='float32')
-    z1 = fluid.layers.elementwise_div(x1, y1)
-     
-    # 例3: shape(X) = (2, 3, 4, 5), shape(Y) = (4, 5), with axis=-1(default) or axis=2
-    x2 = fluid.layers.data(name="x2", shape=[2, 3, 4, 5], dtype='float32')
-    y2 = fluid.layers.data(name="y2", shape=[4, 5], dtype='float32')
-    z2 = fluid.layers.elementwise_div(x2, y2, axis=2)
-     
-    # 例4: shape(X) = (2, 3, 4, 5), shape(Y) = (3, 4), with axis=1
-    x3 = fluid.layers.data(name="x3", shape=[2, 3, 4, 5], dtype='float32')
-    y3 = fluid.layers.data(name="y3", shape=[3, 4], dtype='float32')
-    z3 = fluid.layers.elementwise_div(x3, y3, axis=1)
-     
-    # 例5: shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0
-    x4 = fluid.layers.data(name="x4", shape=[2, 3, 4, 5], dtype='float32')
-    y4 = fluid.layers.data(name="y4", shape=[2], dtype='float32')
-    z4 = fluid.layers.elementwise_div(x4, y4, axis=0)
-     
-    # 例6: shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0
-    x5 = fluid.layers.data(name="x5", shape=[2, 3, 4, 5], dtype='float32')
-    y5 = fluid.layers.data(name="y5", shape=[2], dtype='float32')
-    z5 = fluid.layers.elementwise_div(x5, y5, axis=0)
+        - **x** （Variable）- 多维 ``Tensor`` 或 ``LoDTensor`` 。数据类型为 ``float32`` 、 ``float64`` 、 ``int32`` 或  ``int64``。
+        - **y** （Variable）- 多维 ``Tensor`` 或 ``LoDTensor`` 。数据类型为 ``float32`` 、 ``float64`` 、 ``int32`` 或  ``int64``。
+        - **axis** （int32，可选）-  ``y`` 的维度对应到 ``x`` 维度上时的索引。默认值为 -1。
+        - **act** （str，可选）- 激活函数名称，作用于输出上。默认值为None。详细请参考 :ref:`api_guide_activations` ， 常见的激活函数有: ``relu`` ``tanh`` ``sigmoid`` 等。
+        - **name** （str，可选）- 输出的名字。默认值为None。该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` 。
 
 
+返回：        维度与 ``x`` 相同的 ``Tensor`` 或 ``LoDTensor`` ，数据类型与 ``x`` 相同。
 
+返回类型：        Variable。
 
+**代码示例 1**
 
+..  code-block:: python
 
+    import paddle.fluid as fluid
+    import numpy as np
+    def gen_data():
+        return {
+            "x": np.array([2, 3, 4]),
+            "y": np.array([1, 5, 2])
+        }
+    x = fluid.layers.data(name="x", shape=[3], dtype='float32')
+    y = fluid.layers.data(name="y", shape=[3], dtype='float32')
+    z = fluid.layers.elementwise_div(x, y)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    z_value = exe.run(feed=gen_data(),
+                        fetch_list=[z.name])
+    print(z_value) #[2., 0.6, 2.]
+
+**代码示例 2**
 
+..  code-block:: python
 
+    import paddle.fluid as fluid
+    import numpy as np
+    def gen_data():
+        return {
+            "x": np.random.randint(1, 5, size=[2, 3, 4, 5]).astype('float32'),
+            "y": np.random.randint(1, 5, size=[3, 4]).astype('float32')
+        }
+    x = fluid.layers.data(name="x", shape=[2,3,4,5], dtype='float32')
+    y = fluid.layers.data(name="y", shape=[3,4], dtype='float32')
+    z = fluid.layers.elementwise_div(x, y, axis=1)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    z_value = exe.run(feed=gen_data(),
+                        fetch_list=[z.name])
+    print(z_value) # z.shape=[2,3,4,5]
+
+**代码示例 3**
 
+..  code-block:: python
 
+    import paddle.fluid as fluid
+    import numpy as np
+    def gen_data():
+        return {
+            "x": np.random.randint(1, 5, size=[2, 3, 4, 5]).astype('float32'),
+            "y": np.random.randint(1, 5, size=[5]).astype('float32')
+        }
+    x = fluid.layers.data(name="x", shape=[2,3,4,5], dtype='float32')
+    y = fluid.layers.data(name="y", shape=[3,4], dtype='float32')
+    z = fluid.layers.elementwise_div(x, y, axis=3)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    z_value = exe.run(feed=gen_data(),
+                        fetch_list=[z.name])
+    print(z_value) # z.shape=[2,3,4,5]
 
 
 

doc/fluid/api_cn/layers_cn/elementwise_mul_cn.rst

@@ -5,24 +5,24 @@ elementwise_mul
 
 .. py:function:: paddle.fluid.layers.elementwise_mul(x, y, axis=-1, act=None, name=None)
 
-逐元素相乘算子
+该OP是逐元素相乘算子，输入 ``x`` 与输入 ``y`` 逐元素相乘，并将各个位置的输出元素保存到返回结果中。
 
 等式是：
 
 .. math::
         Out = X \odot Y
 
-- :math:`X` ：任何维度的张量（Tensor）。
-- :math:`Y` ：维度必须小于或等于X维度的张量（Tensor）。
+- :math:`X` ：多维Tensor。
+- :math:`Y` ：维度必须小于等于X维度的Tensor。
 
-此运算算子有两种情况：
-        1. :math:`Y` 的形状（shape）与 :math:`X` 相同。
-        2. :math:`Y` 的形状（shape）是 :math:`X` 的连续子序列。
+对于这个运算算子有2种情况：
+        1. :math:`Y` 的 ``shape`` 与 :math:`X` 相同。
+        2. :math:`Y` 的 ``shape`` 是 :math:`X` 的连续子序列。
 
-对于情况2：
-        1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 将是 :math:`Y` 传到 :math:`X` 上的起始维度索引。
-        2. 如果 ``axis`` 为-1（默认值），则 :math:`axis = rank（X）-rank（Y）` 。
-        3. 考虑到子序列， :math:`Y` 的大小为1的尾随维度将被忽略，例如shape（Y）=（2,1）=>（2）。
+对于情况2:
+        1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 是 :math:`Y` 在 :math:`X` 上的起始维度的位置。
+        2. 如果 ``axis`` 为-1（默认值），则 :math:`axis= rank(X)-rank(Y)` 。
+        3. 考虑到子序列， :math:`Y` 的大小为1的尾部维度将被忽略，例如shape（Y）=（2,1）=>（2）。
 
 例如：
 
@@ -35,52 +35,77 @@ elementwise_mul
         shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0
         shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0
 
-输入X和Y可以携带不同的LoD信息。但输出仅与输入X共享LoD信息。
-
 参数：
-        - **x** （Tensor）- 第一个输入张量（Tensor）。
-        - **y** （Tensor）- 第二个输入张量（Tensor）。
-        - **axis** （INT）- （int，默认-1）。将Y传到X上的起始维度索引。
-        - **act** （basestring | None）- 激活函数名称，应用于输出。
-        - **name** （basestring | None）- 输出的名称。
+        - **x** （Variable）- 多维 ``Tensor`` 或 ``LoDTensor`` 。数据类型为 ``float32`` 、 ``float64`` 、 ``int32`` 或  ``int64``。
+        - **y** （Variable）- 多维 ``Tensor`` 或 ``LoDTensor`` 。数据类型为 ``float32`` 、 ``float64`` 、 ``int32`` 或  ``int64``。
+        - **axis** （int32，可选）-  ``y`` 的维度对应到 ``x`` 维度上时的索引。默认值为 -1。
+        - **act** （str，可选）- 激活函数名称，作用于输出上。默认值为None。详细请参考 :ref:`api_guide_activations` ， 常见的激活函数有: ``relu`` ``tanh`` ``sigmoid`` 等。
+        - **name** （str，可选）- 输出的名字。默认值为None。该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` 。
+
+
+返回：        维度与 ``x`` 相同的 ``Tensor`` 或 ``LoDTensor`` ，数据类型与 ``x`` 相同。
+
+返回类型：        Variable。
+
+**代码示例 1**
 
-返回：        元素运算的输出。
+..  code-block:: python
 
-**代码示例**
+    import paddle.fluid as fluid
+    import numpy as np
+    def gen_data():
+        return {
+            "x": np.array([2, 3, 4]),
+            "y": np.array([1, 5, 2])
+        }
+    x = fluid.layers.data(name="x", shape=[3], dtype='float32')
+    y = fluid.layers.data(name="y", shape=[3], dtype='float32')
+    z = fluid.layers.elementwise_mul(x, y)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    z_value = exe.run(feed=gen_data(),
+                        fetch_list=[z.name])
+    print(z_value) #[2., 15., 8.]
+
+**代码示例 2**
 
 ..  code-block:: python
 
     import paddle.fluid as fluid
-    # 例1: shape(x) = (2, 3, 4, 5), shape(y) = (2, 3, 4, 5)
-    x0 = fluid.layers.data(name="x0", shape=[2, 3, 4, 5], dtype='float32')
-    y0 = fluid.layers.data(name="y0", shape=[2, 3, 4, 5], dtype='float32')
-    z0 = fluid.layers.elementwise_mul(x0, y0)
-     
-    # 例2: shape(X) = (2, 3, 4, 5), shape(Y) = (5)
-    x1 = fluid.layers.data(name="x1", shape=[2, 3, 4, 5], dtype='float32')
-    y1 = fluid.layers.data(name="y1", shape=[5], dtype='float32')
-    z1 = fluid.layers.elementwise_mul(x1, y1)
-     
-    # 例3: shape(X) = (2, 3, 4, 5), shape(Y) = (4, 5), with axis=-1(default) or axis=2
-    x2 = fluid.layers.data(name="x2", shape=[2, 3, 4, 5], dtype='float32')
-    y2 = fluid.layers.data(name="y2", shape=[4, 5], dtype='float32')
-    z2 = fluid.layers.elementwise_mul(x2, y2, axis=2)
-     
-    # 例4: shape(X) = (2, 3, 4, 5), shape(Y) = (3, 4), with axis=1
-    x3 = fluid.layers.data(name="x3", shape=[2, 3, 4, 5], dtype='float32')
-    y3 = fluid.layers.data(name="y3", shape=[3, 4], dtype='float32')
-    z3 = fluid.layers.elementwise_mul(x3, y3, axis=1)
-     
-    # 例5: shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0
-    x4 = fluid.layers.data(name="x4", shape=[2, 3, 4, 5], dtype='float32')
-    y4 = fluid.layers.data(name="y4", shape=[2], dtype='float32')
-    z4 = fluid.layers.elementwise_mul(x4, y4, axis=0)
-     
-    # 例6: shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0
-    x5 = fluid.layers.data(name="x5", shape=[2, 3, 4, 5], dtype='float32')
-    y5 = fluid.layers.data(name="y5", shape=[2], dtype='float32')
-    z5 = fluid.layers.elementwise_mul(x5, y5, axis=0)
+    import numpy as np
+    def gen_data():
+        return {
+            "x": np.random.randint(1, 5, size=[2, 3, 4, 5]).astype('float32'),
+            "y": np.random.randint(1, 5, size=[3, 4]).astype('float32')
+        }
+    x = fluid.layers.data(name="x", shape=[2,3,4,5], dtype='float32')
+    y = fluid.layers.data(name="y", shape=[3,4], dtype='float32')
+    z = fluid.layers.elementwise_mul(x, y, axis=1)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    z_value = exe.run(feed=gen_data(),
+                        fetch_list=[z.name])
+    print(z_value) # z.shape=[2,3,4,5]
+
+**代码示例 3**
 
+..  code-block:: python
+
+    import paddle.fluid as fluid
+    import numpy as np
+    def gen_data():
+        return {
+            "x": np.random.randint(1, 5, size=[2, 3, 4, 5]).astype('float32'),
+            "y": np.random.randint(1, 5, size=[5]).astype('float32')
+        }
+    x = fluid.layers.data(name="x", shape=[2,3,4,5], dtype='float32')
+    y = fluid.layers.data(name="y", shape=[3,4], dtype='float32')
+    z = fluid.layers.elementwise_mul(x, y, axis=3)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    z_value = exe.run(feed=gen_data(),
+                        fetch_list=[z.name])
+    print(z_value) # z.shape=[2,3,4,5]
 
 
 

doc/fluid/api_cn/layers_cn/elementwise_sub_cn.rst

@@ -5,24 +5,24 @@ elementwise_sub
 
 .. py:function:: paddle.fluid.layers.elementwise_sub(x, y, axis=-1, act=None, name=None)
 
-逐元素相减算子
+该OP是逐元素相减算子，输入 ``x`` 与输入 ``y`` 逐元素相减，并将各个位置的输出元素保存到返回结果中。
 
 等式是：
 
 .. math::
        Out = X - Y
 
-- **X** ：任何维度的张量（Tensor）。
-- **Y** ：维度必须小于或等于**X**维度的张量（Tensor）。
+- :math:`X` ：多维Tensor。
+- :math:`Y` ：维度必须小于等于X维度的Tensor。
 
-此运算算子有两种情况：
-        1. :math:`Y` 的形状（shape）与 :math:`X` 相同。
-        2. :math:`Y` 的形状（shape）是 :math:`X` 的连续子序列。
+对于这个运算算子有2种情况：
+        1. :math:`Y` 的 ``shape`` 与 :math:`X` 相同。
+        2. :math:`Y` 的 ``shape`` 是 :math:`X` 的连续子序列。
 
-对于情况2：
-        1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 将是 :math:`Y` 传到 :math:`X` 上的起始维度索引。
-        2. 如果 ``axis`` 为-1（默认值），则 :math:`axis = rank（X）-rank（Y）` 。
-        3. 考虑到子序列， :math:`Y` 的大小为1的尾随维度将被忽略，例如shape（Y）=（2,1）=>（2）。
+对于情况2:
+        1. 用 :math:`Y` 匹配 :math:`X` 的形状（shape），其中 ``axis`` 是 :math:`Y` 在 :math:`X` 上的起始维度的位置。
+        2. 如果 ``axis`` 为-1（默认值），则 :math:`axis= rank(X)-rank(Y)` 。
+        3. 考虑到子序列， :math:`Y` 的大小为1的尾部维度将被忽略，例如shape（Y）=（2,1）=>（2）。
 
 例如：
 
@@ -35,51 +35,77 @@ elementwise_sub
         shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0
         shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0
 
-输入X和Y可以携带不同的LoD信息。但输出仅与输入X共享LoD信息。
-
 参数：
-        - **x** （Tensor）- 第一个输入张量（Tensor）。
-        - **y** （Tensor）- 第二个输入张量（Tensor）。
-        - **axis** （INT）- （int，默认-1）。将Y传到X上的起始维度索引。
-        - **act** （basestring | None）- 激活函数名称，应用于输出。
-        - **name** （basestring | None）- 输出的名称。
+        - **x** （Variable）- 多维 ``Tensor`` 或 ``LoDTensor`` 。数据类型为 ``float32`` 、 ``float64`` 、 ``int32`` 或  ``int64``。
+        - **y** （Variable）- 多维 ``Tensor`` 或 ``LoDTensor`` 。数据类型为 ``float32`` 、 ``float64`` 、 ``int32`` 或  ``int64``。
+        - **axis** （int32，可选）-  ``y`` 的维度对应到 ``x`` 维度上时的索引。默认值为 -1。
+        - **act** （str，可选）- 激活函数名称，作用于输出上。默认值为None。详细请参考 :ref:`api_guide_activations` ， 常见的激活函数有: ``relu`` ``tanh`` ``sigmoid`` 等。
+        - **name** （str，可选）- 输出的名字。默认值为None。该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` 。
+
+
+返回：        维度与 ``x`` 相同的 ``Tensor`` 或 ``LoDTensor`` ，数据类型与 ``x`` 相同。
 
-返回：        元素运算的输出。
+返回类型：        Variable。
+
+**代码示例 1**
+
+..  code-block:: python
 
-**代码示例**
+    import paddle.fluid as fluid
+    import numpy as np
+    def gen_data():
+        return {
+            "x": np.array([2, 3, 4]),
+            "y": np.array([1, 5, 2])
+        }
+    x = fluid.layers.data(name="x", shape=[3], dtype='float32')
+    y = fluid.layers.data(name="y", shape=[3], dtype='float32')
+    z = fluid.layers.elementwise_sub(x, y)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    z_value = exe.run(feed=gen_data(),
+                        fetch_list=[z.name])
+    print(z_value) #[1., -2., 2.]
+
+**代码示例 2**
+
+..  code-block:: python
+
+    import paddle.fluid as fluid
+    import numpy as np
+    def gen_data():
+        return {
+            "x": np.random.randint(1, 5, size=[2, 3, 4, 5]).astype('float32'),
+            "y": np.random.randint(1, 5, size=[3, 4]).astype('float32')
+        }
+    x = fluid.layers.data(name="x", shape=[2,3,4,5], dtype='float32')
+    y = fluid.layers.data(name="y", shape=[3,4], dtype='float32')
+    z = fluid.layers.elementwise_sub(x, y, axis=1)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    z_value = exe.run(feed=gen_data(),
+                        fetch_list=[z.name])
+    print(z_value) # z.shape=[2,3,4,5]
+
+**代码示例 3**
 
 ..  code-block:: python
 
     import paddle.fluid as fluid
-    # 例1: shape(x) = (2, 3, 4, 5), shape(y) = (2, 3, 4, 5)
-    x0 = fluid.layers.data(name="x0", shape=[2, 3, 4, 5], dtype='float32')
-    y0 = fluid.layers.data(name="y0", shape=[2, 3, 4, 5], dtype='float32')
-    z0 = fluid.layers.elementwise_sub(x0, y0)
-     
-    # 例2: shape(X) = (2, 3, 4, 5), shape(Y) = (5)
-    x1 = fluid.layers.data(name="x1", shape=[2, 3, 4, 5], dtype='float32')
-    y1 = fluid.layers.data(name="y1", shape=[5], dtype='float32')
-    z1 = fluid.layers.elementwise_sub(x1, y1)
-     
-    # 例3: shape(X) = (2, 3, 4, 5), shape(Y) = (4, 5), with axis=-1(default) or axis=2
-    x2 = fluid.layers.data(name="x2", shape=[2, 3, 4, 5], dtype='float32')
-    y2 = fluid.layers.data(name="y2", shape=[4, 5], dtype='float32')
-    z2 = fluid.layers.elementwise_sub(x2, y2, axis=2)
-     
-    # 例4: shape(X) = (2, 3, 4, 5), shape(Y) = (3, 4), with axis=1
-    x3 = fluid.layers.data(name="x3", shape=[2, 3, 4, 5], dtype='float32')
-    y3 = fluid.layers.data(name="y3", shape=[3, 4], dtype='float32')
-    z3 = fluid.layers.elementwise_sub(x3, y3, axis=1)
-     
-    # 例5: shape(X) = (2, 3, 4, 5), shape(Y) = (2), with axis=0
-    x4 = fluid.layers.data(name="x4", shape=[2, 3, 4, 5], dtype='float32')
-    y4 = fluid.layers.data(name="y4", shape=[2], dtype='float32')
-    z4 = fluid.layers.elementwise_sub(x4, y4, axis=0)
-     
-    # 例6: shape(X) = (2, 3, 4, 5), shape(Y) = (2, 1), with axis=0
-    x5 = fluid.layers.data(name="x5", shape=[2, 3, 4, 5], dtype='float32')
-    y5 = fluid.layers.data(name="y5", shape=[2], dtype='float32')
-    z5 = fluid.layers.elementwise_sub(x5, y5, axis=0)
+    import numpy as np
+    def gen_data():
+        return {
+            "x": np.random.randint(1, 5, size=[2, 3, 4, 5]).astype('float32'),
+            "y": np.random.randint(1, 5, size=[5]).astype('float32')
+        }
+    x = fluid.layers.data(name="x", shape=[2,3,4,5], dtype='float32')
+    y = fluid.layers.data(name="y", shape=[3,4], dtype='float32')
+    z = fluid.layers.elementwise_sub(x, y, axis=3)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    z_value = exe.run(feed=gen_data(),
+                        fetch_list=[z.name])
+    print(z_value) # z.shape=[2,3,4,5]