From 954bbc043d9abe5200f8b04fb9beab0c6662ad26 Mon Sep 17 00:00:00 2001 From: Liufang Sang Date: Thu, 10 Oct 2019 16:54:09 +0800 Subject: [PATCH] [cherry-pick ] 1.6 en doc (#20398) * fix en api doc test=develop test=document_fix test=document_preview * update api.spec test=develop test=document_fix test=document_preview * fix some details test=develop test=document_fix test=document_preview * update API.spec test=document_fix test=document_preview test=develop --- paddle/fluid/API.spec | 8 +- python/paddle/fluid/layers/nn.py | 152 ++++++++++++++------------- python/paddle/fluid/layers/tensor.py | 20 ++-- 3 files changed, 93 insertions(+), 87 deletions(-) diff --git a/paddle/fluid/API.spec b/paddle/fluid/API.spec index 97832627ea..057e1ac13a 100755 --- a/paddle/fluid/API.spec +++ b/paddle/fluid/API.spec @@ -180,7 +180,7 @@ paddle.fluid.layers.topk (ArgSpec(args=['input', 'k', 'name'], varargs=None, key paddle.fluid.layers.warpctc (ArgSpec(args=['input', 'label', 'blank', 'norm_by_times', 'input_length', 'label_length'], varargs=None, keywords=None, defaults=(0, False, None, None)), ('document', 'a5be881ada816e47ea7a6ee4396da357')) paddle.fluid.layers.sequence_reshape (ArgSpec(args=['input', 'new_dim'], varargs=None, keywords=None, defaults=None), ('document', 'eeb1591cfc854c6ffdac77b376313c44')) paddle.fluid.layers.transpose (ArgSpec(args=['x', 'perm', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '8e72db173d4c082e27cb11f31d8c9bfa')) -paddle.fluid.layers.im2sequence (ArgSpec(args=['input', 'filter_size', 'stride', 'padding', 'input_image_size', 'out_stride', 'name'], varargs=None, keywords=None, defaults=(1, 1, 0, None, 1, None)), ('document', '33134416fc27dd65a767e5f15116ee16')) +paddle.fluid.layers.im2sequence (ArgSpec(args=['input', 'filter_size', 'stride', 'padding', 'input_image_size', 'out_stride', 'name'], varargs=None, keywords=None, defaults=(1, 1, 0, None, 1, None)), ('document', 'fe352915a543cec434f74e9b32ac49da')) paddle.fluid.layers.nce (ArgSpec(args=['input', 'label', 'num_total_classes', 'sample_weight', 'param_attr', 'bias_attr', 'num_neg_samples', 'name', 'sampler', 'custom_dist', 'seed', 'is_sparse'], varargs=None, keywords=None, defaults=(None, None, None, None, None, 'uniform', None, 0, False)), ('document', '83d4ca6dfb957912807f535756e76992')) paddle.fluid.layers.sampled_softmax_with_cross_entropy (ArgSpec(args=['logits', 'label', 'num_samples', 'num_true', 'remove_accidental_hits', 'use_customized_samples', 'customized_samples', 'customized_probabilities', 'seed'], varargs=None, keywords=None, defaults=(1, True, False, None, None, 0)), ('document', 'd4435a63d34203339831ee6a86ef9242')) paddle.fluid.layers.hsigmoid (ArgSpec(args=['input', 'label', 'num_classes', 'param_attr', 'bias_attr', 'name', 'path_table', 'path_code', 'is_custom', 'is_sparse'], varargs=None, keywords=None, defaults=(None, None, None, None, None, False, False)), ('document', 'b83e7dfa81059b39bb137922dc914f50')) @@ -218,7 +218,7 @@ paddle.fluid.layers.scatter_nd_add (ArgSpec(args=['ref', 'index', 'updates', 'na paddle.fluid.layers.scatter_nd (ArgSpec(args=['index', 'updates', 'shape', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', 'e43f1d3a938b35da246aea3e72a020ec')) paddle.fluid.layers.sequence_scatter (ArgSpec(args=['input', 'index', 'updates', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', 'abe3f714120117a5a3d3e639853932bf')) paddle.fluid.layers.random_crop (ArgSpec(args=['x', 'shape', 'seed'], varargs=None, keywords=None, defaults=(None,)), ('document', '042af0b8abea96b40c22f6e70d99e042')) -paddle.fluid.layers.mean_iou (ArgSpec(args=['input', 'label', 'num_classes'], varargs=None, keywords=None, defaults=None), ('document', 'e714b4aa7993dfe9c1a38886875dbaac')) +paddle.fluid.layers.mean_iou (ArgSpec(args=['input', 'label', 'num_classes'], varargs=None, keywords=None, defaults=None), ('document', 'dea29c0c3cdbd5b498afef60e58c9d7c')) paddle.fluid.layers.relu (ArgSpec(args=['x', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '0942c174f4f6fb274976d4357356f6a2')) paddle.fluid.layers.selu (ArgSpec(args=['x', 'scale', 'alpha', 'name'], varargs=None, keywords=None, defaults=(None, None, None)), ('document', 'f93c61f5b0bf933cd425a64dca2c4fdd')) paddle.fluid.layers.log (ArgSpec(args=['x', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '02f668664e3bfc4df6c00d7363467140')) @@ -239,7 +239,7 @@ paddle.fluid.layers.soft_relu (ArgSpec(args=['x', 'threshold', 'name'], varargs= paddle.fluid.layers.flatten (ArgSpec(args=['x', 'axis', 'name'], varargs=None, keywords=None, defaults=(1, None)), ('document', '424ff350578992f201f2c5c30959ef89')) paddle.fluid.layers.sequence_mask (ArgSpec(args=['x', 'maxlen', 'dtype', 'name'], varargs=None, keywords=None, defaults=(None, 'int64', None)), ('document', '6c3f916921b24edaad220f1fcbf039de')) paddle.fluid.layers.stack (ArgSpec(args=['x', 'axis'], varargs=None, keywords=None, defaults=(0,)), ('document', 'a76f347bf27ffe21b990340d5d9524d5')) -paddle.fluid.layers.pad2d (ArgSpec(args=['input', 'paddings', 'mode', 'pad_value', 'data_format', 'name'], varargs=None, keywords=None, defaults=([0, 0, 0, 0], 'constant', 0.0, 'NCHW', None)), ('document', '3f3abdb795a5c2aad8c2312249551ce5')) +paddle.fluid.layers.pad2d (ArgSpec(args=['input', 'paddings', 'mode', 'pad_value', 'data_format', 'name'], varargs=None, keywords=None, defaults=([0, 0, 0, 0], 'constant', 0.0, 'NCHW', None)), ('document', '4e277f064c1765f77f946da194626ca1')) paddle.fluid.layers.unstack (ArgSpec(args=['x', 'axis', 'num'], varargs=None, keywords=None, defaults=(0, None)), ('document', 'b0c4ca08d4eb295189e1b107c920d093')) paddle.fluid.layers.sequence_enumerate (ArgSpec(args=['input', 'win_size', 'pad_value', 'name'], varargs=None, keywords=None, defaults=(0, None)), ('document', 'b870fed41abd2aecf929ece65f555fa1')) paddle.fluid.layers.unique (ArgSpec(args=['x', 'dtype'], varargs=None, keywords=None, defaults=('int32',)), ('document', 'cab0b06e5683875f12f0efc62fa230a9')) @@ -336,7 +336,7 @@ paddle.fluid.layers.reverse (ArgSpec(args=['x', 'axis'], varargs=None, keywords= paddle.fluid.layers.has_inf (ArgSpec(args=['x'], varargs=None, keywords=None, defaults=None), ('document', '51a0fa1cfaf2507c00a215adacdb8a63')) paddle.fluid.layers.has_nan (ArgSpec(args=['x'], varargs=None, keywords=None, defaults=None), ('document', '129cf426e71452fe8276d616a6dc21ae')) paddle.fluid.layers.isfinite (ArgSpec(args=['x'], varargs=None, keywords=None, defaults=None), ('document', 'b9fff4ffc8d11934cde099f4c39bf841')) -paddle.fluid.layers.range (ArgSpec(args=['start', 'end', 'step', 'dtype'], varargs=None, keywords=None, defaults=None), ('document', 'a45b42f21bc5a4e84b60981a3d629ab3')) +paddle.fluid.layers.range (ArgSpec(args=['start', 'end', 'step', 'dtype'], varargs=None, keywords=None, defaults=None), ('document', '3e982b788b95f959eafeeb0696a3cbde')) paddle.fluid.layers.linspace (ArgSpec(args=['start', 'stop', 'num', 'dtype'], varargs=None, keywords=None, defaults=None), ('document', '3663d1148946eed4c1c34c81be586b9e')) paddle.fluid.layers.zeros_like (ArgSpec(args=['x', 'out'], varargs=None, keywords=None, defaults=(None,)), ('document', 'd88a23bcdc443719b3953593f7cef14a')) paddle.fluid.layers.ones_like (ArgSpec(args=['x', 'out'], varargs=None, keywords=None, defaults=(None,)), ('document', 'd18d42059c6b189cbd3fab2fcb206c15')) diff --git a/python/paddle/fluid/layers/nn.py b/python/paddle/fluid/layers/nn.py index 8a1367ff48..549259eaa0 100755 --- a/python/paddle/fluid/layers/nn.py +++ b/python/paddle/fluid/layers/nn.py @@ -7353,57 +7353,55 @@ def im2sequence(input, name=None): """ Extracts image patches from the input tensor to form a tensor of shape - {input.batch_size * output_height * output_width, filter_size_H * - filter_size_W * input.channels} which is similar with im2col. - This op use filter / kernel to scan images and convert these images to - sequences. After expanding, the number of time step are + {input.batch_size * output_height * output_width, filter_size_height * + filter_size_width * input.channels}. This op use filter to scan images + and convert these images to sequences. After expanding, the number of time step are output_height * output_width for an image, in which output_height and output_width are calculated by below equation: .. math:: - output\_size = 1 + \ - (2 * padding + img\_size - block\_size + stride - 1) / stride + output\_height = 1 + \ + (padding\_up + padding\_down + input\_height - filter\_size\_height + stride\_height - 1) / stride\_height \\\\ + output\_width = 1 + \ + (padding\_left + padding\_right + input\_width - filter\_size\_width + stride\_width - 1) / stride\_width - And the dimension of each time step is block_y * block_x * input.channels. + And the dimension of each time step is filter_size_height * filter_size_width * input.channels. - Args: - input (Variable): The input should be a tensor in NCHW format. + Parameters: + input (Variable): The input should be a 4-D Tensor in :math:`NCHW` format. The data type is float32. - 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. + filter_size(int32 | List[int32]): The filter size. If filter_size is a List, + it must contain two integers, :math:`[filter\_size\_height, filter\_size\_width]` . + Otherwise, the filter size will be a square :math:`[filter\_size, filter\_size]` . Default is 1. - 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. + stride(int32 | List[int32]): The stride size. If stride is a List, it must + contain two integers, :math:`[stride\_height, stride\_width]` . Otherwise, the stride size will be a square :math:`[stride\_size, stride\_size]` . Default is 1. - padding(int|tuple): The padding size. If padding is a tuple, it can - contain two integers like (padding_H, padding_W) which means - padding_up = padding_down = padding_H and - padding_left = padding_right = padding_W. Or it can use - (padding_up, padding_left, padding_down, padding_right) to indicate - paddings of four direction. Otherwise, a scalar padding means - padding_up = padding_down = padding_left = padding_right = padding - Default: padding = 0. + padding(int32 | List[int32]): The padding size. If padding is a List, it can + contain four integers like :math:`[padding\_up, padding\_left, padding\_down, padding\_right]` to indicate + paddings of four direction. Or it can contain two integers :math:`[padding\_height, padding\_width]` which means + padding_up = padding_down = padding_height and + padding_left = padding_right = padding_width. Otherwise, a scalar padding means + padding_up = padding_down = padding_left = padding_right = padding. + Default is 0. - input_image_size(Variable): the input contains image real size.It's dim - is [batchsize, 2]. It is dispensable.It is just for batch inference. + input_image_size(Variable, optional): the input contains image real size.It's dim + is :math:`[batchsize, 2]` . It is just for batch inference when not None. Default is None. - out_stride(int|tuple): The scaling of image through CNN. It is - dispensable. It is valid only when input_image_size is not null. - If out_stride is tuple, it must contain two intergers, - (out_stride_H, out_stride_W). Otherwise, - the out_stride_H = out_stride_W = out_stride. + out_stride(int32 | List[int32]): The scaling of image through CNN. It is valid only when input_image_size is not None. + If out_stride is List, it must contain two intergers, + :math:`[out\_stride\_height, out\_stride\_W]` . Otherwise, + the out_stride_height = out_stride_width = out_stride. Default is 1. - name (int): The name of this layer. It is optional. + 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` . + + Returns: + The output is a 2-D LoDTensor with shape {input.batch\_size * output\_height * output\_width, \ + filter\_size\_height * filter\_size\_width * input.channels}. The data type is float32. - Returns: - output: The output is a LoDTensor with shape - {input.batch_size * output_height * output_width, - filter_size_H * filter_size_W * input.channels}. - If we regard output as a matrix, each row of this matrix is - a step of a sequence. + Return Type: Variable Examples: @@ -7455,7 +7453,7 @@ def im2sequence(input, .. code-block:: python import paddle.fluid as fluid - data = fluid.layers.data(name='data', shape=[3, 32, 32], + data = fluid.data(name='data', shape=[None, 3, 32, 32], dtype='float32') output = fluid.layers.im2sequence( input=data, stride=[1, 1], filter_size=[2, 2]) @@ -10302,31 +10300,32 @@ def mean_iou(input, label, num_classes): is then calculated from it. - Args: - input (Variable): A Tensor of prediction results for semantic labels with type int32 or int64. + Parameters: + input (Variable): A n-D Tensor of prediction results for semantic labels with type int32 or int64. label (Variable): A Tensor of ground truth labels with type int32 or int64. Its shape should be the same as input. - num_classes (int): The possible number of labels. - - Returns: - mean_iou (Variable),out_wrong(Variable),out_correct(Variable): - - Three variables: + num_classes (int32): The possible number of labels. - - mean_iou : A Tensor representing the mean intersection-over-union with shape [1]. - - out_wrong: A Tensor with shape [num_classes]. The wrong numbers of each class. - - out_correct: A Tensor with shape [num_classes]. The correct numbers of each class. + Returns: + Three Variables. + - mean_iou(Variable) : A 1-D Tensor representing the mean intersection-over-union with shape [1]. \ + Data type is float32. + - out_wrong(Variable) : A 1-D Tensor with shape [num_classes]. Data type is int32. \ + The wrong numbers of each class. + - out_correct(Variable): A 1-D Tensor with shape [num_classes]. Data type is int32. The correct numbers of each class. + + Examples: .. code-block:: python import paddle.fluid as fluid - iou_shape = [32, 32] + iou_shape = [None, 32, 32] num_classes = 5 - predict = fluid.layers.data(name='predict', shape=iou_shape) - label = fluid.layers.data(name='label', shape=iou_shape) - iou, wrongs, corrects = fluid.layers.mean_iou(predict, label, + predict = fluid.data(name='predict', shape=iou_shape, dtype='int64') + label = fluid.data(name='label', shape=iou_shape, dtype='int64') + mean_iou, out_wrong, out_correct = fluid.layers.mean_iou(predict, label, num_classes) """ helper = LayerHelper('mean_iou', **locals()) @@ -10891,7 +10890,30 @@ def pad2d(input, If mode is 'reflect', paddings[0] and paddings[1] must be no greater than height-1. And the width dimension has the same condition. - Example: + Parameters: + input (Variable): The input image with [N, C, H, W] format or [N, H, W, C] format, which is a 4-D Tensor with data type float32. + paddings (Variable | List[int32]): The padding size. If padding is a List, it must + contain four integers, (padding_top, padding_bottom, padding_left, padding_right). + Otherwise, it is a 1-D Tensor with shape [4]. Data type is int32. + Default is [0, 0, 0, 0]. + mode (str): Three modes: 'constant' (default), 'reflect', 'edge' . + When in 'constant' mode, this op uses a constant value to pad the input tensor. + When in 'reflect' mode, uses reflection of the input boundaries to pad the input tensor. + When in 'edge' mode, uses input boundaries to pad the input tensor. + Default is 'constant' + pad_value (float32): The value to fill the padded areas in 'constant' mode . Default is 0.0 + data_format (str): An string from: "NHWC", "NCHW". Specify the data format of + the input data. + Default is "NCHW" + 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` . + + Returns: a 4-D Tensor padded accordding to paddings and mode and data type is same as input. + + Return Type: Variable + + + Examples: .. code-block:: text Given that X is a channel of image from input: @@ -10927,29 +10949,11 @@ def pad2d(input, [4, 4, 4, 5, 6, 6] [4, 4, 4, 5, 6, 6]] - - Args: - input (Variable): The input image with [N, C, H, W] format or [N, H, W, C] format. - paddings (tuple|list|Variable): The padding size. If padding is a tuple, it must - contain four integers, (padding_top, padding_bottom, padding_left, padding_right). - Default: padding = [0, 0, 0, 0]. - mode (str): Three modes: constant(default), reflect, edge. Default: constant - pad_value (float32): The value to fill the padded areas in constant mode. Default: 0 - data_format (str): An optional string from: "NHWC", "NCHW". Specify the data format of - the input data. - Default: "NCHW" - name (str|None): A name for this layer(optional). If set None, the layer - will be named automatically. - - Returns: - Variable: The tensor variable padded accordding to paddings and mode. - - - Examples: + Code Examples: .. code-block:: python import paddle.fluid as fluid - data = fluid.layers.data(name='data', shape=[3, 32, 32], + data = fluid.data(name='data', shape=[None, 3, 32, 32], dtype='float32') result = fluid.layers.pad2d(input=data, paddings=[1, 2, 3, 4], mode='reflect') diff --git a/python/paddle/fluid/layers/tensor.py b/python/paddle/fluid/layers/tensor.py index e6251c928d..df4498b7a2 100644 --- a/python/paddle/fluid/layers/tensor.py +++ b/python/paddle/fluid/layers/tensor.py @@ -850,18 +850,20 @@ def range(start, end, step, dtype): Values are generated within the half-open interval [start, stop) (in other words, the interval including start but excluding stop). - args: - start(int|float|Variable): Start of interval. The interval includes this value. - end(int|float|Variable): End of interval. The interval does not include this + Parameters: + start(float32 | float64 | int32 | int64 | Variable): Start of interval. The interval includes this value. + when start is Variable, it is a 1-D Tensor with shape [1]. + end(float32 | float64 | int32 | int64 | Variable): End of interval. The interval does not include this value, except in some cases where step is not an integer - and floating point round-off affects the length of out. - step(int|float|Variable): Spacing between values. For any output out, this is the + and floating point round-off affects the length of out. When end is Variable, + it is a 1-D Tensor with shape [1]. + step(float32 | float64 | int32 | int64 | Variable): Spacing between values. For any output out, this is the distance between two adjacent values, out[i+1] - out[i]. - The default step size is 1. - dtype(string): 'float32'|'int32'|..., the data type of the output tensor. + dtype(str): the data type of the output tensor, can be float32, float64, int32, int64. - returns: - Evenly spaced values within a given interval. + Returns: a 1-D Tensor which is evenly spaced values within a given interval. Its data type is set by dtype. + + Return type: Variable examples: -- GitLab