Merge pull request #482 from haowang101779990/1211-update-api-cn-layers

1211 update api cn layers

doc/fluid/api_cn/layers_cn.rst

@@ -20,11 +20,12 @@ array_length
 此功能用于查找输入数组LOD_TENSOR_ARRAY的长度。  
 
 相关API:
-    - :ref:`api_fluid_layers_array_read`
-    - :ref:`api_fluid_layers_array_write`
-    - :ref:`api_fluid_layers_While`
+    - :ref:`cn_api_fluid_layers_array_read`
+    - :ref:`cn_api_fluid_layers_array_write`
+    - :ref:`cn_api_fluid_layers_While`
 
-参数：**array** (LOD_TENSOR_ARRAY)-输入数组，用来计算数组长度
+参数：
+    - **array** (LOD_TENSOR_ARRAY)-输入数组，用来计算数组长度
 
 返回：输入数组LoDTensorArray的长度
 
@@ -201,6 +202,9 @@ memory用于缓存分段数据。memory的初始值可以是零，也可以是
 
 动态RNN可以将多个变量标记为其输出。使用drnn()获得输出序列。
 
+.. note::
+    目前不支持在DynamicRNN中任何层上配置 is_sparse = True
+
 .. py:method:: step_input(x)
   
     将序列标记为动态RNN输入。
@@ -396,12 +400,15 @@ increment
 .. py:function:: paddle.fluid.layers.increment(x, value=1.0, in_place=True)
 
    
-该函数为输入 ``x`` 中的每一个值增加 ``value`` 大小, ``value`` 即函数中待传入的参数。该函数默认直接在原变量 ``x`` 上进行运算。
-  
+该函数为输入 ``x`` 增加 ``value`` 大小, ``value`` 即函数中待传入的参数。该函数默认直接在原变量 ``x`` 上进行运算。
+
+.. note::
+    ``x`` 中元素个数必须为1
+
 参数:
     - **x** (Variable|list) – 含有输入值的张量(tensor)
     - **value** (float) – 需要增加在 ``x`` 变量上的值
-    - **in_place** (bool) – 是否在 ``x`` 变量本身进行增加操作，而非返回其增加后的一个副本而本身不改变。默认为True, 即在其本身进行操作。
+    - **in_place** (bool) – 判断是否在x变量本身执行操作，True原地执行，False时，返回增加后的副本
 
 返回： 每个元素增加后的对象
 
@@ -411,7 +418,8 @@ increment
 
 ..  code-block:: python
   
-    data = fluid.layers.data(name='data', shape=[32, 32], dtype='float32')
+    data = fluid.layers.data(name='data', shape=[1], dtype='float32',
+                         append_batch_size=False)
     data = fluid.layers.increment(x=data, value=3.0, in_place=True)
  
  
@@ -850,7 +858,7 @@ data
         2.如果维度shape包含-1，比如shape=[-1,1],
         “append_batch_size则为False（表示无效）”
 
-    - **dtype** (int|float)-数据类型：float32,float_16,int等
+    - **dtype** (basestring)-数据类型：float32,float_16,int等
     - **type** (VarType)-输出类型。默认为LOD_TENSOR
     - **lod_level** (int)-LoD层。0表示输入数据不是一个序列
     - **stop_gradient** (bool)-布尔类型，提示是否应该停止计算梯度
@@ -1214,7 +1222,7 @@ read_file
 reader也是变量。可以为由fluid.layers.open_files()生成的原始reader或者由fluid.layers.double_buffer()生成的装饰变量，等等。
 
 参数：
-    **reader** (Variable)-将要执行的reader
+    - **reader** (Variable)-将要执行的reader
 
 返回：从给定的reader中读取数据
 
@@ -1246,13 +1254,14 @@ shuffle
 
 .. py:function:: paddle.fluid.layers.shuffle(reader, buffer_size)
 
-使用python装饰器用shuffle 装饰 reader
+创建一个特殊的数据读取器，它的输出数据会被重洗(shuffle)。由原始读取器创建的迭代器得到的输出将会被暂存到shuffle缓存区，其后
+会对其进行重洗运算。shuffle缓存区的大小由参数 ``buffer_size`` 决定。
 
 参数:
     - **reader** (Variable) – 用shuffle装饰的reader
     - **buffer_size** (int) – reader中buffer的大小
 
-返回:用shuffle装饰后的reader
+返回:其输出会被重洗的一个reader（读取器）
 
 返回类型:Variable
 
@@ -2492,16 +2501,15 @@ ctc_greedy_decoder
 .. py:function:: paddle.fluid.layers.ctc_greedy_decoder(input, blank, name=None)
 
 此op用于贪婪策略解码序列，步骤如下:
-    
-    1. 获取输入中的每一行的最大值索引。又名numpy.argmax(input, axis=0)。
-    2. 对于step1结果中的每个序列，在两个空格之间合并重复token并删除所有空格。
+    1. 获取输入中的每一行的最大值索引，也就是numpy.argmax(input, axis=0)。
+    2. 对于step1结果中的每个序列，在两个空格之间合并重复部分（即合并重复的上一步中的到的索引值）并删除所有空格。
 
 
-A simple example as below:
+简单举一个例子，
 
-  ::
+::
 
-        Given:
+        已知：
 
         input.data = [[0.6, 0.1, 0.3, 0.1],
                       [0.3, 0.2, 0.4, 0.1],
@@ -2515,7 +2523,14 @@ A simple example as below:
 
         input.lod = [[4, 4]]
 
-        Then:
+        计算过程：
+
+        1. 将argmax的运算结果应用于输入的第一个序列，即 input.data[0:4] 。
+           则得出的结果为[[0], [2], [1], [0]]
+        2. 合并重复的索引值部分，删除空格，即为0的值。
+           则第一个输入序列对应的输出为：[[2], [1]]
+
+        最后
 
         output.data = [[2],
                        [1],
@@ -2529,7 +2544,7 @@ A simple example as below:
         - **blank** (int) — Connectionist Temporal Classification (CTC) loss空白标签索引,  属于半开区间[0,num_classes + 1）。
         - **name** (str) — 此层的名称。可选。
    
-返回： CTC贪婪解码结果。如果结果中的所有序列都为空，则LoDTensor 为[-1]，其中LoD[[]] dims[1,1]。
+返回： CTC贪婪解码结果是一个形为(Lp,1)的二维张量，其中Lp是所有输出序列的长度之和。如果结果中的所有序列都为空，则输出LoDTensor 为[-1]，其中LoD[[]] 形为[1,1]。
 
 返回类型： 变量（Variable）
     
@@ -2606,23 +2621,30 @@ dropout操作
 丢弃或者保持x的每个元素独立。Dropout是一种正则化技术，通过在训练过程中阻止神经元节点间的联合适应性来减少过拟合。根据给定的丢弃概率dropout操作符随机将一些神经元输出设置为0，其他的仍保持不变。
 
 参数：
-    - **x** Variable）-输入张量
+    - **x** (Variable)-输入张量
     - **dropout_prob** (float)-设置为0的单元的概率
     - **is_test** (bool)-显示是否进行测试用语的标记
     - **seed** (int)-Python整型，用于创建随机种子。如果该参数设为None，则使用随机种子。注：如果给定一个整型种子，始终丢弃相同的输出单元。训练过程中勿用固定不变的种子。
     - **name** (str|None)-该层名称（可选）。如果设置为None,则自动为该层命名
-    - **dropout_implementation** (string)-[‘downgrade_in_infer’(defauld)|’upscale_in_train’] 
-        1.downgrade_in_infer(default), 在预测时减小输出结果 
-            train: out = input * mask 
-	    
-	    inference: out = input * dropout_prob 
-            (mask是一个张量，维度和输入维度相同，值为0或1，值为0的比例即为dropout_prob)
-        2.upscale_in_train, 增加训练时的结果
-	    train: out = input * mask / ( 1.0 - dropout_prob )
-	    
-	    inference: out = input 
-	    (make是一个张量，维度和输入维度相同，值为0或1，值为0的比例即为dropout_prob）
-            dropout操作符可以从程序中移除，程序变得高效。
+    - **dropout_implementation** (string) -   [‘downgrade_in_infer’(defauld)|’upscale_in_train’] 
+      其中:
+      1.downgrade_in_infer(default), 在预测时减小输出结果 
+
+        train: out = input * mask 
+
+        inference: out = input * dropout_prob 
+
+        (mask是一个张量，维度和输入维度相同，值为0或1，值为0的比例即为 ``dropout_prob`` )
+        
+      2.upscale_in_train, 增加训练时的结果
+
+        train: out = input * mask / ( 1.0 - dropout_prob )
+
+        inference: out = input 
+
+        (make是一个张量，维度和输入维度相同，值为0或1，值为0的比例即为 ``dropout_prob`` ）
+
+dropout操作符可以从程序中移除，程序变得高效。
 
 返回：带有x维的张量
 
@@ -2706,7 +2728,7 @@ dynamic_gru
     emb = fluid.layers.embedding(input=data, size=[dict_dim, emb_dim])
     hidden_dim = 512
     x = fluid.layers.fc(input=emb, size=hidden_dim * 3)
-    hidden = fluid.layers.dynamic_gru(input=x, dim=hidden_dim)
+    hidden = fluid.layers.dynamic_gru(input=x, size=hidden_dim)
 
 
 
@@ -2959,8 +2981,8 @@ edit_distance
 
 .. code-block:: python
 
-    x = fluid.layers.data(name='x', shape=[8], dtype='float32')
-    y = fluid.layers.data(name='y', shape=[7], dtype='float32')
+    x = fluid.layers.data(name='x', shape=[1], dtype='float32')
+    y = fluid.layers.data(name='y', shape=[1], dtype='float32')
     cost = fluid.layers.edit_distance(input=x,label=y)
 
 
@@ -4056,23 +4078,41 @@ hash
 hsigmoid
 -------------------------------
 
-.. py:function:: paddle.fluid.layers.hsigmoid(input, label, num_functiones, param_attr=None, bias_attr=None, name=None)
+.. py:function:: paddle.fluid.layers.hsigmoid(input, label, num_functiones, param_attr=None, bias_attr=None, name=None, path_table=None, path_code=None, is_custom=False, is_sparse=False)
 
-层次sigmod（ hierarchical sigmoid ）加速语言模型的训练过程。这个operator将类别组织成一个完整的二叉树，每个叶节点表示一个类(一个单词)，每个内部节点进行一个二分类。对于每个单词，都有一个从根到它的叶子节点的唯一路径，hsigmoid计算路径上每个内部节点的损失（cost），并将它们相加得到总损失（cost）。hsigmoid可以把时间复杂度 :math:`O(N)` 优化到 :math:`O(logN)` ,其中 :math:`N` 表示单词字典的大小。
+层次sigmod（ hierarchical sigmoid ）加速语言模型的训练过程。这个operator将类别组织成一个完全二叉树，也可以使用 ``is_custom`` 参数来传入自定义的树结构来实现层次化。 
+
+树中每个叶节点表示一个类(一个单词)，每个内部节点进行一个二分类。对于每个单词，都有一个从根到它的叶子节点的唯一路径，hsigmoid计算路径上每个内部节点的损失（cost），并将它们相加得到总损失（cost）。
+
+hsigmoid可以把时间复杂度 :math:`O(N)` 优化到 :math:`O(logN)` ,其中 :math:`N` 表示单词字典的大小。
+
+使用默认树结构，请参考 `Hierarchical Probabilistic Neural Network Language Model <http://www.iro.umontreal.ca/~lisa/pointeurs/hierarchical-nnlm-aistats05.pdf>`_ 。
+
+若要使用自定义树结构，请设置 ``is_custom`` 值为True。但在此之前，请完成以下几步部署：
+
+1.使用自定义词典来建立二叉树，每个叶结点都应该是词典中的单词
+
+2.建立一个dict类型数据结构，来存储 **单词id -> 该单词叶结点至根节点路径** 的映射，称之为路径表 ``path_table`` 参数
+
+3.建立一个dict类型数据结构，来存储 **单词id -> 该单词叶结点至根节点路径的编码(code)** 的映射。 编码code是指每次二分类的标签，1为真，0为假
+
+4.现在我们的每个单词都已经有自己的路径和路径编码，当对于同一批输入进行操作时，你可以同时传入一批路径和路径编码进行运算。
 
-`请参考 Hierarchical Probabilistic Neural Network Language Model <http://www.iro.umontreal.ca/~lisa/pointeurs/hierarchical-nnlm-aistats05.pdf>`_
-    
 参数:
     - **input** (Variable) - 输入张量，shape为 ``[N×D]`` ,其中 ``N`` 是minibatch的大小，D是特征大小。
     - **label** (Variable) - 训练数据的标签。该tensor的shape为 ``[N×1]``   
-    - **num_classes** (int) - 类别的数量不能少于2
+    - **num_classes** (int) - 类别的数量不能少于2。若使用默认树结构，该参数必须用户设置。当 ``is_custom=False`` 时，该项绝不能为None。反之，如果 ``is_custom=True`` ，它取值应为非叶节点的个数，来指明二分类实用的类别数目。
     - **param_attr** (ParamAttr|None) - 可学习参数/ hsigmoid权重的参数属性。如果将其设置为ParamAttr的一个属性或None，则将ParamAttr设置为param_attr。如果没有设置param_attr的初始化器，那么使用用Xavier初始化。默认值:没None。
     - **bias_attr** (ParamAttr|bool|None) - hsigmoid偏置的参数属性。如果设置为False，则不会向输出添加偏置。如果将其设置ParamAttr的一个属性或None，则将ParamAttr设置为bias_attr。如果没有设置bias_attr的初始化器，偏置将初始化为零。默认值:None。
     - **name** (str|None) - 该layer的名称(可选)。如果设置为None，该层将被自动命名。默认值:None。
+    - **path_table** (Variable|None) – 存储每一批样本从词到根节点的路径。路径应为从叶至根方向。 ``path_table`` 和 ``path_code`` 应具有相同的形, 对于每个样本 i ，path_table[i]为一个类似np.array的结构，该数组内的每个元素都是其双亲结点权重矩阵的索引
+    - **path_code** (Variable|None) – 存储每批样本的路径编码，仍然是按从叶至根方向。各样本路径编码批都由其各祖先结点的路径编码组成
+    - **is_custom** (bool|False) – 使用用户自定义二叉树取代默认二叉树结构，如果该项为真， 请务必设置 ``path_table`` , ``path_code`` , ``num_classes`` , 否则就需要设置 num_classes 
+    - **is_sparse** (bool|False) – 使用稀疏更新方式，而非密集更新。如果为真， W的梯度和输入梯度将会变得稀疏
+
+返回:  (LoDTensor) 层次sigmod（ hierarchical sigmoid） 。shape[N, 1]
     
-    返回:  (Tensor) 层次sigmod（ hierarchical sigmoid） 。shape[N, 1]
-    
-    返回类型:  Out
+返回类型:  Out
 
 
 **代码示例**
@@ -4083,7 +4123,7 @@ hsigmoid
     	y = fluid.layers.data(name='y', shape=[1], dtype='int64')
     	out = fluid.layers.hsigmoid(input=x, label=y, num_classes=6)
 
-  
+
 
 
 
@@ -5386,7 +5426,7 @@ multiplex
 **代码示例**
 
 ..  code-block:: python
-    
+
    import paddle.fluid as fluid
    
    x1 = fluid.layers.data(name='x1', shape=[4], dtype='float32')
@@ -5408,7 +5448,7 @@ multiplex
 nce
 -------------------------------
 
-.. py:function:: paddle.fluid.layers.nce(input, label, num_total_functiones, sample_weight=None, param_attr=None, bias_attr=None, num_neg_samples=None, name=None)
+.. py:function:: paddle.fluid.layers.nce(input, label, num_total_functiones, sample_weight=None, param_attr=None, bias_attr=None, num_neg_samples=None, name=None, sampler='uniform', custom_dist=None, seed=0, is_sparse=False)
 
 计算并返回噪音对比估计（ noise-contrastive estimation training loss）。
 `请参考 See Noise-contrastive estimation: A new estimation principle for unnormalized statistical models 
@@ -5416,14 +5456,18 @@ nce
 该operator默认使用均匀分布进行抽样。
 
 参数:
-	- **input** (Variable) -  特征
-	- **label** (Variable) -  标签
-    	- **num_total_classes** (int) - 所有样本中的类别的总数
-    	- **sample_weight** (Variable|None) - 存储每个样本权重，shape为[batch_size, 1]存储每个样本的权重。每个样本的默认权重为1.0
-    	- **param_attr** (ParamAttr|None) - 可学习参数/ nce权重的参数属性。如果它没有被设置为ParamAttr的一个属性，nce将创建ParamAttr为param_attr。如没有设置param_attr的初始化器，那么参数将用Xavier初始化。默认值:None
-    	- **bias_attr** (ParamAttr|bool|None) -  nce偏置的参数属性。如果设置为False，则不会向输出添加偏置（bias）。如果值为None或ParamAttr的一个属性，则bias_attr=ParamAtt。如果没有设置bias_attr的初始化器，偏置将被初始化为零。默认值:None
-    	- **num_neg_samples** (int) - 负样例的数量。默认值是10
-    	- **name** (str|None) - 该layer的名称(可选)。如果设置为None，该层将被自动命名
+    - **input** (Variable) -  输入变量
+    - **label** (Variable) -  标签
+    - **num_total_classes** (int) - 所有样本中的类别的总数
+    - **sample_weight** (Variable|None) - 存储每个样本权重，shape为[batch_size, 1]存储每个样本的权重。每个样本的默认权重为1.0
+    - **param_attr** (ParamAttr|None) - :math:`可学习参数/nce权重` 的参数属性。如果它没有被设置为ParamAttr的一个属性，nce将创建ParamAttr为param_attr。如没有设置param_attr的初始化器，那么参数将用Xavier初始化。默认值:None
+    - **bias_attr** (ParamAttr|bool|None) -  nce偏置的参数属性。如果设置为False，则不会向输出添加偏置（bias）。如果值为None或ParamAttr的一个属性，则bias_attr=ParamAtt。如果没有设置bias_attr的初始化器，偏置将被初始化为零。默认值:None
+    - **num_neg_samples** (int) - 负样例的数量。默认值是10
+    - **name** (str|None) - 该layer的名称(可选)。如果设置为None，该层将被自动命名
+    - **sampler** (str) – 取样器，用于从负类别中进行取样。可以是 ‘uniform’, ‘log_uniform’ 或 ‘custom_dist’。 默认 ‘uniform’
+    - **custom_dist** (float[]) – 一个 float[] 并且它的长度为 ``num_total_classes`` 。  如果取样器类别为‘custom_dist’，则使用此参数。 custom_dist[i] 是第i个类别被取样的概率。默认为 None
+    - **seed** (int) – 取样器使用的seed。默认为0
+    - **is_sparse** (bool) – 标志位，指明是否使用稀疏更新,  :math:`weight@GRAD` 和 :math:`bias@GRAD` 会变为 SelectedRows
 
 返回：	nce loss
 
@@ -5434,28 +5478,37 @@ nce
 
 ..  code-block:: python
 
-    window_size = 5
-    words = []
-    for i in xrange(window_size):
-    	words.append(layers.data(
-    	name='word_{0}'.format(i), shape=[1], dtype='int64'))
+		window_size = 5
+		words = []
+		for i in xrange(window_size):
+			words.append(layers.data(
+				name='word_{0}'.format(i), shape=[1], dtype='int64'))
+
+		dict_size = 10000
+		label_word = int(window_size / 2) + 1
 
-    dict_size = 10000
-    label_word = int(window_size / 2) + 1
+		embs = []
+		for i in xrange(window_size):
+			if i == label_word:
+				continue
 
-    embs = []
-    for i in xrange(window_size):
-   	 if i == label_word:
-    	continue
+			emb = layers.embedding(input=words[i], size=[dict_size, 32],
+								   param_attr='emb.w', is_sparse=True)
+			embs.append(emb)
 
-    emb = layers.embedding(input=words[i], size=[dict_size, 32],
-    param_attr='emb.w', is_sparse=True)
-    embs.append(emb)
+		embs = layers.concat(input=embs, axis=1)
+		loss = layers.nce(input=embs, label=words[label_word],
+					  num_total_classes=dict_size, param_attr='nce.w',
+					  bias_attr='nce.b')
 
-    embs = layers.concat(input=embs, axis=1)
-    loss = layers.nce(input=embs, label=words[label_word],
-    num_total_classes=dict_size, param_attr='nce.w',
-    bias_attr='nce.b')
+		#使用custom distribution
+		dist = fluid.layers.assign(input=np.array([0.05,0.5,0.1,0.3,0.05]).astype("float32"))
+		loss = layers.nce(input=embs, label=words[label_word],
+					  num_total_classes=5, param_attr='nce.w',
+					  bias_attr='nce.b',
+					  num_neg_samples=3,
+					  sampler="custom_dist",
+					  custom_dist=dist)
 
 
 
@@ -5691,7 +5744,7 @@ pad_constant_like
 pool2d
 -------------------------------
 
-.. py:function:: paddle.fluid.layers.pool2d(input, pool_size=-1, pool_type='max', pool_stride=1, pool_padding=0, global_pooling=False, use_cudnn=True, ceil_mode=False, name=None)
+.. py:function:: paddle.fluid.layers.pool2d(input, pool_size=-1, pool_type='max', pool_stride=1, pool_padding=0, global_pooling=False, use_cudnn=True, ceil_mode=False, name=None, exclusive=True)
 
 pooling2d操作符根据 ``input`` ， 池化类型 ``pool_type`` ， 池化核大小 ``pool_size`` , 步长 ``pool_stride`` ，填充 ``pool_padding`` 这些参数得到输出。
 
@@ -5702,10 +5755,10 @@ pooling2d操作符根据 ``input`` ， 池化类型 ``pool_type`` ， 池化核
 例如：
 
 输入：
-    X shape：:math:`\left ( N,C_{in},H_{in},W_{in} \right )`
+    X shape：:math:`\left ( N,C,H_{in},W_{in} \right )`
 
 输出：
-    Out shape：:math:`\left ( N,C_{out},H_{out},W_{out} \right )`
+    Out shape：:math:`\left ( N,C,H_{out},W_{out} \right )`
 
 如果 ``ceil_mode`` = false：
 
@@ -5738,21 +5791,22 @@ pooling2d操作符根据 ``input`` ， 池化类型 ``pool_type`` ， 池化核
     hstart &= max(0, i * strides[0] - paddings[0])\\
     hend &= min(H, hstart + ksize[0]) \\
     wstart &= max(0, j * strides[1] - paddings[1]) \\
-    wend & = min(W, wstart + ksize[1]) Output(i ,j) \\
-         & = \frac{sum(Input[hstart:hend, wstart:wend])}{(hend - hstart) * (wend - wstart)}
+    wend & = min(W, wstart + ksize[1]) \\
+    Output(i ,j) & = \frac{sum(Input[hstart:hend, wstart:wend])}{(hend - hstart) * (wend - wstart)}
 
 
 
 参数：
     - **input** (Variable) - 池化操作的输入张量。输入张量格式为NCHW，N为批尺寸，C是通道数，H是特征高度，W是特征宽度
-    - **pool_size** (int) - 池化窗口的边长。如果它是一个元组或列表，它必须包含两个整数值， (pool_size_Height, pool_size_Width)。否则它应是一个整数的平方值。
+    - **pool_size** (int|list|tuple)  - 池化窗口的大小。如果它是一个元组或列表，它必须包含两个整数值， (pool_size_Height, pool_size_Width)。否则它应是一个整数的平方值。
     - **pool_type** (string) - 池化类型，可以是“max”对应max-pooling，“avg”对应average-pooling
-    - **pool_stride** (int) - 池化层的步长。如果它是一个元组或列表，它将包含两个整数，(pool_stride_Height, pool_stride_Width)。否则它是一个整数的平方值。
-    - **pool_padding** (int) - 填充大小。如果它是一个元组或列表，它必须包含两个整数值，(pool_padding_on_Height, pool_padding_on_Width)。否则它是一个整数的平方值。
-    - **global_pooling** （bool，默认false）- 是否用全局池化。如果global_pooling = true，ksize和填充（padding）则被忽略
+    - **pool_stride** (int|list|tuple)  - 池化层的步长。如果它是一个元组或列表，它将包含两个整数，(pool_stride_Height, pool_stride_Width)。否则它是一个整数的平方值。
+    - **pool_padding** (int|list|tuple) - 填充大小。如果它是一个元组或列表，它必须包含两个整数值，(pool_padding_on_Height, pool_padding_on_Width)。否则它是一个整数的平方值。
+    - **global_pooling** （bool，默认false）- 是否用全局池化。如果global_pooling = true， ``pool_size`` 和 ``pool_padding`` 将被忽略。
     - **use_cudnn** （bool，默认false）- 只在cudnn核中用，需要下载cudnn
     - **ceil_mode** （bool，默认false）- 是否用ceil函数计算输出高度和宽度。默认False。如果设为False，则使用floor函数
     - **name** （str|None） - 该层名称（可选）。若设为None，则自动为该层命名。
+    - **exclusive** (bool) - 是否在平均池化模式忽略填充值。默认为True。
 
 返回：池化结果
 
@@ -5789,20 +5843,21 @@ pooling2d操作符根据 ``input`` ， 池化类型 ``pool_type`` ， 池化核
 pool3d
 -------------------------------
 
-.. py:function:: paddle.fluid.layers.pool3d(input, pool_size=-1, pool_type='max', pool_stride=1, pool_padding=0, global_pooling=False, use_cudnn=True, ceil_mode=False, name=None)
+.. py:function:: paddle.fluid.layers.pool3d(input, pool_size=-1, pool_type='max', pool_stride=1, pool_padding=0, global_pooling=False, use_cudnn=True, ceil_mode=False, name=None， exclusive=True)
 
 函数使用上述输入参数的池化配置，为三维空间添加池化操作
 
 参数：
-    - **input** (Vairable) - 池化的输入张量。输入张量的格式为NCHW, N是批尺寸，C是通道数，N是特征高度，W是特征宽度。
-    - **pool_size** (int) - 池化窗口的边长。所有对池化窗口都是正方形，边长为pool_size。
-    - **pool_type** (str) - 池化类型，``ma``对应max-pooling,``avg``对应average-pooling。
-    - **pool_stride** (int) - 跨越步长
-    - **pool_padding** (int) - 填充大小
-    - **global_pooling** (bool) - 是否使用全局池化。如果global_pooling = true,ksize and paddings将被忽略。
-    - **use_cudnn** (bool) - 是否用cudnn核，只有在cudnn库安装时有效
+    - **input** (Vairable) - 池化运算的输入张量。输入张量的格式为NCDHW, N是批尺寸，C是通道数，D是特征深度，H是特征高度，W是特征宽度。
+    - **pool_size** (int|list|tuple) - 池化窗口的大小。如果为元组类型，那么它应该是由三个整数组成：深度，高度，宽度。如果是int类型，它应该是一个整数的立方。
+    - **pool_type** (str) - 池化类型， "max" 对应max-pooling, "avg" 对应average-pooling。
+    - **pool_stride** (int|list|tuple) - 池化跨越步长。如果为元组类型，那么它应该是由三个整数组成：深度，高度，宽度。如果是int类型，它应该是一个整数的立方。
+    - **pool_padding** (int|list|tuple) - 填充大小。如果为元组类型，那么它应该是由三个整数组成：深度，高度，宽度。如果是int类型，它应该是一个整数的立方。
+    - **global_pooling** (bool) - 是否使用全局池化。如果global_pooling = true, ``pool_size`` 和 ``pool_padding`` 将被忽略。
+    - **use_cudnn** (bool) - 是否用cudnn核，只有在cudnn库安装时有效。
     - **ceil_mode** (bool) - 是否用ceil函数计算输出高度和宽度。默认False。如果设为False，则使用floor函数。
     - **name** (str) - 该层名称（可选）。若为空，则自动为该层命名。
+    - **exclusive** (bool) - 是否在平均池化模式忽略填充值。默认为True。
 
 返回：pool3d层的输出
 
@@ -5951,7 +6006,7 @@ P 的取值可为： {0, 1} 或 {0, 0.5, 1}, 其中，0.5表示输入的两文
 **代码示例**
 
 .. code-block:: python
-	
+
     theta = fluid.layers.data(name="x", shape=[2, 3], dtype="float32")
     out_shape = fluid.layers.data(name="y", shape=[-1], dtype="float32")
     data = fluid.layers.affine_grid(theta, out_shape)
@@ -6497,7 +6552,7 @@ Faster-RCNN.使用了roi池化。roi关于roi池化请参考 https://stackoverfl
 **代码示例**
 
 ..  code-block:: python
-        
+
 	pool_out = fluid.layers。roi_pool(输入=x, rois=rois, 7,7,1.0)
 
 
@@ -7087,7 +7142,7 @@ sequence_mask
 sequence_pad
 -------------------------------
 
-.. py:function:: paddle.fluid.layers.sequence_pad(x,pad_value,maxlen=None)
+.. py:function:: paddle.fluid.layers.sequence_pad(x,pad_value,maxlen=None,name=None)
 
 序列填充操作符（Sequence Pad Operator）
 
@@ -7097,7 +7152,6 @@ sequence_pad
 
 ::
 
-
     例1:
 
     给定 1-level LoDTensor
@@ -7114,6 +7168,8 @@ sequence_pad
         Out.data = [[a,b,0,0],[c,d,e,0]]
         Length.data = [[2],[3]]
 
+::
+
     例2:
     
     给定 1-level LoDTensor
@@ -7130,6 +7186,9 @@ sequence_pad
         Out.data = [[[a1,a2],[b1,b2],[0,0]],[[c1,c2],[d1,d2],[e1,e2]]]
         Length.data = [[2],[3]]
 
+
+::
+
     例3:
     
     给定 1-level LoDTensor
@@ -7146,12 +7205,14 @@ sequence_pad
         Out.data = [[[a1,a2],[b1,b2],[p1,p2]],[[c1,c2],[d1,d2],[e1,e2]]]
         Length.data = [[2],[3]]
 
+
 参数：
     - **x** (Vairable) - 输入变量，应包含lod信息
     - **pad_value** (Variable) - 变量，存有放入填充步的值。可以是标量或tensor,维度和序列的时间步长相等。如果是标量,则自动广播到时间步长的维度
     - **maxlen** (int,默认None) - 填充序列的长度。可以为空或者任意正整数。当为空时，以序列中最长序列的长度为准，其他所有序列填充至该长度。当是某个特定的正整数，最大长度必须大于最长初始序列的长度
+    - **name** (str|None) – 该层的命名(可选项)。 如果为 None, 则自动命名
 
-返回：填充序列批（batch）和填充前的初始长度。所有序列的长度相等
+返回：填充序列批（batch）和填充前的初始长度。所有输出序列的长度相等
 
 返回类型：变量（Variable）
 
@@ -7162,8 +7223,9 @@ sequence_pad
     import numpy
 
     x = fluid.layers.data(name='y', shape=[10, 5],
-                 dtype='float32', lod_level=1)
-    pad_value = fluid.layers.assign(input=numpy.array([0]))
+                     dtype='float32', lod_level=1)
+    pad_value = fluid.layers.assign(
+        input=numpy.array([0.0], dtype=numpy.float32))
     out = fluid.layers.sequence_pad(x=x, pad_value=pad_value)
 
 
@@ -7179,7 +7241,7 @@ sequence_pad
 sequence_pool 
 -------------------------------
 
-.. py:function:: paddle.fluid.layers.sequence_pool(input, pool_type)
+.. py:function:: paddle.fluid.layers.sequence_pool(input, pool_type, is_test=False)
 
 该函数为序列的池化添加操作符。将每个实例的所有时间步数特征池化，并用参数中提到的pool_type将特征运用到输入到首部。
 
@@ -7212,6 +7274,7 @@ sequence_pool
 参数：
     - **input** (variable) - 输入变量，为LoDTensor
     - **pool_type** (string) - 池化类型。支持average,sum,sqrt和max
+    - **is_test** (bool, 默认为 False) - 用于区分训练模式和测试评分模式
 
 返回：sequence pooling 变量，类型为张量（Tensor)
 
@@ -7300,7 +7363,7 @@ sequence_reverse
 在第0维上将输入 ``x`` 的各序列倒序。
 
 ::
-    
+
     假设 ``x`` 是一个形为 (5,4) 的LoDTensor， lod信息为 [[0, 2, 5]]，其中，
 
 
@@ -7311,7 +7374,7 @@ sequence_reverse
 输出 ``Y`` 与 ``x`` 具有同样的维数和LoD信息。 于是有：
 
 ::
-    
+
     Y.data() = [ [5, 6, 7, 8], [1, 2, 3, 4], # 索引为0，长度为2的逆序列 
                  [17, 18, 19, 20], [13, 14, 15, 16], [9, 10, 11, 12] # 索引为1，长度为3的逆序列
 
@@ -7906,7 +7969,7 @@ softmax操作符计算k维向量输入中所有其他维的指数和指数值的
 softmax_with_cross_entropy
 -------------------------------
 
-.. py:function:: paddle.fluid.layers.softmax_with_cross_entropy(logits, label, soft_label=False, ignore_index=-100)
+.. py:function:: paddle.fluid.layers.softmax_with_cross_entropy(logits, label, soft_label=False, ignore_index=-100, numeric_stable_mode=False, return_softmax=False)
 
 使用softmax的交叉熵在输出层已被广泛使用。该函数计算输入张量每一行的softmax标准化值，而后计算交叉熵。通过此种方式，可以得到更具数字稳定性的梯度值。
 
@@ -7925,17 +7988,28 @@ softmax_with_cross_entropy
 
 .. math::
    loss_j =  -\sum_{i=0}^{K}\text{label}_i\left(\text{logit}_i - \log\left(\sum_{i=0}^{K}\exp(\text{logit}_i)\right)\right), j = 1,...,K
-   
- 
+
+3.如果 ``numeric_stable_mode`` 为真，在通过softmax和标签计算交叉熵损失前， softmax 首先经由下式计算得出：
+
+.. math::
+    max_j           &= \max_{i=0}^{K}{\text{logit}_i} \\
+    log\_max\_sum_j &= \log\sum_{i=0}^{K}\exp(logit_i - max_j)\\
+    softmax_j &= \exp(logit_j - max_j - {log\_max\_sum}_j)
+
+
 参数:
   - **logits** (Variable) - 未标准化(unscaled)的log概率,一个形为 N X K 的二维张量。 N是batch大小，K是类别总数
   - **label** (Variable) - 2-D 张量，代表了正确标注（ground truth）, 如果 ``soft_label`` 为  False，则该参数是一个形为 N X 1 的Tensor<int64> 。如果 ``soft_label`` 为 True，它是 Tensor<float/double> ，形为 N X K
   - **soft_label** (bool) - 是否将输入标签当作软标签。默认为False
   - **ignore_index** (int) - 指明要无视的目标值，使之不对输入梯度有贡献。仅在 ``soft_label`` 为False时有效，默认为-100 
+  - **numeric_stable_mode** (bool) – 标志位，指明是否使用一个具有更佳数学稳定性的算法。仅在 ``soft_label`` 为 False的GPU模式下生效. 若 ``soft_label`` 为 True 或者执行场所为CPU, 算法一直具有数学稳定性。 注意使用稳定算法时速度可能会变慢。默认为 False
+  - **return_softmax** (bool) – 标志位，指明是否额外返回一个softmax值， 同时返回交叉熵计算结果。默认为False
 
-返回： 交叉熵，一个形为[N x 1]的二维张量
+返回: 
+  - 如果 ``return_softmax`` 为 False， 则返回交叉熵，一个形为[N x 1]的二维张量
+  - 如果 ``return_softmax`` 为 True，则返回元组 (loss, softmax) ，其中交叉熵loss为形为[N x 1]的二维张量，softmax为[N x K]的二维张量
 
-返回类型:	Variable
+返回类型:变量或者两个变量组成的元组
 
 
 **代码示例**
@@ -8360,7 +8434,10 @@ transpose
 
 .. code-block:: python
 
-    x = fluid.layers.data(name='x', shape=[5, 10, 15], dtype='float32')
+    # 请使用 append_batch_size=False 来避免
+    # 在数据张量中添加多余的batch大小维度
+    x = fluid.layers.data(name='x', shape=[5, 10, 15],
+                    dtype='float32', append_batch_size=False)
     x_transposed = layers.transpose(x, perm=[1, 0, 2])
 
 
@@ -9589,22 +9666,22 @@ reverse
 -------------------------------
 
 .. py:function:: paddle.fluid.layers.reverse(x,axis)
-    
-    **reverse**
-    
-    该功能将给定轴上的输入‘x’逆序
 
-    参数：
-        - **x** (Variable)-预逆序到输入
-        - **axis** (int|tuple|list)-其上元素逆序排列的轴。
-    
-    返回：逆序的张量
+**reverse**
 
-    返回类型：变量（Variable）
+该功能将给定轴上的输入‘x’逆序
 
-    **代码示例**：
+参数：
+  - **x** (Variable)-预逆序到输入
+  - **axis** (int|tuple|list)-其上元素逆序排列的轴。
 
-    .. code-block:: python
+返回：逆序的张量
+
+返回类型：变量（Variable）
+
+**代码示例**：
+
+.. code-block:: python
 
         out = fluid.layers.reverse(x=in, axis=0)
         # or:
@@ -9734,6 +9811,7 @@ zeros
 **代码示例**：
 
 .. code-block:: python
+
     data = fluid.layers.zeros(shape=[1], dtype='int64')
 
 
@@ -9760,12 +9838,7 @@ append_LARS
 
 对每一层的学习率运用LARS(LAYER-WISE ADAPTIVE RATE SCALING)
 
-.. code-block python
-
-    .. math::
 
-        learning_rate*=local_gw_ratio * sqrt(sumsq(param))
-            / (sqrt(sumsq(gradient))+ weight_decay * sqrt(sumsq(param)))
 
 参数：
     - **learning_rate** -变量学习率。LARS的全局学习率。
@@ -9773,7 +9846,12 @@ append_LARS
 
 返回： 衰减的学习率
 
+**代码示例** :
 
+.. code-block:: python
+
+        learning_rate*=local_gw_ratio * sqrt(sumsq(param))
+            / (sqrt(sumsq(gradient))+ weight_decay * sqrt(sumsq(param)))
 
 
 
@@ -10455,9 +10533,9 @@ generate_proposals
 
 .. py:function:: paddle.fluid.layers.generate_proposals(scores, bbox_deltas, im_info, anchors, variances, pre_nms_top_n=6000, post_nms_top_n=1000, nms_thresh=0.5, min_size=0.1, eta=1.0, name=None) 
 
-生成proposal标签的Faster-RCNN
+生成proposal的Faster-RCNN
 
-该操作根据每个框的概率为foreground对象，并且可以通过锚（anchors）来计算框来产生RoI。Bbox_deltais和一个objects的分数作为是RPN的输出。最终 ``proposals`` 可用于训练检测网络。
+该操作根据每个框为foreground（前景）对象的概率，并且通过锚（anchors）来计算这些框，进而提出RoI。Bbox_deltais和一个objects的分数作为是RPN的输出。最终 ``proposals`` 可用于训练检测网络。
 
 为了生成 ``proposals`` ，此操作执行以下步骤：
 
@@ -10506,7 +10584,6 @@ iou_similarity
 计算两个框列表的intersection-over-union(IOU)。框列表‘X’应为LoDTensor，‘Y’是普通张量，X成批输入的所有实例共享‘Y’中的框。给定框A和框B，IOU的运算如下：
 
 .. math::
-
     IOU(A, B) = \frac{area(A\cap B)}{area(A)+area(B)-area(A\cap B)}
 
 参数：
@@ -10729,11 +10806,11 @@ rpn_target_assign
 
 对于给定anchors和真实框之间的IoU重叠，该层可以为每个anchors做分类和回归，这些target labels用于训练RPN。classification targets是二进制的类标签（是或不是对象）。根据Faster-RCNN的论文，positive labels有两种anchors：
 
-        （i）anchor/anchors与真实框具有最高IoU重叠；
-        
-        （ii）具有IoU重叠的anchors高于带有任何真实框（ground-truth box）的rpn_positive_overlap0（0.7）。
-        
-        请注意，单个真实框（ground-truth box）可以为多个anchors分配正标签。对于所有真实框（ground-truth box），非正向锚是指其IoU比率低于rpn_negative_overlap（0.3）。既不是正也不是负的anchors对训练目标没有价值。回归目标是与positive anchors相关联而编码的图片真实框。
+(i) anchor/anchors与真实框具有最高IoU重叠；
+
+(ii) 具有IoU重叠的anchors高于带有任何真实框（ground-truth box）的rpn_positive_overlap0（0.7）。
+
+请注意，单个真实框（ground-truth box）可以为多个anchors分配正标签。对于所有真实框（ground-truth box），非正向锚是指其IoU比率低于rpn_negative_overlap（0.3）。既不是正也不是负的anchors对训练目标没有价值。回归目标是与positive anchors相关联而编码的图片真实框。
 
 参数：
         - **bbox_pred** （Variable）- 是一个shape为[N，M，4]的3-D Tensor，表示M个边界框的预测位置。N是批量大小，每个边界框有四个坐标值，即[xmin，ymin，xmax，ymax]。
@@ -10749,7 +10826,13 @@ rpn_target_assign
         - **rpn_positive_overlap** （float）- 对于一个正例的（anchor, gt box）对，是允许anchors和所有真实框之间最小重叠的。
         - **rpn_negative_overlap** （float）- 对于一个反例的（anchor, gt box）对，是允许anchors和所有真实框之间最大重叠的。
 
-返回：        返回元组（predict_scores，predict_location，target_label，target_bbox）。predict_scores和predict_location是RPN的预测结果。 target_label和target_bbox分别是ground-truth。 predict_location是一个shape为[F，4]的2D Tensor， ``target_bbox`` 的shape与 ``predict_location`` 的shape相同，F是foreground anchors的数量。 ``predict_scores`` 是一个shape为[F + B，1]的2D Tensor， ``target_label`` 的shape与 ``predict_scores`` 的shape相同，B是background anchors的数量，F和B取决于此算子的输入。
+返回:
+
+返回元组 (predicted_scores, predicted_location, target_label, target_bbox, bbox_inside_weight) : 
+   - **predicted_scores** 和 **predicted_location** 是RPN的预测结果。 **target_label** 和 **target_bbox** 分别是真实准确数据(ground-truth)。 
+   - **predicted_location** 是一个形为[F，4]的2D Tensor， **target_bbox** 的形与 **predicted_location** 相同，F是foreground anchors的数量。 
+   - **predicted_scores** 是一个shape为[F + B，1]的2D Tensor， **target_label** 的形与 **predict_scores** 的形相同，B是background anchors的数量，F和B取决于此算子的输入。 
+   - **Bbox_inside_weight** 标志着predicted_loction是否为fake_fg（假前景），其形为[F,4]。
 
 返回类型：        元组(tuple)
 
@@ -10766,7 +10849,7 @@ rpn_target_assign
                 append_batch_size=False, dtype=’float32’)
         gt_boxes = layers.data(name=’gt_boxes’, shape=[10, 4],
                 append_batch_size=False, dtype=’float32’)
-        loc_pred, score_pred, loc_target, score_target =
+        loc_pred, score_pred, loc_target, score_target, bbox_inside_weight=
                 fluid.layers.rpn_target_assign(bbox_pred=bbox_pred,
                         cls_logits=cls_logits, anchor_box=anchor_box, gt_boxes=gt_boxes)
         
@@ -11000,8 +11083,9 @@ auc
 
 有两种可能的曲线：
 
-    1. ROC:受试者工作特征曲线
-    2. PR:准确率召回率曲线
+1. ROC:受试者工作特征曲线
+
+2. PR:准确率召回率曲线
 
 参数：
     - **input** (Variable) - 浮点二维变量，值的范围为[0,1]。每一行降序排列。输入应为topk的输出。该变量显示了每个标签的概率。
@@ -11019,7 +11103,7 @@ auc
 
 .. code-block:: python
 
-    # network is a binary classification model and label the ground truth
+    #  network为二分类模型, label为ground truth（正确标记）
     prediction = network(image, is_infer=True)
     auc_out=fluid.layers.auc(input=prediction, label=label)