From e902c36cdf5bf2b2c05a41de6f30b9b7c84071b8 Mon Sep 17 00:00:00 2001 From: chengduoZH Date: Thu, 21 Dec 2017 12:42:48 +0800 Subject: [PATCH 1/3] add conv2d_python doc --- python/paddle/v2/fluid/layers/nn.py | 66 ++++++++++++++++++++++++++--- 1 file changed, 61 insertions(+), 5 deletions(-) diff --git a/python/paddle/v2/fluid/layers/nn.py b/python/paddle/v2/fluid/layers/nn.py index 1db63fbfe8..f49a958a0f 100644 --- a/python/paddle/v2/fluid/layers/nn.py +++ b/python/paddle/v2/fluid/layers/nn.py @@ -481,11 +481,67 @@ def conv2d(input, act=None, name=None): """ - This function creates the op for a 2-dimensional Convolution. - This is performed using the parameters of filters(size, dimensionality etc) - , stride and other configurations for a Convolution operation. - This funciton can also append an activation on top of the - conv-2d output, if mentioned in the input parameters. + **Convlution2D Layer** + + The convolution2D layer calculates the output based on the input, filter + and strides, paddings, dilations, groups parameters. Input(Input) and Output(Output) + are in NCHW format. Where N is batch size, C is the number of channels, H is the height + of the feature, and W is the width of the feature. + The details of convolution layer, please refer UFLDL's `convolution, + `_ . + If bias_attr and activation type are provided, bias is added to the output of the convolution, + and the corresponding activation function is applied to the final result. + For each input :math:`X`, the equation is: + + .. math:: + + Out = \sigma (W\ast X + b) + + In the above equation: + + * :math:`X`: Input value, a tensor with NCHW format. + * :math:`W`: Filter value, a tensor with MCHW format. + * :math:`b`: Bias, . + * :math:\sigma : Activation function. + * :math:`Out`: Output value, the shape of :math:`Out` and :math:`X` may be different. + + Example: + + Input: + Input shape: $(N, C_{in}, H_{in}, W_{in})$ + Filter shape: $(C_{out}, C_{in}, H_f, W_f)$ + Output: + Output shape: $(N, C_{out}, H_{out}, W_{out})$ + Where + $$ + H_{out}= \\frac{(H_{in} + 2 * paddings[0] - (dilations[0] * (H_f - 1) + 1))}{strides[0]}+ 1 \\ + W_{out}= \\frac{(W_{in} + 2 * paddings[1] - (dilations[1] * (W_f - 1) + 1))}{strides[1]}+ 1 + $$ + + All the input variables are passed in as local variables to the LayerHelper + constructor. + + Args: + input(Variable): Input tensors. The format of input tensor is NCHW. + num_filters(int): Number of filters + filter_size(list/int): Filter size of Conv2d Layer + stride(list/int, optional): Strides(h_s, w_s) of Conv2d Layer. Default: 1 + padding(list/int, optional): Paddings(h_pad, w_pad) of Conv2d Layer. Default: 0 + groups(int, optional): The groups number of the Conv2d Layer. Default: 1 + param_attr(ParamAttr): The parameters to the Conv2d Layer. Default: None + bias_attr(ParamAttr): Bias parameter for the Conv2d layer. Default: None + act(str): Activation type. Default: None + name(str): Name/alias of the function + + Returns: + Variable: The tensor variable storing the convolution and \ + non-linearity activation result. + + Examples: + .. code-block:: python + + 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") """ if stride is None: From 1d936f1dfaa884c830723d1eb4a77ef6c1171294 Mon Sep 17 00:00:00 2001 From: chengduoZH Date: Sat, 23 Dec 2017 17:01:30 +0800 Subject: [PATCH 2/3] refine --- python/paddle/v2/fluid/layers/nn.py | 31 +++++++++++++++++++---------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/python/paddle/v2/fluid/layers/nn.py b/python/paddle/v2/fluid/layers/nn.py index f49a958a0f..1240b2576f 100644 --- a/python/paddle/v2/fluid/layers/nn.py +++ b/python/paddle/v2/fluid/layers/nn.py @@ -489,34 +489,40 @@ def conv2d(input, of the feature, and W is the width of the feature. The details of convolution layer, please refer UFLDL's `convolution, `_ . - If bias_attr and activation type are provided, bias is added to the output of the convolution, + If bias attribution and activation type are provided, bias is added to the output of the convolution, and the corresponding activation function is applied to the final result. For each input :math:`X`, the equation is: + .. math:: - Out = \sigma (W\ast X + b) + Out = \sigma (W \\ast X + b) - In the above equation: + In the above equation: * :math:`X`: Input value, a tensor with NCHW format. * :math:`W`: Filter value, a tensor with MCHW format. - * :math:`b`: Bias, . - * :math:\sigma : Activation function. + * :math: \\ast : Convolution operation. + * :math:`b`: Bias value, a 2-D tensor with shape [M, 1]. + * :math: \\sigma : Activation function. * :math:`Out`: Output value, the shape of :math:`Out` and :math:`X` may be different. Example: - Input: + - Input: Input shape: $(N, C_{in}, H_{in}, W_{in})$ + Filter shape: $(C_{out}, C_{in}, H_f, W_f)$ - Output: + + - Output: Output shape: $(N, C_{out}, H_{out}, W_{out})$ Where - $$ - H_{out}= \\frac{(H_{in} + 2 * paddings[0] - (dilations[0] * (H_f - 1) + 1))}{strides[0]}+ 1 \\ + .. math:: + + H_{out}= \\frac{(H_{in} + 2 * paddings[0] - (dilations[0] * (H_f - 1) + 1))}{strides[0]}+ 1 + W_{out}= \\frac{(W_{in} + 2 * paddings[1] - (dilations[1] * (W_f - 1) + 1))}{strides[1]}+ 1 - $$ + All the input variables are passed in as local variables to the LayerHelper constructor. @@ -537,10 +543,13 @@ def conv2d(input, Variable: The tensor variable storing the convolution and \ non-linearity activation result. + Raises: + ValueError: If the shapes of input, filter_size, stride, padding and groups mismatch. + Examples: .. code-block:: python - data = fluid.layers.data(name='data', shape=[3,32, 32], dtype='float32') + 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") """ From 3d2b2d408f9010ca8c5eda80642d5b9431936f00 Mon Sep 17 00:00:00 2001 From: chengduoZH Date: Wed, 27 Dec 2017 18:43:49 +0800 Subject: [PATCH 3/3] refine doc --- python/paddle/v2/fluid/layers/nn.py | 60 +++++++++++++++-------------- 1 file changed, 32 insertions(+), 28 deletions(-) diff --git a/python/paddle/v2/fluid/layers/nn.py b/python/paddle/v2/fluid/layers/nn.py index 1240b2576f..a51275282c 100644 --- a/python/paddle/v2/fluid/layers/nn.py +++ b/python/paddle/v2/fluid/layers/nn.py @@ -478,8 +478,7 @@ def conv2d(input, groups=None, param_attr=None, bias_attr=None, - act=None, - name=None): + act=None): """ **Convlution2D Layer** @@ -498,46 +497,51 @@ def conv2d(input, Out = \sigma (W \\ast X + b) - In the above equation: + In the above equation: * :math:`X`: Input value, a tensor with NCHW format. * :math:`W`: Filter value, a tensor with MCHW format. - * :math: \\ast : Convolution operation. + * :math:`\\ast`: Convolution operation. * :math:`b`: Bias value, a 2-D tensor with shape [M, 1]. - * :math: \\sigma : Activation function. + * :math:`\\sigma`: Activation function. * :math:`Out`: Output value, the shape of :math:`Out` and :math:`X` may be different. Example: - - Input: - Input shape: $(N, C_{in}, H_{in}, W_{in})$ + Input: + Input shape: $(N, C_{in}, H_{in}, W_{in})$ - Filter shape: $(C_{out}, C_{in}, H_f, W_f)$ + Filter shape: $(C_{out}, C_{in}, H_f, W_f)$ - - Output: - Output shape: $(N, C_{out}, H_{out}, W_{out})$ + Output: + Output shape: $(N, C_{out}, H_{out}, W_{out})$ Where - .. math:: - - H_{out}= \\frac{(H_{in} + 2 * paddings[0] - (dilations[0] * (H_f - 1) + 1))}{strides[0]}+ 1 - - W_{out}= \\frac{(W_{in} + 2 * paddings[1] - (dilations[1] * (W_f - 1) + 1))}{strides[1]}+ 1 + .. math:: - - All the input variables are passed in as local variables to the LayerHelper - constructor. + H_{out}&= \\frac{(H_{in} + 2 * paddings[0] - (dilations[0] * (H_f - 1) + 1))}{strides[0]} + 1 \\\\ + W_{out}&= \\frac{(W_{in} + 2 * paddings[1] - (dilations[1] * (W_f - 1) + 1))}{strides[1]} + 1 Args: - input(Variable): Input tensors. The format of input tensor is NCHW. - num_filters(int): Number of filters - filter_size(list/int): Filter size of Conv2d Layer - stride(list/int, optional): Strides(h_s, w_s) of Conv2d Layer. Default: 1 - padding(list/int, optional): Paddings(h_pad, w_pad) of Conv2d Layer. Default: 0 - groups(int, optional): The groups number of the Conv2d Layer. Default: 1 - param_attr(ParamAttr): The parameters to the Conv2d Layer. Default: None - bias_attr(ParamAttr): Bias parameter for the Conv2d layer. Default: None - act(str): Activation type. Default: None - name(str): Name/alias of the function + input(Variable): The input image with [N, C, H, W] format. + num_filters(int): The number of filter. It is as same as the output + image channel. + filter_size(int|tuple|None): The filter size. If filter_size is a tuple, + it must contain two integers, (filter_size_H, filter_size_W). + Otherwise, the filter will be a square. + stride(int|tuple): The stride size. If stride is a tuple, it must + contain two integers, (stride_H, stride_W). Otherwise, the + stride_H = stride_W = stride. Default: stride = 1. + padding(int|tuple): The padding size. If padding is a tuple, it must + contain two integers, (padding_H, padding_W). Otherwise, the + padding_H = padding_W = padding. Default: padding = 0. + groups(int): The groups number of the Conv2d Layer. According to grouped + convolution in Alex Krizhevsky's Deep CNN paper: when group=2, + the first half of the filters is only connected to the first half + of the input channels, while the second half of the filters is only + connected to the second half of the input channels. Default: groups=1 + param_attr(ParamAttr): The parameters to the Conv2d Layer. Default: None + bias_attr(ParamAttr): Bias parameter for the Conv2d layer. Default: None + act(str): Activation type. Default: None Returns: Variable: The tensor variable storing the convolution and \