Refine some api cn_doc (#1247)

* Refine fsp_matrix/deformable_conv/fsp_matrix/polygon_box_transform api.

doc/fluid/api_cn/layers_cn/deformable_conv_cn.rst

@@ -5,9 +5,10 @@ deformable_conv
 
 .. py:function:: paddle.fluid.layers.deformable_conv(input, offset, mask, num_filters, filter_size, stride=1, padding=0, dilation=1, groups=None, deformable_groups=None, im2col_step=None, param_attr=None, bias_attr=None, modulated=True, name=None)
 
-可变形卷积层
+**可变形卷积算子**
+
+deformable_conv op对输入4-D Tensor计算2-D可变形卷积。给定输入Tensor x，输出Tensor y，可变形卷积运算如下所示：
 
-在4-D输入上计算2-D可变形卷积。给定输入图像x，输出特征图y，可变形卷积操作如下所示：
 可形变卷积v2:
 
   :math:`y(p) = \sum_{k=1}^{K}{w_k * x(p + p_k + \Delta p_k) * \Delta m_k}`
@@ -16,19 +17,20 @@ deformable_conv
 
   :math:`y(p) = \sum_{k=1}^{K}{w_k * x(p + p_k + \Delta p_k)}`
 
-其中 :math:`\Delta p_k 和 \Delta m_k` 分别为第k个位置的可学习偏移和调制标量。其中在可形变卷积中:math:`\Delta m_k`为1.
-参考可变形卷积网络v2: `可变形程度越高，结果越好 <https://arxiv.org/abs/1811.11168v2>`_ 和 `形变卷积<https://arxiv.org/abs/1703.06211>`_。
+其中 :math:`\Delta p_k` 和 :math:`\Delta m_k` 分别为第k个位置的可学习偏移和调制标量。在deformable_conv_v1中 :math:`\Delta m_k` 为1.
+
+具体细节可以参考论文：`<<Deformable ConvNets v2: More Deformable, Better Results>> <https://arxiv.org/abs/1811.11168v2>`_ 和 `<<Deformable Convolutional Networks>> <https://arxiv.org/abs/1703.06211>`_ 。
 
 **示例**
      
 输入：
-    输入形状： :math:`(N, C_{in}, H_{in}, W_{in})`
+    input 形状： :math:`(N, C_{in}, H_{in}, W_{in})`
 
     卷积核形状： :math:`(C_{out}, C_{in}, H_f, W_f)`
 
-    偏移形状： :math:`(N, 2 * deformable\_groups * H_f * H_w, H_{in}, W_{in})`
+    offset 形状： :math:`(N, 2 * deformable\_groups * H_f * H_w, H_{in}, W_{in})`
 
-    掩膜形状： :math:`(N, deformable\_groups * H_f * H_w, H_{in}, W_{in})`
+    mask 形状： :math:`(N, deformable\_groups * H_f * H_w, H_{in}, W_{in})`
      
 输出：
     输出形状： :math:`(N, C_{out}, H_{out}, W_{out})`
@@ -43,48 +45,52 @@ deformable_conv
      
 
 参数：
-    - **input** (Variable) - 形式为[N, C, H, W]的输入图像。
-    - **offset** (Variable) – 可变形卷积层的输入坐标偏移。
-    - **Mask** (Variable) – 可变形卷积层的输入掩膜。
-    - **num_filters** (int) – 卷积核数。和输出图像通道数相同。
-    - **filter_size** (int|tuple|None) – 卷积核大小。如果filter_size为元组，则必须包含两个整数(filter_size_H, filter_size_W)。否则卷积核将为方形。
-    - **stride** (int|tuple) – 步长大小。如果stride为元组，则必须包含两个整数(stride_H, stride_W)。否则stride_H = stride_W = stride。默认stride = 1。
-    - **padding** (int|tuple) – padding大小。如果padding为元组，则必须包含两个整数(padding_H, padding_W)。否则padding_H = padding_W = padding。默认padding = 0。
-    - **dilation** (int|tuple) – dilation大小。如果dilation为元组，则必须包含两个整数(dilation_H, dilation_W)。否则dilation_H = dilation_W = dilation。默认dilation = 1。
-    - **groups** (int) – 可变形卷积层的群组数。依据Alex Krizhevsky的Deep CNN论文中的分组卷积，有：当group=2时，前一半卷积核只和前一半输入通道有关，而后一半卷积核只和后一半输入通道有关。默认groups=1。
-    - **deformable_groups** (int) – 可变形群组分区数。默认deformable_groups = 1。
-    - **im2col_step** (int) – 每个im2col计算的最大图像数。总batch大小应该可以被该值整除或小于该值。如果您面临内存问题，可以尝试在此处使用一个更小的值。默认im2col_step = 64。
-    - **param_attr** (ParamAttr|None) – 可变形卷积的可学习参数/权重的参数属性。如果将其设置为None或ParamAttr的一个属性，可变形卷积将创建ParamAttr作为param_attr。如果没有设置此param_attr的Initializer，该参数将被Normal(0.0, std)初始化，且其中的std为 :math:`(\frac{2.0 }{filter\_elem\_num})^{0.5}`。默认值None。
-    - **bias_attr** (ParamAttr|bool|None) – 可变形卷积层的偏置的参数属性。如果设为False，则输出单元不会加偏置。如果设为None或者ParamAttr的一个属性，conv2d会创建ParamAttr作为bias_attr。如果不设置bias_attr的Initializer，偏置会被初始化为0。默认值None。
-    - **modulated** （bool）- 确定使用v1和v2中的哪个版本，如果为True，则选择使用v2。默认为True。
-    - **name** (str|None) – 该层的名字（可选项）。如果设为None，该层将会被自动命名。默认值None。
+    - **input** (Variable) - 形状为 :math:`[N, C, H, W]` 的输入Tensor，数据类型为float32或float64。
+    - **offset** (Variable) – 可变形卷积层的输入坐标偏移，数据类型为float32或float64。
+    - **mask** (Variable, 可选) – 可变形卷积层的输入掩码，当使用可变形卷积算子v2时，请将mask设置为None, 数据类型为float32或float64。
+    - **num_filters** (int) – 卷积核数，与输出Tensor通道数相同。
+    - **filter_size** (int|tuple) – 卷积核大小。如果filter_size为元组，则必须包含两个整数(filter_size_H, filter_size_W)。若数据类型为int，卷积核形状为(filter_size, filter_size)。
+    - **stride** (int|tuple) – 步长大小。如果stride为元组，则必须包含两个整数(stride_H, stride_W)。否则stride_H = stride_W = stride。缺省值为1。
+    - **padding** (int|tuple) – padding大小。如果padding为元组，则必须包含两个整数(padding_H, padding_W)。否则padding_H = padding_W = padding。缺省值为0。
+    - **dilation** (int|tuple) – dilation大小。如果dilation为元组，则必须包含两个整数(dilation_H, dilation_W)。否则dilation_H = dilation_W = dilation。缺省值为1。
+    - **groups** (int) – 卷积组数。依据Alex Krizhevsky的Deep CNN论文中的分组卷积，有：当group=2时，前一半卷积核只和前一半输入通道有关，而后一半卷积核只和后一半输入通道有关。缺省值为1。
+    - **deformable_groups** (int) – 可变形卷积组数。缺省值为1。
+    - **im2col_step** (int) – 每个im2col计算的最大图像数。总batch大小应可以被该值整除或小于该值。如果您面临内存问题，可以尝试在此处使用一个较小的值。缺省值为64。
+    - **param_attr** (ParamAttr，可选) – 可变形卷积的可学习权重的属性。如果将其设置为None或某种ParamAttr，可变形卷积将创建ParamAttr作为param_attr。如果没有设置此param_attr的Initializer，该参数将被Normal(0.0, std)初始化，且其中的std为 :math:`(\frac{2.0 }{filter\_elem\_num})^{0.5}` 。缺省值为None。
+    - **bias_attr** (ParamAttr|bool，可选) – 可变形卷积层的偏置的参数属性。如果设为False，则输出单元不会加偏置。如果设为None或者某种ParamAttr，conv2d会创建ParamAttr作为bias_attr。如果不设置bias_attr的Initializer，偏置会被初始化为0。缺省值为None。
+    - **modulated** （bool）- 确定使用v1和v2中的哪个版本，如果为True，则选择使用v2。缺省值为True。
+    - **name** (str，可选) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，缺省值为None。
  
-返回：储存可变形卷积结果的张量变量。
+返回：可变形卷积输出的4-D Tensor，数据类型为float32或float64。
      
-返回类型：变量(Variable)
+返回类型：Variable
      
-抛出：ValueError – 如果input, filter_size, stride, padding和groups的大小不匹配。
+抛出异常：ValueError – 如果input, filter_size, stride, padding和groups的大小不匹配。
 
 **代码示例**
 
 ..  code-block:: python
 
     #deformable conv v2:
-         
+
     import paddle.fluid as fluid
-    data = fluid.layers.data(name='data', shape=[3, 32, 32], dtype='float32')
-    offset = fluid.layers.data(name='offset', shape=[18, 32, 32], dtype='float32')
-    mask = fluid.layers.data(name='mask', shape=[9, 32, 32], dtype='float32')
+    C_in, H_in, W_in = 3, 32, 32
+    filter_size, deformable_groups = 3, 1
+    data = fluid.layers.data(name='data', shape=[C_in, H_in, W_in], dtype='float32')
+    offset = fluid.layers.data(name='offset', shape=[2*deformable_groups*filter_size**2, H_in, W_in], dtype='float32')
+    mask = fluid.layers.data(name='mask', shape=[deformable_groups*filter_size**2, H_in, W_in], dtype='float32')
     out = fluid.layers.deformable_conv(input=data, offset=offset, mask=mask,
-                                       num_filters=2, filter_size=3, padding=1, modulated=True)
+                                       num_filters=2, filter_size=filter_size, padding=1, modulated=True)
 
     #deformable conv v1:
 
     import paddle.fluid as fluid
-    data = fluid.layers.data(name='data', shape=[3, 32, 32], dtype='float32')
-    offset = fluid.layers.data(name='offset', shape=[18, 32, 32], dtype='float32')
+    C_in, H_in, W_in = 3, 32, 32
+    filter_size, deformable_groups = 3, 1
+    data = fluid.layers.data(name='data', shape=[C_in, H_in, W_in], dtype='float32')
+    offset = fluid.layers.data(name='offset', shape=[2*deformable_groups*filter_size**2, H_in, W_in], dtype='float32')
     out = fluid.layers.deformable_conv(input=data, offset=offset, mask=None,
-                                       num_filters=2, filter_size=3, padding=1, modulated=False)
+                                       num_filters=2, filter_size=filter_size, padding=1, modulated=False)
 
 
 

doc/fluid/api_cn/layers_cn/flatten_cn.rst

@@ -5,7 +5,7 @@ flatten
 
 .. py:function::  paddle.fluid.layers.flatten(x, axis=1, name=None)
 
-将输入张量压扁成二维矩阵
+flatten op将输入的多维Tensor展平成2-D Tensor矩阵
 
 例如：
 
@@ -30,25 +30,27 @@ flatten
         Out.shape = (1, 3 * 100 * 100 * 4)
 
 参数：
-  - **x** (Variable) - 一个秩>=axis 的张量
-  - **axis** (int) - flatten的划分轴，[0, axis) 轴数据被flatten到输出矩阵的0轴，[axis, R)被flatten到输出矩阵的1轴，其中R是输入张量的秩。axis的值必须在[0,R]范围内。当 axis= 0 时，输出张量的形状为 (1，d_0 \* d_1 \*… d_n) ，其输入张量的形状为(d_0, d_1，… d_n)。
-  - **name** (str|None) - 此层的名称(可选)。如果没有设置，层将自动命名。
+  - **x** (Variable) - 一个维度数>=axis 的多维Tensor, 数据类型可以为float32，float64，int8，int32或int64。
+  - **axis** (int) - flatten展开的分割轴，[0, axis) 轴数据被flatten到输出矩阵的0轴，[axis, R)数据被flatten到输出矩阵的1轴，其中R是输入张量的总维度数。axis的值必须在[0,R]范围内。当 axis=0 时，若输入Tensor的维度为 :math:`[d_0, d_1，… d_n]` ，则输出张量的Tensor维度为 :math:`[1，d_0 * d_1 *… d_n]` ，缺省值为1。
+  - **name** (str，可选) - 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，缺省值为None。
 
-返回: 一个二维张量，它包含输入张量的内容，但维数发生变化。输入的[0, axis)维将沿给定轴flatten到输出的前一个维度，剩余的输入维数flatten到输出的后一个维度。
+返回: 一个 2-D Tensor，它包含输入Tensor的数据，但维度发生变化。输入的[0, axis)维将沿axis展平到输出Tensor的0维度，剩余的输入维数展平到输出的1维度。数据类型与输入x相同。
 
 返回类型: Variable
 
 抛出异常：
-  - ValueError: 如果 x 不是一个变量
-  - ValueError: 如果axis的范围不在 [0, rank(x)]
+  - ValueError: 如果 x 不是一个Variable
+  - ValueError: 如果axis的范围不在 [0, rank(x)] 范围内
 
 **代码示例**
 
 .. code-block:: python
 
     import paddle.fluid as fluid
-    x = fluid.layers.data(name="x", shape=[4, 4, 3], dtype="float32")
+    x = fluid.layers.data(name="x", shape=[4, 4, 3], append_batch_size=False, dtype="float32")
+    # x shape is [4, 4, 3]
     out = fluid.layers.flatten(x=x, axis=2)
+    # out shape is [16, 3]
 
 
 

doc/fluid/api_cn/layers_cn/fsp_matrix_cn.rst

@@ -7,21 +7,21 @@ fsp_matrix
 
 **FSP matrix op**
 
-此运算用于计算两个特征映射的求解过程（FSP）矩阵。给定形状为[x_channel，h，w]的特征映射x和形状为[y_channel，h，w]的特征映射y，我们可以分两步得到x和y的fsp矩阵：
+fsp_matrix op用于计算两个4-D Tensor特征图的求解过程（FSP）矩阵。假设特征图x的形状为 :math:`[x\_channel，h，w]` ，特征图y的形状为 :math:`[y\_channel，h，w]` ，fsp_matrix op分两步得到x和y的fsp矩阵：
 
-1.用形状[X_channel，H*W]将X重塑为矩阵，并用形状[H*W，y_channel]将Y重塑和转置为矩阵。
+1.将x reshape到形状为 :math:`[x\_channel，h*w]` 的矩阵，将y reshape到形状为 :math:`[h*w，y\_channel]` 的矩阵。
 
-2.乘以x和y得到形状为[x_channel，y_channel]的fsp矩阵。
+2.对x和y做矩阵乘法得到形状为 :math:`[x\_channel，y\_channel]` 的fsp矩阵。
 
-输出是一批fsp矩阵。
+输出是一个batch的fsp矩阵。
 
 参数：
-    - **x** (Variable): 一个形状为[batch_size, x_channel, height, width]的特征映射
-    - **y** (Variable)：具有形状[batch_size, y_channel, height, width]的特征映射。Y轴通道可以与输入（X）的X轴通道不同，而其他尺寸必须与输入（X）相同。
+    - **x** (Variable): 一个形状为 :math:`[batch\_size, x\_channel, height, width]` 的 4-D 特征图Tensor, 数据类型为float32或float64。
+    - **y** (Variable)：一个形状为 :math:`[batch\_size, y\_channel, height, width]` 的 4-D 特征图Tensor, 数据类型为float32或float64。y_channel可以与输入（x）的x_channel不同，而其他维度必须与输入（x）相同。
 
-返回：形状为[batch_size, x_channel, y_channel]的fsp op的输出。x_channel 是x的通道，y_channel是y的通道。
+返回：一个形状为 :math:`[batch\_size, x\_channel, y\_channel]` 的fsp矩阵, 是一个 3-D Tensor，数据类型与输入数据类型一致。其中，x_channel是输入x的通道数，y_channel是输入y的通道数。数据类型为float32或float64。
 
-返回类型：fsp matrix (Variable)
+返回类型：Variable
 
 **代码示例**
 
@@ -35,8 +35,3 @@ fsp_matrix
                                         filter_size=1)
     loss = fluid.layers.fsp_matrix(feature_map_0, feature_map_1)
 
-
-
-
-
-

doc/fluid/api_cn/layers_cn/polygon_box_transform_cn.rst

@@ -5,18 +5,19 @@ polygon_box_transform
 
 .. py:function:: paddle.fluid.layers.polygon_box_transform(input, name=None)
 
-PolygonBoxTransform 算子。
+**PolygonBoxTransform 算子**
 
-该算子用于将偏移坐标转变为真正的坐标。
+该op用于将偏移坐标改变为真实的坐标。
 
-输入是检测网络的最终几何输出。我们使用 2*n 个数来表示从 polygon_box 中的 n 个顶点(vertice)到像素位置的偏移。由于每个距离偏移包含两个数字 :math:`(x_i, y_i)` ，所以何输出包含 2*n 个通道。
+输入4-D Tensor是检测网络最终的几何输出。我们使用 2*n 个数来表示从 polygon_box 中的 n 个顶点(vertice)到像素位置的偏移。由于每个距离偏移包含两个数 :math:`(x_i, y_i)` ，所以几何输出通道数为 2*n。
 
 参数：
-    - **input** （Variable） - shape 为[batch_size，geometry_channels，height，width]的张量
+    - **input** （Variable） - 形状为 :math:`[batch\_size，geometry\_channels，height，width]` 的4-D Tensor，数据类型为float32或float64。
+    - **name** (str，可选) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，缺省值为None。
 
-返回：与输入 shape 相同
+返回：polygon_box_transform输出的真实坐标，是一个 4-D Tensor。数据类型为float32或float64。
 
-返回类型：output（Variable）
+返回类型：Variable
 
 **代码示例**