fix 5 api_cn documents (#1362)

* fix 5 api_cn documents
test=document_preview

doc/fluid/api_cn/layers_cn/hard_swish_cn.rst

@@ -5,31 +5,44 @@ hard_swish
 
 .. py:function:: paddle.fluid.layers.hard_swish(x, threshold=6.0, scale=6.0, offset=3.0, name=None)
 
-hard_swish激活函数，swish的hard version(https://arxiv.org/pdf/1905.02244.pdf)。
+该OP实现了hard_swish激活函数。hard_swish激活函数在MobileNetV3架构中被提出，相较于swish函数，具有数值稳定性好，计算速度快等优点，具体原理请参考: https://arxiv.org/pdf/1905.02244.pdf
 
  :math:`out = \frac{x * (min(max(0, x+offset), threshold))}{scale}`
 
- `` threshold`` 和 ``scale`` 应该为正， ``offset`` 正负均可，默认参数如上，建议使用默认参数。
+ 阈值 ``threshold`` 和缩放因子 ``scale`` 为正数，位移 ``offset`` 正负均可，建议使用默认参数。
 
 参数：
-    - **x** (Variable) - 要做激活操作的输入变量。
-    - **threshold** (float) - 做激活操作的threshold，默认为6.0。
-    - **scale** (float) - 激活操作的scale，默认为6.0。
-    - **offset** (float) - 激活操作的offset，默认为3.0。
-    - **name** (str|None) - 层名，设置为None，此层将被自动命名。
+    - **x** (Variable) - 输入特征，多维Tensor。数据类型为float32或float64。
+    - **threshold** (float，可选) - 激活操作中Relu函数的阈值，默认值为6.0。 
+    - **scale** (float，可选) - 激活操作的缩放因子，默认值为6.0。
+    - **offset** (float，可选) - 激活操作的位移，默认值为3.0。
+    - **name** (None|str) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。
     
-返回：与输入有着同样shape的输出变量
+返回：经过hard_swish计算后的结果，数据类型及维度和x相同。
 
-返回类型：变量（Variable）
+返回类型：Variable
 
 **代码示例**：
 
 .. code-block:: python
 
     import paddle.fluid as fluid
-    x = fluid.layers.data(name="x", shape=[3,10,32,32], dtype="float32")
+    import numpy as np
+
+    DATATYPE='float32'
+    shape = [1,4]
+
+    x_data = np.array([i for i in range(1,5)]).reshape(shape).astype(DATATYPE)
+
+    x = fluid.layers.data(name="x", shape=shape, dtype=DATATYPE)
     y = fluid.layers.hard_swish(x)
 
+    place = fluid.CUDAPlace(0)
+    exe = fluid.Executor(place)
+    out, = exe.run(feed={'x':x_data}, fetch_list=[y.name])
+    print(out)  # [[0.66666667, 1.66666667,3., 4.]]
+
+
 
 
 

doc/fluid/api_cn/layers_cn/huber_loss_cn.rst

@@ -5,27 +5,28 @@ huber_loss
 
 .. py:function:: paddle.fluid.layers.huber_loss(input, label, delta)
 
-Huber损失是更具鲁棒性的损失函数。 huber损失可以评估输入对标签的合适度。 与MSE损失不同，Huber损失可更为稳健地处理异常值。
 
-当输入和标签之间的距离大于delta时:
+该OP计算输入（input）与标签（label）之间的Huber损失。Huber损失是常用的回归损失之一，相较于平方误差损失，Huber损失减小了对异常点的敏感度，更具鲁棒性。
+
+当输入与标签之差的绝对值大于delta时，计算线性误差:
 
 .. math::
         huber\_loss = delta * (label - input) - 0.5 * delta * delta
 
-当输入和标签之间的距离小于delta时:
+当输入与标签之差的绝对值小于delta时，计算平方误差:
 
 .. math::
         huber\_loss = 0.5 * (label - input) * (label - input)
 
 
 参数:
-  - **input** （Variable） - 此输入是前一个算子计算得到的概率。 第一个维度是批大小batch_size，最后一个维度是1。
-  - **label** （Variable） - 第一个维度为批量大小batch_size且最后一个维度为1的真实值
-  - **delta** （float） -  huber loss的参数，用于控制异常值的范围
+  - **input** （Variable） - 输入的预测数据，维度为[batch_size, 1] 或[batch_size]的Tensor。数据类型为float32或float64。
+  - **label** （Variable） - 输入的真实标签，维度为[batch_size, 1] 或[batch_size]的Tensor。数据类型为float32或float64。
+  - **delta** （float） -  Huber损失的阈值参数，用于控制Huber损失对线性误差或平方误差的侧重。数据类型为float32。
 
-返回： 形为[batch_size, 1]的huber loss.
+返回： 计算出的Huber损失，数据维度和数据类型与label相同的Tensor。
 
-返回类型:   huber_loss (Variable)
+返回类型: Variable
 
 
 
@@ -34,15 +35,18 @@ Huber损失是更具鲁棒性的损失函数。 huber损失可以评估输入对
 ..  code-block:: python
 
     import paddle.fluid as fluid
+    import numpy as np
 
-    x = fluid.layers.data(name='x', shape=[13], dtype='float32')
-    predict = fluid.layers.fc(input=x, size=1)
-    label = fluid.layers.data(
-        name='label', shape=[1], dtype='float32')
-    loss = fluid.layers.huber_loss(
-        input=predict, label=label, delta=1.0)
-
-
-
+    DATATYPE='float32'
+    input_data = np.array([[1.],[2.],[3.],[4.]]).astype(DATATYPE)
+    label_data = np.array([[3.],[3.],[4.],[4.]]).astype(DATATYPE)
 
+    x = fluid.layers.data(name='input', shape=[1], dtype=DATATYPE)
+    y = fluid.layers.data(name='label', shape=[1], dtype=DATATYPE)
+    loss = fluid.layers.huber_loss(input=x, label=y, delta=1.0)
 
+    place = fluid.CPUPlace()
+    #place = fluid.CUDAPlace(0)
+    exe = fluid.Executor(place)
+    HuberLoss, = exe.run(feed={'input':input_data ,'label':label_data}, fetch_list=[loss.name])
+    print(HuberLoss)  #[[1.5], [0.5], [0.5], [0. ]], dtype=float32

doc/fluid/api_cn/layers_cn/linear_lr_warmup_cn.rst

@@ -5,21 +5,35 @@ linear_lr_warmup
 
 .. py:function:: paddle.fluid.layers.linear_lr_warmup(learning_rate, warmup_steps, start_lr, end_lr)
 
-在正常学习率调整之前先应用线性学习率热身(warm up)进行初步调整。
+
+该OP使用学习率优化策略-线性学习率热身(warm up)对学习率进行初步调整。在正常调整学习率之前，先逐步增大学习率，具体原理可参考： `Bag of Tricks for Image Classification with Convolutional Neural Networks <https://arxiv.org/abs/1812.01187>`_
+
+当训练步数（global_step）小于热身步数（warmup_steps）时，学习率lr按如下方式更新：
 
 .. code-block:: text
 
-    if global_step < warmup_steps:
         linear_step = end_lr - start_lr
         lr = start_lr + linear_step * (global_step / warmup_steps)
 
+其中start_lr为warm up起始学习率，end_lr为最终学习率；
+
+当训练步数（global_step）大于等于热身步数（warmup_steps）时，学习率lr为：
+
+.. code-block:: text
+
+        lr = learning_rate
+
+其中learning_rate为热身之后的学习率。
+
 参数：
-    - **learning_rate** （float | Variable） - 学习率，类型为float值或变量。
+    - **learning_rate** （Variable|float） - 热身之后的学习率，它可以是数据类型为float32的1D-Tensor或单个浮点数。
     - **warmup_steps** （int） - 进行warm up过程的步数。
-    - **start_lr** （float） - warm up的起始学习率
+    - **start_lr** （float） - warm up的起始学习率。
     - **end_lr** （float） - warm up的最终学习率。
 
-返回：进行热身衰减后的学习率。
+返回：进行热身衰减后的学习率，数据类型与learning_rate相同。
+
+返回类型：Variable
 
 
 **示例代码**
@@ -27,19 +41,21 @@ linear_lr_warmup
 .. code-block:: python
 
         import paddle.fluid as fluid
+
         boundaries = [100, 200]
         lr_steps = [0.1, 0.01, 0.001]
+        learning_rate = fluid.layers.piecewise_decay(boundaries, lr_steps) #case1, Tensor
+        #learning_rate = 0.1  #case2, float32
         warmup_steps = 50
         start_lr = 1. / 3.
         end_lr = 0.1
-        decayed_lr = fluid.layers.linear_lr_warmup(
-            fluid.layers.piecewise_decay(boundaries, lr_steps),
+        decayed_lr = fluid.layers.linear_lr_warmup(learning_rate,
             warmup_steps, start_lr, end_lr)
 
-
-
-
-
-
-
-
+        place = fluid.CPUPlace()
+        exe = fluid.Executor(place)
+        exe.run(fluid.default_startup_program())
+        out, = exe.run(fetch_list=[decayed_lr.name])
+        print(out)
+        # case1: [0.33333334]
+        # case2: [0.33333334]

doc/fluid/api_cn/layers_cn/lrn_cn.rst

@@ -5,11 +5,10 @@ lrn
 
 .. py:function:: paddle.fluid.layers.lrn(input, n=5, k=1.0, alpha=0.0001, beta=0.75, name=None)
 
-局部响应正则层（Local Response Normalization Layer）
 
-该层对局部输入区域正则化，执行一种侧向抑制（lateral inhibition）。
+该OP实现了局部响应正则化层（Local Response Normalization Layer），用于对局部输入区域正则化，执行一种侧向抑制（lateral inhibition）。更多详情参考： `ImageNet Classification with Deep Convolutional Neural Networks <https://papers.nips.cc/paper/4824-imagenet-classification-with-deep-convolutional-neural-networks.pdf>`_
 
-公式如下：
+其中 ``input`` 是mini-batch的输入特征。计算过程如下：
 
 .. math::
 
@@ -17,24 +16,23 @@ lrn
 
 在以上公式中：
   - :math:`n` ：累加的通道数
-  - :math:`k` ：位移（避免除数为0）
+  - :math:`k` ：位移
   - :math:`\alpha` ： 缩放参数
   - :math:`\beta` ： 指数参数
 
-参考 : `ImageNet Classification with Deep Convolutional Neural Networks <https://papers.nips.cc/paper/4824-imagenet-classification-with-deep-convolutional-neural-networks.pdf>`_
 
 参数：
-    - **input** （Variable）- 该层输入张量，输入张量维度必须为4
-    - **n** (int，默认5） - 累加的通道数
-    - **k** （float，默认1.0）- 位移（通常为正数，避免除数为0）
-    - **alpha** （float，默认1e-4）- 缩放参数
-    - **beta** （float，默认0.75）- 指数
-    - **name** （str，默认None）- 操作符名
+    - **input** （Variable）- 输入特征，维度为[N,C,H,W]的4D-Tensor，其中N为batch大小，C为输入通道数，H为特征高度，W为特征宽度。必须包含4个维度，否则会抛出 ``ValueError`` 的异常。数据类型为float32。
+    - **n** (int，可选） - 累加的通道数，默认值为5。
+    - **k** （float，可选）- 位移，正数。默认值为1.0。
+    - **alpha** （float，可选）- 缩放参数，正数。默认值为1e-4。
+    - **beta** （float，可选）- 指数，正数。默认值为0.75。
+    - **name** (None|str) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None。
 
-抛出异常:
-  - ``ValueError`` - 如果输入张量的阶不为4
 
-返回：张量，存储转置结果
+返回：局部响应正则化得到的输出特征，数据类型及维度和input相同。
+
+返回类型：Variable
 
 **代码示例**：
 
@@ -44,14 +42,5 @@ lrn
     data = fluid.layers.data(
         name="data", shape=[3, 112, 112], dtype="float32")
     lrn = fluid.layers.lrn(input=data)
-
-
-
-
-
-
-
-
-
-
-
+    print(lrn.shape)  # [-1, 3, 112, 112]
+    print(lrn.dtype)  # float32

doc/fluid/api_cn/layers_cn/roi_pool_cn.rst

@@ -6,26 +6,26 @@ roi_pool
 .. py:function:: paddle.fluid.layers.roi_pool(input, rois, pooled_height=1, pooled_width=1, spatial_scale=1.0)
 
 
-roi池化是对非均匀大小的输入执行最大池化，以获得固定大小的特征映射(例如7*7)。
+该OP实现了roi池化操作，对非均匀大小的输入执行最大池化，以获得固定大小的特征映射(例如7*7)。
 
-该operator有三个步骤:
+该OP的操作分三个步骤:
 
-    1. 用pooled_width和pooled_height将每个区域划分为大小相等的部分
-    2. 在每个部分中找到最大的值
-    3. 将这些最大值复制到输出缓冲区
+    1. 用pooled_width和pooled_height将每个proposal区域划分为大小相等的部分；
+    2. 在每个部分中找到最大的值；
+    3. 将这些最大值复制到输出缓冲区。
 
-Faster-RCNN.使用了roi池化。roi关于roi池化请参考 https://stackoverflow.com/questions/43430056/what-is-roi-layer-in-fast-rcnn
+Faster-RCNN使用了roi池化。roi池化的具体原理请参考 https://stackoverflow.com/questions/43430056/what-is-roi-layer-in-fast-rcnn
 
 参数:
-    - **input** (Variable) - 张量，ROIPoolOp的输入。输入张量的格式是NCHW。其中N为batch大小，C为输入通道数，H为特征高度，W为特征宽度
-    - **rois** (Variable) – 待池化的ROIs (Regions of Interest)，形为（num_rois,4）的2D张量，lod level 为1。给定比如[[x1,y1,x2,y2], ...],(x1,y1)为左上点坐标，(x2,y2)为右下点坐标。
-    - **pooled_height** (integer) - (int，默认1)，池化输出的高度。默认:1
-    - **pooled_width** (integer) -  (int，默认1) 池化输出的宽度。默认:1
-    - **spatial_scale** (float) - (float，默认1.0)，用于将ROI coords从输入比例转换为池化时使用的比例。默认1.0
+    - **input** (Variable) - 输入特征，维度为[N,C,H,W]的4D-Tensor，其中N为batch大小，C为输入通道数，H为特征高度，W为特征宽度。数据类型为float32或float64.
+    - **rois** (Variable) – 待池化的ROIs (Regions of Interest)，维度为[num_rois,4]的2D-LoDTensor，lod level 为1。给定如[[x1,y1,x2,y2], ...],其中(x1,y1)为左上点坐标，(x2,y2)为右下点坐标。lod信息记录了每个roi所属的batch_id。
+    - **pooled_height** (int，可选) - 数据类型为int32，池化输出的高度。默认值为1。
+    - **pooled_width** (int，可选) -  数据类型为int32，池化输出的宽度。默认值为1。
+    - **spatial_scale** (float，可选) - 数据类型为float32，用于将ROI coords从输入比例转换为池化时使用的比例。默认值为1.0。
 
-返回: (张量)，ROIPoolOp的输出是一个shape为(num_rois, channel, pooled_h, pooled_w)的4d张量。
+返回: 池化后的特征，维度为[num_rois, C, pooled_height, pooled_width]的4D-Tensor。
 
-返回类型: 变量（Variable）
+返回类型: Variable
 
 
 **代码示例**
@@ -33,19 +33,30 @@ Faster-RCNN.使用了roi池化。roi关于roi池化请参考 https://stackoverfl
 ..  code-block:: python
 
   import paddle.fluid as fluid
-     
-  x = fluid.layers.data(
-            name='x', shape=[8, 112, 112], dtype='float32')
-  rois = fluid.layers.data(
-            name='roi', shape=[4], lod_level=1, dtype='float32')
+  import numpy as np
+
+  DATATYPE='float32'
+
+  place = fluid.CPUPlace()
+  #place = fluid.CUDAPlace(0)
+
+  input_data = np.array([i for i in range(1,17)]).reshape(1,1,4,4).astype(DATATYPE)
+  roi_data =fluid.create_lod_tensor(np.array([[1., 1., 2., 2.], [1.5, 1.5, 3., 3.]]).astype(DATATYPE),[[2]], place)
+
+  x = fluid.layers.data(name='input', shape=[1, 4, 4], dtype=DATATYPE)
+  rois = fluid.layers.data(name='roi', shape=[4], lod_level=1, dtype=DATATYPE)
+
   pool_out = fluid.layers.roi_pool(
             input=x,
             rois=rois,
-            pooled_height=7,
-            pooled_width=7,
+            pooled_height=1,
+            pooled_width=1,
             spatial_scale=1.0)
 
-
+  exe = fluid.Executor(place)
+  out, = exe.run(feed={'input':input_data ,'roi':roi_data}, fetch_list=[pool_out.name])
+  print(out)   #array([[[[11.]]], [[[16.]]]], dtype=float32)
+  print(np.array(out).shape)  # (2, 1, 1, 1)