add the chinese doc for distributed collective api (#2445)

* add distributed collective api_cn; test=develop

doc/fluid/api_cn/api_tree_cn.rst

@@ -13,6 +13,7 @@ API接口
     data/dataset_cn.rst
     data_feeder_cn.rst
     dataset_cn.rst
+    distributed_cn.rst
     dygraph_cn.rst
     executor_cn.rst
     initializer_cn.rst

doc/fluid/api_cn/distributed_cn.rst

+=======================
+paddle.distributed
+=======================
+
+
+
+
+..  toctree::
+    :maxdepth: 1
+
+    distributed_cn/all_gather_cn.rst
+    distributed_cn/all_reduce_cn.rst
+    distributed_cn/barrier_cn.rst
+    distributed_cn/broadcast_cn.rst
+    distributed_cn/reduce_cn.rst
+    distributed_cn/scatter_cn.rst

doc/fluid/api_cn/distributed_cn/all_gather_cn.rst

+.. _cn_api_distributed_all_gather:
+
+all_gather
+-------------------------------
+
+
+.. py:function:: paddle.distributed.all_gather(tensor_list, tensor, group=0)
+
+进程组内所有进程的指定tensor进行聚合操作，并返回给所有进程聚合的结果。
+
+参数
+:::::::::
+    - tensor_list (list) - 操作的输出Tensor列表。列表中的每个元素均为Tensor，每个Tensor的数据类型为：float32、float64、int32、int64。
+    - tensor (Tensor) - 操作的输入Tensor。Tensor的数据类型为：float32、float64、int32、int64。
+    - group (int，可选) - 工作的进程组编号，默认为0。
+
+返回
+:::::::::
+无
+
+代码示例
+:::::::::
+.. code-block:: python
+
+        import paddle
+        import paddle.prepare_context as prepare_context
+
+        paddle.disable_static()
+        paddle.set_device('gpu:%d'%paddle.ParallelEnv().dev_id)
+        prepare_context()
+        tensor_list = []
+        if paddle.ParallelEnv().local_rank == 0:
+            np_data1 = np.array([[4, 5, 6], [4, 5, 6]])
+            np_data2 = np.array([[4, 5, 6], [4, 5, 6]])
+            data1 = paddle.to_tensor(np_data1)
+            data2 = paddle.to_tensor(np_data2)
+            paddle.distributed.all_gather(tensor_list, data1)
+        else:
+            np_data1 = np.array([[1, 2, 3], [1, 2, 3]])
+            np_data2 = np.array([[1, 2, 3], [1, 2, 3]])
+            data1 = paddle.to_tensor(np_data1)
+            data2 = paddle.to_tensor(np_data2)
+            out = paddle.distributed.all_gather(tensor_list, data2)

doc/fluid/api_cn/distributed_cn/all_reduce_cn.rst

+.. _cn_api_distributed_all_reduce:
+
+all_reduce
+-------------------------------
+
+
+.. py:function:: paddle.distributed.all_reduce(tensor, op=ReduceOp.SUM, group=0)
+
+进程组内所有进程的指定tensor进行归约操作，并返回给所有进程归约的结果。
+
+参数
+:::::::::
+    - tensor (Tensor) - 操作的输入Tensor，同时也会将归约结果返回至此Tensor中。Tensor的数据类型为：float32、float64、int32、int64。
+    - op (ReduceOp.SUM|ReduceOp.MAX|ReduceOp.Min|ReduceOp.PROD，可选) - 归约的具体操作，比如求和，取最大值，取最小值和求乘积，默认为求和归约。
+    - group (int，可选) - 工作的进程组编号，默认为0。
+
+返回
+:::::::::
+无
+
+代码示例
+:::::::::
+.. code-block:: python
+
+        import paddle
+        from paddle.distributed import ReduceOp
+        import paddle.prepare_context as prepare_context
+
+        paddle.disable_static()
+        paddle.set_device('gpu:%d'%paddle.ParallelEnv().dev_id)
+        prepare_context()
+        if paddle.ParallelEnv().local_rank == 0:
+            np_data = np.array([[4, 5, 6], [4, 5, 6]])
+        else:
+            np_data = np.array([[1, 2, 3], [1, 2, 3]])
+        data = paddle.to_tensor(np_data)
+        paddle.distributed.all_reduce(data)
+        out = data.numpy()

doc/fluid/api_cn/distributed_cn/barrier_cn.rst

+.. _cn_api_distributed_barrier:
+
+barrier
+-------------------------------
+
+
+.. py:function:: paddle.distributed.barrier(group=0)
+
+同步进程组内的所有进程。
+
+参数
+:::::::::
+    - group (int，可选) - 工作的进程组编号，默认为0。
+
+返回
+:::::::::
+无
+
+代码示例
+:::::::::
+.. code-block:: python
+
+        import paddle
+        import paddle.prepare_context as prepare_context
+
+        paddle.disable_static()
+        paddle.set_device('gpu:%d'%paddle.ParallelEnv().dev_id)
+        prepare_context()
+        paddle.distributed.barrier()

doc/fluid/api_cn/distributed_cn/broadcast_cn.rst

+.. _cn_api_distributed_broadcast:
+
+broadcast
+-------------------------------
+
+
+.. py:function:: paddle.distributed.broadcast(tensor, src, group=0)
+
+广播一个Tensor给其他所有进程
+
+参数
+:::::::::
+    - tensor (Tensor) - 如果当前进程编号是源，那么这个Tensor变量将被发送给其他进程，否则这个Tensor将接收源发送过来的数据。Tensor的数据类型为：float32、float64、int32、int64。
+    - src (int) - 发送源的进程编号。
+    - group (int，可选) - 工作的进程组编号，默认为0。
+
+返回
+:::::::::
+无
+
+代码示例
+:::::::::
+.. code-block:: python
+
+        import paddle
+        import paddle.prepare_context as prepare_context
+
+        paddle.disable_static()
+        paddle.set_device('gpu:%d'%paddle.ParallelEnv().dev_id)
+        prepare_context()
+        if paddle.ParallelEnv().local_rank == 0:
+            np_data = np.array([[4, 5, 6], [4, 5, 6]])
+        else:
+            np_data = np.array([[1, 2, 3], [1, 2, 3]])
+        data = paddle.to_tensor(np_data)
+        paddle.distributed.broadcast(data, 1)
+        out = data.numpy()
+        # [[1, 2, 3], [1, 2, 3]]

doc/fluid/api_cn/distributed_cn/reduce_cn.rst

+.. _cn_api_distributed_reduce:
+
+reduce
+-------------------------------
+
+
+.. py:function:: paddle.distributed.reduce(tensor, dst, op=ReduceOp.SUM, group=0)
+
+进程组内所有进程的指定tensor进行归约操作，并返回给所有进程归约的结果。
+
+参数
+:::::::::
+    - tensor (Tensor) - 操作的输入Tensor，结果返回至目标进程号的Tensor中。Tensor的数据类型为：float32、float64、int32、int64。
+    - dst (int) - 返回操作结果的目标进程编号。
+    - op (ReduceOp.SUM|ReduceOp.MAX|ReduceOp.Min|ReduceOp.PROD，可选) - 归约的具体操作，比如求和，取最大值，取最小值和求乘积，默认为求和归约。
+    - group (int，可选) - 工作的进程组编号，默认为0。
+
+返回
+:::::::::
+无
+
+代码示例
+:::::::::
+.. code-block:: python
+
+        import paddle
+        import paddle.prepare_context as prepare_context
+
+        paddle.disable_static()
+        paddle.set_device('gpu:%d'%paddle.ParallelEnv().dev_id)
+        prepare_context()
+        if paddle.ParallelEnv().local_rank == 0:
+            np_data = np.array([[4, 5, 6], [4, 5, 6]])
+        else:
+            np_data = np.array([[1, 2, 3], [1, 2, 3]])
+        data = paddle.to_tensor(np_data)
+        paddle.distributed.reduce(data, 0)
+        out = data.numpy()
+        # [[5, 7, 9], [5, 7, 9]]

doc/fluid/api_cn/distributed_cn/scatter_cn.rst

+.. _cn_api_distributed_scatter:
+
+scatter
+-------------------------------
+
+
+.. py:function:: paddle.distributed.scatter(tensor, tensor_list=None, src=0, group=0)
+
+进程组内指定进程源的tensor列表分发到其他所有进程中。
+
+参数
+:::::::::
+    - tensor (Tensor) - 操作的输出Tensor。Tensor的数据类型为：float32、float64、int32、int64。
+    - tensor_list (list，可选) - 操作的输入Tensor列表，默认为None。列表中的每个元素均为Tensor，每个Tensor的数据类型为：float32、float64、int32、int64。
+    - src (int，可选) - 操作的源进程号，该进程号的Tensor列表将分发到其他进程中。默认为0。
+    - group (int，可选) - 工作的进程组编号，默认为0。
+
+返回
+:::::::::
+无
+
+代码示例
+:::::::::
+.. code-block:: python
+
+        import paddle
+        import paddle.prepare_context as prepare_context
+
+        paddle.disable_static()
+        paddle.set_device('gpu:%d'%paddle.ParallelEnv().dev_id)
+        prepare_context()
+        if paddle.ParallelEnv().local_rank == 0:
+            np_data1 = np.array([7, 8, 9])
+            np_data2 = np.array([10, 11, 12])
+        else:
+            np_data1 = np.array([1, 2, 3])
+            np_data2 = np.array([4, 5, 6])
+        data1 = paddle.to_tensor(np_data1)
+        data2 = paddle.to_tensor(np_data2)
+        if paddle.ParallelEnv().local_rank == 0:
+            paddle.distributed.scatter(data1, src=1)
+        else:
+            paddle.distributed.scatter(data1, tensor_list=[data1, data2], src=1)
+        out = data1.numpy()

doc/fluid/api_cn/index_cn.rst

@@ -113,6 +113,7 @@ Note。
     data_cn/data_reader_cn.rst
     data_cn/dataset_cn.rst
     dataset_cn.rst
+    distributed_cn.rst
     dygraph_cn.rst
     executor_cn.rst
     initializer_cn.rst

scripts/api_white_list.txt

@@ -8,3 +8,9 @@ transpiler_cn/RoundRobin_cn.rst
 optimizer_cn/Dpsgd_cn.rst
 io_cn/ComposeNotAligned_cn.rst
 dygraph_cn/DataParallel_cn.rst
+distributed_cn/all_gather_cn.rst
+distributed_cn/all_reduce_cn.rst
+distributed_cn/barrier_cn.rst
+distributed_cn/broadcast_cn.rst
+distributed_cn/reduce_cn.rst
+distributed_cn/scatter_cn.rst