Update Executor api doc. (#1913)

doc/fluid/api_cn/fluid_cn/Executor_cn.rst

@@ -84,7 +84,7 @@ Executor支持单GPU、多GPU以及CPU运行。在Executor构造时，需要传
     exe.close()
 
 
-.. py:method:: run(program=None, feed=None, fetch_list=None, feed_var_name='feed', fetch_var_name='fetch', scope=None, return_numpy=True,use_program_cache=False)
+.. py:method:: run(program=None, feed=None, fetch_list=None, feed_var_name='feed', fetch_var_name='fetch', scope=None, return_numpy=True, use_program_cache=False, return_merged=True)
 
 执行指定的Program或者CompiledProgram。需要注意的是，执行器会执行Program或CompiledProgram中的所有算子，而不会根据fetch_list对Program或CompiledProgram中的算子进行裁剪。同时，需要传入运行该模型用到的scope，如果没有指定scope，执行器将使用全局scope，即fluid.global_scope()。
 
@@ -95,9 +95,10 @@ Executor支持单GPU、多GPU以及CPU运行。在Executor构造时，需要传
   - **feed_var_name** (str) – 该参数表示数据输入算子(feed operator)的输入变量名称。默认为："feed"。
   - **fetch_var_name** (str) – 该参数表示结果获取算子(fetch operator)的输出变量名称。默认为："fetch"。
   - **scope** (Scope) – 该参数表示执行当前program所使用的作用域，用户可以为不同的program指定不同的作用域。默认值：fluid.global_scope()。
-  - **return_numpy** (bool) – 该参数表示是否将返回返回的计算结果（fetch list中指定的变量）转化为numpy；如果为False，则每个变量返回的类型为LoDTensor，否则返回变量的类型为numpy.ndarray。默认为：True。
+  - **return_numpy** (bool) – 该参数表示是否将返回的计算结果（fetch list中指定的变量）转化为numpy；如果为False，则每个变量返回的类型为LoDTensor，否则返回变量的类型为numpy.ndarray。默认为：True。
   - **use_program_cache** (bool) – 该参数表示是否对输入的Program进行缓存。如果该参数为True，在以下情况时，模型运行速度可能会更快：输入的program为 ``fluid.Program`` ，并且模型运行过程中，调用该接口的参数（program、 feed变量名和fetch_list变量）名始终不变。默认为：False。
-  
+  - **return_merged** (bool) – 该参数表示是否按照执行设备维度将返回的计算结果（fetch list中指定的变量）进行合并。如果 ``return_merged`` 设为False，返回值类型是一个Tensor的二维列表（ ``return_numpy`` 设为Fasle时）或者一个numpy.ndarray的二维列表（ ``return_numpy`` 设为True时）。如果 ``return_merged`` 设为True，返回值类型是一个Tensor的一维列表（ ``return_numpy`` 设为Fasle时）或者一个numpy.ndarray的一维列表（ ``return_numpy`` 设为True时）。更多细节请参考示例代码2。如果返回的计算结果是变长的，请设置 ``return_merged`` 为False，即不按照执行设备维度合并返回的计算结果。该参数的默认值为True，但这仅是为了兼容性考虑，在未来的版本中默认值可能会更改为False。
+
 返回：返回fetch_list中指定的变量值
 
 返回类型：List
@@ -107,7 +108,7 @@ Executor支持单GPU、多GPU以及CPU运行。在Executor构造时，需要传
      2. 如果可用的CPU核数或GPU卡数大于1，则fetch出来的结果为不同设备上的相同变量值（fetch_list中的变量）在第0维拼接在一起。
 
 
-**示例代码**
+**示例代码1**
 
 .. code-block:: python
 
@@ -131,6 +132,62 @@ Executor支持单GPU、多GPU以及CPU运行。在Executor构造时，需要传
             outs = exe.run(feed={'X': x},
                            fetch_list=[loss.name])
 
+
+**示例代码2**
+
+.. code-block:: python
+
+            import paddle.fluid as fluid
+            import numpy as np
+            # 创建Executor对象
+            place = fluid.CUDAPlace(0)
+            exe = fluid.Executor(place)
+            data = fluid.data(name='X', shape=[None, 1], dtype='float32')
+            class_dim = 2
+            prediction = fluid.layers.fc(input=data, size=class_dim)
+            loss = fluid.layers.mean(prediction)
+            adam = fluid.optimizer.Adam()
+            adam.minimize(loss)
+            # 运行且仅运行一次startup program
+            exe.run(fluid.default_startup_program())
+            build_strategy = fluid.BuildStrategy()
+            binary = fluid.CompiledProgram(fluid.default_main_program()).with_data_parallel(
+                loss_name=loss.name, build_strategy=build_strategy)
+            batch_size = 6
+            x = np.random.random(size=(batch_size, 1)).astype('float32')
+            # 1) 设置 return_merged 参数为False以获取不合并的计算结果：
+            unmerged_prediction, = exe.run(binary, feed={'X': x},
+                fetch_list=[prediction.name],
+                return_merged=False)
+            # 如果用户使用两个GPU卡来运行此python代码示例，输出结果将为(2, 3, class_dim)。
+            # 输出结果中第一个维度值代表所使用的GPU卡数，而第二个维度值代表batch_size和所使用
+            # 的GPU卡数之商。
+            print("The unmerged prediction shape: {}".format(np.array(unmerged_prediction).shape))
+            print(unmerged_prediction)
+            # 2) 设置 return_merged 参数为True以获取合并的计算结果：
+            merged_prediction, = exe.run(binary, feed={'X': x},
+                fetch_list=[prediction.name],
+                return_merged=True)
+            # 如果用户使用两个GPU卡来运行此python代码示例，输出结果将为(6, class_dim)。输出结果
+            # 中第一个维度值代表batch_size值。
+            print("The merged prediction shape: {}".format(np.array(merged_prediction).shape))
+            print(merged_prediction)
+            # 输出:
+            # The unmerged prediction shape: (2, 3, 2)
+            # [array([[-0.37620035, -0.19752218],
+            #        [-0.3561043 , -0.18697084],
+            #        [-0.24129935, -0.12669306]], dtype=float32), array([[-0.24489994, -0.12858354],
+            #        [-0.49041364, -0.25748932],
+            #        [-0.44331917, -0.23276259]], dtype=float32)]
+            # The merged prediction shape: (6, 2)
+            # [[-0.37789783 -0.19921964]
+            #  [-0.3577645  -0.18863106]
+            #  [-0.24274671 -0.12814042]
+            #  [-0.24635398 -0.13003758]
+            #  [-0.49232286 -0.25939852]
+            #  [-0.44514108 -0.2345845 ]]
+
+
 .. py:method:: infer_from_dataset(program=None, dataset=None, scope=None, thread=0, debug=False, fetch_list=None, fetch_info=None, print_period=100)
 
 infer_from_dataset的文档与train_from_dataset几乎完全相同，只是在分布式训练中，推进梯度将在infer_from_dataset中禁用。 infer_from_dataset（）可以非常容易地用于多线程中的评估。