increase example code of py_func, fix some wrong description of API doc (#1609)

resolve #20977
fix Issue: PaddlePaddle/Paddle#20977

* increase example code of py_func, fix some wrong description of API doc

* increase example code of py_func, fix some wrong description of API doc

doc/fluid/advanced_usage/development/new_op/new_python_op.md

 # 如何写新的Python OP
 
-PaddlePaddle Fluid通过 `py_func` 接口支持在Python端编写op。 
+PaddlePaddle Fluid通过 `py_func` 接口支持在Python端自定义OP。 py_func的设计原理在于Paddle中的LodTensor可以与numpy数组可以方便的互相转换，从而可以使用Python中的numpy API来自定义一个Python OP。
 
 
 ## py_func接口概述
@@ -14,12 +14,12 @@ def py_func(func, x, out, backward_func=None, skip_vars_in_backward_input=None):
 
 其中，
 
-- `x` 是Python Op的输入变量，可以是单个 `Variable` 或者 `List[Variable]` 。
-- `out` 是Python Op的输出变量，可以是单个 `Variable` 或者 `List[Variable]` 。
-- `func` 是Python Op的前向函数。在运行网络前向时，框架会调用 `out = func(*x)` ，根据前向输入 `x` 和前向函数 `func` 计算前向输出 `out`。
+- `x` 是Python Op的输入变量，可以是单个 `Variable` | `tuple[Variable]` | `list[Variable]` 。多个Variable以tuple[Variable]或list[Variale]的形式传入，其中Variable为LoDTensor或Tenosr。
+- `out` 是Python Op的输出变量，可以是单个 `Variable` | `tuple[Variable]` | `list[Variable]` 。其中Variable既可以为LoDTensor或Tensor，也可以为numpy数组。
+- `func` 是Python Op的前向函数。在运行网络前向时，框架会调用 `out = func(*x)` ，根据前向输入 `x` 和前向函数 `func` 计算前向输出 `out`。在 ``func`` 建议先主动将LoDTensor转换为numpy数组，方便灵活的使用numpy相关的操作，如果未转换成numpy，则可能某些操作无法兼容。
 - `backward_func` 是Python Op的反向函数。若 `backward_func` 为 `None` ，则该Python Op没有反向计算逻辑；
   若 `backward_func` 不为 `None`，则框架会在运行网路反向时调用 `backward_func` 计算前向输入 `x` 的梯度。
-- `skip_vars_in_backward_input` 为反向函数 `backward_func` 中不需要的输入，可以是单个 `Variable` 或者 `List[Variable]` 。
+- `skip_vars_in_backward_input` 为反向函数 `backward_func` 中不需要的输入，可以是单个 `Variable` | `tuple[Variable]` | `list[Variable]` 。
 
 
 ## 如何使用py_func编写Python Op
@@ -28,7 +28,7 @@ def py_func(func, x, out, backward_func=None, skip_vars_in_backward_input=None):
 
 - 第一步：定义前向函数和反向函数
 
-前向函数和反向函数均由Python编写。
+前向函数和反向函数均由Python编写，可以方便地使用Python与numpy中的相关API来实现一个自定义的OP。
 
 若前向函数的输入为 `x_1`, `x_2`, ..., `x_n` ，输出为`y_1`, `y_2`, ..., `y_m`，则前向函数的定义格式为：
 ```Python
@@ -46,25 +46,52 @@ def backward_func(x_1, x_2, ..., x_n, y_1, y_2, ..., y_m, dy_1, dy_2, ..., dy_m)
 
 若反向函数不需要某些前向输入变量或前向输出变量，可设置 `skip_vars_in_backward_input` 进行排除（步骤三中会叙述具体的排除方法）。
 
-此处我们利用numpy库完成tanh的前向函数和反向函数编写。
+注：，x_1, ..., x_n为输入的多个LodTensor，请以tuple(Variable)或list[Variable]的形式在py_func中传入。建议先主动将LodTensor通过numpy.array转换为数组，否则Python与numpy中的某些操作可能无法兼容使用在LodTensor上。
+
+此处我们利用numpy的相关API完成tanh的前向函数和反向函数编写。下面给出多个前向与反向函数定义的示例：
 
 ```Python
 import numpy as np
 
-def my_tanh(x):
+# 前向函数1：模拟tanh激活函数
+def tanh(x):
+    # 可以直接将LodTensor作为np.tanh的输入参数
     return np.tanh(x)
 
-def my_tanh_grad(x, y, dy):
+# 前向函数2：将两个2-D LodTenosr相加，输入多个LodTensor以list[Variable]或tuple(Variable)形式
+def element_wise_add(x, y): 
+    # 必须先手动将LodTensor转换为numpy数组，否则无法支持numpy的shape操作
+    x = np.array(x)    
+    y = np.array(y)
+
+    if x.shape != y.shape:
+        raise AssertionError("the shape of inputs must be the same!")
+
+    result = np.zeros(x.shape, dtype='int32')
+    for i in range(len(x)):
+        for j in range(len(x[0])):
+            result[i][j] = x[i][j] + y[i][j]
+
+    return result
+
+# 前向函数3：可用于调试正在运行的网络（打印值）
+def debug_func(x):
+    # 可以直接将LodTensor作为print的输入参数
+    print(x)
+
+# 前向函数1对应的反向函数，默认的输入顺序为：x、out、out的梯度
+def tanh_grad(x, y, dy):
+    # 必须先手动将LodTensor转换为numpy数组，否则"+/-"等操作无法使用
     return np.array(dy) * (1 - np.square(np.array(y)))
 ```
 
 注意，前向函数和反向函数的输入均是 `LoDTensor` 类型，输出可以是Numpy Array或 `LoDTensor`。
-由于 `LoDTensor` 实现了Python的buffer protocol协议，因此我们既可通过 `numpy.array` 直接将 `LoDTensor` 转换为Numpy Array，也可直接将 `LoDTensor` 作为Numpy函数的输入参数。
+由于 `LoDTensor` 实现了Python的buffer protocol协议，因此即可通过 `numpy.array` 直接将 `LoDTensor` 转换为numpy Array来进行操作，也可直接将 `LoDTensor` 作为numpy函数的输入参数。但建议先主动转换为numpy Array，则可以任意的使用python与numpy中的所有操作（例如"numpy array的+/-/shape"）。
 
 tanh的反向函数不需要前向输入x，因此我们可定义一个不需要前向输入x的反向函数，并在后续通过 `skip_vars_in_backward_input` 进行排除 :
 
 ```Python
-def my_tanh_grad_without_x(y, dy):
+def tanh_grad_without_x(y, dy):
     return np.array(dy) * (1 - np.square(np.array(y)))
 ```
 
@@ -89,13 +116,13 @@ out_var = create_tmp_var(fluid.default_main_program(), name='output', dtype='flo
 `py_func` 的调用方式为：
 
 ```Python
-fluid.layers.py_func(func=my_tanh, x=in_var, out=out_var, backward_func=my_tanh_grad)
+fluid.layers.py_func(func=tanh, x=in_var, out=out_var, backward_func=tanh_grad)
 ```
 
 若我们不希望在反向函数输入参数中出现前向输入，则可使用 `skip_vars_in_backward_input` 进行排查，简化反向函数的参数列表。
 
 ```Python
-fluid.layers.py_func(func=my_tanh, x=in_var, out=out_var, backward_func=my_tanh_grad_without_x,
+fluid.layers.py_func(func=tanh, x=in_var, out=out_var, backward_func=tanh_grad_without_x,
     skip_vars_in_backward_input=in_var)
 ```
 

doc/fluid/api_cn/layers_cn/py_func_cn.rst

@@ -5,7 +5,9 @@ py_func
 
 .. py:function:: paddle.fluid.layers.py_func(func, x, out, backward_func=None, skip_vars_in_backward_input=None)
 
-PaddlePaddle Fluid通过该接口在Python端注册OP。所注册的Python OP的前向函数是 ``func``, 反向函数是 ``backward_func`` 。 Paddle将在前向部分调用 ``func`` ，并在反向部分调用 ``backward_func`` （如果 ``backward_func`` 不是None)。 ``x`` 为 ``func`` 的输入，必须为LoDTensor类型； ``out``  为 ``func`` 的输出， 既可以是LoDTensor类型, 也可以是NumPy数组。
+PaddlePaddle Fluid通过py_func在Python端注册OP。py_func的设计原理在于Paddle中的LodTensor与numpy数组可以方便的互相转换，从而可使用Python中的numpy API来自定义一个Python OP。
+
+该自定义的Python OP的前向函数是 ``func``, 反向函数是 ``backward_func`` 。 Paddle将在前向部分调用 ``func`` ，并在反向部分调用 ``backward_func`` （如果 ``backward_func`` 不是None)。 ``x`` 为 ``func`` 的输入，必须为LoDTensor类型； ``out``  为 ``func`` 的输出， 既可以是LoDTensor类型, 也可以是numpy数组。
 
 反向函数 ``backward_func`` 的输入依次为：前向输入 ``x`` 、前向输出 ``out`` 、 ``out`` 的梯度。 如果 ``out`` 的某些变量没有梯度，则 ``backward_func`` 的相关输入变量为None。如果 ``x`` 的某些变量没有梯度，则用户应在 ``backward_func`` 中主动返回None。 
 
@@ -14,39 +16,40 @@ PaddlePaddle Fluid通过该接口在Python端注册OP。所注册的Python OP的
 此功能还可用于调试正在运行的网络，可以通过添加没有输出的 ``py_func`` 运算，并在 ``func`` 中打印输入 ``x`` 。
 
 参数:
-    - **func** （callable） - 所注册的Python OP的前向函数，运行网络时，将根据该函数与前向输入 ``x`` ，计算前向输出 ``out`` 。
-    - **x** (Variable) -  前向函数 ``func`` 的输入，可以为 Variable | tuple[Variable] | list[Variale]， 其中 Variable 为LoDTensor类型。
-    - **out** (Variable) -  前向函数 ``func`` 输出，可以为 Variable | tuple[Variable] | list[Variale]，其中 Variable 既可以为LoDTensor类型，也可以为NumPy数组。由于Paddle无法自动推断 ``out`` 的形状和数据类型，必须应事先创建 ``out`` 。
+    - **func** （callable） - 所注册的Python OP的前向函数，运行网络时，将根据该函数与前向输入 ``x`` ，计算前向输出 ``out`` 。 在 ``func`` 建议先主动将LoDTensor转换为numpy数组，方便灵活的使用numpy相关的操作，如果未转换成numpy，则可能某些操作无法兼容。
+    - **x** (Variable|tuple(Variable)|list[Variale]) -  前向函数 ``func`` 的输入，多个LoDTensor以tuple(Variable)或list[Variale]的形式传入，其中Variable为LoDTensor或Tenosr。
+    - **out** (Variable|tuple(Variable)|list[Variale]) -  前向函数 ``func`` 的输出，可以为Variable|tuple(Variable)|list[Variale]，其中Variable既可以为LoDTensor或Tensor，也可以为numpy数组。由于Paddle无法自动推断 ``out`` 的形状和数据类型，必须应事先创建 ``out`` 。
     - **backward_func** (callable，可选) - 所注册的Python OP的反向函数。默认值为None，意味着没有反向计算。若不为None，则会在运行网络反向时调用 ``backward_func`` 计算 ``x`` 的梯度。 
-    - **skip_vars_in_backward_input** (Variable，可选) -  ``backward_func`` 的输入中不需要的变量，可以是 单个Variable | list[Variable] | tuple[Variable]。 这些变量必须是 ``x`` 和 ``out`` 中的一个。默认值为None，意味着没有变量需要从 ``x`` 和 ``out`` 中去除。若不为None，则这些变量将不是 ``backward_func`` 的输入。该参数仅在 ``backward_func`` 不为None时有用。
+    - **skip_vars_in_backward_input** (Variable，可选) -  ``backward_func`` 的输入中不需要的变量，可以是Variable|tuple(Variable)|list[Variale]。 这些变量必须是 ``x`` 和 ``out`` 中的一个。默认值为None，意味着没有变量需要从 ``x`` 和 ``out`` 中去除。若不为None，则这些变量将不是 ``backward_func`` 的输入。该参数仅在 ``backward_func`` 不为None时有用。
 
 返回: 前向函数的输出 ``out``
 
-返回类型: Variable | list[Variable] | tuple[Variable]
+返回类型: Variable|tuple(Variable)|list[Variable]
 
-**代码示例**:
+**示例代码1**:
 
 ..  code-block:: python
 
     import paddle.fluid as fluid
     import six
 
-    def create_tmp_var(name, dtype, shape):
-        return fluid.default_main_program().current_block().create_var(
-            name=name, dtype=dtype, shape=shape)
-
-    # Paddle C++ op提供的tanh激活函数
-    # 此处仅采用tanh作为示例展示py_func的使用方法
+    # 自定义的前向函数，可直接输入LoDTenosor
     def tanh(x):
         return np.tanh(x)
 
-    # 跳过前向输入x
+    # 在反向函数中跳过前向输入x，返回x的梯度。
+    # 必须使用np.array主动将LodTensor转换为numpy，否则"+/-"等操作无法使用
     def tanh_grad(y, dy):
         return np.array(dy) * (1 - np.square(np.array(y)))
 
+    # 自定义的前向函数，可用于调试正在运行的网络（打印值）
     def debug_func(x):
         print(x)
     
+    def create_tmp_var(name, dtype, shape):
+        return fluid.default_main_program().current_block().create_var(
+            name=name, dtype=dtype, shape=shape)
+
     def simple_net(img, label):
         hidden = img
         for idx in six.moves.range(4):
@@ -59,15 +62,67 @@ PaddlePaddle Fluid通过该接口在Python端注册OP。所注册的Python OP的
                 out=new_hidden, backward_func=tanh_grad,
                 skip_vars_in_backward_input=hidden)
 
-            # 用户自定义的调试层，可以打印出变量细则
+            # 用户自定义的调试函数，打印出输入的LodTensor
             fluid.layers.py_func(func=debug_func, x=hidden, out=None)
 
         prediction = fluid.layers.fc(hidden, size=10, act='softmax')
         loss = fluid.layers.cross_entropy(input=prediction, label=label)
         return fluid.layers.mean(loss)
 
+**示例代码2**:
+
+..  code-block:: python
+    
+    # 该示例展示了如何将LoDTensor转化为numpy数组，并利用numpy API来自定义一个OP
+    import paddle.fluid as fluid
+    import numpy as np
+
+    def element_wise_add(x, y): 
+        # 必须先手动将LodTensor转换为numpy数组，否则无法支持numpy的shape操作
+        x = np.array(x)    
+        y = np.array(y)
+
+        if x.shape != y.shape:
+            raise AssertionError("the shape of inputs must be the same!")
+
+        result = np.zeros(x.shape, dtype='int32')
+        for i in range(len(x)):
+            for j in range(len(x[0])):
+                result[i][j] = x[i][j] + y[i][j]
+
+        return result
+
+    def create_tmp_var(name, dtype, shape):
+        return fluid.default_main_program().current_block().create_var(
+                    name=name, dtype=dtype, shape=shape)
+
+    def py_func_demo():
+        start_program = fluid.default_startup_program()
+        main_program = fluid.default_main_program()
+
+        # 创建前向函数的输入变量
+        x = fluid.data(name='x', shape=[2,3], dtype='int32')
+        y = fluid.data(name='y', shape=[2,3], dtype='int32')
+        
+        # 创建前向函数的输出变量，必须指明变量名称name/数据类型dtype/维度shape
+        output = create_tmp_var('output','int32', [3,1])
 
+        # 输入多个LodTensor以list[Variable]或tuple(Variable)形式
+        fluid.layers.py_func(func=element_wise_add, x=[x,y], out=output)
 
+        exe=fluid.Executor(fluid.CPUPlace())
+        exe.run(start_program)
 
+        # 给program喂入numpy数组
+        input1 = np.random.randint(1, 10, size=[2,3], dtype='int32')
+        input2 = np.random.randint(1, 10, size=[2,3], dtype='int32')
+        out = exe.run(main_program, 
+                    feed={'x':input1, 'y':input2},
+                    fetch_list=[output.name])
+        print("{0} + {1} = {2}".format(input1, input2, out))
 
+    py_func_demo()
 
+    # 参考输出：
+    # [[5, 9, 9]   + [[7, 8, 4]  =  [array([[12, 17, 13]
+    #  [7, 5, 2]]     [1, 3, 3]]            [8, 8, 5]], dtype=int32)]