Add gather_tree_cn.rst (#1537)

* Polish cn doc fo gru_unit, lstm_unit and scaled_dot_product_attention.

* Add gather_tree_cn.rst and update the data type of assign/fill_constant_batch_size_like/gather_nd.

* Fix _cn_api_fluid_layers_gather_tree

* Update tensor_array_to_tensor and add mse_loss.

doc/fluid/api_cn/layers_cn.rst

@@ -113,6 +113,7 @@ fluid.layers
     layers_cn/fsp_matrix_cn.rst
     layers_cn/gather_cn.rst
     layers_cn/gather_nd_cn.rst
+    layers_cn/gather_tree_cn.rst
     layers_cn/gaussian_random_batch_size_like_cn.rst
     layers_cn/gaussian_random_cn.rst
     layers_cn/generate_mask_labels_cn.rst
@@ -173,6 +174,7 @@ fluid.layers
     layers_cn/mean_cn.rst
     layers_cn/mean_iou_cn.rst
     layers_cn/merge_selected_rows_cn.rst
+    layers_cn/mse_loss_cn.rst
     layers_cn/mul_cn.rst
     layers_cn/multi_box_head_cn.rst
     layers_cn/multiclass_nms_cn.rst

doc/fluid/api_cn/layers_cn/assign_cn.rst

@@ -8,7 +8,7 @@ assign
 该OP将输入Tensor或numpy数组拷贝至输出Tensor。
 
 参数：
-    - **input** (Variable|np.ndarray) - 输入Tensor或numpy数组，支持数据类型为float32, float64, int32和int64。
+    - **input** (Variable|np.ndarray) - 输入Tensor或numpy数组，支持数据类型为float32, float64, int32, int64和bool。
     - **output** (Variable，可选) - 输出Tensor。如果为None，则创建一个新的Tensor作为输出Tensor，默认值为None。
 
 返回：输出Tensor，形状、数据类型、数据值和 ``input`` 一致。

doc/fluid/api_cn/layers_cn/fill_constant_batch_size_like_cn.rst

@@ -3,18 +3,19 @@
 fill_constant_batch_size_like
 -------------------------------
 
-.. py:function:: paddle.fluid.layers.fill_constant_batch_size_like(input,shape,dtype,value,input_dim_idx=0,output_dim_idx=0)
+.. py:function:: paddle.fluid.layers.fill_constant_batch_size_like(input,shape,dtype,value,input_dim_idx=0,output_dim_idx=0,force_cpu=False)
 
 该OP创建一个形状为shape并且数据类型为dtype的Tensor，同时用 ``value`` 中提供的常量初始化该Tensor。在输入为LoDTensor并且input_dim_idx为0的
 时候将输出output_dim_idx维度的大小设置为input输入的batch_size的值，创建的Tensor的stop_gradient属性默认为False。
 
 参数：
-    - **input** (Variable)- 输入的Tensor或者LoDTensor，支持数据类型为 float32， float64， int32， int64。
+    - **input** (Variable)- 输入的Tensor或者LoDTensor，支持数据类型为 float32， float64， int32， int64，bool。
     - **shape** (list)- 创建Tensor的shape，最后创建的LoDTensor的shape可能会依据input发生变动。
-    - **dtype** (np.dtype|core.VarDesc.VarType|str)- 创建Tensor的数据类型，支持数据类型为 float32， float64， int32， int64。
+    - **dtype** (np.dtype|core.VarDesc.VarType|str)- 创建Tensor的数据类型，支持数据类型为 float32， float64， int32， int64，bool。
     - **value** (float|int)-  用于初始化输出Tensor的常量数据的值。
     - **input_dim_idx** (int)- 当值为0并且输入为LoDTensor的时候，创建Tensor的output_dim_idx维度会设置为input的batch_size值，默认值为0。
     - **output_dim_idx** (int) -用于指定创建的Tensor哪个维度设置为输入batch_size的值，默认值为0。
+    - **force_cpu** (bool)- 用于返回的Tensor是否创建在CPU上，默认值为False，若设为true，则数据在CPU上。
 
 返回：创建的Tensor, 数据类型为dtype。
 

doc/fluid/api_cn/layers_cn/gather_nd_cn.rst

@@ -50,7 +50,7 @@ gather_nd
 
 
 参数：
-    - **input** (Variable) - 输入张量，数据类型可以是int32，int64，float32，float64。
+    - **input** (Variable) - 输入张量，数据类型可以是int32，int64，float32，float64, bool。
     - **index** (int) - 输入的索引张量，数据类型为非负int32或非负int64。它的维度 :code:`index.rank` 必须大于1，并且 :code:`index.shape[-1] <= input.rank` 。
     - **name** (string) - 该层的名字，默认值为None，表示会自动命名。
     

doc/fluid/api_cn/layers_cn/gather_tree_cn.rst

+.. _cn_api_fluid_layers_gather_tree:
+
+gather_tree
+-------------------------------
+
+.. py:function:: paddle.fluid.layers.gather_tree(ids, parents)
+
+该OP在整个束搜索(Beam Search)结束后使用。在搜索结束后，可以获得每个时间步选择的的候选词id及其对应的在搜索树中的parent节点， ``ids`` 和 ``parents`` 的形状布局均为 :math:`[max\_time, batch\_size, beam\_size]` ，该OP从最后一个时间步回溯产生完整的id序列。
+
+
+示例：
+
+::
+
+        给定:
+            ids = [[[2 2]
+                    [6 1]]
+                   [[3 9]
+                    [6 1]]
+                   [[0 1]
+                    [9 0]]]
+            parents = [[[0 0]
+                        [1 1]]
+                       [[1 0]
+                        [1 0]]
+                       [[0 0]
+                        [0 1]]]
+
+        结果:                
+            gather_tree(ids, parents)  
+                        = [[[2 2]
+                            [1 6]]
+                           [[3 3]
+                            [6 1]]
+                           [[0 1]
+                            [9 0]]]
+
+
+
+参数：
+    - **ids** (Variable) - 形状为 :math:`[length, batch\_size, beam\_size]` 的三维Tensor，数据类型是int32或int64。包含了所有时间步选择的id。
+    - **parents** (Variable) - 形状和数据类型均与 ``ids`` 相同的Tensor。包含了束搜索中每一时间步所选id对应的parent。
+    
+返回：和 ``ids`` 具有相同形状和数据类型的Tensor。包含了根据parent回溯而收集产生的完整id序列。
+
+返回类型：Variable
+
+**代码示例**：
+
+.. code-block:: python
+
+    import paddle.fluid as fluid
+
+    ids = fluid.data(name='ids',
+                     shape=[5, 2, 2],
+                     dtype='int64')
+    parents = fluid.data(name='parents',
+                         shape=[5, 2, 2],
+                         dtype='int64')
+    final_sequences = fluid.layers.gather_tree(ids, parents)
+
+
+
+
+

doc/fluid/api_cn/layers_cn/gru_unit_cn.rst

@@ -29,7 +29,7 @@ Gated Recurrent Unit（GRU）循环神经网络计算单元。该OP用于完成
     h_t & = (1-u_t) \odot h_{t-1} + u_t \odot \tilde{h_t}
 
 
-其中， :math:`x_t` 为当前时间步的输入，这个输入并非 ``input``，该OP不包含 :math:`W_{ux}x_{t}, W_{rx}x_{t}, W_{cx}x_{t}` 的计算，**注意** 要在该OP前使用大小为 ``size`` 的3倍的全连接层并将其输出作为 ``input``；
+其中， :math:`x_t` 为当前时间步的输入，这个输入并非 ``input``，该OP不包含 :math:`W_{ux}x_{t}, W_{rx}x_{t}, W_{cx}x_{t}` 的计算，**注意** 要在该OP前使用大小为GRU隐单元数目的3倍的全连接层并将其输出作为 ``input``；
 :math:`h_{t-1}` 为前一时间步的隐状态 ``hidden``； :math:`u_t` 、 :math:`r_t` 、 :math:`\tilde{h_t}` 和 :math:`h_t` 分别代表了GRU单元中update gate（更新门）、reset gate（重置门）、candidate hidden（候选隐状态）和隐状态输出; :math:`\odot` 为逐个元素相乘；
 :math:`W_{uh}, b_u` 、 :math:`W_{rh}, b_r` 和 :math:`W_{ch}, b_c` 分别代表更新门、重置门和候选隐状态在计算时使用的权重矩阵和偏置。在实现上，三个权重矩阵合并为一个 :math:`[D, D \times 3]` 形状的Tensor存放，三个偏置拼接为一个 :math:`[1, D \times 3]` 形状的Tensor存放，其中 :math:`D` 为隐单元的数目；权重Tensor存放布局为： :math:`W_{uh}` 和 :math:`W_{rh}` 拼接为 :math:`[D, D  \times 2]` 形状位于前半部分，:math:`W_{ch}` 以 :math:`[D, D]` 形状位于后半部分。
 

doc/fluid/api_cn/layers_cn/lstm_unit_cn.rst

@@ -31,7 +31,7 @@ Long-Short Term Memory（LSTM）循环神经网络计算单元。该OP用于完
     - **bias_attr** (ParamAttr，可选) - 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。
     - **name**  (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
 
-返回：Variable的二元组，包含了两个形状均为 :math:`[N, D]` 的Tensor，分别表示hiddel和cell输出，即公式中的 :math:`h_{t}` 和 :math:`c_{t}` 。数据类型与输入 ``x_t`` 相同。
+返回：Variable的二元组，包含了两个形状和数据类型均与 ``hidden_t_prev`` 相同的Tensor，分别表示hiddel和cell输出，即公式中的 :math:`h_{t}` 和 :math:`c_{t}` 。
 
 返回类型：tuple
 

doc/fluid/api_cn/layers_cn/mse_loss_cn.rst

+.. _cn_api_fluid_layers_mse_loss:
+
+mse_loss
+-------------------------------
+
+.. py:function:: paddle.fluid.layers.mse_loss(input,label)
+
+该OP用于计算预测值和目标值的均方差误差。
+
+对于预测值input和目标值label，公式为：
+
+.. math::
+
+    Out = MEAN((input-label)^{2})
+
+参数：
+    - **input** (Variable) - 预测值，维度为 :math:`[N_1, N_2, ..., N_k, D]` 的多维Tensor，其中最后一维D是类别数目。数据类型为float32或float64。
+    - **label** (Variable) - 目标值，维度为 :math:`[N_1, N_2, ..., N_k, D]` 的多维Tensor，其中最后一维D是类别数目。数据类型为float32或float64。
+
+返回：预测值和目标值的均方差
+
+返回类型：变量（Variable）
+
+**代码示例**：
+
+.. code-block:: python
+
+    import paddle.fluid as fluid
+    y = fluid.data(name='y', shape=[1], dtype='float32')
+    y_predict = fluid.data(name='y_predict', shape=[1], dtype='float32')
+    cost = fluid.layers.mse_loss(input=y_predict, label=y)
+
+
+

doc/fluid/api_cn/layers_cn/tensor_array_to_tensor_cn.rst

@@ -3,44 +3,78 @@
 tensor_array_to_tensor
 -------------------------------
 
-.. py:function:: paddle.fluid.layers.tensor_array_to_tensor(input, axis=1, name=None)
+.. py:function:: paddle.fluid.layers.tensor_array_to_tensor(input, axis=1, name=None, use_stack=False)
 
-该OP在指定轴上连接LoDTensorArray中的元素。
+该OP将 ``input`` 这个LoDTensorArray中的所有Tensor沿 ``axis`` 指定的轴进行拼接（concat）或堆叠（stack）。
+
+示例：
+
+::
+    
+    - 案例 1：
+
+        给定:
+            
+            input.data = {[[0.6, 0.1, 0.3],
+                           [0.5, 0.3, 0.2]],
+                          [[1.3],
+                           [1.8]],
+                          [[2.3, 2.1],
+                           [2.5, 2.4]]}
+
+            axis = 1, use_stack = False
+
+        结果:                
+
+            output.data = [[0.6, 0.1, 0.3, 1.3, 2.3, 2.1],
+                           [0.5, 0.3, 0.2, 1.8, 2.5, 2.4]]
+
+            output_index.data = [3, 1, 2]
+
+    - 案例 2：
+
+        给定:
+            
+            input.data = {[[0.6, 0.1],
+                           [0.5, 0.3]],
+                          [[0.3, 1.3],
+                           [0.2, 1.8]],
+                          [[2.3, 2.1],
+                           [2.5, 2.4]]}
+
+            axis = 1, use_stack = False
+
+        结果:                
+
+            output.data = [[[0.6, 0.1]
+                            [0.3, 1.3]
+                            [2.3, 2.1],
+                           [[0.5, 0.3]
+                            [0.2, 1.8]
+                            [2.5, 2.4]]]
+
+            output_index.data = [2, 2, 2]
 
 参数：
   - **input** (Variable) - 输入的LoDTensorArray。支持的数据类型为：float32、float64、int32、int64。
   - **axis** (int，可选) - 指定对输入Tensor进行运算的轴， ``axis`` 的有效范围是[-R, R)，R是输入 ``input`` 中Tensor的Rank，``axis`` 为负时与 ``axis`` +R 等价。默认值为1。
   - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
+  - **use_stack** (bool，可选) – 指明使用stack或concat进行运算，若为stack模式，要求LoDTensorArray中的所有Tensor具有相同的形状。默认值为False。
 
-返回：LoDTensor
+返回：Variable的二元组， 包含了两个Tensor。第一个Tensor表示对数组内的元素进行stack或concat的输出结果，数据类型与数组中的Tensor相同；第二个Tensor包含了数组中各Tensor在 `axis` 维度的大小，数据类型为int32。
 
-返回类型： Variable
+返回类型： tuple
 
 **代码示例：**
 
 .. code-block:: python
 
-  import paddle.fluid as fluid
-  import numpy as np
-
-  place = fluid.CPUPlace()
-
-  x1 = fluid.layers.data(name="x", shape=[2,2], lod_level=0)
-  tmp = fluid.layers.fill_constant(shape=[2,3], dtype="float32", value=1)
-  x_arr = fluid.layers.create_array(dtype="float32")
-  c0 = fluid.layers.fill_constant(shape=[1], dtype='int64', value=0)
-  fluid.layers.array_write(x=tmp, i=c0, array=x_arr)
-  c1 = fluid.layers.fill_constant(shape=[1], dtype='int64', value=1)
-  fluid.layers.array_write(x=x1, i=c1, array=x_arr)
-  output, output_index = fluid.layers.tensor_array_to_tensor(input=x_arr, axis=1)
-
-  exe = fluid.Executor(place)
-  exe.run(fluid.default_startup_program())
-
-  feedx = fluid.LoDTensor()
-  feedx.set(np.array([[1.3,-2.4],[0,4]]).astype("float32"), place)
-  res = exe.run(fluid.default_main_program(), feed={'x':feedx}, fetch_list=[output], return_numpy=False)
-
-  print(np.array(res[0]))
-  # [[ 1.   1.   1.   1.3 -2.4]
-  #  [ 1.   1.   1.   0.   4. ]]
+    import paddle.fluid as fluid
+    import numpy as np
+    x0 = fluid.layers.assign(np.random.rand(2, 2).astype("float32"))
+    x1 = fluid.layers.assign(np.random.rand(2, 2).astype("float32"))
+    i = fluid.layers.fill_constant(shape=[1], dtype="int64", value=0)
+    array = fluid.layers.create_array(dtype='float32')
+    fluid.layers.array_write(x0, i, array)
+    fluid.layers.array_write(x1, i + 1, array)
+    output, output_index = fluid.layers.tensor_array_to_tensor(input=array)

doc/fluid/api_cn/nets_cn/scaled_dot_product_attention_cn.rst

@@ -21,11 +21,11 @@ scaled_dot_product_attention
 参数：
     - **queries** （Variable） - 形状为 :math:`[N, L_q, d_k \times h]` 的三维Tensor，其中 :math:`N` 为batch_size， :math:`L_q` 为查询序列长度， :math:`d_k \times h` 为查询的特征维度大小，:math:`h` 为head数。数据类型为float32或float64。
     - **keys** （Variable） - 形状为 :math:`[N, L_k, d_k \times h]` 的三维Tensor，其中 :math:`N` 为batch_size， :math:`L_k` 为键值序列长度， :math:`d_k \times h` 为键的特征维度大小，:math:`h` 为head数。数据类型与 ``queries`` 相同。
-    - **values** （Variable） - 形状为 :math:`[N, L_k, d_v \times h]` 的三维Tensor，其中 :math:`N` 为batch_size， :math:`L_v` 为键值序列长度， :math:`d_v \times h` 为值的特征维度大小，:math:`h` 为head数。数据类型与 ``queries`` 相同。
+    - **values** （Variable） - 形状为 :math:`[N, L_k, d_v \times h]` 的三维Tensor，其中 :math:`N` 为batch_size， :math:`L_k` 为键值序列长度， :math:`d_v \times h` 为值的特征维度大小，:math:`h` 为head数。数据类型与 ``queries`` 相同。
     - **num_heads** （int） - 指明所使用的head数。head数为1时不对输入进行线性变换。默认值为1。
     - **dropout_rate** （float） - 以指定的概率对要attention到的内容进行dropout。默认值为0，即不使用dropout。
 
-返回： 形状为 :math:`[N, L_q, d_v * h]` 的三维Tensor，其中 :math:`N` 为batch_size， :math:`L_q` 为查询序列长度， :math:`d_v * h` 为值的特征维度大小。与输入具有相同的数据类型。表示。
+返回： 形状为 :math:`[N, L_q, d_v * h]` 的三维Tensor，其中 :math:`N` 为batch_size， :math:`L_q` 为查询序列长度， :math:`d_v * h` 为值的特征维度大小。与输入具有相同的数据类型。表示Multi-Head Attention的输出。
 
 返回类型： Variable