From 8fb0635c997c7fb20383f061692ad032482d8f3e Mon Sep 17 00:00:00 2001 From: LielinJiang <50691816+LielinJiang@users.noreply.github.com> Date: Thu, 10 Oct 2019 14:54:30 +0800 Subject: [PATCH] [cherry-pick]Polish english apis' doc for 1.6 (#20374) * Polish english apis' doc (#20198) * refine Normal Uniform documnet * refine eng doc, test=release/1.6, test=document_fix --- paddle/fluid/API.spec | 22 +++--- python/paddle/fluid/layers/detection.py | 26 +++++-- python/paddle/fluid/layers/distributions.py | 85 ++++++++++----------- python/paddle/fluid/layers/nn.py | 42 ++++++---- 4 files changed, 103 insertions(+), 72 deletions(-) diff --git a/paddle/fluid/API.spec b/paddle/fluid/API.spec index a2634aaceb..83c5b86211 100755 --- a/paddle/fluid/API.spec +++ b/paddle/fluid/API.spec @@ -279,7 +279,7 @@ paddle.fluid.layers.maxout (ArgSpec(args=['x', 'groups', 'name'], varargs=None, paddle.fluid.layers.space_to_depth (ArgSpec(args=['x', 'blocksize', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '26decdea9376b6b9a0d3432d82ca207b')) paddle.fluid.layers.affine_grid (ArgSpec(args=['theta', 'out_shape', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', 'f85b263b7b6698d000977529a28f202b')) paddle.fluid.layers.sequence_reverse (ArgSpec(args=['x', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '5b32ed21ab89140a8e758002923a0da3')) -paddle.fluid.layers.affine_channel (ArgSpec(args=['x', 'scale', 'bias', 'data_layout', 'name', 'act'], varargs=None, keywords=None, defaults=(None, None, 'NCHW', None, None)), ('document', '9f303c67538e468a36c5904a0a3aa110')) +paddle.fluid.layers.affine_channel (ArgSpec(args=['x', 'scale', 'bias', 'data_layout', 'name', 'act'], varargs=None, keywords=None, defaults=(None, None, 'NCHW', None, None)), ('document', 'ecc4b1323028bde0518d666882d03515')) paddle.fluid.layers.similarity_focus (ArgSpec(args=['input', 'axis', 'indexes', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '18ec2e3afeb90e70c8b73d2b71c40fdb')) paddle.fluid.layers.hash (ArgSpec(args=['input', 'hash_size', 'num_hash', 'name'], varargs=None, keywords=None, defaults=(1, None)), ('document', 'a0b73c21be618cec0281e7903039e5e3')) paddle.fluid.layers.grid_sampler (ArgSpec(args=['x', 'grid', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '5d16663e096d7f04954c70ce1cc5e195')) @@ -424,7 +424,7 @@ paddle.fluid.layers.roi_perspective_transform (ArgSpec(args=['input', 'rois', 't paddle.fluid.layers.generate_proposal_labels (ArgSpec(args=['rpn_rois', 'gt_classes', 'is_crowd', 'gt_boxes', 'im_info', 'batch_size_per_im', 'fg_fraction', 'fg_thresh', 'bg_thresh_hi', 'bg_thresh_lo', 'bbox_reg_weights', 'class_nums', 'use_random', 'is_cls_agnostic', 'is_cascade_rcnn'], varargs=None, keywords=None, defaults=(256, 0.25, 0.25, 0.5, 0.0, [0.1, 0.1, 0.2, 0.2], None, True, False, False)), ('document', '69def376b42ef0681d0cc7f53a2dac4b')) paddle.fluid.layers.generate_proposals (ArgSpec(args=['scores', 'bbox_deltas', 'im_info', 'anchors', 'variances', 'pre_nms_top_n', 'post_nms_top_n', 'nms_thresh', 'min_size', 'eta', 'name'], varargs=None, keywords=None, defaults=(6000, 1000, 0.5, 0.1, 1.0, None)), ('document', 'b7d707822b6af2a586bce608040235b1')) paddle.fluid.layers.generate_mask_labels (ArgSpec(args=['im_info', 'gt_classes', 'is_crowd', 'gt_segms', 'rois', 'labels_int32', 'num_classes', 'resolution'], varargs=None, keywords=None, defaults=None), ('document', 'b319b10ddaf17fb4ddf03518685a17ef')) -paddle.fluid.layers.iou_similarity (ArgSpec(args=['x', 'y', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '72fca4a39ccf82d5c746ae62d1868a99')) +paddle.fluid.layers.iou_similarity (ArgSpec(args=['x', 'y', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', 'e24478fd1fcf1727d4947fe14356b3d4')) paddle.fluid.layers.box_coder (ArgSpec(args=['prior_box', 'prior_box_var', 'target_box', 'code_type', 'box_normalized', 'name', 'axis'], varargs=None, keywords=None, defaults=('encode_center_size', True, None, 0)), ('document', '511d7033c0cfce1a5b88c04ad6e7ed5b')) paddle.fluid.layers.polygon_box_transform (ArgSpec(args=['input', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', 'e308ce1661cb722b220a6f482f85b9e4')) paddle.fluid.layers.yolov3_loss (ArgSpec(args=['x', 'gt_box', 'gt_label', 'anchors', 'anchor_mask', 'class_num', 'ignore_thresh', 'downsample_ratio', 'gt_score', 'use_label_smooth', 'name'], varargs=None, keywords=None, defaults=(None, True, None)), ('document', 'df35e6510e8db0844320ec77dc8b7dc4')) @@ -446,18 +446,18 @@ paddle.fluid.layers.piecewise_decay (ArgSpec(args=['boundaries', 'values'], vara paddle.fluid.layers.noam_decay (ArgSpec(args=['d_model', 'warmup_steps'], varargs=None, keywords=None, defaults=None), ('document', 'fd57228fb76195e66bbcc8d8e42c494d')) paddle.fluid.layers.cosine_decay (ArgSpec(args=['learning_rate', 'step_each_epoch', 'epochs'], varargs=None, keywords=None, defaults=None), ('document', '1062e487dd3b50a6e58b5703b4f594c9')) paddle.fluid.layers.linear_lr_warmup (ArgSpec(args=['learning_rate', 'warmup_steps', 'start_lr', 'end_lr'], varargs=None, keywords=None, defaults=None), ('document', 'dc7292c456847ba41cfd318e9f7f4363')) -paddle.fluid.layers.Uniform ('paddle.fluid.layers.distributions.Uniform', ('document', 'af70e7003f437e7a8a9e28cded35c433')) +paddle.fluid.layers.Uniform ('paddle.fluid.layers.distributions.Uniform', ('document', '9b1a9ebdd8ae18bf562486611ed74e59')) paddle.fluid.layers.Uniform.__init__ (ArgSpec(args=['self', 'low', 'high'], varargs=None, keywords=None, defaults=None), ('document', '6adf97f83acf6453d4a6a4b1070f3754')) -paddle.fluid.layers.Uniform.entropy (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', 'ba59f9ce77af3c93e2b4c8af1801a24e')) +paddle.fluid.layers.Uniform.entropy (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', 'cde9f1980a2be7939798b32ec8cd59e1')) paddle.fluid.layers.Uniform.kl_divergence (ArgSpec(args=['self', 'other'], varargs=None, keywords=None, defaults=None), ('document', '3baee52abbed82d47e9588d9dfe2f42f')) -paddle.fluid.layers.Uniform.log_prob (ArgSpec(args=['self', 'value'], varargs=None, keywords=None, defaults=None), ('document', 'b79091014ceaffb6a7372a198a341c23')) -paddle.fluid.layers.Uniform.sample (ArgSpec(args=['self', 'shape', 'seed'], varargs=None, keywords=None, defaults=(0,)), ('document', 'adac334af13f6984e991b3ecf12b8cb7')) -paddle.fluid.layers.Normal ('paddle.fluid.layers.distributions.Normal', ('document', '3265262d0d8b3b32c6245979a5cdced9')) +paddle.fluid.layers.Uniform.log_prob (ArgSpec(args=['self', 'value'], varargs=None, keywords=None, defaults=None), ('document', 'ad4ed169f86c00923621504c782010b0')) +paddle.fluid.layers.Uniform.sample (ArgSpec(args=['self', 'shape', 'seed'], varargs=None, keywords=None, defaults=(0,)), ('document', '9002ab4a80769211565b64298a770db5')) +paddle.fluid.layers.Normal ('paddle.fluid.layers.distributions.Normal', ('document', '948f3a95ca14c952401e6a2ec30a35f9')) paddle.fluid.layers.Normal.__init__ (ArgSpec(args=['self', 'loc', 'scale'], varargs=None, keywords=None, defaults=None), ('document', '6adf97f83acf6453d4a6a4b1070f3754')) -paddle.fluid.layers.Normal.entropy (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', 'd2db47b1e62c037a2570fc526b93f518')) -paddle.fluid.layers.Normal.kl_divergence (ArgSpec(args=['self', 'other'], varargs=None, keywords=None, defaults=None), ('document', '2e8845cdf1129647e6fa6e816876cd3b')) -paddle.fluid.layers.Normal.log_prob (ArgSpec(args=['self', 'value'], varargs=None, keywords=None, defaults=None), ('document', 'b79091014ceaffb6a7372a198a341c23')) -paddle.fluid.layers.Normal.sample (ArgSpec(args=['self', 'shape', 'seed'], varargs=None, keywords=None, defaults=(0,)), ('document', 'adac334af13f6984e991b3ecf12b8cb7')) +paddle.fluid.layers.Normal.entropy (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', '254ff8081a9df3cb96db045411dfbcbd')) +paddle.fluid.layers.Normal.kl_divergence (ArgSpec(args=['self', 'other'], varargs=None, keywords=None, defaults=None), ('document', '9fc9bd26e5211e2c6ad703a7fba08e65')) +paddle.fluid.layers.Normal.log_prob (ArgSpec(args=['self', 'value'], varargs=None, keywords=None, defaults=None), ('document', 'ad4ed169f86c00923621504c782010b0')) +paddle.fluid.layers.Normal.sample (ArgSpec(args=['self', 'shape', 'seed'], varargs=None, keywords=None, defaults=(0,)), ('document', '9002ab4a80769211565b64298a770db5')) paddle.fluid.layers.Categorical ('paddle.fluid.layers.distributions.Categorical', ('document', '865c9dac8af6190e05588486ba091ee8')) paddle.fluid.layers.Categorical.__init__ (ArgSpec(args=['self', 'logits'], varargs=None, keywords=None, defaults=None), ('document', '933b96c9ebab8e2c1f6007a50287311e')) paddle.fluid.layers.Categorical.entropy (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', 'b360a2a7a4da07c2d268b329e09c82c1')) diff --git a/python/paddle/fluid/layers/detection.py b/python/paddle/fluid/layers/detection.py index 73b1f11dbe..915afc7e09 100644 --- a/python/paddle/fluid/layers/detection.py +++ b/python/paddle/fluid/layers/detection.py @@ -591,20 +591,36 @@ def iou_similarity(x, y, name=None): ${comment} Args: - x(${x_type}): ${x_comment} - y(${y_type}): ${y_comment} + x (Variable): ${x_comment}.The data type is float32 or float64. + y (Variable): ${y_comment}.The data type is float32 or float64. Returns: - out(${out_type}): ${out_comment} + Variable: ${out_comment}.The data type is same with x. Examples: .. code-block:: python + import numpy as np import paddle.fluid as fluid - x = fluid.layers.data(name='x', shape=[4], dtype='float32') - y = fluid.layers.data(name='y', shape=[4], dtype='float32') + use_gpu = False + place = fluid.CUDAPlace(0) if use_gpu else fluid.CPUPlace() + exe = fluid.Executor(place) + + x = fluid.data(name='x', shape=[None, 4], dtype='float32') + y = fluid.data(name='y', shape=[None, 4], dtype='float32') iou = fluid.layers.iou_similarity(x=x, y=y) + + exe.run(fluid.default_startup_program()) + test_program = fluid.default_main_program().clone(for_test=True) + + [out_iou] = exe.run(test_program, + fetch_list=iou, + feed={'x': np.array([[0.5, 0.5, 2.0, 2.0], + [0., 0., 1.0, 1.0]]).astype('float32'), + 'y': np.array([[1.0, 1.0, 2.5, 2.5]]).astype('float32')}) + # out_iou is [[0.2857143], + # [0. ]] with shape: [2, 1] """ helper = LayerHelper("iou_similarity", **locals()) if name is None: diff --git a/python/paddle/fluid/layers/distributions.py b/python/paddle/fluid/layers/distributions.py index 4a85da2d36..6954b2d882 100644 --- a/python/paddle/fluid/layers/distributions.py +++ b/python/paddle/fluid/layers/distributions.py @@ -135,12 +135,13 @@ class Uniform(Distribution): broadcasting (e.g., `high - low` is a valid operation). Args: - low(float|list|numpy.ndarray|Variable): The lower boundary of uniform distribution. - high(float|list|numpy.ndarray|Variable): The higher boundary of uniform distribution. + low(float|list|numpy.ndarray|Variable): The lower boundary of uniform distribution.The data type is float32 + high(float|list|numpy.ndarray|Variable): The higher boundary of uniform distribution.The data type is float32 Examples: .. code-block:: python + import numpy as np from paddle.fluid import layers from paddle.fluid.layers import Uniform @@ -158,19 +159,19 @@ class Uniform(Distribution): # With broadcasting: u4 = Uniform(low=3.0, high=[5.0, 6.0, 7.0]) - # Variable as input - dims = 3 - - low = layers.data(name='low', shape=[dims], dtype='float32') - high = layers.data(name='high', shape=[dims], dtype='float32') - values = layers.data(name='values', shape=[dims], dtype='float32') + # Complete example + value_npdata = np.array([0.8], dtype="float32") + value_tensor = layers.create_tensor(dtype="float32") + layers.assign(value_npdata, value_tensor) - uniform = Uniform(low, high) + uniform = Uniform([0.], [2.]) - sample = uniform.sample([2, 3]) + sample = uniform.sample([2]) + # a random tensor created by uniform distribution with shape: [2, 1] entropy = uniform.entropy() - lp = uniform.log_prob(values) - + # [0.6931472] with shape: [1] + lp = uniform.log_prob(value_tensor) + # [-0.6931472] with shape: [1] """ def __init__(self, low, high): @@ -193,7 +194,7 @@ class Uniform(Distribution): seed (int): Python integer number. Returns: - Variable: A tensor with prepended dimensions shape. + Variable: A tensor with prepended dimensions shape.The data type is float32. """ batch_shape = list((self.low + self.high).shape) @@ -224,7 +225,7 @@ class Uniform(Distribution): value (Variable): The input tensor. Returns: - Variable: log probability. + Variable: log probability.The data type is same with value. """ lb_bool = control_flow.less_than(self.low, value) @@ -237,7 +238,7 @@ class Uniform(Distribution): """Shannon entropy in nats. Returns: - Variable: Shannon entropy of uniform distribution. + Variable: Shannon entropy of uniform distribution.The data type is float32. """ return nn.log(self.high - self.low) @@ -265,8 +266,8 @@ class Normal(Distribution): * :math:`Z`: is the normalization constant. Args: - loc(float|list|numpy.ndarray|Variable): The mean of normal distribution. - scale(float|list|numpy.ndarray|Variable): The std of normal distribution. + loc(float|list|numpy.ndarray|Variable): The mean of normal distribution.The data type is float32. + scale(float|list|numpy.ndarray|Variable): The std of normal distribution.The data type is float32. Examples: .. code-block:: python @@ -278,36 +279,34 @@ class Normal(Distribution): dist = Normal(loc=0., scale=3.) # Define a batch of two scalar valued Normals. # The first has mean 1 and standard deviation 11, the second 2 and 22. - dist = Normal(loc=[1, 2.], scale=[11, 22.]) + dist = Normal(loc=[1., 2.], scale=[11., 22.]) # Get 3 samples, returning a 3 x 2 tensor. dist.sample([3]) # Define a batch of two scalar valued Normals. # Both have mean 1, but different standard deviations. - dist = Normal(loc=1., scale=[11, 22.]) + dist = Normal(loc=1., scale=[11., 22.]) # Define a batch of two scalar valued Normals. # Both have mean 1, but different standard deviations. - dist = Normal(loc=1., scale=[11, 22.]) - - # Variable as input - dims = 3 - - loc = layers.data(name='loc', shape=[dims], dtype='float32') - scale = layers.data(name='scale', shape=[dims], dtype='float32') - other_loc = layers.data( - name='other_loc', shape=[dims], dtype='float32') - other_scale = layers.data( - name='other_scale', shape=[dims], dtype='float32') - values = layers.data(name='values', shape=[dims], dtype='float32') - - normal = Normal(loc, scale) - other_normal = Normal(other_loc, other_scale) - - sample = normal.sample([2, 3]) - entropy = normal.entropy() - lp = normal.log_prob(values) - kl = normal.kl_divergence(other_normal) + dist = Normal(loc=1., scale=[11., 22.]) + + # Complete example + value_npdata = np.array([0.8], dtype="float32") + value_tensor = layers.create_tensor(dtype="float32") + layers.assign(value_npdata, value_tensor) + + normal_a = Normal([0.], [1.]) + normal_b = Normal([0.5], [2.]) + + sample = normal_a.sample([2]) + # a random tensor created by normal distribution with shape: [2, 1] + entropy = normal_a.entropy() + # [1.4189385] with shape: [1] + lp = normal_a.log_prob(value_tensor) + # [-1.2389386] with shape: [1] + kl = normal_a.kl_divergence(normal_b) + # [0.34939718] with shape: [1] """ def __init__(self, loc, scale): @@ -330,7 +329,7 @@ class Normal(Distribution): seed (int): Python integer number. Returns: - Variable: A tensor with prepended dimensions shape. + Variable: A tensor with prepended dimensions shape.The data type is float32. """ batch_shape = list((self.loc + self.scale).shape) @@ -356,7 +355,7 @@ class Normal(Distribution): """Shannon entropy in nats. Returns: - Variable: Shannon entropy of normal distribution. + Variable: Shannon entropy of normal distribution.The data type is float32. """ batch_shape = list((self.loc + self.scale).shape) @@ -372,7 +371,7 @@ class Normal(Distribution): value (Variable): The input tensor. Returns: - Variable: log probability. + Variable: log probability.The data type is same with value. """ var = self.scale * self.scale @@ -387,7 +386,7 @@ class Normal(Distribution): other (Normal): instance of Normal. Returns: - Variable: kl-divergence between two normal distributions. + Variable: kl-divergence between two normal distributions.The data type is float32. """ assert isinstance(other, Normal), "another distribution must be Normal" diff --git a/python/paddle/fluid/layers/nn.py b/python/paddle/fluid/layers/nn.py index 5410b1487f..8b6c97f942 100755 --- a/python/paddle/fluid/layers/nn.py +++ b/python/paddle/fluid/layers/nn.py @@ -13674,32 +13674,48 @@ def affine_channel(x, Args: x (Variable): Feature map input can be a 4D tensor with order NCHW or NHWC. It also can be a 2D tensor and the affine transformation - is applied in the second dimension. + is applied in the second dimension.The data type is float32 or float64. scale (Variable): 1D input of shape (C), the c-th element is the scale factor of the affine transformation for the c-th channel of - the input. + the input.The data type is float32 or float64. bias (Variable): 1D input of shape (C), the c-th element is the bias of the affine transformation for the c-th channel of the input. - data_layout (string, default NCHW): NCHW or NHWC. If input is 2D + The data type is float32 or float64. + data_layout (str, default NCHW): NCHW or NHWC. If input is 2D tensor, you can ignore data_layout. - name (str, default None): The name of this layer. + name (str, default None): The name of this layer. For more information, + please refer to :ref:`api_guide_Name` . act (str, default None): Activation to be applied to the output of this layer. Returns: - out (Variable): A tensor of the same shape and data layout with x. + Variable: A tensor which has the same shape, data layout and data type with x. Examples: .. code-block:: python - + + import numpy as np import paddle.fluid as fluid - data = fluid.layers.data(name='data', shape=[3, 32, 32], - dtype='float32') - input_scale = fluid.layers.create_parameter(shape=[3], - dtype="float32") - input_bias = fluid.layers.create_parameter(shape=[3], - dtype="float32") + + use_gpu = False + place = fluid.CUDAPlace(0) if use_gpu else fluid.CPUPlace() + exe = fluid.Executor(place) + + data = fluid.data(name='data', shape=[None, 1, 2, 2], dtype='float32') + input_scale = fluid.layers.create_parameter(shape=[1], dtype="float32", + default_initializer=fluid.initializer.Constant(2.0)) + input_bias = fluid.layers.create_parameter(shape=[1],dtype="float32", + default_initializer=fluid.initializer.Constant(0.5)) out = fluid.layers.affine_channel(data,scale=input_scale, - bias=input_bias) + bias=input_bias) + + exe.run(fluid.default_startup_program()) + test_program = fluid.default_main_program().clone(for_test=True) + + [out_array] = exe.run(test_program, + fetch_list=out, + feed={'data': np.ones([1,1,2,2]).astype('float32')}) + # out_array is [[[[2.5, 2.5], + # [2.5, 2.5]]]] with shape: [1, 1, 2, 2] """ helper = LayerHelper("affine_channel", **locals()) -- GitLab