From 5c649d9a1e12be65d9c53d10a645c2e961c4260a Mon Sep 17 00:00:00 2001 From: wangchaochaohu Date: Thu, 10 Oct 2019 23:34:33 +0800 Subject: [PATCH] fix the reduce api en doc (#20223) * fix the reduce api en doc test=document_fix test=develop * fix the fluid.data test=develop test=document_fix * fix the API.spec test=develop test=document_fix * fix according the review test=develop test=document_fix * fix the confilict test=develop test=document_fix --- paddle/fluid/API.spec | 10 +-- python/paddle/fluid/layers/nn.py | 117 ++++++++++++++++++------------- 2 files changed, 74 insertions(+), 53 deletions(-) diff --git a/paddle/fluid/API.spec b/paddle/fluid/API.spec index 5a083cb8790..078b43e4843 100644 --- a/paddle/fluid/API.spec +++ b/paddle/fluid/API.spec @@ -157,11 +157,11 @@ paddle.fluid.layers.sequence_expand_as (ArgSpec(args=['x', 'y', 'name'], varargs paddle.fluid.layers.sequence_pad (ArgSpec(args=['x', 'pad_value', 'maxlen', 'name'], varargs=None, keywords=None, defaults=(None, None)), ('document', 'df08b9c499ab3a90f95d08ab5b6c6c62')) paddle.fluid.layers.sequence_unpad (ArgSpec(args=['x', 'length', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', 'e478180d5bc010a84f35af958cafa62c')) paddle.fluid.layers.lstm_unit (ArgSpec(args=['x_t', 'hidden_t_prev', 'cell_t_prev', 'forget_bias', 'param_attr', 'bias_attr', 'name'], varargs=None, keywords=None, defaults=(0.0, None, None, None)), ('document', 'fe126c58e4339410e875ab1eba246d21')) -paddle.fluid.layers.reduce_sum (ArgSpec(args=['input', 'dim', 'keep_dim', 'name'], varargs=None, keywords=None, defaults=(None, False, None)), ('document', 'dd5f06fb7cf39ca06cbab4abd03e6893')) -paddle.fluid.layers.reduce_mean (ArgSpec(args=['input', 'dim', 'keep_dim', 'name'], varargs=None, keywords=None, defaults=(None, False, None)), ('document', 'a3024789eba11a70c2ef27c358173400')) -paddle.fluid.layers.reduce_max (ArgSpec(args=['input', 'dim', 'keep_dim', 'name'], varargs=None, keywords=None, defaults=(None, False, None)), ('document', '10023caec4d7f78c3b901f023a1feaa7')) -paddle.fluid.layers.reduce_min (ArgSpec(args=['input', 'dim', 'keep_dim', 'name'], varargs=None, keywords=None, defaults=(None, False, None)), ('document', '1a1c91625ce3c32646f69ca10d4d1da7')) -paddle.fluid.layers.reduce_prod (ArgSpec(args=['input', 'dim', 'keep_dim', 'name'], varargs=None, keywords=None, defaults=(None, False, None)), ('document', 'b386471f0476c80c61d8c8672278063d')) +paddle.fluid.layers.reduce_sum (ArgSpec(args=['input', 'dim', 'keep_dim', 'name'], varargs=None, keywords=None, defaults=(None, False, None)), ('document', 'ecb55075fdf89a866bcede85e60aebad')) +paddle.fluid.layers.reduce_mean (ArgSpec(args=['input', 'dim', 'keep_dim', 'name'], varargs=None, keywords=None, defaults=(None, False, None)), ('document', '968c9b17affaf714e5021c3dc8d68c73')) +paddle.fluid.layers.reduce_max (ArgSpec(args=['input', 'dim', 'keep_dim', 'name'], varargs=None, keywords=None, defaults=(None, False, None)), ('document', 'd37e3a9a05c00e032d4b7876c4f6b414')) +paddle.fluid.layers.reduce_min (ArgSpec(args=['input', 'dim', 'keep_dim', 'name'], varargs=None, keywords=None, defaults=(None, False, None)), ('document', 'fad9e8057b48a075502b4d845f776b01')) +paddle.fluid.layers.reduce_prod (ArgSpec(args=['input', 'dim', 'keep_dim', 'name'], varargs=None, keywords=None, defaults=(None, False, None)), ('document', 'e165c6e99b1f5b773897c5910ccc7f4f')) paddle.fluid.layers.reduce_all (ArgSpec(args=['input', 'dim', 'keep_dim', 'name'], varargs=None, keywords=None, defaults=(None, False, None)), ('document', 'e365c540ec448a73e2b2e75796ed029e')) paddle.fluid.layers.reduce_any (ArgSpec(args=['input', 'dim', 'keep_dim', 'name'], varargs=None, keywords=None, defaults=(None, False, None)), ('document', 'fbc9e73da7a2964ba5693864aed36abb')) paddle.fluid.layers.sequence_first_step (ArgSpec(args=['input'], varargs=None, keywords=None, defaults=None), ('document', '227a75392ae194de0504f5c6812dade9')) diff --git a/python/paddle/fluid/layers/nn.py b/python/paddle/fluid/layers/nn.py index 7be288215e2..579ab2f93f5 100755 --- a/python/paddle/fluid/layers/nn.py +++ b/python/paddle/fluid/layers/nn.py @@ -5889,21 +5889,27 @@ def reduce_sum(input, dim=None, keep_dim=False, name=None): Computes the sum of tensor elements over the given dimension. Args: - input (Variable): The input variable which is a Tensor or LoDTensor. - dim (list|int|None): The dimensions along which the sum is performed. If + input (Variable): The input variable which is a Tensor, the data type is float32, + float64, int32, int64. + dim (list|int, optional): The dimensions along which the sum is performed. If :attr:`None`, sum all elements of :attr:`input` and return a Tensor variable with a single element, otherwise must be in the range :math:`[-rank(input), rank(input))`. If :math:`dim[i] < 0`, the dimension to reduce is :math:`rank + dim[i]`. - keep_dim (bool|False): Whether to reserve the reduced dimension in the + keep_dim (bool, optional): Whether to reserve the reduced dimension in the output Tensor. The result tensor will have one fewer dimension - than the :attr:`input` unless :attr:`keep_dim` is true. - name(str|None): A name for this layer(optional). If set None, the layer - will be named automatically. + than the :attr:`input` unless :attr:`keep_dim` is true, default + value is False. + 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: - Variable: The reduced Tensor variable. + Variable: Tensor, results of summation operation on the specified dim of input tensor, + it's data type is the same as input's Tensor. + Raises: + TypeError, if out data type is different with the input data type. + Examples: .. code-block:: python @@ -5912,7 +5918,7 @@ def reduce_sum(input, dim=None, keep_dim=False, name=None): # [[0.2, 0.3, 0.5, 0.9] # [0.1, 0.2, 0.6, 0.7]] # Each example is followed by the corresponding output tensor. - x = fluid.layers.data(name='x', shape=[4, 2], dtype='float32') + x = fluid.data(name='x', shape=[2, 4], dtype='float32') fluid.layers.reduce_sum(x) # [3.5] fluid.layers.reduce_sum(x, dim=0) # [0.3, 0.5, 1.1, 1.6] fluid.layers.reduce_sum(x, dim=-1) # [1.9, 1.6] @@ -5922,7 +5928,7 @@ def reduce_sum(input, dim=None, keep_dim=False, name=None): # [[[1, 2], [3, 4]], # [[5, 6], [7, 8]]] # Each example is followed by the corresponding output tensor. - y = fluid.layers.data(name='y', shape=[2, 2, 2], dtype='float32') + y = fluid.data(name='y', shape=[2, 2, 2], dtype='float32') fluid.layers.reduce_sum(y, dim=[1, 2]) # [10, 26] fluid.layers.reduce_sum(y, dim=[0, 1]) # [16, 20] @@ -5957,22 +5963,28 @@ def reduce_mean(input, dim=None, keep_dim=False, name=None): Computes the mean of the input tensor's elements along the given dimension. Args: - input (Variable): The input variable which is a Tensor or LoDTensor. - dim (list|int|None): The dimension along which the mean is computed. If + input (Variable): The input variable which is a Tensor, the data type is float32, + float64, int32, int64. + dim (list|int, optional): The dimension along which the mean is computed. If `None`, compute the mean over all elements of :attr:`input` and return a variable with a single element, otherwise it must be in the range :math:`[-rank(input), rank(input))`. If :math:`dim[i] < 0`, the dimension to reduce is :math:`rank(input) + dim[i]`. - keep_dim (bool): Whether to reserve the reduced dimension in the + keep_dim (bool, optional): Whether to reserve the reduced dimension in the output Tensor. The result tensor will have one fewer dimension - than the :attr:`input` unless :attr:`keep_dim` is true. - name(str|None): A name for this layer(optional). If set `None`, the layer - will be named automatically. - + than the :attr:`input` unless :attr:`keep_dim` is true, default + value is False. + 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: - Variable: The reduced mean Variable. - + Variable: Tensor, results of average on the specified dim of input tensor, + it's data type is the same as input's Tensor. + + Raises: + TypeError, if out data type is different with the input data type. + Examples: .. code-block:: python @@ -5981,7 +5993,7 @@ def reduce_mean(input, dim=None, keep_dim=False, name=None): # [[0.2, 0.3, 0.5, 0.9] # [0.1, 0.2, 0.6, 0.7]] # Each example is followed by the correspending output tensor. - x = fluid.layers.data(name='x', shape=[4, 2], dtype='float32') + x = fluid.data(name='x', shape=[2, 4], dtype='float32') fluid.layers.reduce_mean(x) # [0.4375] fluid.layers.reduce_mean(x, dim=0) # [0.15, 0.25, 0.55, 0.8] fluid.layers.reduce_mean(x, dim=-1) # [0.475, 0.4] @@ -5991,7 +6003,7 @@ def reduce_mean(input, dim=None, keep_dim=False, name=None): # [[[1.0, 2.0], [3.0, 4.0]], # [[5.0, 6.0], [7.0, 8.0]]] # Each example is followed by the correspending output tensor. - y = fluid.layers.data(name='y', shape=[2, 2, 2], dtype='float32') + y = fluid.data(name='y', shape=[2, 2, 2], dtype='float32') fluid.layers.reduce_mean(y, dim=[1, 2]) # [2.5, 6.5] fluid.layers.reduce_mean(y, dim=[0, 1]) # [4.0, 5.0] """ @@ -6025,20 +6037,23 @@ def reduce_max(input, dim=None, keep_dim=False, name=None): Computes the maximum of tensor elements over the given dimension. Args: - input (Variable): The input variable which is a Tensor or LoDTensor. - dim (list|int|None): The dimension along which the maximum is computed. + input (Variable): The input variable which is a Tensor, the data type is float32, + float64, int32, int64. + dim (list|int, optional): The dimension along which the maximum is computed. If :attr:`None`, compute the maximum over all elements of :attr:`input` and return a Tensor variable with a single element, otherwise must be in the range :math:`[-rank(input), rank(input))`. If :math:`dim[i] < 0`, the dimension to reduce is :math:`rank + dim[i]`. - keep_dim (bool): Whether to reserve the reduced dimension in the + keep_dim (bool, optional): Whether to reserve the reduced dimension in the output Tensor. The result tensor will have one fewer dimension - than the :attr:`input` unless :attr:`keep_dim` is true. - name(str|None): A name for this layer(optional). If set None, the layer - will be named automatically. + than the :attr:`input` unless :attr:`keep_dim` is true, default + value is False. + 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: - Variable: The reduced Tensor variable. + Variable: Tensor, results of maximum on the specified dim of input tensor, + it's data type is the same as input's Tensor. Examples: .. code-block:: python @@ -6048,7 +6063,7 @@ def reduce_max(input, dim=None, keep_dim=False, name=None): # [[0.2, 0.3, 0.5, 0.9] # [0.1, 0.2, 0.6, 0.7]] # Each example is followed by the correspending output tensor. - x = fluid.layers.data(name='x', shape=[4, 2], dtype='float32') + x = fluid.data(name='x', shape=[2, 4], dtype='float32') fluid.layers.reduce_max(x) # [0.9] fluid.layers.reduce_max(x, dim=0) # [0.2, 0.3, 0.6, 0.9] fluid.layers.reduce_max(x, dim=-1) # [0.9, 0.7] @@ -6058,7 +6073,7 @@ def reduce_max(input, dim=None, keep_dim=False, name=None): # [[[1.0, 2.0], [3.0, 4.0]], # [[5.0, 6.0], [7.0, 8.0]]] # Each example is followed by the correspending output tensor. - y = fluid.layers.data(name='y', shape=[2, 2, 2], dtype='float32') + y = fluid.data(name='y', shape=[2, 2, 2], dtype='float32') fluid.layers.reduce_max(y, dim=[1, 2]) # [4.0, 8.0] fluid.layers.reduce_max(y, dim=[0, 1]) # [7.0, 8.0] """ @@ -6083,20 +6098,23 @@ def reduce_min(input, dim=None, keep_dim=False, name=None): Computes the minimum of tensor elements over the given dimension. Args: - input (Variable): The input variable which is a Tensor or LoDTensor. - dim (list|int|None): The dimensions along which the minimum is computed. + input (Variable): The input variable which is a Tensor, the data type is float32, + float64, int32, int64. + dim (list|int, optional): The dimensions along which the minimum is computed. If :attr:`None`, compute the minimum over all elements of :attr:`input` and return a Tensor variable with a single element, otherwise must be in the range :math:`[-rank(input), rank(input))`. If :math:`dim[i] < 0`, the dimension to reduce is :math:`rank + dim[i]`. - keep_dim (bool): Whether to reserve the reduced dimension in the + keep_dim (bool, optional): Whether to reserve the reduced dimension in the output Tensor. The result tensor will have one fewer dimension - than the :attr:`input` unless :attr:`keep_dim` is true. - name(str|None): A name for this layer(optional). If set None, the layer - will be named automatically. + than the :attr:`input` unless :attr:`keep_dim` is true, default + value is False. + 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: - Variable: The reduced Tensor variable. + Variable: Tensor, result of minimum on the specified dim of input tensor, + it's data type is the same as input's Tensor. Examples: .. code-block:: python @@ -6106,7 +6124,7 @@ def reduce_min(input, dim=None, keep_dim=False, name=None): # [[0.2, 0.3, 0.5, 0.9] # [0.1, 0.2, 0.6, 0.7]] # Each example is followed by the correspending output tensor. - x = fluid.layers.data(name='x', shape=[4, 2], dtype='float32') + x = fluid.data(name='x', shape=[2, 4], dtype='float32') fluid.layers.reduce_min(x) # [0.1] fluid.layers.reduce_min(x, dim=0) # [0.1, 0.2, 0.5, 0.7] fluid.layers.reduce_min(x, dim=-1) # [0.2, 0.1] @@ -6116,7 +6134,7 @@ def reduce_min(input, dim=None, keep_dim=False, name=None): # [[[1.0, 2.0], [3.0, 4.0]], # [[5.0, 6.0], [7.0, 8.0]]] # Each example is followed by the correspending output tensor. - y = fluid.layers.data(name='y', shape=[2, 2, 2], dtype='float32') + y = fluid.data(name='y', shape=[2, 2, 2], dtype='float32') fluid.layers.reduce_min(y, dim=[1, 2]) # [1.0, 5.0] fluid.layers.reduce_min(y, dim=[0, 1]) # [1.0, 2.0] """ @@ -6141,21 +6159,24 @@ def reduce_prod(input, dim=None, keep_dim=False, name=None): Computes the product of tensor elements over the given dimension. Args: - input (Variable): The input variable which is a Tensor or LoDTensor. - dim (list|int|None): The dimensions along which the product is performed. If + input (Variable): The input variable which is a Tensor, the data type is float32, + float64, int32, int64. + dim (list|int, optional): The dimensions along which the product is performed. If :attr:`None`, multipy all elements of :attr:`input` and return a Tensor variable with a single element, otherwise must be in the range :math:`[-rank(input), rank(input))`. If :math:`dim[i] < 0`, the dimension to reduce is :math:`rank + dim[i]`. - keep_dim (bool|False): Whether to reserve the reduced dimension in the + keep_dim (bool, optional): Whether to reserve the reduced dimension in the output Tensor. The result tensor will have one fewer dimension - than the :attr:`input` unless :attr:`keep_dim` is true. - name(str|None): A name for this layer(optional). If set None, the - layer will be named automatically. + than the :attr:`input` unless :attr:`keep_dim` is true, default + value is False. + 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: - Variable: The reduced Tensor variable. - + Variable: Tensor, result of product on the specified dim of input tensor, + it's data type is the same as input's Tensor. + Examples: .. code-block:: python @@ -6164,7 +6185,7 @@ def reduce_prod(input, dim=None, keep_dim=False, name=None): # [[0.2, 0.3, 0.5, 0.9] # [0.1, 0.2, 0.6, 0.7]] # Each example is followed by the correspending output tensor. - x = fluid.layers.data(name='x', shape=[4, 2], dtype='float32') + x = fluid.data(name='x', shape=[2, 4], dtype='float32') fluid.layers.reduce_prod(x) # [0.0002268] fluid.layers.reduce_prod(x, dim=0) # [0.02, 0.06, 0.3, 0.63] fluid.layers.reduce_prod(x, dim=-1) # [0.027, 0.0084] @@ -6175,7 +6196,7 @@ def reduce_prod(input, dim=None, keep_dim=False, name=None): # [[[1.0, 2.0], [3.0, 4.0]], # [[5.0, 6.0], [7.0, 8.0]]] # Each example is followed by the correspending output tensor. - y = fluid.layers.data(name='y', shape=[2, 2, 2], dtype='float32') + y = fluid.data(name='y', shape=[2, 2, 2], dtype='float32') fluid.layers.reduce_prod(y, dim=[1, 2]) # [24.0, 1680.0] fluid.layers.reduce_prod(y, dim=[0, 1]) # [105.0, 384.0] """ -- GitLab