From 1bbc9b6410e252c9703b47ab369a9c59fa97ccd2 Mon Sep 17 00:00:00 2001 From: LoneRanger <836253168@qq.com> Date: Fri, 23 Dec 2022 20:17:45 +0800 Subject: [PATCH] Fix docs(91-100) (#49109) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 修改linspace参数"stop"的介绍 * 更新了conv2d_transpose英文文档中 1.公式异常 2.参数说明异常 3.padding=SAME和VALID的公式说明; test=docs_preview * 解决了 1.英文版Note中的api_fluid_layers_conv2d的链接失效， 2. 英文版参数中的padding_start的参数错误 3. 参数中bias_attr和param_attr的链接失效 4. 参数缺少optional * 更新了paddle.static.auc的英文文档的Return描述以及函数的参数 * Update python/paddle/tensor/creation.py Co-authored-by: Ligoml <39876205+Ligoml@users.noreply.github.com> * 更新了shard_index的ignore_value描述 * 修改了英文文档的paddle.static.nn.conv3d_transpose的公式介绍 * add py_func COPY-FROM label; test=document_fix * Update python/paddle/tensor/manipulation.py Co-authored-by: Ligoml <39876205+Ligoml@users.noreply.github.com> * formula; test=document_fix * formula; test=document_fix * formula; test=document_fix Co-authored-by: Ligoml <39876205+Ligoml@users.noreply.github.com> --- python/paddle/fluid/layers/sequence_lod.py | 28 ++-- python/paddle/static/nn/common.py | 149 +++++++++++---------- python/paddle/static/nn/metric.py | 24 ++-- python/paddle/tensor/creation.py | 4 +- python/paddle/tensor/manipulation.py | 2 +- 5 files changed, 108 insertions(+), 99 deletions(-) diff --git a/python/paddle/fluid/layers/sequence_lod.py b/python/paddle/fluid/layers/sequence_lod.py index 8f04a0fef92..a09ef08daf1 100644 --- a/python/paddle/fluid/layers/sequence_lod.py +++ b/python/paddle/fluid/layers/sequence_lod.py @@ -63,7 +63,7 @@ def sequence_conv( r""" Note: - Only receives LoDTensor as input. If your input is Tensor, please use conv2d Op.(fluid.layers.** :ref:`api_fluid_layers_conv2d` ). + Only receives LoDTensor as input. If your input is Tensor, please use conv2d Op.(fluid.layers.** :ref:`api_paddle_nn_functional_conv2d` ). This operator receives input sequences with variable length and other convolutional configuration parameters(num_filters, filter_size) to apply the convolution operation. @@ -114,29 +114,29 @@ def sequence_conv( and K is hidden_size of input. Only lod_level of 1 is supported. The data type should be float32 or float64. num_filters (int): the number of filters. - filter_size (int): the height of filter. Specified filter width is not supported, the width is + filter_size (int, optional): the height of filter. Specified filter width is not supported, the width is hidden_size by default. Default: 3. - filter_stride (int): stride of the filter. Currently only supports :attr:`stride` = 1. - padding (bool): the parameter :attr:`padding` take no effect and will be discarded in the + filter_stride (int, optional): stride of the filter. Currently only supports :attr:`stride` = 1. + padding (bool, optional): the parameter :attr:`padding` take no effect and will be discarded in the future. Currently, it will always pad input to make sure the length of the output is the same as input whether :attr:`padding` is set true or false. Because the length of input sequence may be shorter than :attr:`filter\_size`, which will cause the convolution result to not be computed correctly. These padding data will not be trainable or updated while training. Default: True. - padding_start (int): It is used to indicate the start index for padding the input + padding_start (int, optional): It is used to indicate the start index for padding the input sequence, which can be negative. The negative number means to pad :attr:`|padding_start|` time-steps of all-zero data at the beginning of each instance. The positive number means to skip :attr:`padding_start` time-steps of each instance, and it will pad :math:`filter\_size + padding\_start - 1` time-steps of all-zero data at the end of the sequence to ensure that the output is the same length as the input. - If set None, the same length :math:`\\frac{filter\_size}{2}` of data will be filled + If set None, the same length :math:`\frac{filter\_size}{2}` of data will be filled on both sides of the sequence. If set 0, the length of :math:`filter\_size - 1` data is padded at the end of each input sequence. Default: None. - bias_attr (ParamAttr): To specify the bias parameter property. Default: None, which means the - default bias parameter property is used. See usage for details in :ref:`api_fluid_ParamAttr` . - param_attr (ParamAttr): To specify the weight parameter property. Default: None, which means the - default weight parameter property is used. See usage for details in :ref:`api_fluid_ParamAttr` . - act (str): Activation to be applied to the output of this layer, such as tanh, softmax, + bias_attr (ParamAttr, optional): To specify the bias parameter property. Default: None, which means the + default bias parameter property is used. See usage for details in :ref:`api_paddle_ParamAttr` . + param_attr (ParamAttr, optional): To specify the weight parameter property. Default: None, which means the + default weight parameter property is used. See usage for details in :ref:`api_paddle_ParamAttr` . + act (str, optional): Activation to be applied to the output of this layer, such as tanh, softmax, sigmoid, relu. For more information, please refer to :ref:`api_guide_activations_en` . Default: None. name (str, optional): The default value is None. Normally there is no need for user to set this property. For more information, please refer to :ref:`api_guide_Name` . @@ -1302,9 +1302,9 @@ def sequence_enumerate(input, win_size, pad_value=0, name=None): r""" Generate a new sequence for the input index sequence with \ - shape ``[d_1, win_size]``, which enumerates all the \ - sub-sequences with length ``win_size`` of the input with \ - shape ``[d_1, 1]``, and padded by ``pad_value`` if necessary in generation. + shape ``[d_1, win_size]``, which enumerates all the \ + sub-sequences with length ``win_size`` of the input with \ + shape ``[d_1, 1]``, and padded by ``pad_value`` if necessary in generation. Please note that the `input` must be LodTensor. diff --git a/python/paddle/static/nn/common.py b/python/paddle/static/nn/common.py index b64f3730981..c8e8e5455c7 100644 --- a/python/paddle/static/nn/common.py +++ b/python/paddle/static/nn/common.py @@ -188,7 +188,6 @@ def instance_norm( input, epsilon=1e-05, param_attr=None, bias_attr=None, name=None ): r""" - :api_attr: Static Graph **Instance Normalization Layer** @@ -390,7 +389,6 @@ def data_norm( enable_scale_and_shift=False, ): r""" - :api_attr: Static Graph **Data Normalization Layer** @@ -589,7 +587,6 @@ def group_norm( name=None, ): """ - :api_attr: Static Graph **Group Normalization Layer** @@ -1021,7 +1018,6 @@ def conv3d( data_format="NCDHW", ): r""" - :api_attr: Static Graph The convolution3D layer calculates the output based on the input, filter and strides, paddings, dilations, groups parameters. Input(Input) and @@ -1125,19 +1121,6 @@ def conv3d( convolution result, and if act is not None, the tensor variable storing convolution and non-linearity activation result. - Raises: - ValueError: If the type of `use_cudnn` is not bool. - ValueError: If `data_format` is not "NCDHW" or "NDHWC". - ValueError: If the channel dimmention of the input is less than or equal to zero. - ValueError: If `padding` is a string, but not "SAME" or "VALID". - ValueError: If `padding` is a tuple, but the element corresponding to the input's batch size is not 0 - or the element corresponding to the input's channel is not 0. - ShapeError: If the input is not 5-D Tensor. - ShapeError: If the input's dimension size and filter's dimension size not equal. - ShapeError: If the dimension size of input minus the size of `stride` is not 2. - ShapeError: If the number of input channels is not equal to filter's channels * groups. - ShapeError: If the number of output channels is not be divided by groups. - Examples: .. code-block:: python @@ -1330,7 +1313,6 @@ def conv2d_transpose( data_format='NCHW', ): r""" - :api_attr: Static Graph The convolution2D transpose layer calculates the output based on the input, filter, and dilations, strides, paddings. Input(Input) and output(Output) @@ -1375,24 +1357,38 @@ def conv2d_transpose( .. math:: - H^\prime_{out} &= (H_{in} - 1) * strides[0] - pad_height_top - pad_height_bottom + dilations[0] * (H_f - 1) + 1 \\ - W^\prime_{out} &= (W_{in} - 1) * strides[1] - pad_width_left - pad_width_right + dilations[1] * (W_f - 1) + 1 \\ + H^\prime_{out} &= (H_{in} - 1) * strides[0] - 2 * paddings[0] + dilations[0] * (H_f - 1) + 1 \\ + W^\prime_{out} &= (W_{in} - 1) * strides[1] - 2 * paddings[1] + dilations[1] * (W_f - 1) + 1 \\ H_{out} &\in [ H^\prime_{out}, H^\prime_{out} + strides[0] ] \\ W_{out} &\in [ W^\prime_{out}, W^\prime_{out} + strides[1] ] - Note: - The conv2d_transpose can be seen as the backward of the conv2d. For conv2d, - when stride > 1, conv2d maps multiple input shape to the same output shape, - so for conv2d_transpose, when stride > 1, input shape maps multiple output shape. - If output_size is None, :math:`H_{out} = H^\prime_{out}, W_{out} = W^\prime_{out}`; - else, the :math:`H_{out}` of the output size must between :math:`H^\prime_{out}` - and :math:`H^\prime_{out} + strides[0]`, and the :math:`W_{out}` of the output size must - between :math:`W^\prime_{out}` and :math:`W^\prime_{out} + strides[1]`, - conv2d_transpose can compute the kernel size automatically. + If `padding` = `"SAME"`: + + .. math:: + H^\prime_{out} &= \frac{(H_{in} + stride[0] - 1)}{stride[0]} \\ + W^\prime_{out} &= \frac{(H_{in} + stride[1] - 1)}{stride[1]} + + If `padding` = `"VALID"`: + + .. math:: + H^\prime_{out} &= (H_{in} - 1) * strides[0] + dilations[0] * (H_f - 1) + 1 \\ + W^\prime_{out} &= (W_{in} − 1) * strides[1] + dilations[1] * (W_f − 1) + 1 + + If output_size is None, :math:`H_{out} = H^\prime_{out}, W_{out} = W^\prime_{out}`; + else, the :math:`H_{out}` of the output size must between :math:`H^\prime_{out}` + and :math:`H^\prime_{out} + strides[0]`, and the :math:`W_{out}` of the output size must + between :math:`W^\prime_{out}` and :math:`W^\prime_{out} + strides[1]`, + + Since transposed convolution can be treated as the inverse of convolution, and according to the input-output formula for convolution, + different sized input feature layers may correspond to the same sized output feature layer, + the size of the output feature layer for a fixed sized input feature layer is not unique to transposed convolution + + If `output_size` is specified, `conv2d_transpose` can compute the kernel size automatically. Args: - input(Tensor): 4-D Tensor with [N, C, H, W] or [N, H, W, C] format, - its data type is float32 or float64. + input(Tensor): 4-D Tensor with [N, C, H, W] or [N, H, W, C] format where N is the batch_size, + C is the input_channels, H is the input_height and W is the input_width. + Its data type is float32 or float64. num_filters(int): The number of the filter. It is as same as the output image channel. output_size(int|tuple, optional): The output image size. If output size is a @@ -1406,26 +1402,23 @@ def conv2d_transpose( Otherwise, filter_size_height = filter_size_width = filter_size. None if use output size to calculate filter_size. Default: None. filter_size and output_size should not be None at the same time. - stride(int|tuple, optional): The stride size. It means the stride in transposed convolution. - If stride is a tuple, it must contain two integers, (stride_height, stride_width). - Otherwise, stride_height = stride_width = stride. Default: stride = 1. padding(str|int|list|tuple, optional): The padding size. It means the number of zero-paddings on both sides for each dimension. If `padding` is a string, either 'VALID' or 'SAME' which is the padding algorithm. If `padding` is a tuple or list, - it could be in three forms: `[pad_height, pad_width]` or - `[pad_height_top, pad_height_bottom, pad_width_left, pad_width_right]`, - and when `data_format` is `"NCHW"`, `padding` can be in the form + it could be in three forms: + (1) Contains 4 binary groups: when `data_format` is `"NCHW"`, `padding` can be in the form `[[0,0], [0,0], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right]]`. when `data_format` is `"NHWC"`, `padding` can be in the form `[[0,0], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right], [0,0]]`. - Default: padding = 0. + (2) Contains 4 integer values：`[pad_height_top, pad_height_bottom, pad_width_left, pad_width_right]` + (3) Contains 2 integer values：`[pad_height, pad_width]`, in this case, `padding_height_top = padding_height_bottom = padding_height`， + `padding_width_left = padding_width_right = padding_width`. If an integer, `padding_height = padding_width = padding`. Default: padding = 0. + stride(int|tuple, optional): The stride size. It means the stride in transposed convolution. + If stride is a tuple, it must contain two integers, (stride_height, stride_width). + Otherwise, stride_height = stride_width = stride. Default: stride = 1. dilation(int|tuple, optional): The dilation size. It means the spacing between the kernel points. If dilation is a tuple, it must contain two integers, (dilation_height, dilation_width). Otherwise, dilation_height = dilation_width = dilation. Default: dilation = 1. - filter_size(int|tuple, optional): The filter size. If filter_size is a tuple, - it must contain two integers, (filter_size_height, filter_size_width). - Otherwise, filter_size_height = filter_size_width = filter_size. None if - use output size to calculate filter_size. Default: None. groups(int, optional): The groups number of the Conv2d transpose layer. Inspired by grouped convolution in Alex Krizhevsky's Deep CNN paper, in which when group=2, the first half of the filters is only connected to the @@ -1436,11 +1429,10 @@ def conv2d_transpose( of conv2d_transpose. If it is set to None or one attribute of ParamAttr, conv2d_transpose will create ParamAttr as param_attr. If the Initializer of the param_attr is not set, the parameter is initialized with Xavier. Default: None. - bias_attr (ParamAttr|bool, optional): The parameter attribute for the bias of conv2d_transpose. - If it is set to False, no bias will be added to the output units. - If it is set to None or one attribute of ParamAttr, conv2d_transpose - will create ParamAttr as bias_attr. If the Initializer of the bias_attr - is not set, the bias is initialized zero. Default: None. + bias_attr (ParamAttr|bool, optional): Specifies the object for the bias parameter attribute. + The default value is None, which means that the default bias parameter attribute is used. + For detailed information, please refer to :ref:`paramattr`. + The default bias initialisation for the conv2d_transpose operator is 0.0. use_cudnn(bool, optional): Use cudnn kernel or not, it is valid only when the cudnn library is installed. Default: True. act (str, optional): Activation type, if it is set to None, activation is not appended. @@ -1692,7 +1684,6 @@ def conv3d_transpose( data_format='NCDHW', ): r""" - :api_attr: Static Graph The convolution3D transpose layer calculates the output based on the input, filter, and dilations, strides, paddings. Input(Input) and output(Output) @@ -1744,17 +1735,33 @@ def conv3d_transpose( H_{out} &\in [ H^\prime_{out}, H^\prime_{out} + strides[1] ] \\ W_{out} &\in [ W^\prime_{out}, W^\prime_{out} + strides[2] ] - Note: - The conv3d_transpose can be seen as the backward of the conv3d. For conv3d, - when stride > 1, conv3d maps multiple input shape to the same output shape, - so for conv3d_transpose, when stride > 1, input shape maps multiple output shape. - If output_size is None, :math:`H_{out} = H^\prime_{out}, :math:`H_{out} = \ - H^\prime_{out}, W_{out} = W^\prime_{out}`; else, the :math:`D_{out}` of the output - size must between :math:`D^\prime_{out}` and :math:`D^\prime_{out} + strides[0]`, - the :math:`H_{out}` of the output size must between :math:`H^\prime_{out}` - and :math:`H^\prime_{out} + strides[1]`, and the :math:`W_{out}` of the output size must - between :math:`W^\prime_{out}` and :math:`W^\prime_{out} + strides[2]`, - conv3d_transpose can compute the kernel size automatically. + If `padding` = `"SAME"`: + + .. math:: + D^\prime_{out} &= \frac{(D_{in} + stride[0] - 1)}{stride[0]} \\ + H^\prime_{out} &= \frac{(H_{in} + stride[1] - 1)}{stride[1]} \\ + W^\prime_{out} &= \frac{(H_{in} + stride[2] - 1)}{stride[2]} + + If `padding` = `"VALID"`: + + .. math:: + D^\prime_{out} &= (D_{in} - 1) * strides[0] + dilations[0] * (D_f - 1) + 1 \\ + H^\prime_{out} &= (H_{in} - 1) * strides[1] + dilations[1] * (H_f - 1) + 1 \\ + W^\prime_{out} &= (W_{in} − 1) * strides[2] + dilations[2] * (W_f − 1) + 1 + + If `output_size` is None, :math:`D_{out} = D^\prime_{out}, :math:`H_{out} = \ + H^\prime_{out}, W_{out} = W^\prime_{out}`; else, the specified `output_size_depth` (the depth of the ouput feature layer) :math:`D_{out}` + must between :math:`D^\prime_{out}` and :math:`D^\prime_{out} + strides[0]`(not including :math:`D^\prime_{out} + strides[0]`), + the specified `output_size_height` (the height of the ouput feature layer) :math:`H_{out}` must between :math:`H^\prime_{out}` + and :math:`H^\prime_{out} + strides[1]`(not including :math:`H^\prime_{out} + strides[1]`), + and the the specified `output_size_width` (the width of the ouput feature layer) :math:`W_{out}` must + between :math:`W^\prime_{out}` and :math:`W^\prime_{out} + strides[2]`(not including :math:`W^\prime_{out} + strides[2]`). + + Since transposed convolution can be treated as the inverse of convolution, + and since different sized input feature layers may correspond to the same sized output feature layer according to the input-output formula for convolution, + the size of the output feature layer for a fixed sized input feature layer is not unique to transposed convolution. + + If `output_size` is specified, `conv3d_transpose` can compute the kernel size automatically. Args: input(Tensor): The input is 5-D Tensor with shape [N, C, D, H, W] or [N, D, H, W, C], the data type @@ -1824,19 +1831,6 @@ def conv3d_transpose( variable storing the transposed convolution result, and if act is not None, the tensor variable storing transposed convolution and non-linearity activation result. - Raises: - ValueError: If the type of `use_cudnn` is not bool. - ValueError: If `data_format` is not "NCDHW" or "NDHWC". - ValueError: If `padding` is a string, but not "SAME" or "VALID". - ValueError: If `padding` is a tuple, but the element corresponding to the input's batch size is not 0 - or the element corresponding to the input's channel is not 0. - ValueError: If `output_size` and filter_size are None at the same time. - ShapeError: If the input is not 5-D Tensor. - ShapeError: If the input's dimension size and filter's dimension size not equal. - ShapeError: If the dimension size of input minus the size of `stride` is not 2. - ShapeError: If the number of input channels is not equal to filter's channels. - ShapeError: If the size of `output_size` is not equal to that of `stride`. - Examples: .. code-block:: python @@ -3051,6 +3045,7 @@ def py_func(func, x, out, backward_func=None, skip_vars_in_backward_input=None): ``x`` will be inferred automatically. This API can also be used to debug the neural network by setting the ``func`` as a function that only print variables. + Args: func (callable): The forward function of the registered OP. When the network is running, the forward output ``out`` will be calculated according to this @@ -3074,10 +3069,15 @@ def py_func(func, x, out, backward_func=None, skip_vars_in_backward_input=None): that no tensors need to be removed from ``x`` and ``out``. If it is not None, these tensors will not be the input of ``backward_func``. This parameter is only useful when ``backward_func`` is not None. + Returns: - Tensor|tuple(Tensor)|list[Tensor]: The output ``out`` of the forward function ``func``. + Tensor|tuple(Tensor)|list[Tensor], The output ``out`` of the forward function ``func``. + Examples: + .. code-block:: python + :name: code-example1 + # example 1: import paddle import numpy as np @@ -3123,7 +3123,10 @@ def py_func(func, x, out, backward_func=None, skip_vars_in_backward_input=None): feed={'x':input1, 'y':input2}, fetch_list=[res.name]) print(out) + .. code-block:: python + :name: code-example2 + # example 2: # This example shows how to turn Tensor into numpy array and # use numpy API to register an Python OP diff --git a/python/paddle/static/nn/metric.py b/python/paddle/static/nn/metric.py index 9b386c38c8e..7406525b9df 100644 --- a/python/paddle/static/nn/metric.py +++ b/python/paddle/static/nn/metric.py @@ -154,19 +154,25 @@ def auc( label(Tensor): A 2D int Tensor indicating the label of the training data. The height is batch size and width is always 1. A Tensor with type int32,int64. - curve(str): Curve type, can be 'ROC' or 'PR'. Default 'ROC'. - num_thresholds(int): The number of thresholds to use when discretizing + curve(str, optional): Curve type, can be 'ROC' or 'PR'. Default 'ROC'. + num_thresholds(int, optional): The number of thresholds to use when discretizing the roc curve. Default 4095. - topk(int): only topk number of prediction output will be used for auc. - slide_steps: when calc batch auc, we can not only use step currently but the previous steps can be used. slide_steps=1 means use the current step, slide_steps=3 means use current step and the previous second steps, slide_steps=0 use all of the steps. - ins_tag_weight(Tensor): A 2D int Tensor indicating the data's tag weight, 1 means real data, 0 means fake data. Default None, and it will be assigned to a tensor of value 1. + topk(int, optional): only topk number of prediction output will be used for auc. + slide_steps(int, optional): when calc batch auc, we can not only use step currently but the previous steps can be used. slide_steps=1 means use the current step, slide_steps=3 means use current step and the previous second steps, slide_steps=0 use all of the steps. + ins_tag_weight(Tensor, optional): A 2D int Tensor indicating the data's tag weight, 1 means real data, 0 means fake data. Default None, and it will be assigned to a tensor of value 1. A Tensor with type float32,float64. Returns: - Tensor: A tuple representing the current AUC. - The return tuple is auc_out, batch_auc_out, [ - batch_stat_pos, batch_stat_neg, stat_pos, stat_neg ] - Data type is Tensor, supporting float32, float64. + Tensor: A tuple representing the current AUC. Data type is Tensor, supporting float32, float64. + The return tuple is auc_out, batch_auc_out, [batch_stat_pos, batch_stat_neg, stat_pos, stat_neg ] + + auc_out: the result of the accuracy rate + batch_auc_out: the result of the batch accuracy + batch_stat_pos: the statistic value for label=1 at the time of batch calculation + batch_stat_neg: the statistic value for label=0 at the time of batch calculation + stat_pos: the statistic for label=1 at the time of calculation + stat_neg: the statistic for label=0 at the time of calculation + Examples: .. code-block:: python diff --git a/python/paddle/tensor/creation.py b/python/paddle/tensor/creation.py index 98587f58747..ed1a7e27188 100644 --- a/python/paddle/tensor/creation.py +++ b/python/paddle/tensor/creation.py @@ -272,12 +272,12 @@ def create_tensor(dtype, name=None, persistable=False): def linspace(start, stop, num, dtype=None, name=None): r""" - Return fixed number of evenly spaced values within a given interval. + Return fixed number of evenly spaced values within a given interval. Note: no gradient calculation is performed. Args: start(int|float|Tensor): The input :attr:`start` is start of range. It is a int, float, \ or a 0-D Tensor with data type int32, int64, float32 or float64. - stop(int|float|Tensor): The input :attr:`stop` is start variable of range. It is a int, float, \ + stop(int|float|Tensor): The input :attr:`stop` is end of range. It is a int, float, \ or a 0-D Tensor with data type int32, int64, float32 or float64. num(int|Tensor): The input :attr:`num` is given num of the sequence. It is an int, \ or a 0-D Tensor with data type int32. diff --git a/python/paddle/tensor/manipulation.py b/python/paddle/tensor/manipulation.py index 7bb9a675d76..8f25e7e762d 100644 --- a/python/paddle/tensor/manipulation.py +++ b/python/paddle/tensor/manipulation.py @@ -682,7 +682,7 @@ def shard_index(input, index_num, nshards, shard_id, ignore_value=-1): index_num (int): An integer represents the integer above the maximum value of `input`. nshards (int): The number of shards. shard_id (int): The index of the current shard. - ignore_value (int): An integer value out of sharded index range. + ignore_value (int, optional): An integer value out of sharded index range. The default value is -1. Returns: Tensor. -- GitLab