Fix conv bn cos_sim cn doc (#1183)

* update conv2d 
conv3d
conv2d_transpose
conv3d_transpose
batch_norm
cos_sim
cross_entropy
npair_loss
dropout
img_conv_group cn doc

doc/fluid/api_cn/layers_cn/batch_norm_cn.rst

@@ -7,14 +7,14 @@ batch_norm
 
 批正则化层（Batch Normalization Layer）
 
-可用作conv2d和全链接操作的正则化函数。该层需要的数据格式如下：
+可用作卷积和全连接操作的批正则化函数，根据当前批次数据按通道计算的均值和方差进行正则化。该层需要的数据格式如下：
 
 1.NHWC[batch,in_height,in_width,in_channels]
 2.NCHW[batch,in_channels,in_height,in_width]
 
 更多详情请参考 : `Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift <https://arxiv.org/pdf/1502.03167.pdf>`_
 
-``input`` 是mini-batch的输入特征。
+``input`` 是mini-batch的输入。
 
 .. math::
     \mu_{\beta}        &\gets \frac{1}{m} \sum_{i=1}^{m} x_i                                 \quad &// mini-batch-mean \\
@@ -22,7 +22,12 @@ batch_norm
     \hat{x_i}          &\gets \frac{x_i - \mu_\beta} {\sqrt{\sigma_{\beta}^{2} + \epsilon}}  \quad &// normalize \\
     y_i &\gets \gamma \hat{x_i} + \beta                                                      \quad &// scale-and-shift
 
-当use_global_stats = True时， :math:`\mu_{\beta}` 和 :math:`\sigma_{\beta}^{2}` 不是一个minibatch的统计数据。 它们是全局（或运行）统计数据。 （它通常来自预先训练好的模型。）训练和测试（或预测）具有相同的行为：
+    moving\_mean = moving\_mean * momentum + mini\_batch\_mean * (1. - momentum)                     \global mean
+    moving\_variance = moving\_variance * momentum + mini\_batch\_var * (1. - momentum)              \global variance
+
+moving_mean和moving_var是训练过程中统计得到的全局均值和方差，在预测或者评估中使用。
+
+当use_global_stats = True时， :math:`\mu_{\beta}` 和 :math:`\sigma_{\beta}^{2}` 不是一个minibatch的统计数据。 它们是全局（或运行）统计数据（moving_mean和moving_variance），通常来自预先训练好的模型。训练和测试（或预测）具有相同的行为：
 
 .. math::
 
@@ -33,42 +38,42 @@ batch_norm
 
 
 参数：
-    - **input** (Variable) - 输入变量的排序，可以为 2, 3, 4, 5。
-    - **act** （string，默认None）- 激活函数类型，linear|relu|prelu|...
-    - **is_test** （bool,默认False） - 指示它是否在测试阶段。
-    - **momentum** （float，默认0.9）- 此值用于计算 moving_mean 和 moving_var。更新公式为:  :math:`moving\_mean = moving\_mean * momentum + new\_mean * (1. - momentum)` ， :math:`moving\_var = moving\_var * momentum + new\_var * (1. - momentum)` ， 默认值0.9。
-    - **epsilon** （float，默认1e-05）- 加在分母上为了数值稳定的值。默认值为1e-5。
-    - **param_attr** （ParamAttr|None） - batch_norm参数范围的属性，如果设为None或者是ParamAttr的一个属性，batch_norm创建ParamAttr为param_attr。如果没有设置param_attr的初始化函数，参数初始化为Xavier。默认：None。
-    - **bias_attr** （ParamAttr|None） - batch_norm bias参数的属性，如果设为None或者是ParamAttr的一个属性，batch_norm创建ParamAttr为bias_attr。如果没有设置bias_attr的初始化函数，参数初始化为0。默认：None。
-    - **data_layout** （string,默认NCHW) - NCHW|NHWC。
-    - **in_place** （bool，默认False）- 得出batch norm可复用记忆的输入和输出。
-    - **name** （string，默认None）- 该层名称（可选）。若设为None，则自动为该层命名。
-    - **moving_mean_name** （string，默认None）- moving_mean的名称，存储全局Mean。如果将其设置为None, ``batch_norm`` 将随机命名全局平均值；否则， ``batch_norm`` 将命名全局平均值为 ``moving_mean_name`` 。
-    - **moving_variance_name** （string，默认None）- moving_variance的名称，存储全局变量。如果将其设置为None, ``batch_norm`` 将随机命名全局方差；否则， ``batch_norm`` 将命名全局方差为 ``moving_variance_name`` 。
+    - **input** (Variable) - batch_norm算子的输入特征，是一个Variable类型，输入维度可以是 2, 3, 4, 5。数据类型：float32和float64。
+    - **act** （string）- 激活函数类型，可以是leaky_realu、relu、prelu等。默认：None。
+    - **is_test** （bool） - 指示它是否在测试阶段，非训练阶段使用训练过程中统计到的全局均值和全局方差。默认：False。
+    - **momentum** （float）- 此值用于计算 moving_mean 和 moving_var。更新公式为:  :math:`moving\_mean = moving\_mean * momentum + new\_mean * (1. - momentum)` ， :math:`moving\_var = moving\_var * momentum + new\_var * (1. - momentum)` ， 默认：0.9。
+    - **epsilon** （float）- 加在分母上为了数值稳定的值。默认：1e-5。
+    - **param_attr** (ParamAttr|None) ：指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。batch_norm算子默认的权重初始化是1.0。
+    - **bias_attr** （ParamAttr|None）- 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。batch_norm算子默认的偏置初始化是0.0。
+    - **data_layout** （string) - 指定输入数据格式，数据格式可以为NCHW或者NHWC。默认：NCHW。
+    - **in_place** （bool）- batch_norm的输出复用输入的tensor，可以节省显存。默认：False。
+    - **name** (str|None) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。
+    - **moving_mean_name** （string）- moving_mean的名称，存储全局均值。如果将其设置为None, ``batch_norm`` 将随机命名全局均值；否则， ``batch_norm`` 将命名全局均值为 ``moving_mean_name`` 。默认：None。
+    - **moving_variance_name** （string）- moving_variance的名称，存储全局变量。如果将其设置为None, ``batch_norm`` 将随机命名全局方差；否则， ``batch_norm`` 将命名全局方差为 ``moving_variance_name`` 。默认：None。
     - **do_model_average_for_mean_and_var** （bool，默认False）- 是否为mean和variance做模型均值。
-    - **fuse_with_relu** （bool）- 如果为True，batch norm后该操作符执行relu。
-    - **use_global_stats** （bool, Default False） – 是否使用全局均值和方差。 在预测或测试模式下，将use_global_stats设置为true或将is_test设置为true，并且行为是等效的。 在训练模式中，当设置use_global_stats为True时，在训练期间也使用全局均值和方差。
+    - **fuse_with_relu** （bool）- 如果为True，batch_norm后该操作符执行relu。默认：False。
+    - **use_global_stats** （bool） – 是否使用全局均值和方差。 在预测或测试模式下，将use_global_stats设置为true或将is_test设置为true，并且行为是等效的。 在训练模式中，当设置use_global_stats为True时，在训练期间也使用全局均值和方差。默认：False。
 
-返回： 张量，在输入中运用批正则后的结果
+返回： 维度和输入相同的Tensor，在输入中运用批正则后的结果。
 
-返回类型：变量（Variable）
+返回类型：Variable
 
 **代码示例**：
 
 .. code-block:: python
-    
+
     import paddle.fluid as fluid
+    import numpy as np
     x = fluid.layers.data(name='x', shape=[3, 7, 3, 7], dtype='float32', append_batch_size=False)
-    hidden1 = fluid.layers.fc(input=x, size=200, param_attr='fc1.w')
-    hidden2 = fluid.layers.batch_norm(input=hidden1)
-
-
-
-
-
-
-
-
-
+    hidden1 = fluid.layers.fc(input=x, size=200)
+    param_attr = fluid.ParamAttr(name='batch_norm_w', initializer=fluid.initializer.Constant(value=1.0))
+    bias_attr = fluid.ParamAttr(name='batch_norm_b', initializer=fluid.initializer.Constant(value=0.0))
+    hidden2 = fluid.layers.batch_norm(input=hidden1, param_attr = param_attr, bias_attr = bias_attr)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    exe.run(fluid.default_startup_program())
+    np_x = np.random.random(size=(3, 7, 3, 7)).astype('float32')
+    output = exe.run(feed={"x": np_x}, fetch_list = [hidden2])
+    print(output)
 
 

doc/fluid/api_cn/layers_cn/conv2d_cn.rst

@@ -5,7 +5,7 @@ conv2d
 
 .. py:function:: paddle.fluid.layers.conv2d(input, num_filters, filter_size, stride=1, padding=0, dilation=1, groups=None, param_attr=None, bias_attr=None, use_cudnn=True, act=None, name=None)
 
-卷积二维层（convolution2D layer）根据输入、滤波器（filter）、步长（stride）、填充（padding）、dilations、一组参数计算输出。输入和输出是NCHW格式，N是批尺寸，C是通道数，H是特征高度，W是特征宽度。滤波器是MCHW格式，M是输出图像通道数，C是输入图像通道数，H是滤波器高度，W是滤波器宽度。如果组数大于1，C等于输入图像通道数除以组数的结果。详情请参考UFLDL's : `卷积 <http://ufldl.stanford.edu/tutorial/supervised/FeatureExtractionUsingConvolution/>`_ 。如果提供了bias属性和激活函数类型，bias会添加到卷积（convolution）的结果中相应的激活函数会作用在最终结果上。
+二维卷积层（convolution2D layer）根据输入、滤波器（filter）、步长（stride）、填充（padding）、膨胀比例（dilations）一组参数计算输出特征层大小。输入和输出是NCHW格式，其中N是批尺寸，C是通道数，H是特征层的高度，W是特征层的宽度。滤波器是MCHW格式，M是输出图像通道数，C是输入图像通道数，H是滤波器高度，W是滤波器宽度。如果组数大于1，C等于输入图像通道数除以组数的结果。详情请参考UFLDL's : `卷积 <http://ufldl.stanford.edu/tutorial/supervised/FeatureExtractionUsingConvolution/>`_ 。如果bias_attr不为False，卷积计算会添加偏置项。如果指定了激活函数类型，相应的激活函数会作用在最终结果上。
 
 对每个输入X，有等式：
 
@@ -14,24 +14,24 @@ conv2d
     Out = \sigma \left ( W * X + b \right )
 
 其中：
-    - :math:`X` ：输入值，NCHW格式的张量（Tensor）
-    - :math:`W` ：滤波器值，MCHW格式的张量（Tensor）
+    - :math:`X` ：输入图像，NCHW格式的张量（Tensor）
+    - :math:`W` ：滤波器，MCHW格式的张量（Tensor）
     - :math:`*` ： 卷积操作
-    - :math:`b` ：Bias值，二维张量（Tensor），shape为 ``[M,1]``
+    - :math:`b` ：偏置值，二维张量（Tensor），shape为 ``[M,1]``
     - :math:`\sigma` ：激活函数
-    - :math:`Out` ：输出值，``Out`` 和 ``X`` 的shape可能不同
+    - :math:`Out` ：输出值， ``Out`` 和 ``X`` 的shape可能不同
 
 **示例**
 
 - 输入：
 
-  输入shape：:math:`( N,C_{in},H_{in},W_{in} )`
+  输入shape：:math:`（N,C_{in},H_{in},W_{in}）`
 
-  滤波器shape： :math:`( C_{out},C_{in},H_{f},W_{f} )`
+  滤波器shape： :math:`（C_{out},C_{in},H_{f},W_{f}）`
 
 - 输出：
 
-  输出shape： :math:`( N,C_{out},H_{out},W_{out} )`
+  输出shape： :math:`（N,C_{out},H_{out},W_{out}）`
 
 其中
 
@@ -42,41 +42,37 @@ conv2d
     W_{out} = \frac{\left ( W_{in}+2*paddings[1]-\left ( dilations[1]*\left ( W_{f}-1 \right )+1 \right ) \right )}{strides[1]}+1
 
 参数：
-    - **input** (Variable) - 格式为[N,C,H,W]格式的输入图像
-    - **num_filters** (int) - 滤波器数。和输出图像通道相同
-    - **filter_size** (int|tuple|None) - 滤波器大小。如果filter_size是一个元组，则必须包含两个整型数，（filter_size_H，filter_size_W）。否则，滤波器为square
-    - **stride** (int|tuple) - 步长(stride)大小。如果步长（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）大小。如果膨胀（dialation）为元组，则必须包含两个整型数，（dilation_H,dilation_W）。否则，dilation_H = dilation_W = dilation。默认：dilation = 1
-    - **groups** (int) - 卷积二维层（Conv2D Layer）的组数。根据Alex Krizhevsky的深度卷积神经网络（CNN）论文中的成组卷积：当group=2，滤波器的前一半仅和输入通道的前一半连接。滤波器的后一半仅和输入通道的后一半连接。默认：groups = 1
-    - **param_attr** (ParamAttr|None) - conv2d的可学习参数/权重的参数属性。如果设为None或者ParamAttr的一个属性，conv2d创建ParamAttr为param_attr。如果param_attr的初始化函数未设置，参数则初始化为 :math:`Normal(0.0,std)` ，并且std为 :math:`\frac{2.0}{filter\_elem\_num}^{0.5}` 。默认为None
-    - **bias_attr** (ParamAttr|bool|None) - conv2d bias的参数属性。如果设为False，则没有bias加到输出。如果设为None或者ParamAttr的一个属性，conv2d创建ParamAttr为bias_attr。如果bias_attr的初始化函数未设置，bias初始化为0.默认为None
-    - **use_cudnn** （bool） - 是否用cudnn核，仅当下载cudnn库才有效。默认：True
-    - **act** (str) - 激活函数类型，如果设为None，则未添加激活函数。默认：None
-    - **name** (str|None) - 该层名称（可选）。若设为None，则自动为该层命名。
-
-返回：张量，存储卷积和非线性激活结果
-
-返回类型：变量（Variable）
-
-抛出异常:
-  - ``ValueError`` - 如果输入shape和filter_size，stride,padding和group不匹配。
+    - **input** (Variable) - 输入，格式为[N,C,H,W]的4-D Tensor。数据类型：float32和float64。
+    - **num_filters** (int) - 滤波器（卷积核）的个数。和输出图像通道相同。
+    - **filter_size** (int|tuple) - 滤波器大小。如果filter_size是一个元组，则必须包含两个整型数，（filter_size_height，filter_size_width）。否则，filter_size_height = filter_size_width = filter_size。
+    - **stride** (int|tuple) - 步长stride大小。滤波器和输入进行卷积计算时滑动的步长。如果步长stride是一个元组，则必须包含两个整型数，（stride_height,stride_width）。否则，stride_height = stride_width = stride。默认：stride = 1。
+    - **padding** (int|tuple) - 填充padding大小，输入的每个特征层四周填充的0的数量，padding_height代表特征层上下两边每一边填充0的数量，padding_width代表特征层左右两边每一边填充0的数量。如果填充padding为元组，则必须包含两个整型数，（padding_height,padding_width)。否则，padding_height = padding_width = padding。默认：padding = 0。
+    - **dilation** (int|tuple) - 膨胀比例dilation大小。空洞卷积时会指该参数，滤波器对输入进行卷积时，感受野里每相邻两个特征点之间的空洞信息，根据`可视化效果图<https://github.com/vdumoulin/conv_arithmetic/blob/master/README.md>`_较好理解。如果膨胀比例dialation为元组，则必须包含两个整型数，（dilation_height,dilation_width）。否则，dilation_height = dilation_width = dilation。默认：dilation = 1。
+    - **groups** (int) - 二维卷积层（conv2d layer）的组数。根据Alex Krizhevsky的深度卷积神经网络（CNN）论文中的成组卷积：当group=2，输入和滤波器分别根据通道数量平均分为两组，第一组滤波器和第一组输入进行卷积计算，第二组滤波器和第二组输入进行卷积计算。默认：groups = 1。
+    - **param_attr** (ParamAttr|None) ：指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。conv2d算子默认的权重初始化是Xavier。
+    - **bias_attr** （ParamAttr|False|None）- 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。conv2d算子默认的偏置初始化是0.0。
+    - **use_cudnn** （bool） - 是否用cudnn核，仅当下载cudnn库才有效。默认：True。
+    - **act** (str|None) - 激活函数类型，如果设为None，则未添加激活函数。默认：None。
+    - **name** (str|None) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。
+
+返回：维度和输入相同的Tensor。如果未指定激活层，则返回卷积计算的结果，如果指定激活层，则返回卷积和激活计算之后的最终结果。
+
+返回类型：Variable
 
 **代码示例**：
 
 .. code-block:: python
 
     import paddle.fluid as fluid
+    import numpy as np
     data = fluid.layers.data(name='data', shape=[3, 32, 32], dtype='float32')
-    conv2d = fluid.layers.conv2d(input=data, num_filters=2, filter_size=3, act="relu")
-
-
-
-
-
-
-
-
-
+    param_attr = fluid.ParamAttr(name='conv2d.weight', initializer=fluid.initializer.Xavier(uniform=False), learning_rate=0.001)
+    res = fluid.layers.conv2d(input=data, num_filters=2, filter_size=3, act="relu", param_attr=param_attr)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    exe.run(fluid.default_startup_program())
+    x = np.random.rand(1, 3, 32, 32).astype("float32")
+    output = exe.run(feed={"data": x}, fetch_list=[res])
+    print(output)
 
 

doc/fluid/api_cn/layers_cn/conv2d_transpose_cn.rst

@@ -5,44 +5,37 @@ conv2d_transpose
 
 .. py:function:: paddle.fluid.layers.conv2d_transpose(input, num_filters, output_size=None, filter_size=None, padding=0, stride=1, dilation=1, groups=None, param_attr=None, bias_attr=None, use_cudnn=True, act=None, name=None)
 
-2-D卷积转置层（Convlution2D transpose layer）
+二维转置卷积层（Convlution2D transpose layer）
 
-该层根据 输入（input）、滤波器（filter）和卷积核膨胀（dilations）、步长（stride）、填充（padding）来计算输出。输入(Input)和输出(Output)为NCHW格式，其中 ``N`` 为batch大小， ``C`` 为通道数（channel），``H`` 为特征高度， ``W`` 为特征宽度。参数(膨胀、步长、填充)分别都包含两个元素。这两个元素分别表示高度和宽度。欲了解卷积转置层细节，请参考下面的说明和 参考文献_ 。如果参数 ``bias_attr`` 和 ``act`` 不为 ``None``，则在卷积的输出中加入偏置，并对最终结果应用相应的激活函数。
+该层根据输入（input）、滤波器（filter）和卷积核膨胀比例（dilations）、步长（stride）、填充（padding）来计算输出特征层大小或者通过output_size指定输出特征层大小。输入(Input)和输出(Output)为NCHW格式，其中N为批尺寸，C为通道数（channel），H为特征层高度，W为特征层宽度。滤波器是MCHW格式，M是输出图像通道数，C是输入图像通道数，H是滤波器高度，W是滤波器宽度。如果组数大于1，C等于输入图像通道数除以组数的结果。转置卷积的计算过程相当于卷积的反向计算。转置卷积又被称为反卷积（但其实并不是真正的反卷积）。欲了解转置卷积层细节，请参考下面的说明和 参考文献_ 。如果参数bias_attr不为False, 转置卷积计算会添加偏置项。如果act不为None，则转置卷积计算之后添加相应的激活函数。
 
 .. _参考文献: https://arxiv.org/pdf/1603.07285.pdf
 
+
 输入 :math:`X` 和输出 :math:`Out` 函数关系如下：
 
 .. math::
                         Out=\sigma (W*X+b)\\
 
 其中：
-    -  :math:`X` : 输入张量，具有 ``NCHW`` 格式
-
-    -  :math:`W` : 滤波器张量，具有 ``NCHW`` 格式
-
-    -  :math:`*` : 卷积操作
-
+    -  :math:`X` : 输入图像，具有NCHW格式的张量（Tensor）
+    -  :math:`W` : 滤波器，具有NCHW格式的张量（Tensor）
+    -  :math:`*` : 卷积计算（注意：转置卷积本质上的计算还是卷积）
     -  :math:`b` : 偏置（bias），二维张量，shape为 ``[M,1]``
-
     -  :math:`σ` : 激活函数
+    -  :math:`Out` : 输出值，Out和 ``X`` 的 ``shape`` 可能不同
 
-    -  :math:`Out` : 输出值，Out和 ``X`` 的 ``shape`` 可能不一样
+**示例**
 
-**样例**：
+- 输入：
 
-输入：
+    输入的shape： :math:`（N，C_{in}， H_{in}， W_{in}）`
 
-.. math::
+    滤波器的shape ： :math:`（C_{in}, C_{out}, H_f, W_f）`
 
-    输入张量的shape :  （N，C_{in}， H_{in}， W_{in})
+- 输出：
 
-    滤波器（filter）shape ： （C_{in}, C_{out}, H_f, W_f)
-
-输出：
-
-.. math::
-    输出张量的 shape ： （N，C_{out}, H_{out}, W_{out})
+    输出的 shape ： :math:`（N，C_{out}, H_{out}, W_{out}）`
 
 其中
 
@@ -54,48 +47,46 @@ conv2d_transpose
         & W_{out}\in[W'_{out},W'_{out} + strides[1])\\
 
 注意：
-如果 ``output_size`` 为None，则 :math:`H_{out}` = :math:`H^\prime_{out}` , :math:`W_{out}` = :math:`W^\prime_{out}` ;
-否则， 输出size的 :math:`H_{out}` 应当介于 :math:`H^\prime_{out}`
-和 :math:`H^\prime_{out} + strides[0]` 之间, 并且输出size的 :math:`W_{out}` 应当介于 :math:`W^\prime_{out}` 和 :math:`W^\prime_{out} + strides[1]` 之间, ``conv2d_transpose`` 可以自动计算kernel大小。
-
-参数:
-  - **input** （Variable）- 输入张量，格式为[N, C, H, W]
-  - **num_filters** (int) - 滤波器（卷积核）的个数，与输出的图片的通道数（ channel ）相同
-  - **output_size** (int|tuple|None) - 输出图片的大小。如果output_size是一个元组（tuple），则该元形式为（image_H,image_W),这两个值必须为整型。如果output_size=None,则内部会使用filter_size、padding和stride来计算output_size。如果output_size和filter_size是同时指定的，那么它们应满足上面的公式。
-  - **filter_size** (int|tuple|None) - 滤波器大小。如果filter_size是一个tuple，则形式为(filter_size_H, filter_size_W)。否则，滤波器将是一个方阵。如果filter_size=None，则内部会计算输出大小。
-  - **padding** (int|tuple) - 填充大小。如果padding是一个元组，它必须包含两个整数(padding_H、padding_W)。否则，padding_H = padding_W = padding。默认:padding = 0。
-  - **stride** (int|tuple) - 步长大小。如果stride是一个元组，那么元组的形式为(stride_H、stride_W)。否则，stride_H = stride_W = stride。默认:stride = 1。
-  - **dilation** (int|元组) - 膨胀(dilation)大小。如果dilation是一个元组，那么元组的形式为(dilation_H, dilation_W)。否则，dilation_H = dilation_W = dilation。默认:dilation= 1。
-  - **groups** (int) - Conv2d转置层的groups个数。从Alex Krizhevsky的CNN Deep论文中的群卷积中受到启发，当group=2时，前半部分滤波器只连接到输入通道的前半部分，而后半部分滤波器只连接到输入通道的后半部分。默认值:group = 1。
-  - **param_attr** (ParamAttr|None) - conv2d_transfer中可学习参数/权重的属性。如果param_attr值为None或ParamAttr的一个属性，conv2d_transfer使用ParamAttrs作为param_attr的值。如果没有设置的param_attr初始化器，那么使用Xavier初始化。默认值:None。
-  - **bias_attr** (ParamAttr|bool|None) - conv2d_tran_bias中的bias属性。如果设置为False，则不会向输出单元添加偏置。如果param_attr值为None或ParamAttr的一个属性，将conv2d_transfer使用ParamAttrs作为，bias_attr。如果没有设置bias_attr的初始化器，bias将初始化为零。默认值:None。
-  - **use_cudnn** (bool) - 是否使用cudnn内核，只有已安装cudnn库时才有效。默认值:True。
-  - **act** (str) -  激活函数类型，如果设置为None，则不使用激活函数。默认值:None。
-  - **name** (str|None) -  该layer的名称(可选)。如果设置为None， 将自动命名该layer。默认值:True。
 
+如果output_size为None，则 :math:`H_{out}` = :math:`H^\prime_{out}` , :math:`W_{out}` = :math:`W^\prime_{out}` ;否则，指定的output_size_height（输出特征层的高） :math:`H_{out}` 应当介于 :math:`H^\prime_{out}` 和 :math:`H^\prime_{out} + strides[0]` 之间（不包含 :math:`H^\prime_{out} + strides[0]` ）, 并且指定的output_size_width（输出特征层的宽） :math:`W_{out}` 应当介于 :math:`W^\prime_{out}` 和 :math:`W^\prime_{out} + strides[1]` 之间（不包含 :math:`W^\prime_{out} + strides[1]` ）。 
 
-返回： 存储卷积转置结果的张量。
+由于转置卷积可以当成是卷积的反向计算，而根据卷积的输入输出计算公式来说，不同大小的输入特征层可能对应着相同大小的输出特征层，所以对应到转置卷积来说，固定大小的输入特征层对应的输出特征层大小并不唯一。
 
-返回类型: 变量（variable）
+如果指定了output_size， ``conv2d_transpose`` 可以自动计算滤波器的大小。
 
-抛出异常:
-    -  ``ValueError`` : 如果输入的shape、filter_size、stride、padding和groups不匹配，抛出ValueError
-
-**代码示例**
+参数:
+  - **input** （Variable）- 输入，格式为[N, C, H, W]的4-D Tensor。数据类型：float32和float64。
+  - **num_filters** (int) - 滤波器（卷积核）的个数，与输出图片的通道数相同。
+  - **output_size** (int|tuple|None) - 输出图片的大小。如果output_size是一个元组，则必须包含两个整型数，（output_size_height，output_size_width）。如果output_size=None，则内部会使用filter_size、padding和stride来计算output_size。如果output_size和filter_size是同时指定的，那么它们应满足上面的公式。默认：None。output_size和filter_size不能同时为None。
+  - **filter_size** (int|tuple|None) - 滤波器大小。如果filter_size是一个元组，则必须包含两个整型数，（filter_size_height, filter_size_width）。否则，filter_size_height = filter_size_width = filter_size。如果filter_size=None，则必须指定output_size， ``conv2d_transpose`` 内部会根据output_size、padding和stride计算出滤波器大小。默认：None。output_size和filter_size不能同时为None。
+  - **padding** (int|tuple) - 填充padding大小。padding参数在输入特征层每边添加 ``dilation * (kernel_size - 1) - padding`` 个0。如果padding是一个元组，它必须包含两个整数(padding_height，padding_width)。否则，padding_height = padding_width = padding。默认：padding = 0。
+  - **stride** (int|tuple，可选) - 步长stride大小。滤波器和输入进行卷积计算时滑动的步长。如果stride是一个元组，则必须包含两个整型数，形式为(stride_height，stride_width)。否则，stride_height = stride_width = stride。默认：stride = 1。
+  - **dilation** (int|tuple) - 膨胀比例(dilation)大小。空洞卷积时会指该参数，滤波器对输入进行卷积时，感受野里每相邻两个特征点之间的空洞信息，根据 `可视化效果图 <https://github.com/vdumoulin/conv_arithmetic/blob/master/README.md>`_ 较好理解。如果膨胀比例dilation是一个元组，那么元组必须包含两个整型数，形式为(dilation_height, dilation_width)。否则，dilation_height = dilation_width = dilation。默认：dilation= 1。
+  - **groups** (int) - 二维转置卷积层的组数。从Alex Krizhevsky的CNN Deep论文中的群卷积中受到启发，当group=2时，输入和滤波器分别根据通道数量平均分为两组，第一组滤波器和第一组输入进行卷积计算，第二组滤波器和第二组输入进行卷积计算。默认：group = 1。
+  - **param_attr** (ParamAttr|None) ：指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。conv2d_transpose算子默认的权重初始化是Xavier。
+  - **bias_attr** （ParamAttr|False|None）- 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。conv2d_transpose算子默认的偏置初始化是0.0。
+  - **use_cudnn** (bool) - 是否使用cudnn内核，只有已安装cudnn库时才有效。默认：True。
+  - **act** (str) -  激活函数类型，如果设置为None，则不使用激活函数。默认：None。
+  - **name** (str|None) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。
+
+返回：维度和输入相同的Tensor。如果未指定激活层，则返回转置卷积计算的结果，如果指定激活层，则返回转置卷积和激活计算之后的最终结果。
+
+返回类型：Variable
+
+**代码示例**：
 
 ..  code-block:: python
 
     import paddle.fluid as fluid
+    import numpy as np
     data = fluid.layers.data(name='data', shape=[3, 32, 32], dtype='float32')
-    conv2d_transpose = fluid.layers.conv2d_transpose(input=data, num_filters=2, filter_size=3)
-
-
-
-
-
-
-
-
-
+    param_attr = fluid.ParamAttr(name='conv2d.weight', initializer=fluid.initializer.Xavier(uniform=False), learning_rate=0.001)
+    res = fluid.layers.conv2d_transpose(input=data, output_size=66, num_filters=2, filter_size=3, act="relu", param_attr=param_attr)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    exe.run(fluid.default_startup_program())
+    x = np.random.rand(1, 3, 32, 32).astype("float32")
+    output = exe.run(feed={"data": x}, fetch_list=[res])
+    print(output)
 
 

doc/fluid/api_cn/layers_cn/conv3d_cn.rst

@@ -5,7 +5,7 @@ conv3d
 
 .. py:function:: paddle.fluid.layers.conv3d(input, num_filters, filter_size, stride=1, padding=0, dilation=1, groups=None, param_attr=None, bias_attr=None, use_cudnn=True, act=None, name=None)
 
-3D卷积层（convolution3D layer）根据输入、滤波器（filter）、步长（stride）、填充（padding）、膨胀（dilations）、组数参数计算得到输出。输入和输出是NCHW格式，N是批尺寸，C是通道数，H是特征高度，W是特征宽度。卷积三维（Convlution3D）和卷积二维（Convlution2D）相似，但多了一维深度（depth）。如果提供了bias属性和激活函数类型，bias会添加到卷积（convolution）的结果中相应的激活函数会作用在最终结果上。
+三维卷积层（convolution3D layer）根据输入、滤波器（filter）、步长（stride）、填充（padding）、膨胀比例（dilations），一组参数计算得到输出特征层大小。输入和输出是NCDHW格式，N是批尺寸，C是通道数，D是特征层深度，H是特征层高度，W是特征层宽度。3D卷积（Convlution3D）和2D卷积（Convlution2D）相似，但多了一维深度信息（depth）。如果bias_attr不为False，卷积（convolution）计算会添加偏置项。如果指定了激活函数类型，相应的激活函数会作用在最终结果上。
 
 对每个输入X，有等式：
 
@@ -25,11 +25,14 @@ conv3d
 **示例**
 
 - 输入：
-    输入shape： :math:`(N, C_{in}, D_{in}, H_{in}, W_{in})`
 
-    滤波器shape： :math:`(C_{out}, C_{in}, D_f, H_f, W_f)`
+  输入shape： :math:`(N, C_{in}, D_{in}, H_{in}, W_{in})`
+
+  滤波器shape： :math:`(C_{out}, C_{in}, D_f, H_f, W_f)`
+
 - 输出：
-    输出shape： :math:`(N, C_{out}, D_{out}, H_{out}, W_{out})`
+
+  输出shape： :math:`(N, C_{out}, D_{out}, H_{out}, W_{out})`
 
 其中
 
@@ -41,39 +44,37 @@ conv3d
     W_{out}&= \frac{(W_{in} + 2 * paddings[2] - (dilations[2] * (W_f - 1) + 1))}{strides[2]} + 1
 
 参数：
-    - **input** (Variable) - 格式为[N,C,D,H,W]格式的输入图像
-    - **num_fliters** (int) - 滤波器数。和输出图像通道相同
-    - **filter_size** (int|tuple|None) - 滤波器大小。如果filter_size是一个元组，则必须包含三个整型数，(filter_size_D, filter_size_H, filter_size_W)。否则，滤波器为棱长为int的立方体形。
-    - **stride** (int|tuple) - 步长(stride)大小。如果步长（stride）为元组，则必须包含三个整型数， (stride_D, stride_H, stride_W)。否则，stride_D = stride_H = stride_W = stride。默认：stride = 1
-    - **padding** (int|tuple) - 填充（padding）大小。如果填充（padding）为元组，则必须包含三个整型数，(padding_D, padding_H, padding_W)。否则， padding_D = padding_H = padding_W = padding。默认：padding = 0
-    - **dilation** (int|tuple) - 膨胀（dilation）大小。如果膨胀（dialation）为元组，则必须包含两个整型数， (dilation_D, dilation_H, dilation_W)。否则，dilation_D = dilation_H = dilation_W = dilation。默认：dilation = 1
-    - **groups** (int) - 卷积三维层（Conv3D Layer）的组数。根据Alex Krizhevsky的深度卷积神经网络（CNN）论文中的成组卷积：当group=2，滤波器的前一半仅和输入通道的前一半连接。滤波器的后一半仅和输入通道的后一半连接。默认：groups = 1
-    - **param_attr** (ParamAttr|None) - Conv3D的可学习参数/权重的参数属性。如果设为None或者ParamAttr的一个属性，Conv3D创建ParamAttr为param_attr。如果param_attr的初始化函数未设置，参数则初始化为 :math:`Normal(0.0,std)`，并且std为 :math:`\left ( \frac{2.0}{filter\_elem\_num} \right )^{0.5}` 。默认为None
-    - **bias_attr** (ParamAttr|bool|None) - Conv3D bias的参数属性。如果设为False，则没有bias加到输出。如果设为None或者ParamAttr的一个属性，Conv3D创建ParamAttr为bias_attr。如果bias_attr的初始化函数未设置，bias初始化为0.默认为None
-    - **use_cudnn** （bool） - 是否用cudnn核，仅当下载cudnn库才有效。默认：True
-    - **act** (str) - 激活函数类型，如果设为None，则未添加激活函数。默认：None
-    - **name** (str|None) - 该层名称（可选）。若设为None，则自动为该层命名。
-
-返回：张量，存储卷积和非线性激活结果
-
-返回类型：变量（Variable）
-
-抛出异常：
-  - ``ValueError`` - 如果 ``input`` 的形和 ``filter_size`` ， ``stride`` , ``padding`` 和 ``group`` 不匹配。
+    - **input** (Variable) - 输入，格式为[N,C,D,H,W]格式的5-D Tensor。数据类型：float32和float64。
+    - **num_fliters** (int) - 滤波器（卷积核）的个数。和输出图像通道相同。
+    - **filter_size** (int|tuple) - 滤波器大小。如果filter_size是一个元组，则必须包含三个整型数，(filter_size_depth, filter_size_height, filter_size_width)。如果filter_size是一个int型，则filter_size_depth = filter_size_height = filter_size_width = filter_size。
+    - **stride** (int|tuple) - 步长(stride)大小。滤波器和输入进行卷积计算时滑动的步长。如果步长（stride）为元组，则必须包含三个整型数， (stride_depth, stride_height, stride_width)。否则，stride_depth = stride_height = stride_width = stride。默认：stride = 1。
+    - **padding** (int|tuple) - 填充（padding）大小。padding参数在输入特征层每边添加padding个0。如果填充（padding）为元组，则必须包含三个整型数，(padding_depth, padding_height, padding_width)。否则， padding_depth = padding_height = padding_width = padding。默认：padding = 0。
+    - **dilation** (int|tuple) - 膨胀比例（dilation）大小。空洞卷积时会指该参数，滤波器对输入进行卷积时，感受野里每相邻两个特征点之间的空洞信息，根据`可视化效果图<https://github.com/vdumoulin/conv_arithmetic/blob/master/README.md>`_较好理解。如果膨胀比例（dialation）为元组，则必须包含三个整型数， (dilation_depth, dilation_height, dilation_width)。否则，dilation_depth = dilation_height = dilation_width = dilation。默认：dilation = 1。
+    - **groups** (int) - 三维卷积层（conv3d layer）的组数。根据Alex Krizhevsky的深度卷积神经网络（CNN）论文中的成组卷积：当group=2，输入和滤波器分别根据通道数量平均分为两组，第一组滤波器和第一组输入进行卷积计算，第二组滤波器和第二组输入进行卷积计算。默认：groups = 1。
+    - **param_attr** (ParamAttr|None) ：指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。conv3d算子默认的权重初始化是Xavier。
+    - **bias_attr** （ParamAttr|False|None）- 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。conv3d算子默认的偏置初始化是0.0。
+    - **use_cudnn** （bool） - 是否用cudnn核，仅当下载cudnn库才有效。默认：True。
+    - **act** (str) - 激活函数类型，如果设为None，则未添加激活函数。默认：None。
+    - **name** (str|None) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。
+
+返回：维度和输入相同的Tensor。如果未指定激活层，则返回卷积计算的结果，如果指定激活层，则返回卷积和激活计算之后的最终结果。
+
+返回类型：Variable
 
 **代码示例**：
 
 .. code-block:: python
 
     import paddle.fluid as fluid
+    import numpy as np
     data = fluid.layers.data(name='data', shape=[3, 12, 32, 32], dtype='float32')
-    conv3d = fluid.layers.conv3d(input=data, num_filters=2, filter_size=3, act="relu")
-
-
-
-
-
-
-
+    param_attr = fluid.ParamAttr(name='conv3d.weight', initializer=fluid.initializer.Xavier(uniform=False), learning_rate=0.001)
+    res = fluid.layers.conv3d(input=data, num_filters=2, filter_size=3, act="relu", param_attr=param_attr)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    exe.run(fluid.default_startup_program())
+    x = np.random.rand(1, 3, 12, 32, 32).astype("float32")
+    output = exe.run(feed={"data": x}, fetch_list=[res])
+    print(output)
 
 

doc/fluid/api_cn/layers_cn/conv3d_transpose_cn.rst

@@ -5,102 +5,90 @@ conv3d_transpose
 
 .. py:function:: paddle.fluid.layers.conv3d_transpose(input, num_filters, output_size=None, filter_size=None, padding=0, stride=1, dilation=1, groups=None, param_attr=None, bias_attr=None, use_cudnn=True, act=None, name=None)
 
-3-D卷积转置层（Convlution3D transpose layer)
+三维转置卷积层（Convlution3D transpose layer)
 
-该层根据 输入（input）、滤波器（filter）和卷积核膨胀（dilations）、步长（stride）、填充来计算输出。输入(Input)和输出(Output)为NCDHW格式。其中 ``N`` 为batch大小， ``C`` 为通道数（channel）, ``D``  为特征深度, ``H`` 为特征高度， ``W`` 为特征宽度。参数(膨胀、步长、填充)分别包含两个元素。这两个元素分别表示高度和宽度。欲了解卷积转置层细节，请参考下面的说明和 参考文献_ 。如果参数 ``bias_attr`` 和 ``act`` 不为None，则在卷积的输出中加入偏置，并对最终结果应用相应的激活函数
+该层根据输入（input）、滤波器（filter）和卷积核膨胀比例（dilations）、步长（stride）、填充（padding）来计算输出特征层大小或者通过output_size指定输出特征层大小。输入(Input)和输出(Output)为NCDHW格式。其中N为批尺寸，C为通道数（channel），D为特征深度，H为特征层高度，W为特征层宽度。转置卷积的计算过程相当于卷积的反向计算。转置卷积又被称为反卷积（但其实并不是真正的反卷积）。欲了解卷积转置层细节，请参考下面的说明和 参考文献_ 。如果参数bias_attr不为False, 转置卷积计算会添加偏置项。如果act不为None，则转置卷积计算之后添加相应的激活函数。
 
 .. _参考文献: http://www.matthewzeiler.com/wp-content/uploads/2017/07/cvpr2010.pdf
 
-输入X和输出Out函数关系X，有等式如下：
+输入 :math:`X` 和输出 :math:`Out` 函数关系如下：
 
 .. math::
                         \\Out=\sigma (W*X+b)\\
 
 其中：
-    -  :math:`X` : 输入张量，具有 ``NCDHW`` 格式
-
-    -  :math:`W` : 滤波器张量，，具有 ``NCDHW`` 格式
-
-    -  :math:`*` : 卷积操作
-
+    -  :math:`X` : 输入图像，具有NCDHW格式的张量（Tensor）
+    -  :math:`W` : 滤波器，具有NCDHW格式的张量（Tensor）
+    -  :math:`*` : 卷积操作（注意：转置卷积本质上的计算还是卷积）
     -  :math:`b` : 偏置（bias），二维张量，shape为 ``[M,1]``
-
     -  :math:`σ` : 激活函数
-
     -  :math:`Out` : 输出值， ``Out`` 和 ``X`` 的 shape可能不一样
 
-
-**样例**
+**示例**
 
 输入:
 
-.. math::
-
-    Input shape: (N,C_{in},D_{in},H_{in},W_{in})
+    输入的shape：:math:`（N,C_{in}, D_{in}, H_{in}, W_{in}）`
 
-    Filter shape: (C_{in},C_{out},D_f,H_f,W_f)
+    滤波器的shape：:math:`（C_{in}, C_{out}, D_f, H_f, W_f）`
 
 
 
 输出:
 
-.. math::
-
-    Output shape: (N,C_{out},D_{out},H_{out},W_{out})
+    输出的shape：:math:`（N,C_{out}, D_{out}, H_{out}, W_{out}）`
 
 
 其中：
 
 .. math::
 
+    D'_{out}=(D_{in}-1)*strides[0]-2*paddings[0]+dilations[0]*(D_f-1)+1
+    H'_{out}=(H_{in}-1)*strides[1]-2*paddings[1]+dilations[1]*(H_f-1)+1
+    W'_{out}=(W_{in}-1)*strides[2]-2*paddings[2]+dilations[2]*(W_f-1)+1
+    D_{out}\in[D'_{out},D'_{out} + strides[0])
+    H_{out}\in[H'_{out},H'_{out} + strides[1])
+    W_{out}\in[W'_{out},W'_{out} + strides[2])
 
+注意：
 
-    D_{out}=(D_{in}-1)*strides[0]-2*paddings[0]+dilations[0]*(D_f-1)+1
-
-    H_{out}=(H_{in}-1)*strides[1]-2*paddings[1]+dilations[1]*(H_f-1)+1
-
-    W_{out}=(W_{in}-1)*strides[2]-2*paddings[2]+dilations[2]*(W_f-1)+1
+如果output_size为None，则:math:`D_{out}` = :math:`D^\prime_{out}` , :math:`H_{out}` = :math:`H^\prime_{out}` , :math:`W_{out}` = :math:`W^\prime_{out}` ;否则，指定的output_size_depth（输出特征层的深度） :math:`D_{out}` 应当介于 :math:`D^\prime_{out}` 和 :math:`D^\prime_{out} + strides[0]` 之间（不包含 :math:`D^\prime_{out} + strides[0]` ），指定的output_size_height（输出特征层的高） :math:`H_{out}` 应当介于 :math:`H^\prime_{out}` 和 :math:`H^\prime_{out} + strides[1]` 之间（不包含 :math:`H^\prime_{out} + strides[1]` ）, 并且指定的output_size_width（输出特征层的宽） :math:`W_{out}` 应当介于 :math:`W^\prime_{out}` 和 :math:`W^\prime_{out} + strides[2]` 之间（不包含 :math:`W^\prime_{out} + strides[2]` ）。 
 
+由于转置卷积可以当成是卷积的反向计算，而根据卷积的输入输出计算公式来说，不同大小的输入特征层可能对应着相同大小的输出特征层，所以对应到转置卷积来说，固定大小的输入特征层对应的输出特征层大小并不唯一。
 
+如果指定了output_size， ``conv3d_transpose`` 可以自动计算滤波器的大小。
 
 参数:
-  - **input** （Variable）- 输入张量，格式为[N, C, D, H, W]
-  - **num_filters** (int) - 滤波器（卷积核）的个数，与输出的图片的通道数（channel）相同
-  - **output_size** (int|tuple|None) - 输出图片的大小。如果 ``output_size`` 是一个元组（tuple），则该元形式为（image_H,image_W),这两个值必须为整型。如果 ``output_size=None`` ,则内部会使用filter_size、padding和stride来计算output_size。如果 ``output_size`` 和 ``filter_size`` 是同时指定的，那么它们应满足上面的公式。
-  - **filter_size** (int|tuple|None) - 滤波器大小。如果 ``filter_size`` 是一个tuple，则形式为(filter_size_H, filter_size_W)。否则，滤波器将是一个方阵。如果 ``filter_size=None`` ，则内部会计算输出大小。
-  - **padding** (int|tuple) - 填充大小。如果 ``padding`` 是一个元组，它必须包含两个整数(padding_H、padding_W)。否则，padding_H = padding_W = padding。默认:padding = 0。
-  - **stride** (int|tuple) - 步长大小。如果 ``stride`` 是一个元组，那么元组的形式为(stride_H、stride_W)。否则，stride_H = stride_W = stride。默认:stride = 1。
-  - **dilation** (int|元组) - 膨胀大小。如果 ``dilation`` 是一个元组，那么元组的形式为(dilation_H, dilation_W)。否则，dilation_H = dilation_W = dilation_W。默认:dilation= 1。
-  - **groups** (int) - Conv3D转置层的groups个数。从Alex Krizhevsky的CNN Deep论文中的群卷积中受到启发，当group=2时，前半部分滤波器只连接到输入通道的前半部分，而后半部分滤波器只连接到输入通道的后半部分。默认值:group = 1。
-  - **param_attr** (ParamAttr|None) - conv3d_transpose中可学习参数/权重的属性。如果param_attr值为None或ParamAttr的一个属性，conv3d_transpose使用ParamAttrs作为param_attr的值。如果没有设置的param_attr初始化器，那么使用Xavier初始化。默认值:None。
-  - **bias_attr** (ParamAttr|bool|None) - conv3d_transpose中的bias属性。如果设置为False，则不会向输出单元添加偏置。如果param_attr值为None或ParamAttr的一个属性，将conv3d_transpose使用ParamAttrs作为bias_attr。如果没有设置bias_attr的初始化器，bias将初始化为零。默认值:None。
-  - **use_cudnn** (bool) - 是否使用cudnn内核，只有已安装cudnn库时才有效。默认值:True。
-  - **act** (str) -  激活函数类型，如果设置为None，则不使用激活函数。默认值:None。
-  - **name** (str|None) - 该layer的名称(可选)。如果设置为None， 将自动命名该layer。默认值:True。
-
-
-返回： 存储卷积转置结果的张量。
-
-返回类型: 变量（variable）
-
-抛出异常:
-    -  ``ValueError``  : 如果输入的shape、filter_size、stride、padding和groups不匹配，抛出ValueError
-
-
-**代码示例**
+  - **input** （Variable）- 输入，格式为[N, C, D, H, W]的5-D Tensor。数据类型：float32和float64。
+  - **num_filters** (int) - 滤波器（卷积核）的个数，与输出的图片的通道数相同。
+  - **output_size** (int|tuple|None) - 输出图片的大小。如果output_size是一个元组，则必须包含三个整型数，（output_size_depth，output_size_height，output_size_width）。如果output_size=None，则内部会使用filter_size、padding和stride来计算output_size。如果output_size和filter_size是同时指定的，那么它们应满足上面的公式。默认：None。output_size和filter_size不能同时为None。
+  - **filter_size** (int|tuple|None) - 滤波器大小。如果filter_size是一个元组，则必须包含三个整型数，（filter_size_depth，filter_size_height, filter_size_width）。否则，filter_size_depth = filter_size_height = filter_size_width = filter_size。如果filter_size=None，则必须指定output_size， ``conv2d_transpose`` 内部会根据output_size、padding和stride计算出滤波器大小。默认：None。output_size和filter_size不能同时为None。
+  - **padding** (int|tuple) - 填充padding大小。padding参数在输入特征层每边添加 ``dilation * (kernel_size - 1) - padding`` 个0。如果padding是一个元组，它必须包含三个整数(padding_depth，padding_height，padding_width)。否则，padding_depth = padding_height = padding_width = padding。默认：padding = 0。
+  - **stride** (int|tuple) - 步长stride大小。滤波器和输入进行卷积计算时滑动的步长。如果stride是一个元组，那么元组的形式为(stride_depth，stride_height，stride_width)。否则，stride_depth = stride_height = stride_width = stride。默认：stride = 1。
+  - **dilation** (int|tuple) - 膨胀比例dilation大小。空洞卷积时会指该参数，滤波器对输入进行卷积时，感受野里每相邻两个特征点之间的空洞信息，根据 `可视化效果图 <https://github.com/vdumoulin/conv_arithmetic/blob/master/README.md>`_ 较好理解。如果膨胀比例dilation是一个元组，那么元组的形式为(dilation_depth，dilation_height， dilation_width)。否则，dilation_depth = dilation_height = dilation_width = dilation。默认:dilation= 1。
+  - **groups** (int) - 三维转置卷积层的组数。从Alex Krizhevsky的CNN Deep论文中的群卷积中受到启发，当group=2时，输入和滤波器分别根据通道数量平均分为两组，第一组滤波器和第一组输入进行卷积计算，第二组滤波器和第二组输入进行卷积计算。默认：group = 1。
+  - **param_attr** (ParamAttr|None) ：指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。conv3d_transpose算子默认的权重初始化是Xavier。
+  - **bias_attr** （ParamAttr|False|None）- 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。conv3d_transpose算子默认的偏置初始化是0.0。
+  - **use_cudnn** (bool) - 是否使用cudnn内核，只有已安装cudnn库时才有效。默认：True。
+  - **act** (str) -  激活函数类型，如果设置为None，则不使用激活函数。默认：None。
+  - **name** (str|None) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。
+
+返回：维度和输入相同的Tensor。如果未指定激活层，则返回转置卷积计算的结果，如果指定激活层，则返回转置卷积和激活计算之后的最终结果。
+
+返回类型：Variable
+
+**代码示例**：
 
 ..  code-block:: python
 
     import paddle.fluid as fluid
+    import numpy as np
     data = fluid.layers.data(name='data', shape=[3, 12, 32, 32], dtype='float32')
-    conv3d_transpose = fluid.layers.conv3d_transpose(input=data, num_filters=2, filter_size=3)
-
-
-
-
-
-
-
-
-
-
+    param_attr = fluid.ParamAttr(name='conv3d.weight', initializer=fluid.initializer.Xavier(uniform=False), learning_rate=0.001)
+    res = fluid.layers.conv3d_transpose(input=data, output_size=(14, 66, 66), num_filters=2, filter_size=3, act="relu", param_attr=param_attr)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    exe.run(fluid.default_startup_program())
+    x = np.random.rand(1, 3, 12, 32, 32).astype("float32")
+    output = exe.run(feed={"data": x}, fetch_list=[res])
+    print(output)

doc/fluid/api_cn/layers_cn/cos_sim_cn.rst

@@ -11,28 +11,34 @@ cos_sim
 
         Out = \frac{X^{T}*Y}{\sqrt{X^{T}*X}*\sqrt{Y^{T}*Y}}
 
-输入X和Y必须具有相同的shape，除非输入Y的第一维为1(不同于输入X)，在计算它们的余弦相似度之前，Y的第一维会被broadcasted，以匹配输入X的shape。
+输入X和Y必须具有相同的shape。但是有一个例外：如果输入Y的第一维为1(不同于输入X的第一维度)，在计算它们的余弦相似度之前，Y的第一维度会自动进行广播(broadcast)，以便于匹配输入X的shape。
 
-输入X和Y都携带或者都不携带LoD(Level of Detail)信息。但输出仅采用输入X的LoD信息。
+输入X和Y可以都携带或者都不携带LoD(Level of Detail)信息。但输出和输入X的LoD信息保持一致。
 
 参数：
-    - **X** (Variable) - cos_sim操作函数的一个输入
-    - **Y** (Variable) - cos_sim操作函数的第二个输入
+    - **X** (Variable) - cos_sim操作函数的第一个输入，维度为 ``[N_1, N_2, ..., N_k]`` 的多维Tensor, 维度不能小于2。数据类型：float32。
+    - **Y** (Variable) - cos_sim操作函数的第二个输入，维度为 ``[N_1 或者 1, N_2, ..., N_k]`` 的多维Tensor。数据类型：float32。
 
-返回：cosine(X,Y)的输出
+返回：LoDTensor。输出两个输入的余弦相似度。
 
-返回类型：变量（Variable)
+返回类型：Variable
 
-**代码示例**
+**代码示例**：
 
 ..  code-block:: python
 
-     import paddle.fluid as fluid
-     x = fluid.layers.data(name='x', shape=[3, 7], dtype='float32', append_batch_size=False)
-     y = fluid.layers.data(name='y', shape=[1, 7], dtype='float32', append_batch_size=False)
-     out = fluid.layers.cos_sim(x, y)
-
-
+    import paddle.fluid as fluid
+    import numpy as np
+    x = fluid.layers.data(name='x', shape=[3, 7], dtype='float32', append_batch_size=False)
+    y = fluid.layers.data(name='y', shape=[1, 7], dtype='float32', append_batch_size=False)
+    out = fluid.layers.cos_sim(x, y)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    exe.run(fluid.default_startup_program())
+    np_x = np.random.random(size=(3, 7)).astype('float32')
+    np_y = np.random.random(size=(1, 7)).astype('float32')
+    output = exe.run(feed={"x": np_x, "y": np_y}, fetch_list = [out])
+    print(output)
 
 
 

doc/fluid/api_cn/layers_cn/dropout_cn.rst

@@ -7,19 +7,17 @@ dropout
 
 dropout操作
 
-丢弃或者保持x的每个元素独立。Dropout是一种正则化技术，通过在训练过程中阻止神经元节点间的联合适应性来减少过拟合。根据给定的丢弃概率dropout操作符随机将一些神经元输出设置为0，其他的仍保持不变。
+丢弃或者保持x的每个元素独立。Dropout是一种正则化手段，通过在训练过程中阻止神经元节点间的相关性来减少过拟合。根据给定的丢弃概率，dropout操作符按丢弃概率随机将一些神经元输出设置为0，其他的仍保持不变。
 
 dropout op可以从Program中删除，提高执行效率。
 
 参数：
-    - **x** (Variable)-输入张量
-    - **dropout_prob** (float)-设置为0的单元的概率
-    - **is_test** (bool)-显示是否进行测试用语的标记
-    - **seed** (int)-Python整型，用于创建随机种子。如果该参数设为None，则使用随机种子。注：如果给定一个整型种子，始终丢弃相同的输出单元。训练过程中勿用固定不变的种子。
-    - **name** (str|None)-该层名称（可选）。如果设置为None,则自动为该层命名
-    - **dropout_implementation** (string) -
-
-      [‘downgrade_in_infer’(default)|’upscale_in_train’] 其中:
+    - **x** (Variable) - 输入，多维Tensor。数据类型：float32和float64。
+    - **dropout_prob** (float32) - 输入单元的丢弃概率，即输入单元设置为0的概率。默认：0.5。
+    - **is_test** (bool) - 标记是否是测试阶段。默认：False。
+    - **seed** (int) - 整型数据，用于创建随机种子。如果该参数设为None，则使用随机种子。注：如果给定一个整型种子，始终丢弃相同的输出单元。训练过程中勿用固定不变的种子。
+    - **name** (str|None) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值为None。
+    - **dropout_implementation** (str) - 丢弃单元的方式，有两种'downgrade_in_infer'和'upscale_in_train'两种选择，默认：'downgrade_in_infer'。具体作用可以参考一下描述。
 
       1. downgrade_in_infer(default), 在预测时减小输出结果
 
@@ -37,25 +35,24 @@ dropout op可以从Program中删除，提高执行效率。
 
          (mask是一个张量，维度和输入维度相同，值为0或1，值为0的比例即为 ``dropout_prob`` ）
 
-dropout操作符可以从程序中移除，程序变得高效。
+dropout操作符可以从程序中移除，使程序变得高效。
 
-返回：与输入X，shape相同的张量
+返回：Tensor。经过丢弃部分数据之后的结果，与输入X形状相同的张量。
 
-返回类型：变量
+返回类型：Variable
 
 **代码示例**：
 
 .. code-block:: python
 
     import paddle.fluid as fluid
-    x = fluid.layers.data(name="data", shape=[32, 32], dtype="float32")
+    import numpy as np
+    x = fluid.layers.data(name="x", shape=[32, 32], dtype="float32")
     droped = fluid.layers.dropout(x, dropout_prob=0.5)
-
-
-
-
-
-
-
-
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    exe.run(fluid.default_startup_program())
+    np_x = np.random.random(size=(32, 32)).astype('float32')
+    output = exe.run(feed={"x": np_x}, fetch_list = [droped])
+    print(output)
 

doc/fluid/api_cn/layers_cn/npair_loss_cn.rst

@@ -9,23 +9,24 @@ npair_loss
 
 参考阅读 `Improved Deep Metric Learning with Multi class N pair Loss Objective <http://www.nec-labs.com/uploads/images/Department-Images/MediaAnalytics/papers/nips16_npairmetriclearning.pdf>`_
 
-NPair损失需要成对的数据。NPair损失分为两部分：第一部分是嵌入向量上的L2正则化器；第二部分是以anchor的相似矩阵和正的相似矩阵为逻辑的交叉熵损失。
+NPair损失需要成对的数据。NPair损失分为两部分：第一部分是对嵌入向量进行L2正则化；第二部分是每一对数据的相似性矩阵的每一行和映射到ont-hot之后的标签的交叉熵损失的和。
 
 参数:
-    - **anchor** (Variable) -  嵌入锚定图像的向量。尺寸=[batch_size, embedding_dims]
-    - **positive** (Variable) -  嵌入正图像的向量。尺寸=[batch_size, embedding_dims]
-    - **labels** (Variable) - 1维张量，尺寸=[batch_size]
-    - **l2_reg** (float32) - 嵌入向量的L2正则化项，默认值：0.002
+    - **anchor** (Variable) -  锚点图像的嵌入Tensor，形状为[batch_size, embedding_dims]的2-D Tensor。数据类型：float32和float64。
+    - **positive** (Variable) -  正例图像的嵌入Tensor，形状为[batch_size, embedding_dims]的2-D Tensor。数据类型：float32和float64。
+    - **labels** (Variable) - 标签向量，形状为[batch_size]的1-DTensor。数据类型：float32、float64和int64。
+    - **l2_reg** (float) - 嵌入向量的L2正则化系数，默认：0.002。
 
-返回： npair loss，尺寸=[1]
+返回： Tensor。经过npair loss计算之后的结果，是一个值。
 
-返回类型：npair loss(Variable)
+返回类型：Variable
 
 **代码示例**：
 
 .. code-block:: python
 
     import paddle.fluid as fluid
+    import numpy as np
     anchor = fluid.layers.data(
               name = 'anchor', shape = [18, 6], dtype = 'float32', append_batch_size=False)
     positive = fluid.layers.data(
@@ -33,7 +34,15 @@ NPair损失需要成对的数据。NPair损失分为两部分：第一部分是
     labels = fluid.layers.data(
               name = 'labels', shape = [18], dtype = 'float32', append_batch_size=False)
 
-    npair_loss = fluid.layers.npair_loss(anchor, positive, labels, l2_reg = 0.002)
+    res = fluid.layers.npair_loss(anchor, positive, labels, l2_reg = 0.002)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    exe.run(fluid.default_startup_program())
+    a = np.random.rand(18, 6).astype("float32")
+    p = np.random.rand(18, 6).astype("float32")
+    l = np.random.rand(18).astype("float32")
+    output = exe.run(feed={"anchor": a, "positive": p, "labels": l}, fetch_list=[res])
+    print(output)
 
 
 

doc/fluid/api_cn/nets_cn/img_conv_group_cn.rst

@@ -5,39 +5,46 @@ img_conv_group
 
 .. py:function:: paddle.fluid.nets.img_conv_group(input, conv_num_filter, pool_size, conv_padding=1, conv_filter_size=3, conv_act=None, param_attr=None, conv_with_batchnorm=False, conv_batchnorm_drop_rate=0.0, pool_stride=1, pool_type='max', use_cudnn=True)
 
-Image Convolution Group由Convolution2d，BatchNorm，DropOut和Pool2d组成。根据输入参数，img_conv_group将使用Convolution2d，BatchNorm，DropOut对Input进行连续计算，并将最后一个结果传递给Pool2d。
+Image Convolution Group由Convolution2d，BatchNorm，DropOut和Pool2d组成。根据输入参数，img_conv_group将使用Convolution2d，BatchNorm，DropOut对Input进行连续计算，得到最后结果。
 
 参数：
-       - **input** （Variable） - 具有[N，C，H，W]格式的输入图像。
-       - **conv_num_filter** （list | tuple） - 表示该组的过滤器数。
-       - **pool_size** （int | list | tuple） -  ``Pool2d Layer`` 池的大小。如果pool_size是列表或元组，则它必须包含两个整数（pool_size_H，pool_size_W）。否则，pool_size_H = pool_size_W = pool_size。
-       - **conv_padding** （int | list | tuple） - Conv2d Layer的 ``padding`` 大小。如果 ``padding`` 是列表或元组，则其长度必须等于 ``conv_num_filter`` 的长度。否则，所有Conv2d图层的 ``conv_padding`` 都是相同的。默认1。
-       - **conv_filter_size** （int | list | tuple） - 过滤器大小。如果filter_size是列表或元组，则其长度必须等于 ``conv_num_filter`` 的长度。否则，所有Conv2d图层的 ``conv_filter_size`` 都是相同的。默认3。
-       - **conv_act** （str） -  ``Conv2d Layer`` 的激活类型， ``BatchNorm`` 后面没有。默认值：无。
-       - **param_attr** （ParamAttr） - Conv2d层的参数。默认值：无
-       - **conv_with_batchnorm** （bool | list） - 表示在 ``Conv2d Layer`` 之后是否使用 ``BatchNorm`` 。如果 ``conv_with_batchnorm`` 是一个列表，则其长度必须等于 ``conv_num_filter`` 的长度。否则， ``conv_with_batchnorm`` 指示是否所有Conv2d层都遵循 ``BatchNorm``。默认为False。
-       - **conv_batchnorm_drop_rate** （float | list） - 表示 ``BatchNorm`` 之后的 ``Dropout Layer`` 的 ``rop_rate`` 。如果 ``conv_batchnorm_drop_rate`` 是一个列表，则其长度必须等于 ``conv_num_filter`` 的长度。否则，所有 ``Dropout Layers`` 的 ``drop_rate`` 都是   ``conv_batchnorm_drop_rate`` 。默认值为0.0。
-       - **pool_stride** （int | list | tuple） -  ``Pool2d`` 层的汇集步幅。如果 ``pool_stride`` 是列表或元组，则它必须包含两个整数（pooling_stride_H，pooling_stride_W）。否则，pooling_stride_H = pooling_stride_W = pool_stride。默认1。
-       - **pool_type** （str） - 池化类型可以是最大池化的 ``max`` 和平均池化的 ``avg`` 。默认max。
+       - **input** （Variable） - 输入，格式为[N，C，H，W]的4-D Tensor。数据类型：float32和float64。
+       - **conv_num_filter** （list | tuple） - 卷积中使用的滤波器数。
+       - **pool_size** （int | list | tuple） - 池化层中池化核的大小。如果pool_size是列表或元组，则它必须包含两个整数（pool_size_height，pool_size_width）。否则，pool_size_height = pool_size_width = pool_size。
+       - **conv_padding** （int | list | tuple） - 卷积层中的填充 ``padding`` 的大小。如果 ``padding`` 是列表或元组，则其长度必须等于 ``conv_num_filter`` 的长度。否则，所有卷积的 ``conv_padding`` 都是相同的。默认：1。
+       - **conv_filter_size** （int | list | tuple） - 卷积层中滤波器大小。如果filter_size是列表或元组，则其长度必须等于 ``conv_num_filter`` 的长度。否则，所有卷积的 ``conv_filter_size`` 都是相同的。默认：3。
+       - **conv_act** （str） -  卷积层之后接的的激活层类型， ``BatchNorm`` 后面没有。默认：None。
+       - **param_attr** (ParamAttr|None) ：指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。conv2d算子默认的权重初始化是Xavier。
+       - **conv_with_batchnorm** （bool | list） - 表示在卷积层之后是否使用 ``BatchNorm`` 。如果 ``conv_with_batchnorm`` 是一个列表，则其长度必须等于 ``conv_num_filter`` 的长度。否则， ``conv_with_batchnorm`` 指示是否所有卷积层后都使用 ``BatchNorm`` 。默认：False。
+       - **conv_batchnorm_drop_rate** （float | list） - 表示 ``BatchNorm`` 之后的 ``Dropout Layer`` 的 ``drop_rate`` 。如果 ``conv_batchnorm_drop_rate`` 是一个列表，则其长度必须等于 ``conv_num_filter`` 的长度。否则，所有 ``Dropout Layers`` 的 ``drop_rate`` 都是   ``conv_batchnorm_drop_rate`` 。默认：0.0。
+       - **pool_stride** （int | list | tuple） -  池化层的池化步长。如果 ``pool_stride`` 是列表或元组，则它必须包含两个整数（pooling_stride_height，pooling_stride_width）。否则，pooling_stride_height = pooling_stride_width = pool_stride。默认：1。
+       - **pool_type** （str） - 池化类型可以是最大池化的 ``max`` 和平均池化的 ``avg`` 。默认：max。
        - **use_cudnn** （bool） - 是否使用cudnn内核，仅在安装cudnn库时才有效。默认值：True
        
-返回：  使用Convolution2d进行串行计算后的最终结果，BatchNorm，DropOut和Pool2d。
+返回： Tensor。使用Convolution2d，BatchNorm，DropOut和Pool2d进行串行计算后的最终结果。
 
-返回类型：  变量（Variable）。
+返回类型： Variable
 
-**代码示例**
+**代码示例**：
 
 .. code-block:: python
 
-          import paddle.fluid as fluid
-          img = fluid.layers.data(name='img', shape=[1, 28, 28], dtype='float32')
-          conv_pool = fluid.nets.img_conv_group(input=img,
-                                                conv_padding=1,
-                                                conv_num_filter=[3, 3],
-                                                conv_filter_size=3,
-                                                conv_act="relu",
-                                                pool_size=2,
-                                                pool_stride=2)
+    import paddle.fluid as fluid
+    import numpy as np
+    img = fluid.layers.data(name='img', shape=[1, 28, 28], dtype='float32')
+    conv_pool = fluid.nets.img_conv_group(input=img,
+                                          conv_padding=1,
+                                          conv_num_filter=[3, 3],
+                                          conv_filter_size=3,
+                                          conv_act="relu",
+                                          pool_size=2,
+                                          pool_stride=2)
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    exe.run(fluid.default_startup_program())
+    np_x = np.random.random(size=(1, 1, 28, 28)).astype('float32')
+    output = exe.run(feed={"img": np_x}, fetch_list = [conv_pool])
+    print(output)