From 5a2be87f30add121a4edfa5848b7dcd0d6615a84 Mon Sep 17 00:00:00 2001 From: LielinJiang <50691816+LielinJiang@users.noreply.github.com> Date: Wed, 9 Sep 2020 23:38:13 +0800 Subject: [PATCH] Update 2.0 api doc including conv and kl loss (#2487) * update conv kl-loss doc --- doc/fluid/api/nn.rst | 8 +- doc/fluid/api/nn/Conv2d.rst | 13 ++ doc/fluid/api/nn/Conv3d.rst | 13 ++ doc/fluid/api/nn/ConvTranspose2d.rst | 13 ++ doc/fluid/api/nn/ConvTranspose3d.rst | 13 ++ doc/fluid/api/nn/conv2d.rst | 7 - doc/fluid/api/nn/conv2d_transpose.rst | 7 - doc/fluid/api/nn/conv3d.rst | 7 - doc/fluid/api/nn/conv3d_transpose.rst | 7 - doc/fluid/api/nn/functional.rst | 5 + doc/fluid/api/nn/functional/conv2d.rst | 11 ++ doc/fluid/api/nn/functional/conv3d.rst | 11 ++ .../api/nn/functional/conv_transpose2d.rst | 11 ++ .../api/nn/functional/conv_transpose3d.rst | 11 ++ doc/fluid/api/nn/functional/kl_div.rst | 10 ++ doc/fluid/api/nn/loss.rst | 2 + doc/fluid/api/nn/loss/KLDivLoss.rst | 13 ++ doc/fluid/api_cn/nn_cn.rst | 7 +- doc/fluid/api_cn/nn_cn/Conv2d_cn.rst | 103 +++++++++++++++ doc/fluid/api_cn/nn_cn/Conv3d_cn.rst | 110 ++++++++++++++++ doc/fluid/api_cn/nn_cn/ConvTranspose2d_cn.rst | 106 +++++++++++++++ doc/fluid/api_cn/nn_cn/ConvTranspose3d_cn.rst | 106 +++++++++++++++ .../api_cn/nn_cn/conv2d_transpose_cn.rst | 7 - doc/fluid/api_cn/nn_cn/conv3d_cn.rst | 7 - .../api_cn/nn_cn/conv3d_transpose_cn.rst | 7 - doc/fluid/api_cn/nn_cn/functional_cn.rst | 5 + .../conv2d_cn.rst} | 82 +++++------- .../api_cn/nn_cn/functional_cn/conv3d_cn.rst | 83 ++++++++++++ .../functional_cn/conv_transpose2d_cn.rst | 120 +++++++++++++++++ .../functional_cn/conv_transpose3d_cn.rst | 124 ++++++++++++++++++ .../api_cn/nn_cn/functional_cn/kl_div_cn.rst | 65 +++++++++ doc/fluid/api_cn/nn_cn/kldiv_loss_cn.rst | 7 - doc/fluid/api_cn/nn_cn/loss_cn.rst | 1 + .../api_cn/nn_cn/loss_cn/KLDivLoss_cn.rst | 68 ++++++++++ 34 files changed, 1060 insertions(+), 110 deletions(-) create mode 100644 doc/fluid/api/nn/Conv2d.rst create mode 100644 doc/fluid/api/nn/Conv3d.rst create mode 100644 doc/fluid/api/nn/ConvTranspose2d.rst create mode 100644 doc/fluid/api/nn/ConvTranspose3d.rst delete mode 100644 doc/fluid/api/nn/conv2d.rst delete mode 100644 doc/fluid/api/nn/conv2d_transpose.rst delete mode 100644 doc/fluid/api/nn/conv3d.rst delete mode 100644 doc/fluid/api/nn/conv3d_transpose.rst create mode 100644 doc/fluid/api/nn/functional/conv2d.rst create mode 100644 doc/fluid/api/nn/functional/conv3d.rst create mode 100644 doc/fluid/api/nn/functional/conv_transpose2d.rst create mode 100644 doc/fluid/api/nn/functional/conv_transpose3d.rst create mode 100644 doc/fluid/api/nn/functional/kl_div.rst create mode 100644 doc/fluid/api/nn/loss/KLDivLoss.rst create mode 100644 doc/fluid/api_cn/nn_cn/Conv2d_cn.rst create mode 100644 doc/fluid/api_cn/nn_cn/Conv3d_cn.rst create mode 100644 doc/fluid/api_cn/nn_cn/ConvTranspose2d_cn.rst create mode 100644 doc/fluid/api_cn/nn_cn/ConvTranspose3d_cn.rst delete mode 100644 doc/fluid/api_cn/nn_cn/conv2d_transpose_cn.rst delete mode 100644 doc/fluid/api_cn/nn_cn/conv3d_cn.rst delete mode 100644 doc/fluid/api_cn/nn_cn/conv3d_transpose_cn.rst rename doc/fluid/api_cn/nn_cn/{Conv2D_cn.rst => functional_cn/conv2d_cn.rst} (57%) mode change 100644 => 100755 create mode 100755 doc/fluid/api_cn/nn_cn/functional_cn/conv3d_cn.rst create mode 100644 doc/fluid/api_cn/nn_cn/functional_cn/conv_transpose2d_cn.rst create mode 100644 doc/fluid/api_cn/nn_cn/functional_cn/conv_transpose3d_cn.rst create mode 100644 doc/fluid/api_cn/nn_cn/functional_cn/kl_div_cn.rst delete mode 100644 doc/fluid/api_cn/nn_cn/kldiv_loss_cn.rst create mode 100644 doc/fluid/api_cn/nn_cn/loss_cn/KLDivLoss_cn.rst diff --git a/doc/fluid/api/nn.rst b/doc/fluid/api/nn.rst index d9ad7ad29..6eb77f469 100644 --- a/doc/fluid/api/nn.rst +++ b/doc/fluid/api/nn.rst @@ -33,10 +33,10 @@ paddle.nn nn/ConstantPad2d.rst nn/ConstantPad3d.rst nn/continuous_value_model.rst - nn/conv2d.rst - nn/conv2d_transpose.rst - nn/conv3d.rst - nn/conv3d_transpose.rst + nn/Conv2d.rst + nn/Conv3d.rst + nn/ConvTranspose2d.rst + nn/ConvTranspose3d.rst nn/cosine_decay.rst nn/cosine_similarity.rst nn/CosineSimilarity.rst diff --git a/doc/fluid/api/nn/Conv2d.rst b/doc/fluid/api/nn/Conv2d.rst new file mode 100644 index 000000000..239d4440f --- /dev/null +++ b/doc/fluid/api/nn/Conv2d.rst @@ -0,0 +1,13 @@ +.. THIS FILE IS GENERATED BY `gen_doc.{py|sh}` + !DO NOT EDIT THIS FILE MANUALLY! + +.. _api_nn_layer_conv_Conv2d: + +Conv2d +------ + +.. autoclass:: paddle.nn.layer.conv.Conv2d + :members: + :inherited-members: + :noindex: + diff --git a/doc/fluid/api/nn/Conv3d.rst b/doc/fluid/api/nn/Conv3d.rst new file mode 100644 index 000000000..23a878b43 --- /dev/null +++ b/doc/fluid/api/nn/Conv3d.rst @@ -0,0 +1,13 @@ +.. THIS FILE IS GENERATED BY `gen_doc.{py|sh}` + !DO NOT EDIT THIS FILE MANUALLY! + +.. _api_nn_layer_conv_Conv3d: + +Conv3d +------ + +.. autoclass:: paddle.nn.layer.conv.Conv3d + :members: + :inherited-members: + :noindex: + diff --git a/doc/fluid/api/nn/ConvTranspose2d.rst b/doc/fluid/api/nn/ConvTranspose2d.rst new file mode 100644 index 000000000..0c1198338 --- /dev/null +++ b/doc/fluid/api/nn/ConvTranspose2d.rst @@ -0,0 +1,13 @@ +.. THIS FILE IS GENERATED BY `gen_doc.{py|sh}` + !DO NOT EDIT THIS FILE MANUALLY! + +.. _api_nn_layer_conv_ConvTranspose2d: + +ConvTranspose2d +--------------- + +.. autoclass:: paddle.nn.layer.conv.ConvTranspose2d + :members: + :inherited-members: + :noindex: + diff --git a/doc/fluid/api/nn/ConvTranspose3d.rst b/doc/fluid/api/nn/ConvTranspose3d.rst new file mode 100644 index 000000000..5d0345a4f --- /dev/null +++ b/doc/fluid/api/nn/ConvTranspose3d.rst @@ -0,0 +1,13 @@ +.. THIS FILE IS GENERATED BY `gen_doc.{py|sh}` + !DO NOT EDIT THIS FILE MANUALLY! + +.. _api_nn_layer_conv_ConvTranspose3d: + +ConvTranspose3d +--------------- + +.. autoclass:: paddle.nn.layer.conv.ConvTranspose3d + :members: + :inherited-members: + :noindex: + diff --git a/doc/fluid/api/nn/conv2d.rst b/doc/fluid/api/nn/conv2d.rst deleted file mode 100644 index 70d463577..000000000 --- a/doc/fluid/api/nn/conv2d.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _api_nn_conv2d: - -conv2d -------------------------------- -:doc_source: paddle.fluid.layers.conv2d - - diff --git a/doc/fluid/api/nn/conv2d_transpose.rst b/doc/fluid/api/nn/conv2d_transpose.rst deleted file mode 100644 index 23935a5b9..000000000 --- a/doc/fluid/api/nn/conv2d_transpose.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _api_nn_conv2d_transpose: - -conv2d_transpose -------------------------------- -:doc_source: paddle.fluid.layers.conv2d_transpose - - diff --git a/doc/fluid/api/nn/conv3d.rst b/doc/fluid/api/nn/conv3d.rst deleted file mode 100644 index 8207226de..000000000 --- a/doc/fluid/api/nn/conv3d.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _api_nn_conv3d: - -conv3d -------------------------------- -:doc_source: paddle.fluid.layers.conv3d - - diff --git a/doc/fluid/api/nn/conv3d_transpose.rst b/doc/fluid/api/nn/conv3d_transpose.rst deleted file mode 100644 index 9bcaf0e3a..000000000 --- a/doc/fluid/api/nn/conv3d_transpose.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _api_nn_conv3d_transpose: - -conv3d_transpose -------------------------------- -:doc_source: paddle.fluid.layers.conv3d_transpose - - diff --git a/doc/fluid/api/nn/functional.rst b/doc/fluid/api/nn/functional.rst index 57463af63..1c8c2d3fc 100644 --- a/doc/fluid/api/nn/functional.rst +++ b/doc/fluid/api/nn/functional.rst @@ -9,8 +9,13 @@ functional functional/l1_loss.rst functional/nll_loss.rst functional/mse_loss.rst + functional/kl_div.rst functional/one_hot.rst functional/ctc_loss.rst functional/adaptive_avg_pool2d.rst functional/adaptive_avg_pool3d.rst + functional/conv2d.rst + functional/conv3d.rst + functional/conv_transpose2d.rst + functional/conv_transpose3d.rst functional/bilinear.rst diff --git a/doc/fluid/api/nn/functional/conv2d.rst b/doc/fluid/api/nn/functional/conv2d.rst new file mode 100644 index 000000000..bdf3753b9 --- /dev/null +++ b/doc/fluid/api/nn/functional/conv2d.rst @@ -0,0 +1,11 @@ +.. THIS FILE IS GENERATED BY `gen_doc.{py|sh}` + !DO NOT EDIT THIS FILE MANUALLY! + +.. _api_nn_functional_conv_conv2d: + +conv2d +------ + +.. autofunction:: paddle.nn.functional.conv.conv2d + :noindex: + diff --git a/doc/fluid/api/nn/functional/conv3d.rst b/doc/fluid/api/nn/functional/conv3d.rst new file mode 100644 index 000000000..11588b19a --- /dev/null +++ b/doc/fluid/api/nn/functional/conv3d.rst @@ -0,0 +1,11 @@ +.. THIS FILE IS GENERATED BY `gen_doc.{py|sh}` + !DO NOT EDIT THIS FILE MANUALLY! + +.. _api_nn_functional_conv_conv3d: + +conv3d +------ + +.. autofunction:: paddle.nn.functional.conv.conv3d + :noindex: + diff --git a/doc/fluid/api/nn/functional/conv_transpose2d.rst b/doc/fluid/api/nn/functional/conv_transpose2d.rst new file mode 100644 index 000000000..da09490ed --- /dev/null +++ b/doc/fluid/api/nn/functional/conv_transpose2d.rst @@ -0,0 +1,11 @@ +.. THIS FILE IS GENERATED BY `gen_doc.{py|sh}` + !DO NOT EDIT THIS FILE MANUALLY! + +.. _api_nn_functional_conv_conv_transpose2d: + +conv_transpose2d +---------------- + +.. autofunction:: paddle.nn.functional.conv.conv_transpose2d + :noindex: + diff --git a/doc/fluid/api/nn/functional/conv_transpose3d.rst b/doc/fluid/api/nn/functional/conv_transpose3d.rst new file mode 100644 index 000000000..722a2d8b8 --- /dev/null +++ b/doc/fluid/api/nn/functional/conv_transpose3d.rst @@ -0,0 +1,11 @@ +.. THIS FILE IS GENERATED BY `gen_doc.{py|sh}` + !DO NOT EDIT THIS FILE MANUALLY! + +.. _api_nn_functional_conv_conv_transpose3d: + +conv_transpose3d +---------------- + +.. autofunction:: paddle.nn.functional.conv.conv_transpose3d + :noindex: + diff --git a/doc/fluid/api/nn/functional/kl_div.rst b/doc/fluid/api/nn/functional/kl_div.rst new file mode 100644 index 000000000..cbd2e10aa --- /dev/null +++ b/doc/fluid/api/nn/functional/kl_div.rst @@ -0,0 +1,10 @@ +.. _api_nn_functional_kl_div: + +kl_div +------------------------------- + +.. autoclass:: paddle.nn.functional.kl_div + :members: + :inherited-members: + :noindex: + diff --git a/doc/fluid/api/nn/loss.rst b/doc/fluid/api/nn/loss.rst index 825a11bee..c9c351b78 100644 --- a/doc/fluid/api/nn/loss.rst +++ b/doc/fluid/api/nn/loss.rst @@ -11,5 +11,7 @@ loss loss/L1Loss.rst loss/MSELoss.rst loss/NLLLoss.rst + loss/KLDivLoss.rst loss/SmoothL1Loss.rst loss/CTCLoss.rst + loss/KLDivLoss.rst diff --git a/doc/fluid/api/nn/loss/KLDivLoss.rst b/doc/fluid/api/nn/loss/KLDivLoss.rst new file mode 100644 index 000000000..797e815e2 --- /dev/null +++ b/doc/fluid/api/nn/loss/KLDivLoss.rst @@ -0,0 +1,13 @@ +.. THIS FILE IS GENERATED BY `gen_doc.{py|sh}` + !DO NOT EDIT THIS FILE MANUALLY! + +.. _api_nn_loss_KLDivLoss: + +KLDivLoss +------------------------------- + +.. autoclass:: paddle.nn.loss.KLDivLoss + :members: + :inherited-members: + :noindex: + diff --git a/doc/fluid/api_cn/nn_cn.rst b/doc/fluid/api_cn/nn_cn.rst index bf3dc98f8..deaf80a07 100644 --- a/doc/fluid/api_cn/nn_cn.rst +++ b/doc/fluid/api_cn/nn_cn.rst @@ -8,8 +8,11 @@ paddle.nn .. toctree:: :maxdepth: 1 - nn_cn/Conv1D_cn.rst - nn_cn/Conv2D_cn.rst + nn_cn/Conv1d_cn.rst + nn_cn/Conv2d_cn.rst + nn_cn/Conv3d_cn.rst + nn_cn/ConvTranspose2d_cn.rst + nn_cn/ConvTranspose3d_cn.rst nn_cn/diag_embed_cn.rst nn_cn/interpolate_cn.rst nn_cn/Linear_cn.rst diff --git a/doc/fluid/api_cn/nn_cn/Conv2d_cn.rst b/doc/fluid/api_cn/nn_cn/Conv2d_cn.rst new file mode 100644 index 000000000..ffc23cb83 --- /dev/null +++ b/doc/fluid/api_cn/nn_cn/Conv2d_cn.rst @@ -0,0 +1,103 @@ +Conv2d +------------------------------- + +.. py:class:: paddle.nn.Conv2d(in_channels, out_channels, kernel_size, stride=1, padding=0, dilation=1, groups=1, padding_mode='zeros', weight_attr=None, bias_attr=None, data_format="NCHW") + + + +**二维卷积层** + +该OP是二维卷积层（convolution2d layer），根据输入、卷积核、步长（stride）、填充（padding）、空洞大小（dilations）一组参数计算输出特征层大小。输入和输出是NCHW或NHWC格式，其中N是批尺寸，C是通道数，H是特征高度，W是特征宽度。卷积核是MCHW格式，M是输出图像通道数，C是输入图像通道数，H是卷积核高度，W是卷积核宽度。如果组数(groups)大于1，C等于输入图像通道数除以组数的结果。详情请参考UFLDL's : `卷积 `_ 。如果bias_attr不为False，卷积计算会添加偏置项。 + +对每个输入X，有等式： + +.. math:: + + Out = \sigma \left ( W * X + b \right ) + +其中： + - :math:`X` ：输入值，NCHW或NHWC格式的4-D Tensor + - :math:`W` ：卷积核值，MCHW格式的4-D Tensor + - :math:`*` ：卷积操作 + - :math:`b` ：偏置值，2-D Tensor，形状为 ``[M,1]`` + - :math:`\sigma` ：激活函数 + - :math:`Out` ：输出值，NCHW或NHWC格式的4-D Tensor， 和 ``X`` 的形状可能不同 + + +参数： + - **in_channels** (int) - 输入图像的通道数。 + - **out_channels** (int) - 由卷积操作产生的输出的通道数。 + - **kernel_size** (int|list|tuple) - 卷积核大小。可以为单个整数或包含两个整数的元组或列表，分别表示卷积核的高和宽。如果为单个整数，表示卷积核的高和宽都等于该整数。 + - **stride** (int|list|tuple，可选) - 步长大小。可以为单个整数或包含两个整数的元组或列表，分别表示卷积沿着高和宽的步长。如果为单个整数，表示沿着高和宽的步长都等于该整数。默认值：1。 + - **padding** (int|list|tuple|str，可选) - 填充大小。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法，计算细节可参考上述 ``padding`` = "SAME"或 ``padding`` = "VALID" 时的计算公式。如果它是一个元组或列表，它可以有3种格式：(1)包含4个二元组：当 ``data_format`` 为"NCHW"时为 [[0,0], [0,0], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right]]，当 ``data_format`` 为"NHWC"时为[[0,0], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right], [0,0]]；(2)包含4个整数值：[padding_height_top, padding_height_bottom, padding_width_left, padding_width_right]；(3)包含2个整数值：[padding_height, padding_width]，此时padding_height_top = padding_height_bottom = padding_height， padding_width_left = padding_width_right = padding_width。若为一个整数，padding_height = padding_width = padding。默认值：0。 + - **dilation** (int|list|tuple，可选) - 空洞大小。可以为单个整数或包含两个整数的元组或列表，分别表示卷积核中的元素沿着高和宽的空洞。如果为单个整数，表示高和宽的空洞都等于该整数。默认值：1。 + - **groups** (int，可选) - 二维卷积层的组数。根据Alex Krizhevsky的深度卷积神经网络（CNN）论文中的成组卷积：当group=n，输入和卷积核分别根据通道数量平均分为n组，第一组卷积核和第一组输入进行卷积计算，第二组卷积核和第二组输入进行卷积计算，……，第n组卷积核和第n组输入进行卷积计算。默认值：1。 + - **padding_mode** (str, 可选): 填充模式。 包括 ``'zeros'``, ``'reflect'``, ``'replicate'`` 或者 ``'circular'``. 默认值: ``'zeros'`` . + - **weight_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **bias_attr** （ParamAttr|bool，可选）- 指定偏置参数属性的对象。若 ``bias_attr`` 为bool类型，只支持为False，表示没有偏置参数。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。 + + +属性 +:::::::::::: +.. py:attribute:: weight +本层的可学习参数，类型为 ``Parameter`` + +.. py:attribute:: bias +本层的可学习偏置，类型为 ``Parameter`` + +形状: + - 输入: :math:`(N, C_{in}, H_{in}, W_{in})` + - 输出: :math:`(N, C_{out}, H_{out}, W_{out})` + + 其中: + + .. math:: + H_{out} = \frac{(H_{in} + 2 * paddings[0] - (dilations[0] * (kernel\_size[0] - 1) + 1))}{strides[0]} + 1 + + W_{out} = \frac{(W_{in} + 2 * paddings[1] - (dilations[1] * (kernel\_size[1] - 1) + 1))}{strides[1]} + 1 + + 如果 ``padding`` = "SAME": + + .. math:: + H_{out} = \frac{(H_{in} + stride[0] - 1)}{stride[0]} + + .. math:: + W_{out} = \frac{(W_{in} + stride[1] - 1)}{stride[1]} + + 如果 ``padding`` = "VALID": + + .. math:: + H_{out} = \frac{\left ( H_{in} -\left ( dilation[0]*\left ( kernel\_size[0]-1 \right )+1 \right ) \right )}{stride[0]}+1 + + W_{out} = \frac{\left ( W_{in} -\left ( dilation[1]*\left ( kernel\_size[1]-1 \right )+1 \right ) \right )}{stride[1]}+1 + + +抛出异常： + - ``ValueError`` - 如果 ``data_format`` 既不是"NCHW"也不是"NHWC"。 + - ``ValueError`` - 如果 ``input`` 的通道数未被明确定义。 + - ``ValueError`` - 如果 ``padding`` 是字符串，既不是"SAME"也不是"VALID"。 + - ``ValueError`` - 如果 ``padding`` 含有4个二元组，与批尺寸对应维度的值不为0或者与通道对应维度的值不为0。 + - ``ShapeError`` - 如果输入不是4-D Tensor。 + - ``ShapeError`` - 如果输入和卷积核的维度大小不相同。 + - ``ShapeError`` - 如果输入的维度大小与 ``stride`` 之差不是2。 + - ``ShapeError`` - 如果输出的通道数不能被 ``groups`` 整除。 + + +**代码示例**： + +.. code-block:: python + + import numpy as np + import paddle + import paddle.nn as nn + x = np.random.uniform(-1, 1, (2, 4, 8, 8)).astype('float32') + + paddle.disable_static() + x_var = paddle.to_tensor(x) + conv = nn.Conv2d(4, 6, (3, 3)) + y_var = conv(x_var) + y_np = y_var.numpy() + print(y_np.shape) + + # (2, 6, 6, 6) diff --git a/doc/fluid/api_cn/nn_cn/Conv3d_cn.rst b/doc/fluid/api_cn/nn_cn/Conv3d_cn.rst new file mode 100644 index 000000000..1f61e1d4e --- /dev/null +++ b/doc/fluid/api_cn/nn_cn/Conv3d_cn.rst @@ -0,0 +1,110 @@ +Conv3d +------------------------------- + +.. py:class:: paddle.nn.Conv3d(in_channels, out_channels, kernel_size, stride=1, padding=0, dilation=1, groups=1, padding_mode='zeros', weight_attr=None, bias_attr=None, data_format="NCDHW") + + + +**三维卷积层** + +该OP是三维卷积层（convolution3D layer），根据输入、卷积核、步长（stride）、填充（padding）、空洞大小（dilations）一组参数计算得到输出特征层大小。输入和输出是NCDHW或NDWHC格式，其中N是批尺寸，C是通道数，D是特征层深度，H是特征层高度，W是特征层宽度。三维卷积（Convlution3D）和二维卷积（Convlution2D）相似，但多了一维深度信息（depth）。如果bias_attr不为False，卷积计算会添加偏置项。 + +对每个输入X，有等式： + +.. math:: + + Out = \sigma \left ( W * X + b \right ) + +其中： + - :math:`X` ：输入值，NCDHW或NDHWC格式的5-D Tensor + - :math:`W` ：卷积核值，MCDHW格式的5-D Tensor + - :math:`*` ：卷积操作 + - :math:`b` ：偏置值，2-D Tensor，形为 ``[M,1]`` + - :math:`\sigma` ：激活函数 + - :math:`Out` ：输出值, NCDHW或NDHWC格式的5-D Tensor，和 ``X`` 的形状可能不同 + +参数： + - **in_channels** (int) - 输入图像的通道数。 + - **out_channels** (int) - 由卷积操作产生的输出的通道数。 + - **kernel_size** (int|list|tuple) - 卷积核大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积核的深度，高和宽。如果为单个整数，表示卷积核的深度，高和宽都等于该整数。 + - **stride** (int|list|tuple，可选) - 步长大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积沿着深度，高和宽的步长。如果为单个整数，表示沿着高和宽的步长都等于该整数。默认值：1。 + - **padding** (int|list|tuple|str，可选) - 填充大小。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法，计算细节可参考上述 ``padding`` = "SAME"或 ``padding`` = "VALID" 时的计算公式。如果它是一个元组或列表，它可以有3种格式：(1)包含5个二元组：当 ``data_format`` 为"NCDHW"时为 [[0,0], [0,0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right]]，当 ``data_format`` 为"NDHWC"时为[[0,0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right], [0,0]]；(2)包含6个整数值：[padding_depth_front, padding_depth_back, padding_height_top, padding_height_bottom, padding_width_left, padding_width_right]；(3)包含3个整数值：[padding_depth, padding_height, padding_width]，此时 padding_depth_front = padding_depth_back = padding_depth, padding_height_top = padding_height_bottom = padding_height, padding_width_left = padding_width_right = padding_width。若为一个整数，padding_depth = padding_height = padding_width = padding。默认值：0。 + - **dilation** (int|list|tuple，可选) - 空洞大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积核中的元素沿着深度，高和宽的空洞。如果为单个整数，表示深度，高和宽的空洞都等于该整数。默认值：1。 + - **groups** (int，可选) - 三维卷积层的组数。根据Alex Krizhevsky的深度卷积神经网络（CNN）论文中的成组卷积：当group=n，输入和卷积核分别根据通道数量平均分为n组，第一组卷积核和第一组输入进行卷积计算，第二组卷积核和第二组输入进行卷积计算，……，第n组卷积核和第n组输入进行卷积计算。默认值：1。 + - **padding_mode** (str, 可选): 填充模式。 包括 ``'zeros'``, ``'reflect'``, ``'replicate'`` 或者 ``'circular'``. 默认值: ``'zeros'`` . + - **weight_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **bias_attr** （ParamAttr|bool，可选）- 指定偏置参数属性的对象。若 ``bias_attr`` 为bool类型，只支持为False，表示没有偏置参数。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCDHW"和"NDHWC"。N是批尺寸，C是通道数，D是特征深度，H是特征高度，W是特征宽度。默认值："NCDHW"。 + + +属性 +:::::::::::: +.. py:attribute:: weight +本层的可学习参数，类型为 ``Parameter`` + +.. py:attribute:: bias +本层的可学习偏置，类型为 ``Parameter`` + +形状： + + - 输入：:math:`(N, C_{in}, D_{in}, H_{in}, W_{in})` + - 输出：:math:`(N, C_{out}, D_{out}, H_{out}, W_{out})` + + 其中 + + .. math:: + + D_{out} &= \frac{\left ( D_{in} + padding\_depth\_front + padding\_depth\_back-\left ( dilation[0]*\left ( kernel\_size[0]-1 \right )+1 \right ) \right )}{stride[0]}+1 + + H_{out} &= \frac{\left ( H_{in} + padding\_height\_top + padding\_height\_bottom-\left ( dilation[1]*\left ( kernel\_size[1]-1 \right )+1 \right ) \right )}{stride[1]}+1 + + W_{out} &= \frac{\left ( W_{in} + padding\_width\_left + padding\_width\_right -\left ( dilation[2]*\left ( kernel\_size[2]-1 \right )+1 \right ) \right )}{stride[2]}+1 + + 如果 ``padding`` = "SAME": + + .. math:: + D_{out} = \frac{(D_{in} + stride[0] - 1)}{stride[0]} + + H_{out} = \frac{(H_{in} + stride[1] - 1)}{stride[1]} + + W_{out} = \frac{(W_{in} + stride[2] - 1)}{stride[2]} + + 如果 ``padding`` = "VALID": + + .. math:: + D_{out} = \frac{\left ( D_{in} -\left ( dilation[0]*\left ( kernel\_size[0]-1 \right )+1 \right ) \right )}{stride[0]}+1 + + H_{out} = \frac{\left ( H_{in} -\left ( dilation[1]*\left ( kernel\_size[1]-1 \right )+1 \right ) \right )}{stride[1]}+1 + + W_{out} = \frac{\left ( W_{in} -\left ( dilation[2]*\left ( kernel\_size[2]-1 \right )+1 \right ) \right )}{stride[2]}+1 + +抛出异常： + - ``ValueError`` - 如果 ``data_format`` 既不是"NCDHW"也不是"NDHWC"。 + - ``ValueError`` - 如果 ``input`` 的通道数未被明确定义。 + - ``ValueError`` - 如果 ``padding`` 是字符串，既不是"SAME"也不是"VALID"。 + - ``ValueError`` - 如果 ``padding`` 含有5个二元组，与批尺寸对应维度的值不为0或者与通道对应维度的值不为0。 + - ``ShapeError`` - 如果输入不是5-D Tensor。 + - ``ShapeError`` - 如果输入和卷积核的维度大小不相同。 + - ``ShapeError`` - 如果输入的维度大小与 ``stride`` 之差不是2。 + - ``ShapeError`` - 如果输出的通道数不能被 ``groups`` 整除。 + + +**代码示例**： + +.. code-block:: python + + import numpy as np + + import paddle + import paddle.nn as nn + x = np.random.uniform(-1, 1, (2, 4, 8, 8, 8)).astype('float32') + + paddle.disable_static() + + x_var = paddle.to_tensor(x) + conv = nn.Conv3d(4, 6, (3, 3, 3)) + y_var = conv(x_var) + y_np = y_var.numpy() + print(y_np.shape) + + # (2, 6, 6, 6, 6) diff --git a/doc/fluid/api_cn/nn_cn/ConvTranspose2d_cn.rst b/doc/fluid/api_cn/nn_cn/ConvTranspose2d_cn.rst new file mode 100644 index 000000000..7cf28d4fb --- /dev/null +++ b/doc/fluid/api_cn/nn_cn/ConvTranspose2d_cn.rst @@ -0,0 +1,106 @@ +ConvTranspose2d +------------------------------- + +.. py:class:: paddle.nn.ConvTranspose2d(in_channels, out_channels, kernel_size, stride=1, padding=0, output_padding=0, groups=1, dilation=1, weight_attr=None, bias_attr=None, data_format="NCHW") + + +二维转置卷积层（Convlution2d transpose layer） + +该层根据输入（input）、卷积核（kernel）和空洞大小（dilations）、步长（stride）、填充（padding）来计算输出特征层大小或者通过output_size指定输出特征层大小。输入(Input)和输出(Output)为NCHW或NHWC格式，其中N为批尺寸，C为通道数（channel），H为特征层高度，W为特征层宽度。卷积核是MCHW格式，M是输出图像通道数，C是输入图像通道数，H是卷积核高度，W是卷积核宽度。如果组数大于1，C等于输入图像通道数除以组数的结果。转置卷积的计算过程相当于卷积的反向计算。转置卷积又被称为反卷积（但其实并不是真正的反卷积）。欲了解转置卷积层细节，请参考下面的说明和 参考文献_ 。如果参数bias_attr不为False, 转置卷积计算会添加偏置项。 + +.. _参考文献: https://arxiv.org/pdf/1603.07285.pdf + + +输入 :math:`X` 和输出 :math:`Out` 函数关系如下： + +.. math:: + Out=\sigma (W*X+b)\\ + +其中： + - :math:`X` : 输入，具有NCHW或NHWC格式的4-D Tensor + - :math:`W` : 卷积核，具有NCHW格式的4-D Tensor + - :math:`*` : 卷积计算（注意：转置卷积本质上的计算还是卷积） + - :math:`b` : 偏置（bias），2-D Tensor，形状为 ``[M,1]`` + - :math:`σ` : 激活函数 + - :math:`Out` : 输出值，NCHW或NHWC格式的4-D Tensor， 和 ``X`` 的形状可能不同 + + +注意： + +如果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]` ）。 + +由于转置卷积可以当成是卷积的反向计算，而根据卷积的输入输出计算公式来说，不同大小的输入特征层可能对应着相同大小的输出特征层，所以对应到转置卷积来说，固定大小的输入特征层对应的输出特征层大小并不唯一。 + +如果指定了output_size， ``conv2d_transpose`` 可以自动计算卷积核的大小。 + +参数: + - **in_channels** (int) - 输入图像的通道数。 + - **out_channels** (int) - 卷积核的个数，和输出特征图通道数相同。 + - **kernel_size** (int|list|tuple) - 卷积核大小。可以为单个整数或包含两个整数的元组或列表，分别表示卷积核的高和宽。如果为单个整数，表示卷积核的高和宽都等于该整数。 + - **stride** (int|tuple, 可选) - 步长大小。如果 ``stride`` 为元组或列表，则必须包含两个整型数，分别表示垂直和水平滑动步长。否则，表示垂直和水平滑动步长均为 ``stride`` 。默认值：1。 + - **padding** (int|tuple, 可选) - 填充大小。如果 ``padding`` 为元组或列表，则必须包含两个整型数，分别表示竖直和水平边界填充大小。否则，表示竖直和水平边界填充大小均为 ``padding`` 。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法，计算细节可参考下方形状 ``padding`` = "SAME"或 ``padding`` = "VALID" 时的计算公式。默认值：0。 + - **output_padding** (int|list|tuple, optional): 输出形状上一侧额外添加的大小. 默认值: 0. + - **groups** (int, 可选) - 二维卷积层的组数。根据Alex Krizhevsky的深度卷积神经网络（CNN）论文中的分组卷积：当group=2，卷积核的前一半仅和输入特征图的前一半连接。卷积核的后一半仅和输入特征图的后一半连接。默认值：1。 + - **dilation** (int|tuple, 可选) - 空洞大小。可以为单个整数或包含两个整数的元组或列表，分别表示卷积核中的元素沿着高和宽的空洞。如果为单个整数，表示高和宽的空洞都等于该整数。默认值：1。 + - **weight_attr** (ParamAttr, 可选) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **bias_attr** (ParamAttr|bool, 可选) - 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。 + + +形状: + + - 输入：:math:`（N，C_{in}， H_{in}， W_{in}）` + + + - 输出：:math:`（N，C_{out}, H_{out}, W_{out}）` + + 其中 + + .. math:: + + & H'_{out} = (H_{in}-1)*strides[0] - pad\_height\_top - pad\_height\_bottom + dilations[0]*(kernel\_size[0]-1)+1\\ + & W'_{out} = (W_{in}-1)*strides[1]- pad\_width\_left - pad\_width\_right + dilations[1]*(kernel\_size[1]-1)+1 \\ + & H_{out}\in[H'_{out},H'_{out} + strides[0])\\ + & W_{out}\in[W'_{out},W'_{out} + strides[1])\\ + + 如果 ``padding`` = "SAME": + + .. math:: + & H'_{out} = \frac{(H_{in} + stride[0] - 1)}{stride[0]}\\ + & W'_{out} = \frac{(W_{in} + stride[1] - 1)}{stride[1]}\\ + + 如果 ``padding`` = "VALID": + + .. math:: + & H'_{out} = (H_{in}-1)*strides[0] + dilations[0]*(kernel\_size[0]-1)+1\\ + & W'_{out} = (W_{in}-1)*strides[1] + dilations[1]*(kernel\_size[1]-1)+1 \\ + +抛出异常: + - ``ValueError`` : 如果输入的shape、filter_size、stride、padding和groups不匹配，抛出ValueError + - ``ValueError`` - 如果 ``data_format`` 既不是"NCHW"也不是"NHWC"。 + - ``ValueError`` - 如果 ``padding`` 是字符串，既不是"SAME"也不是"VALID"。 + - ``ValueError`` - 如果 ``padding`` 含有4个二元组，与批尺寸对应维度的值不为0或者与通道对应维度的值不为0。 + - ``ValueError`` - 如果 ``output_size`` 和 ``filter_size`` 同时为None。 + - ``ShapeError`` - 如果输入不是4-D Tensor。 + - ``ShapeError`` - 如果输入和卷积核的维度大小不相同。 + - ``ShapeError`` - 如果输入的维度大小与 ``stride`` 之差不是2。 + +**代码示例** + +.. code-block:: python + + import numpy as np + import paddle + import paddle.nn as nn + + x = np.random.uniform(-1, 1, (2, 4, 8, 8)).astype('float32') + + paddle.disable_static() + + x_var = paddle.to_tensor(x) + conv = nn.ConvTranspose2d(4, 6, (3, 3)) + y_var = conv(x_var) + y_np = y_var.numpy() + print(y_np.shape) + + # (2, 6, 10, 10) diff --git a/doc/fluid/api_cn/nn_cn/ConvTranspose3d_cn.rst b/doc/fluid/api_cn/nn_cn/ConvTranspose3d_cn.rst new file mode 100644 index 000000000..67c8fb483 --- /dev/null +++ b/doc/fluid/api_cn/nn_cn/ConvTranspose3d_cn.rst @@ -0,0 +1,106 @@ +ConvTranspose3d +------------------------------- + +.. py:class:: paddle.nn.ConvTranspose3d(in_channels, out_channels, kernel_size, stride=1, padding=0, output_padding=0, groups=1, dilation=1, weight_attr=None, bias_attr=None, data_format="NCDHW") + + +三维转置卷积层（Convlution3d transpose layer) + +该层根据输入（input）、卷积核（kernel）和卷积核空洞大小（dilations）、步长（stride）、填充（padding）来计算输出特征层大小或者通过output_size指定输出特征层大小。输入(Input)和输出(Output)为NCDHW或者NDHWC格式。其中N为批尺寸，C为通道数（channel），D为特征深度，H为特征层高度，W为特征层宽度。转置卷积的计算过程相当于卷积的反向计算。转置卷积又被称为反卷积（但其实并不是真正的反卷积）。欲了解卷积转置层细节，请参考下面的说明和 参考文献_ 。如果参数bias_attr不为False, 转置卷积计算会添加偏置项。 + +.. _参考文献: http://www.matthewzeiler.com/wp-content/uploads/2017/07/cvpr2010.pdf + +输入 :math:`X` 和输出 :math:`Out` 函数关系如下： + +.. math:: + \\Out=\sigma (W*X+b)\\ + +其中： + - :math:`X` : 输入，具有NCDHW或NDHWC格式的5-D Tensor + - :math:`W` : 卷积核，具有NCDHW格式的5-D Tensor + - :math:`*` : 卷积操作（注意：转置卷积本质上的计算还是卷积） + - :math:`b` : 偏置（bias），2-D Tensor，形状为 ``[M,1]`` + - :math:`σ` : 激活函数 + - :math:`Out` : 输出值，NCDHW或NDHWC格式的5-D Tensor，和 ``X`` 的形状可能不同 + + +注意： + +如果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]` ）。 + +由于转置卷积可以当成是卷积的反向计算，而根据卷积的输入输出计算公式来说，不同大小的输入特征层可能对应着相同大小的输出特征层，所以对应到转置卷积来说，固定大小的输入特征层对应的输出特征层大小并不唯一。 + +如果指定了output_size， 该算子可以自动计算卷积核的大小。 + +参数: + - **in_channels** (int) - 输入图像的通道数。 + - **out_channels** (int) - 卷积核的个数，和输出特征图个数相同。 + - **kernel_size** (int|list|tuple) - 卷积核大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积核的深度，高和宽。如果为单个整数，表示卷积核的深度，高和宽都等于该整数。默认：None。output_size和kernel_size不能同时为None。 + - **stride** (int|tuple, 可选) - 步长大小。如果 ``stride`` 为元组或列表，则必须包含三个整型数，分别表示深度，垂直和水平滑动步长。否则，表示深度，垂直和水平滑动步长均为 ``stride`` 。默认值：1。 + - **padding** (int|tuple, 可选) - 填充大小。如果 ``padding`` 为元组或列表，则必须包含三个整型数，分别表示深度，竖直和水平边界填充大小。否则，表示深度，竖直和水平边界填充大小均为 ``padding`` 。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法，计算细节可参考下方形状 ``padding`` = "SAME"或 ``padding`` = "VALID" 时的计算公式。默认值：0。 + - **output_padding** (int|list|tuple, optional): 输出形状上一侧额外添加的大小. 默认值: 0. + - **groups** (int, 可选) - 二维卷积层的组数。根据Alex Krizhevsky的深度卷积神经网络（CNN）论文中的分组卷积：当group=2，卷积核的前一半仅和输入特征图的前一半连接。卷积核的后一半仅和输入特征图的后一半连接。默认值：1。 + - **dilation** (int|tuple, 可选) - 空洞大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积核中的元素沿着深度，高和宽的空洞。如果为单个整数，表示深度，高和宽的空洞都等于该整数。默认值：1。 + - **weight_attr** (ParamAttr, 可选) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **bias_attr** (ParamAttr|bool, 可选) - 指定偏置参数属性的对象。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCDHW"。 + +形状: + + - 输入：:math:`（N，C_{in}， H_{in}， W_{in}）` + + + - 输出：:math:`（N，C_{out}, H_{out}, W_{out}）` + + 其中 + + .. math:: + + & D'_{out}=(D_{in}-1)*strides[0] - pad\_depth\_front - pad\_depth\_back + dilations[0]*(kernel\_size[0]-1)+1\\ + & H'_{out} = (H_{in}-1)*strides[1] - pad\_height\_top - pad\_height\_bottom + dilations[1]*(kernel\_size[1]-1)+1\\ + & W'_{out} = (W_{in}-1)*strides[2]- pad\_width\_left - pad\_width\_right + dilations[2]*(kernel\_size[2]-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])\\ + + 如果 ``padding`` = "SAME": + + .. math:: + & D'_{out} = \frac{(D_{in} + stride[0] - 1)}{stride[0]}\\ + & H'_{out} = \frac{(H_{in} + stride[1] - 1)}{stride[1]}\\ + & W'_{out} = \frac{(W_{in} + stride[2] - 1)}{stride[2]}\\ + + 如果 ``padding`` = "VALID": + + .. math:: + & D'_{out} = (D_{in}-1)*strides[0] + dilations[0]*(kernel\_size[0]-1)+1\\ + & H'_{out} = (H_{in}-1)*strides[1] + dilations[1]*(kernel\_size[1]-1)+1\\ + & W'_{out} = (W_{in}-1)*strides[2] + dilations[2]*(kernel\_size[2]-1)+1 \\ + +抛出异常: + - ``ValueError`` : 如果输入的shape、kernel_size、stride、padding和groups不匹配，抛出ValueError + - ``ValueError`` - 如果 ``data_format`` 既不是"NCHW"也不是"NHWC"。 + - ``ValueError`` - 如果 ``padding`` 是字符串，既不是"SAME"也不是"VALID"。 + - ``ValueError`` - 如果 ``padding`` 含有4个二元组，与批尺寸对应维度的值不为0或者与通道对应维度的值不为0。 + - ``ValueError`` - 如果 ``output_size`` 和 ``filter_size`` 同时为None。 + - ``ShapeError`` - 如果输入不是4-D Tensor。 + - ``ShapeError`` - 如果输入和卷积核的维度大小不相同。 + - ``ShapeError`` - 如果输入的维度大小与 ``stride`` 之差不是2。 + +**代码示例** + +.. code-block:: python + + import numpy as np + import paddle + import paddle.nn as nn + x = np.random.uniform(-1, 1, (2, 4, 8, 8, 8)).astype('float32') + + paddle.disable_static() + x_var = paddle.to_tensor(x) + conv = nn.ConvTranspose3d(4, 6, (3, 3, 3)) + y_var = conv(x_var) + y_np = y_var.numpy() + print(y_np.shape) + + # (2, 6, 10, 10, 10) diff --git a/doc/fluid/api_cn/nn_cn/conv2d_transpose_cn.rst b/doc/fluid/api_cn/nn_cn/conv2d_transpose_cn.rst deleted file mode 100644 index 5acaf87b7..000000000 --- a/doc/fluid/api_cn/nn_cn/conv2d_transpose_cn.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _cn_api_nn_cn_conv2d_transpose: - -conv2d_transpose -------------------------------- -:doc_source: paddle.fluid.layers.conv2d_transpose - - diff --git a/doc/fluid/api_cn/nn_cn/conv3d_cn.rst b/doc/fluid/api_cn/nn_cn/conv3d_cn.rst deleted file mode 100644 index d1ee9627a..000000000 --- a/doc/fluid/api_cn/nn_cn/conv3d_cn.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _cn_api_nn_cn_conv3d: - -conv3d -------------------------------- -:doc_source: paddle.fluid.layers.conv3d - - diff --git a/doc/fluid/api_cn/nn_cn/conv3d_transpose_cn.rst b/doc/fluid/api_cn/nn_cn/conv3d_transpose_cn.rst deleted file mode 100644 index 383fa32f4..000000000 --- a/doc/fluid/api_cn/nn_cn/conv3d_transpose_cn.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _cn_api_nn_cn_conv3d_transpose: - -conv3d_transpose -------------------------------- -:doc_source: paddle.fluid.layers.conv3d_transpose - - diff --git a/doc/fluid/api_cn/nn_cn/functional_cn.rst b/doc/fluid/api_cn/nn_cn/functional_cn.rst index a0bc4267f..d5e5c8e4b 100644 --- a/doc/fluid/api_cn/nn_cn/functional_cn.rst +++ b/doc/fluid/api_cn/nn_cn/functional_cn.rst @@ -28,6 +28,11 @@ functional functional_cn/mse_loss_cn.rst functional_cn/adaptive_avg_pool2d_cn.rst functional_cn/adaptive_avg_pool3d_cn.rst + functional_cn/kl_div_cn.rst + functional_cn/conv2d_cn.rst + functional_cn/conv3d_cn.rst + functional_cn/conv_transpose2d_cn.rst + functional_cn/conv_transpose3d_cn.rst functional_cn/sigmoid_cn.rst functional_cn/adaptive_avg_pool1d_cn.rst functional_cn/adaptive_max_pool1d_cn.rst diff --git a/doc/fluid/api_cn/nn_cn/Conv2D_cn.rst b/doc/fluid/api_cn/nn_cn/functional_cn/conv2d_cn.rst old mode 100644 new mode 100755 similarity index 57% rename from doc/fluid/api_cn/nn_cn/Conv2D_cn.rst rename to doc/fluid/api_cn/nn_cn/functional_cn/conv2d_cn.rst index b374e34f3..aa03a6197 --- a/doc/fluid/api_cn/nn_cn/Conv2D_cn.rst +++ b/doc/fluid/api_cn/nn_cn/functional_cn/conv2d_cn.rst @@ -1,16 +1,9 @@ -Conv2D +conv2d ------------------------------- -.. py:class:: paddle.nn.Conv2d(num_channels, num_filters, filter_size, padding=0, stride=1, dilation=1, groups=None, param_attr=None, bias_attr=None, use_cudnn=True, act=None, name=None, data_format="NCHW", dtype="float32") +.. py:function:: paddle.nn.functional.conv2d(x, weight, bias=None, stride=1, padding=0, dilation=1, groups=1, data_format="NCHW", name=None) -:alias_main: paddle.nn.Conv2D -:alias: paddle.nn.Conv2D,paddle.nn.layer.Conv2D,paddle.nn.layer.conv.Conv2D - - - -**二维卷积层** - -该OP是二维卷积层（convolution2D layer），根据输入、滤波器、步长（stride）、填充（padding）、膨胀比例（dilations）一组参数计算输出特征层大小。输入和输出是NCHW或NHWC格式，其中N是批尺寸，C是通道数，H是特征高度，W是特征宽度。滤波器是MCHW格式，M是输出图像通道数，C是输入图像通道数，H是滤波器高度，W是滤波器宽度。如果组数(groups)大于1，C等于输入图像通道数除以组数的结果。详情请参考UFLDL's : `卷积 `_ 。如果bias_attr不为False，卷积计算会添加偏置项。如果指定了激活函数类型，相应的激活函数会作用在最终结果上。 +该OP是二维卷积层（convolution2d layer），根据输入、卷积核、步长（stride）、填充（padding）、空洞大小（dilations）一组参数计算输出特征层大小。输入和输出是NCHW或NHWC格式，其中N是批尺寸，C是通道数，H是特征高度，W是特征宽度。卷积核是MCHW格式，M是输出图像通道数，C是输入图像通道数，H是卷积核高度，W是卷积核宽度。如果组数(groups)大于1，C等于输入图像通道数除以组数的结果。详情请参考UFLDL's : `卷积 `_ 。如果bias_attr不为False，卷积计算会添加偏置项。如果指定了激活函数类型，相应的激活函数会作用在最终结果上。 对每个输入X，有等式： @@ -20,7 +13,7 @@ Conv2D 其中： - :math:`X` ：输入值，NCHW或NHWC格式的4-D Tensor - - :math:`W` ：滤波器值，MCHW格式的4-D Tensor + - :math:`W` ：卷积核值，MCHW格式的4-D Tensor - :math:`*` ：卷积操作 - :math:`b` ：偏置值，2-D Tensor，形状为 ``[M,1]`` - :math:`\sigma` ：激活函数 @@ -32,7 +25,7 @@ Conv2D 输入形状：:math:`（N,C_{in},H_{in},W_{in}）` - 滤波器形状： :math:`（C_{out},C_{in},H_{f},W_{f}）` + 卷积核形状： :math:`（C_{out},C_{in},H_{f},W_{f}）` - 输出： @@ -61,41 +54,31 @@ Conv2D W_{out} = \frac{\left ( W_{in} -\left ( dilation[1]*\left ( W_{f}-1 \right )+1 \right ) \right )}{stride[1]}+1 + 参数： - - **num_channels** (int) - 输入图像的通道数。 - - **num_filters** (int) - 滤波器（卷积核）的个数。和输出图像通道相同。 - - **filter_size** (int|list|tuple) - 滤波器大小。如果它是一个列表或元组，则必须包含两个整数值：（filter_size_height，filter_size_width）。若为一个整数，filter_size_height = filter_size_width = filter_size。 + - **x** (Tensor) - 输入是形状为 :math:`[N, C, H, W]` 或 :math:`[N, H, W, C]` 的4-D Tensor，N是批尺寸，C是通道数，H是特征高度，W是特征宽度，数据类型为float16, float32或float64。 + - **weight** (Tensor)) - 形状为 :math:`[M, C/g, kH, kW]` 的卷积核。 M是输出通道数， g是分组的个数，kH是卷积核的高度，kW是卷积核的宽度。 + - **bias** (int|list|tuple) - 偏置项，形状为： :math:`[M,]` 。 + - **stride** (int|list|tuple，可选) - 步长大小。卷积核和输入进行卷积计算时滑动的步长。如果它是一个列表或元组，则必须包含两个整型数：（stride_height,stride_width）。若为一个整数，stride_height = stride_width = stride。默认值：1。 - **padding** (int|list|tuple|str，可选) - 填充大小。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法，计算细节可参考上述 ``padding`` = "SAME"或 ``padding`` = "VALID" 时的计算公式。如果它是一个元组或列表，它可以有3种格式：(1)包含4个二元组：当 ``data_format`` 为"NCHW"时为 [[0,0], [0,0], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right]]，当 ``data_format`` 为"NHWC"时为[[0,0], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right], [0,0]]；(2)包含4个整数值：[padding_height_top, padding_height_bottom, padding_width_left, padding_width_right]；(3)包含2个整数值：[padding_height, padding_width]，此时padding_height_top = padding_height_bottom = padding_height， padding_width_left = padding_width_right = padding_width。若为一个整数，padding_height = padding_width = padding。默认值：0。 - - **stride** (int|list|tuple，可选) - 步长大小。滤波器和输入进行卷积计算时滑动的步长。如果它是一个列表或元组，则必须包含两个整型数：（stride_height,stride_width）。若为一个整数，stride_height = stride_width = stride。默认值：1。 - - **dilation** (int|list|tuple，可选) - 膨胀比例大小。空洞卷积时会使用该参数，滤波器对输入进行卷积时，感受野里每相邻两个特征点之间的空洞信息。如果膨胀比例为列表或元组，则必须包含两个整型数：（dilation_height,dilation_width）。若为一个整数，dilation_height = dilation_width = dilation。默认值：1。 - - **groups** (int，可选) - 二维卷积层的组数。根据Alex Krizhevsky的深度卷积神经网络（CNN）论文中的成组卷积：当group=n，输入和滤波器分别根据通道数量平均分为n组，第一组滤波器和第一组输入进行卷积计算，第二组滤波器和第二组输入进行卷积计算，……，第n组滤波器和第n组输入进行卷积计算。默认值：1。 - - **param_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **dilation** (int|list|tuple，可选) - 空洞大小。空洞卷积时会使用该参数，卷积核对输入进行卷积时，感受野里每相邻两个特征点之间的空洞信息。如果空洞大小为列表或元组，则必须包含两个整型数：（dilation_height,dilation_width）。若为一个整数，dilation_height = dilation_width = dilation。默认值：1。 + - **groups** (int，可选) - 二维卷积层的组数。根据Alex Krizhevsky的深度卷积神经网络（CNN）论文中的成组卷积：当group=n，输入和卷积核分别根据通道数量平均分为n组，第一组卷积核和第一组输入进行卷积计算，第二组卷积核和第二组输入进行卷积计算，……，第n组卷积核和第n组输入进行卷积计算。默认值：1。 + - **weight_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 - **bias_attr** （ParamAttr|bool，可选）- 指定偏置参数属性的对象。若 ``bias_attr`` 为bool类型，只支持为False，表示没有偏置参数。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 - - **use_cudnn** （bool，可选）- 是否使用cudnn内核。只有已安装cudnn库时才有效。默认值：True。 - - **act** (str，可选) - 激活函数类型， 如tanh、softmax、sigmoid，relu等，支持列表请参考 :ref:`api_guide_activations` 。如果设为None，则未添加激活函数。默认值：None。 - - **name** (str，可选) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值：None。 - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。 - - **dtype** (str, 可选) – 权重的数据类型，可以为float32或float64。默认为float32。 - + - **name** (str，可选) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值：None。 -属性 -:::::::::::: -.. py:attribute:: weight -本层的可学习参数，类型为 ``Parameter`` +返回：4-D Tensor，数据类型与 ``x`` 一致。返回卷积的结果。 -.. py:attribute:: bias -本层的可学习偏置，类型为 ``Parameter`` - -返回: 无。 +返回类型：Tensor。 抛出异常： - - ``ValueError`` - 如果 ``use_cudnn`` 不是bool值。 - ``ValueError`` - 如果 ``data_format`` 既不是"NCHW"也不是"NHWC"。 - ``ValueError`` - 如果 ``input`` 的通道数未被明确定义。 - ``ValueError`` - 如果 ``padding`` 是字符串，既不是"SAME"也不是"VALID"。 - ``ValueError`` - 如果 ``padding`` 含有4个二元组，与批尺寸对应维度的值不为0或者与通道对应维度的值不为0。 - ``ShapeError`` - 如果输入不是4-D Tensor。 - - ``ShapeError`` - 如果输入和滤波器的维度大小不相同。 + - ``ShapeError`` - 如果输入和卷积核的维度大小不相同。 - ``ShapeError`` - 如果输入的维度大小与 ``stride`` 之差不是2。 - ``ShapeError`` - 如果输出的通道数不能被 ``groups`` 整除。 @@ -104,17 +87,20 @@ Conv2D .. code-block:: python - import numpy as np - from paddle import fluid - import paddle.fluid.dygraph as dg - from paddle import nn - x = np.random.uniform(-1, 1, (2, 4, 8, 8)).astype('float32') - place = fluid.CPUPlace() - with dg.guard(place): - x_var = dg.to_variable(x) - conv = nn.Conv2D(4, 6, (3, 3)) - y_var = conv(x_var) - y_np = y_var.numpy() - print(y_np.shape) - - # (2, 6, 6, 6) + import paddle + import paddle.nn.functional as F + import numpy as np + + x = np.random.randn(2, 3, 8, 8).astype(np.float32) + w = np.random.randn(6, 3, 3, 3).astype(np.float32) + + paddle.disable_static() + + x_var = paddle.to_tensor(x) + w_var = paddle.to_tensor(w) + y_var = F.conv2d(x_var, w_var) + y_np = y_var.numpy() + + print(y_np.shape) + + # (2, 6, 6, 6) \ No newline at end of file diff --git a/doc/fluid/api_cn/nn_cn/functional_cn/conv3d_cn.rst b/doc/fluid/api_cn/nn_cn/functional_cn/conv3d_cn.rst new file mode 100755 index 000000000..a96871b1c --- /dev/null +++ b/doc/fluid/api_cn/nn_cn/functional_cn/conv3d_cn.rst @@ -0,0 +1,83 @@ +conv3d +------------------------------- + +.. py:function:: paddle.nn.functional.conv3d(x, weight, bias=None, stride=1, padding=0, dilation=1, groups=1, data_format="NCHW", name=None) + +该OP是三维卷积层（convolution3D layer），根据输入、卷积核、步长（stride）、填充（padding）、空洞大小（dilations）一组参数计算得到输出特征层大小。输入和输出是NCDHW或NDWHC格式，其中N是批尺寸，C是通道数，D是特征层深度，H是特征层高度，W是特征层宽度。三维卷积（Convlution3D）和二维卷积（Convlution2D）相似，但多了一维深度信息（depth）。如果bias_attr不为False，卷积计算会添加偏置项。 + +对每个输入X，有等式： + +.. math:: + + Out = \sigma \left ( W * X + b \right ) + +其中： + - :math:`X` ：输入值，NCDHW或NDHWC格式的5-D Tensor + - :math:`W` ：卷积核值，MCDHW格式的5-D Tensor + - :math:`*` ：卷积操作 + - :math:`b` ：偏置值，2-D Tensor，形为 ``[M,1]`` + - :math:`\sigma` ：激活函数 + - :math:`Out` ：输出值, NCDHW或NDHWC格式的5-D Tensor，和 ``X`` 的形状可能不同 + +**示例** + +- 输入： + + 输入形状： :math:`(N, C_{in}, D_{in}, H_{in}, W_{in})` + + 卷积核形状： :math:`(C_{out}, C_{in}, D_f, H_f, W_f)` + +- 输出： + + 输出形状： :math:`(N, C_{out}, D_{out}, H_{out}, W_{out})` + +参数： + - **x** (Tensor) - 输入是形状为 :math:`[N, C, H, W]` 或 :math:`[N, H, W, C]` 的4-D Tensor，N是批尺寸，C是通道数，H是特征高度，W是特征宽度，数据类型为float16, float32或float64。 + - **weight** (Tensor) - 形状为 :math:`[M, C/g, kH, kW]` 的卷积核（卷积核）。 M是输出通道数， g是分组的个数，kH是卷积核的高度，kW是卷积核的宽度。 + - **bias** (int|list|tuple) - 偏置项，形状为： :math:`[M,]` 。 + - **stride** (int|list|tuple，可选) - 步长大小。卷积核和输入进行卷积计算时滑动的步长。如果它是一个列表或元组，则必须包含两个整型数：（stride_height,stride_width）。若为一个整数，stride_height = stride_width = stride。默认值：1。 + - **padding** (int|list|tuple|str，可选) - 填充大小。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法，计算细节可参考上述 ``padding`` = "SAME"或 ``padding`` = "VALID" 时的计算公式。如果它是一个元组或列表，它可以有3种格式：(1)包含5个二元组：当 ``data_format`` 为"NCDHW"时为 [[0,0], [0,0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right]]，当 ``data_format`` 为"NDHWC"时为[[0,0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right], [0,0]]；(2)包含6个整数值：[padding_depth_front, padding_depth_back, padding_height_top, padding_height_bottom, padding_width_left, padding_width_right]；(3)包含3个整数值：[padding_depth, padding_height, padding_width]，此时 padding_depth_front = padding_depth_back = padding_depth, padding_height_top = padding_height_bottom = padding_height, padding_width_left = padding_width_right = padding_width。若为一个整数，padding_depth = padding_height = padding_width = padding。默认值：0。 + - **dilation** (int|list|tuple，可选) - 空洞大小。空洞卷积时会使用该参数，卷积核对输入进行卷积时，感受野里每相邻两个特征点之间的空洞信息。如果空洞大小为列表或元组，则必须包含两个整型数：（dilation_height,dilation_width）。若为一个整数，dilation_height = dilation_width = dilation。默认值：1。 + - **groups** (int，可选) - 二维卷积层的组数。根据Alex Krizhevsky的深度卷积神经网络（CNN）论文中的成组卷积：当group=n，输入和卷积核分别根据通道数量平均分为n组，第一组卷积核和第一组输入进行卷积计算，第二组卷积核和第二组输入进行卷积计算，……，第n组卷积核和第n组输入进行卷积计算。默认值：1。 + - **weight_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **bias_attr** （ParamAttr|bool，可选）- 指定偏置参数属性的对象。若 ``bias_attr`` 为bool类型，只支持为False，表示没有偏置参数。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。 + - **name** (str，可选) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值：None。 + +返回：5-D Tensor，数据类型与 ``input`` 一致。返回卷积计算的结果。 + +返回类型：Tensor。 + +抛出异常： + - ``ValueError`` - 如果 ``use_cudnn`` 不是bool值。 + - ``ValueError`` - 如果 ``data_format`` 既不是"NCDHW"也不是"NDHWC"。 + - ``ValueError`` - 如果 ``input`` 的通道数未被明确定义。 + - ``ValueError`` - 如果 ``padding`` 是字符串，既不是"SAME"也不是"VALID"。 + - ``ValueError`` - 如果 ``padding`` 含有5个二元组，与批尺寸对应维度的值不为0或者与通道对应维度的值不为0。 + - ``ShapeError`` - 如果输入不是5-D Tensor。 + - ``ShapeError`` - 如果输入和卷积核的维度大小不相同。 + - ``ShapeError`` - 如果输入的维度大小与 ``stride`` 之差不是2。 + - ``ShapeError`` - 如果输出的通道数不能被 ``groups`` 整除。 + + +**代码示例**： + +.. code-block:: python + + import numpy as np + import paddle + import paddle.nn.functional as F + + x = np.random.randn(2, 3, 8, 8, 8).astype(np.float32) + w = np.random.randn(6, 3, 3, 3, 3).astype(np.float32) + + paddle.disable_static() + + x_var = paddle.to_tensor(x) + w_var = paddle.to_tensor(w) + y_var = F.conv3d(x_var, w_var) + + y_np = y_var.numpy() + print(y_np.shape) + + # (2, 6, 6, 6, 6) \ No newline at end of file diff --git a/doc/fluid/api_cn/nn_cn/functional_cn/conv_transpose2d_cn.rst b/doc/fluid/api_cn/nn_cn/functional_cn/conv_transpose2d_cn.rst new file mode 100644 index 000000000..b2b5b68eb --- /dev/null +++ b/doc/fluid/api_cn/nn_cn/functional_cn/conv_transpose2d_cn.rst @@ -0,0 +1,120 @@ + +conv_transpose2d +------------------------------- + + +.. py:function:: paddle.nn.functional.conv_transpose2d(x, weight, bias=None, stride=1, padding=0, output_padding=0, groups=1, dilation=1, data_format='NCHW', output_size=None, name=None) + + + +二维转置卷积层（Convlution2D transpose layer） + +该层根据输入（input）、卷积核（kernel）和空洞大小（dilations）、步长（stride）、填充（padding）来计算输出特征层大小或者通过output_size指定输出特征层大小。输入(Input)和输出(Output)为NCHW或NHWC格式，其中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或NHWC格式的4-D Tensor + - :math:`W` : 卷积核，具有NCHW格式的4-D Tensor + - :math:`*` : 卷积计算（注意：转置卷积本质上的计算还是卷积） + - :math:`b` : 偏置（bias），2-D Tensor，形状为 ``[M,1]`` + - :math:`σ` : 激活函数 + - :math:`Out` : 输出值，NCHW或NHWC格式的4-D Tensor， 和 ``X`` 的形状可能不同 + +**示例** + +- 输入： + + 输入Tensor的形状： :math:`（N，C_{in}， H_{in}， W_{in}）` + + 卷积核的形状 ： :math:`（C_{in}, C_{out}, H_f, W_f）` + +- 输出： + + 输出Tensor的形状 ： :math:`（N，C_{out}, H_{out}, W_{out}）` + +其中 + +.. math:: + + & H'_{out} = (H_{in}-1)*strides[0] - pad\_height\_top - pad\_height\_bottom + dilations[0]*(H_f-1)+1\\ + & W'_{out} = (W_{in}-1)*strides[1]- pad\_width\_left - pad\_width\_right + dilations[1]*(W_f-1)+1 \\ + & H_{out}\in[H'_{out},H'_{out} + strides[0])\\ + & W_{out}\in[W'_{out},W'_{out} + strides[1])\\ + +如果 ``padding`` = "SAME": + +.. math:: + & H'_{out} = \frac{(H_{in} + stride[0] - 1)}{stride[0]}\\ + & W'_{out} = \frac{(W_{in} + stride[1] - 1)}{stride[1]}\\ + +如果 ``padding`` = "VALID": + +.. math:: + & H'_{out} = (H_{in}-1)*strides[0] + dilations[0]*(H_f-1)+1\\ + & W'_{out} = (W_{in}-1)*strides[1] + dilations[1]*(W_f-1)+1 \\ + +注意： + +如果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]` ）。 + +由于转置卷积可以当成是卷积的反向计算，而根据卷积的输入输出计算公式来说，不同大小的输入特征层可能对应着相同大小的输出特征层，所以对应到转置卷积来说，固定大小的输入特征层对应的输出特征层大小并不唯一。 + +如果指定了output_size， ``conv2d_transpose`` 可以自动计算卷积核的大小。 + +参数: + - **x** (Tensor) - 输入是形状为 :math:`[N, C, H, W]` 或 :math:`[N, H, W, C]` 的4-D Tensor，N是批尺寸，C是通道数，H是特征高度，W是特征宽度，数据类型为float16, float32或float64。 + - **weight** (Tensor) - 形状为 :math:`[C, M/g, kH, kW]` 的卷积核（卷积核）。 M是输出通道数， g是分组的个数，kH是卷积核的高度，kW是卷积核的宽度。 + - **bias** (int|list|tuple) - 偏置项，形状为： :math:`[M,]` 。 + - **stride** (int|list|tuple，可选) - 步长大小。如果 ``stride`` 为元组，则必须包含两个整型数，分别表示垂直和水平滑动步长。否则，表示垂直和水平滑动步长均为 ``stride`` 。默认值：1。 + - **padding** (int|list|tuple|str，可选) - 填充大小。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法，计算细节可参考上述 ``padding`` = "SAME"或 ``padding`` = "VALID" 时的计算公式。如果它是一个元组或列表，它可以有3种格式：(1)包含4个二元组：当 ``data_format`` 为"NCHW"时为 [[0,0], [0,0], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right]]，当 ``data_format`` 为"NHWC"时为[[0,0], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right], [0,0]]；(2)包含4个整数值：[padding_height_top, padding_height_bottom, padding_width_left, padding_width_right]；(3)包含2个整数值：[padding_height, padding_width]，此时padding_height_top = padding_height_bottom = padding_height， padding_width_left = padding_width_right = padding_width。若为一个整数，padding_height = padding_width = padding。默认值：0。 + - **output_padding** (int|list|tuple, optional): 输出形状上一侧额外添加的大小. 默认值: 0. + - **dilation** (int|list|tuple，可选) - 空洞大小。空洞卷积时会使用该参数，卷积核对输入进行卷积时，感受野里每相邻两个特征点之间的空洞信息。如果空洞大小为列表或元组，则必须包含两个整型数：（dilation_height,dilation_width）。若为一个整数，dilation_height = dilation_width = dilation。默认值：1。 + - **groups** (int，可选) - 二维卷积层的组数。根据Alex Krizhevsky的深度卷积神经网络（CNN）论文中的成组卷积：当group=n，输入和卷积核分别根据通道数量平均分为n组，第一组卷积核和第一组输入进行卷积计算，第二组卷积核和第二组输入进行卷积计算，……，第n组卷积核和第n组输入进行卷积计算。默认值：1。 + - **weight_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **bias_attr** （ParamAttr|bool，可选）- 指定偏置参数属性的对象。若 ``bias_attr`` 为bool类型，只支持为False，表示没有偏置参数。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。 + - **name** (str，可选) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值：None。 + + +返回：4-D Tensor，数据类型与 ``input`` 一致。如果未指定激活层，则返回转置卷积计算的结果，如果指定激活层，则返回转置卷积和激活计算之后的最终结果。 + +返回类型：Variable + +抛出异常: + - ``ValueError`` : 如果输入的shape、kernel_size、stride、padding和groups不匹配，抛出ValueError + - ``ValueError`` - 如果 ``data_format`` 既不是"NCHW"也不是"NHWC"。 + - ``ValueError`` - 如果 ``padding`` 是字符串，既不是"SAME"也不是"VALID"。 + - ``ValueError`` - 如果 ``padding`` 含有4个二元组，与批尺寸对应维度的值不为0或者与通道对应维度的值不为0。 + - ``ValueError`` - 如果 ``output_size`` 和 ``filter_size`` 同时为None。 + - ``ShapeError`` - 如果输入不是4-D Tensor。 + - ``ShapeError`` - 如果输入和卷积核的维度大小不相同。 + - ``ShapeError`` - 如果输入的维度大小与 ``stride`` 之差不是2。 + +**代码示例** + +.. code-block:: python + + import numpy as np + import paddle + import paddle.nn.functional as F + + x = np.random.randn(2, 3, 8, 8).astype(np.float32) + w = np.random.randn(3, 6, 3, 3).astype(np.float32) + + paddle.disable_static() + x_var = paddle.to_tensor(x) + w_var = paddle.to_tensor(w) + y_var = F.conv_transpose2d(x_var, w_var) + y_np = y_var.numpy() + print(y_np.shape) + + # (2, 6, 10, 10) + + diff --git a/doc/fluid/api_cn/nn_cn/functional_cn/conv_transpose3d_cn.rst b/doc/fluid/api_cn/nn_cn/functional_cn/conv_transpose3d_cn.rst new file mode 100644 index 000000000..4c78cc746 --- /dev/null +++ b/doc/fluid/api_cn/nn_cn/functional_cn/conv_transpose3d_cn.rst @@ -0,0 +1,124 @@ +conv_transpose3d +------------------------------- + + +.. py:function:: paddle.nn.functional.conv_transpose3d(x, weight, bias=None, stride=1, padding=0, output_padding=0, groups=1, dilation=1, data_format='NCHW', output_size=None, name=None) + + + + +三维转置卷积层（Convlution3d transpose layer) + +该层根据输入（input）、卷积核（kernel）和卷积核空洞大小（dilations）、步长（stride）、填充（padding）来计算输出特征层大小或者通过output_size指定输出特征层大小。输入(Input)和输出(Output)为NCDHW或者NDHWC格式。其中N为批尺寸，C为通道数（channel），D为特征深度，H为特征层高度，W为特征层宽度。转置卷积的计算过程相当于卷积的反向计算。转置卷积又被称为反卷积（但其实并不是真正的反卷积）。欲了解卷积转置层细节，请参考下面的说明和 参考文献_ 。如果参数bias_attr不为False, 转置卷积计算会添加偏置项。 + +.. _参考文献: http://www.matthewzeiler.com/wp-content/uploads/2017/07/cvpr2010.pdf + +输入 :math:`X` 和输出 :math:`Out` 函数关系如下： + +.. math:: + \\Out=\sigma (W*X+b)\\ + +其中： + - :math:`X` : 输入，具有NCDHW或NDHWC格式的5-D Tensor + - :math:`W` : 卷积核，具有NCDHW格式的5-D Tensor + - :math:`*` : 卷积操作（注意：转置卷积本质上的计算还是卷积） + - :math:`b` : 偏置（bias），2-D Tensor，形状为 ``[M,1]`` + - :math:`σ` : 激活函数 + - :math:`Out` : 输出值，NCDHW或NDHWC格式的5-D Tensor，和 ``X`` 的形状可能不同 + +**示例** + +输入: + + 输入的shape：:math:`（N,C_{in}, D_{in}, H_{in}, W_{in}）` + + 卷积核的shape：:math:`（C_{in}, C_{out}, D_f, H_f, W_f）` + +输出: + + 输出的shape：:math:`（N,C_{out}, D_{out}, H_{out}, W_{out}）` + + +其中： + +.. math:: + + & D'_{out}=(D_{in}-1)*strides[0] - pad\_depth\_front - pad\_depth\_back + dilations[0]*(D_f-1)+1\\ + & H'_{out}=(H_{in}-1)*strides[1] - pad\_height\_top - pad\_height\_bottom + dilations[1]*(H_f-1)+1\\ + & W'_{out}=(W_{in}-1)*strides[2] - pad\_width\_left - pad\_width\_right + 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])\\ + +如果 ``padding`` = "SAME": + +.. math:: + D'_{out} = \frac{(D_{in} + stride[0] - 1)}{stride[0]}\\ + H'_{out} = \frac{(H_{in} + stride[1] - 1)}{stride[1]}\\ + W'_{out} = \frac{(W_{in} + stride[2] - 1)}{stride[2]}\\ + +如果 ``padding`` = "VALID": + +.. math:: + D'_{out}=(D_{in}-1)*strides[0] + dilations[0]*(D_f-1)+1\\ + H'_{out}=(H_{in}-1)*strides[1] + dilations[1]*(H_f-1)+1\\ + W'_{out}=(W_{in}-1)*strides[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， ``conv_transpose3d`` 可以自动计算卷积核的大小。 + +参数: + - **x** (Tensor) - 形状为 :math:`[N, C, D, H, W]` 或 :math:`[N, D, H, W, C]` 的5-D Tensor，N是批尺寸，C是通道数，D是特征深度，H是特征高度，W是特征宽度，数据类型：float32或float64。 + - **weight** (Tensor) - 形状为 :math:`[C, M/g, kD, kH, kW]` 的卷积核。 M是输出通道数， g是分组的个数，kD是卷积核的深度，kH是卷积核的高度，kW是卷积核的宽度。 + - **bias** (int|list|tuple) - 偏置项，形状为： :math:`[M,]` 。 + - **stride** (int|list|tuple，可选) - 步长大小。如果 ``stride`` 为元组或列表，则必须包含三个整型数，分别表示深度，垂直和水平滑动步长。否则，表示深度，垂直和水平滑动步长均为 ``stride`` 。默认值：1。 + - **padding** (int|list|tuple|str，可选) - 填充padding大小。padding参数在输入特征层每边添加 ``dilation * (kernel_size - 1) - padding`` 个0。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法，计算细节可参考上述 ``padding`` = "SAME"或 ``padding`` = "VALID" 时的计算公式。如果它是一个元组或列表，它可以有3种格式：(1)包含5个二元组：当 ``data_format`` 为"NCDHW"时为 [[0,0], [0,0], [pad_depth_front, pad_depth_back], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right]]，当 ``data_format`` 为"NDHWC"时为[[0,0], [pad_depth_front, pad_depth_back], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right], [0,0]]；(2)包含6个整数值：[pad_depth_front, pad_depth_back, pad_height_top, pad_height_bottom, pad_width_left, pad_width_right]；(3)包含3个整数值：[pad_depth, pad_height, pad_width]，此时 pad_depth_front = pad_depth_back = pad_depth, pad_height_top = pad_height_bottom = pad_height, pad_width_left = pad_width_right = pad_width。若为一个整数，pad_depth = pad_height = pad_width = padding。默认值：0。 + - **output_padding** (int|list|tuple, optional): 输出形状上一侧额外添加的大小. 默认值: 0. + - **dilation** (int|list|tuple，可选) - 空洞大小。空洞卷积时会使用该参数，卷积核对输入进行卷积时，感受野里每相邻两个特征点之间的空洞信息。如果空洞大小为列表或元组，则必须包含两个整型数：（dilation_height,dilation_width）。若为一个整数，dilation_height = dilation_width = dilation。默认值：1。 + - **groups** (int，可选) - 三维转置卷积层的组数。从Alex Krizhevsky的CNN Deep论文中的群卷积中受到启发，当group=2时，输入和卷积核分别根据通道数量平均分为两组，第一组卷积核和第一组输入进行卷积计算，第二组卷积核和第二组输入进行卷积计算。默认：group = 1。 + - **weight_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **bias_attr** （ParamAttr|bool，可选）- 指定偏置参数属性的对象。若 ``bias_attr`` 为bool类型，只支持为False，表示没有偏置参数。默认值为None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N是批尺寸，C是通道数，H是特征高度，W是特征宽度。默认值："NCHW"。 + - **name** (str，可选) – 具体用法请参见 :ref:`cn_api_guide_Name` ，一般无需设置，默认值：None。 + + +返回：5-D Tensor，数据类型与 ``input`` 一致。如果未指定激活层，则返回转置卷积计算的结果，如果指定激活层，则返回转置卷积和激活计算之后的最终结果。 + +返回类型：Tensor + +抛出异常: + - ``ValueError`` - 如果输入的shape、kernel_size、stride、padding和groups不匹配。 + - ``ValueError`` - 如果 ``data_format`` 既不是"NCDHW"也不是"NDHWC"。 + - ``ValueError`` - 如果 ``padding`` 是字符串，既不是"SAME"也不是"VALID"。 + - ``ValueError`` - 如果 ``padding`` 含有5个二元组，与批尺寸对应维度的值不为0或者与通道对应维度的值不为0。 + - ``ValueError`` - 如果 ``output_size`` 和 ``filter_size`` 同时为None。 + - ``ShapeError`` - 如果输入不是5-D Tensor。 + - ``ShapeError`` - 如果输入和卷积核的维度大小不相同。 + - ``ShapeError`` - 如果输入的维度大小与 ``stride`` 之差不是2。 + +**代码示例** + +.. code-block:: python + + import numpy as np + + import paddle + import paddle.nn.functional as F + + x = np.random.randn(2, 3, 8, 8, 8).astype(np.float32) + w = np.random.randn(3, 6, 3, 3, 3).astype(np.float32) + + paddle.disable_static() + + x_var = paddle.to_tensor(x) + w_var = paddle.to_tensor(w) + y_var = F.conv_transpose3d(x_var, w_var) + y_np = y_var.numpy() + print(y_np.shape) + + # (2, 6, 10, 10, 10) diff --git a/doc/fluid/api_cn/nn_cn/functional_cn/kl_div_cn.rst b/doc/fluid/api_cn/nn_cn/functional_cn/kl_div_cn.rst new file mode 100644 index 000000000..87aeca464 --- /dev/null +++ b/doc/fluid/api_cn/nn_cn/functional_cn/kl_div_cn.rst @@ -0,0 +1,65 @@ +kl_div +------------------------------- + +.. py:function:: paddle.nn.functional.kl_div(input, label, reduction='mean', name=None) + +该算子计算输入(Input)和输入(Label)之间的Kullback-Leibler散度损失。注意其中输入(Input)应为对数概率值，输入(Label)应为概率值。 + +kL发散损失计算如下： + +.. math:: + + l(input, label) = label * (log(label) - input) + + +当 ``reduction`` 为 ``none`` 时，输出损失与输入（x）形状相同，各点的损失单独计算，不会对结果做reduction 。 + +当 ``reduction`` 为 ``mean`` 时，输出损失为[1]的形状，输出为所有损失的平均值。 + +当 ``reduction`` 为 ``sum`` 时，输出损失为[1]的形状，输出为所有损失的总和。 + +当 ``reduction`` 为 ``batchmean`` 时，输出损失为[N]的形状，N为批大小，输出为所有损失的总和除以批量大小。 + +参数: + - **input** (Tensor) - KL散度损失算子的输入张量。维度为[N, \*]的多维Tensor，其中N是批大小，\*表示任何数量的附加维度，数据类型为float32或float64。 + - **label** (Tensor) - KL散度损失算子的张量。与输入 ``input`` 的维度和数据类型一致的多维Tensor。 + - **reduction** (str，可选) - 要应用于输出的reduction类型，可用类型为‘none’ | ‘batchmean’ | ‘mean’ | ‘sum’，‘none’表示无reduction，‘batchmean’ 表示输出的总和除以批大小，‘mean’ 表示所有输出的平均值，‘sum’表示输出的总和。 + - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置。默认值：None。 + +返回：Tensor KL散度损失。 + + +**代码示例：** + +.. code-block:: python + + import paddle + import numpy as np + import paddle.nn.functional as F + + paddle.disable_static() + + shape = (5, 20) + input = np.random.uniform(-10, 10, shape).astype('float32') + target = np.random.uniform(-10, 10, shape).astype('float32') + + # 'batchmean' reduction, loss shape will be [N] + pred_loss = F.kl_div(paddle.to_tensor(input), + paddle.to_tensor(target), reduction='batchmean') + # shape=[5] + + # 'mean' reduction, loss shape will be [1] + pred_loss = F.kl_div(paddle.to_tensor(input), + paddle.to_tensor(target), reduction='mean') + # shape=[1] + + # 'sum' reduction, loss shape will be [1] + pred_loss = F.kl_div(paddle.to_tensor(input), + paddle.to_tensor(target), reduction='sum') + # shape=[1] + + # 'none' reduction, loss shape is same with input shape + pred_loss = F.kl_div(paddle.to_tensor(input), + paddle.to_tensor(target), reduction='none') + # shape=[5, 20] + diff --git a/doc/fluid/api_cn/nn_cn/kldiv_loss_cn.rst b/doc/fluid/api_cn/nn_cn/kldiv_loss_cn.rst deleted file mode 100644 index 5660c0d67..000000000 --- a/doc/fluid/api_cn/nn_cn/kldiv_loss_cn.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _cn_api_nn_cn_kldiv_loss: - -kldiv_loss -------------------------------- -:doc_source: paddle.fluid.layers.kldiv_loss - - diff --git a/doc/fluid/api_cn/nn_cn/loss_cn.rst b/doc/fluid/api_cn/nn_cn/loss_cn.rst index 7ed0c02b7..24081ffd6 100644 --- a/doc/fluid/api_cn/nn_cn/loss_cn.rst +++ b/doc/fluid/api_cn/nn_cn/loss_cn.rst @@ -15,5 +15,6 @@ loss loss_cn/MarginRankingLoss_cn.rst loss_cn/MSELoss_cn.rst loss_cn/NLLLoss_cn.rst + loss_cn/KLDivLoss_cn.rst loss_cn/SmoothL1Loss.rst loss_cn/CTCLoss_cn.rst diff --git a/doc/fluid/api_cn/nn_cn/loss_cn/KLDivLoss_cn.rst b/doc/fluid/api_cn/nn_cn/loss_cn/KLDivLoss_cn.rst new file mode 100644 index 000000000..49267b8a1 --- /dev/null +++ b/doc/fluid/api_cn/nn_cn/loss_cn/KLDivLoss_cn.rst @@ -0,0 +1,68 @@ +KLDivLoss +------------------------------- + +.. py:class:: paddle.nn.loss.KLDivLoss(reduction='mean') + +该算子计算输入(Input)和输入(Label)之间的Kullback-Leibler散度损失。注意其中输入(Input)应为对数概率值，输入(Label)应为概率值。 + +kL发散损失计算如下： + +.. math:: + + l(input, label) = label * (log(label) - input) + + +当 ``reduction`` 为 ``none`` 时，输出损失与输入（input）形状相同，各点的损失单独计算，不会对结果做reduction 。 + +当 ``reduction`` 为 ``mean`` 时，输出损失为[1]的形状，输出为所有损失的平均值。 + +当 ``reduction`` 为 ``sum`` 时，输出损失为[1]的形状，输出为所有损失的总和。 + +当 ``reduction`` 为 ``batchmean`` 时，输出损失为[N]的形状，N为批大小，输出为所有损失的总和除以批量大小。 + +参数: + - **reduction** (str，可选) - 要应用于输出的reduction类型，可用类型为‘none’ | ‘batchmean’ | ‘mean’ | ‘sum’，‘none’表示无reduction，‘batchmean’ 表示输出的总和除以批大小，‘mean’ 表示所有输出的平均值，‘sum’表示输出的总和。 + +形状: + - **input** (Tensor): - 输入的Tensor，维度是[N, *], 其中N是batch size， `*` 是任意数量的额外维度。数据类型为：float32、float64。 + - **label** (Tensor): - 标签，维度是[N, *], 与 ``input`` 相同。数据类型为：float32、float64。 + - **output** (Tensor): - 输入 ``input`` 和标签 ``label`` 间的kl散度。如果 `reduction` 是 ``'none'``, 则输出Loss的维度为 [N, *], 与输入 ``input`` 相同。如果 `reduction` 是 ``'batchmean'`` 、 ``'mean'`` 或 ``'sum'``, 则输出Loss的维度为 [1]。 + +**代码示例：** + +.. code-block:: python + + import paddle + import numpy as np + import paddle.nn as nn + + paddle.disable_static() + + shape = (5, 20) + x = np.random.uniform(-10, 10, shape).astype('float32') + target = np.random.uniform(-10, 10, shape).astype('float32') + + # 'batchmean' reduction, loss shape will be [N] + kldiv_criterion = nn.KLDivLoss(reduction='batchmean') + pred_loss = kldiv_criterion(paddle.to_tensor(x), + paddle.to_tensor(target)) + # shape=[5] + + # 'mean' reduction, loss shape will be [1] + kldiv_criterion = nn.KLDivLoss(reduction='mean') + pred_loss = kldiv_criterion(paddle.to_tensor(x), + paddle.to_tensor(target)) + # shape=[1] + + # 'sum' reduction, loss shape will be [1] + kldiv_criterion = nn.KLDivLoss(reduction='sum') + pred_loss = kldiv_criterion(paddle.to_tensor(x), + paddle.to_tensor(target)) + # shape=[1] + + # 'none' reduction, loss shape is same with X shape + kldiv_criterion = nn.KLDivLoss(reduction='none') + pred_loss = kldiv_criterion(paddle.to_tensor(x), + paddle.to_tensor(target)) + # shape=[5, 20] + -- GitLab