From 95ed04f6e4cc4aba8cc880d4b5e54185febb5d64 Mon Sep 17 00:00:00 2001 From: huzhiqiang <912790387@qq.com> Date: Fri, 11 Oct 2019 11:57:55 +0800 Subject: [PATCH] Cherrypick en doc: reorder_lod_tensor_by_rank , map_reader, WeightNormParamAttr, io.compose (#20463) * modify map_reader en doc (#20229) * modify WeightNormParamAttr en doc (#20218) * modify reorder_lod_tensor_by_rank en doc * modify compose en doc (#20217) --- paddle/fluid/API.spec | 8 +-- .../reorder_lod_tensor_by_rank_op.cc | 5 +- python/paddle/fluid/layers/control_flow.py | 7 +- python/paddle/fluid/param_attr.py | 42 ++++++++---- python/paddle/reader/decorator.py | 65 ++++++++++++++----- 5 files changed, 88 insertions(+), 39 deletions(-) diff --git a/paddle/fluid/API.spec b/paddle/fluid/API.spec index fdca632d14e..89485f45805 100644 --- a/paddle/fluid/API.spec +++ b/paddle/fluid/API.spec @@ -94,9 +94,9 @@ paddle.fluid.io.DataLoader.__init__ paddle.fluid.io.DataLoader.from_dataset (ArgSpec(args=['dataset', 'places', 'drop_last'], varargs=None, keywords=None, defaults=(True,)), ('document', 'eb8b6d31e1c2ec2ca8ebbb62fcf46557')) paddle.fluid.io.DataLoader.from_generator (ArgSpec(args=['feed_list', 'capacity', 'use_double_buffer', 'iterable', 'return_list'], varargs=None, keywords=None, defaults=(None, None, True, True, False)), ('document', 'e3bdde36774236c3e381d2218e9cc09e')) paddle.fluid.io.cache (ArgSpec(args=['reader'], varargs=None, keywords=None, defaults=None), ('document', '1676886070eb607cb608f7ba47be0d3c')) -paddle.fluid.io.map_readers (ArgSpec(args=['func'], varargs='readers', keywords=None, defaults=None), ('document', '77cbadb09df588e21e5cc0819b69c87d')) +paddle.fluid.io.map_readers (ArgSpec(args=['func'], varargs='readers', keywords=None, defaults=None), ('document', '2d0903e1d2f00b4f1d6618e6b5310121')) paddle.fluid.io.buffered (ArgSpec(args=['reader', 'size'], varargs=None, keywords=None, defaults=None), ('document', '0d6186f109feceb99f60ec50a0a624cb')) -paddle.fluid.io.compose (ArgSpec(args=[], varargs='readers', keywords='kwargs', defaults=None), ('document', '884291104e1c3f37f33aae44b7deeb0d')) +paddle.fluid.io.compose (ArgSpec(args=[], varargs='readers', keywords='kwargs', defaults=None), ('document', '81c933c8da58041d91f084dcf6322349')) paddle.fluid.io.chain (ArgSpec(args=[], varargs='readers', keywords=None, defaults=None), ('document', 'e0311508658a7e741fc39feea8be0ad2')) paddle.fluid.io.shuffle (ArgSpec(args=['reader', 'buf_size'], varargs=None, keywords=None, defaults=None), ('document', 'e42ea6fee23ce26b23cb142cd1d6522d')) paddle.fluid.io.firstn (ArgSpec(args=['reader', 'n'], varargs=None, keywords=None, defaults=None), ('document', 'c5bb8f7dd4f917f1569a368aab5b8aad')) @@ -379,7 +379,7 @@ paddle.fluid.layers.StaticRNN.step (ArgSpec(args=['self'], varargs=None, keyword paddle.fluid.layers.StaticRNN.step_input (ArgSpec(args=['self', 'x'], varargs=None, keywords=None, defaults=None), ('document', '903387ec11f3d0bf46821d31a68cffa5')) paddle.fluid.layers.StaticRNN.step_output (ArgSpec(args=['self', 'o'], varargs=None, keywords=None, defaults=None), ('document', '252890d4c3199a7623ab8667e13fd837')) paddle.fluid.layers.StaticRNN.update_memory (ArgSpec(args=['self', 'mem', 'var'], varargs=None, keywords=None, defaults=None), ('document', '7a0000520f179f35239956a5ba55119f')) -paddle.fluid.layers.reorder_lod_tensor_by_rank (ArgSpec(args=['x', 'rank_table'], varargs=None, keywords=None, defaults=None), ('document', '5b552a1f0f7eb4dacb768a975ba15d08')) +paddle.fluid.layers.reorder_lod_tensor_by_rank (ArgSpec(args=['x', 'rank_table'], varargs=None, keywords=None, defaults=None), ('document', 'db67cfcdd20ff6380d125a7553d62121')) paddle.fluid.layers.Print (ArgSpec(args=['input', 'first_n', 'message', 'summarize', 'print_tensor_name', 'print_tensor_type', 'print_tensor_shape', 'print_tensor_lod', 'print_phase'], varargs=None, keywords=None, defaults=(-1, None, 20, True, True, True, True, 'both')), ('document', '3130bed32922b9fd84ce2dea6250f635')) paddle.fluid.layers.is_empty (ArgSpec(args=['x', 'cond'], varargs=None, keywords=None, defaults=(None,)), ('document', '3011dc695f490afdf504dc24f628319a')) paddle.fluid.layers.sigmoid (ArgSpec(args=['x', 'name'], varargs=None, keywords=None, defaults=(None,)), ('document', '7bd26680989f33301a4a68000d5af4b0')) @@ -1098,7 +1098,7 @@ paddle.fluid.CUDAPinnedPlace ('paddle.fluid.core_avx.CUDAPinnedPlace', ('documen paddle.fluid.CUDAPinnedPlace.__init__ __init__(self: paddle.fluid.core_avx.CUDAPinnedPlace) -> None paddle.fluid.ParamAttr ('paddle.fluid.param_attr.ParamAttr', ('document', '7b5bfe856689036b8fffb71af1558e5c')) paddle.fluid.ParamAttr.__init__ (ArgSpec(args=['self', 'name', 'initializer', 'learning_rate', 'regularizer', 'trainable', 'gradient_clip', 'do_model_average'], varargs=None, keywords=None, defaults=(None, None, 1.0, None, True, None, True)), ('document', '6adf97f83acf6453d4a6a4b1070f3754')) -paddle.fluid.WeightNormParamAttr ('paddle.fluid.param_attr.WeightNormParamAttr', ('document', 'b5ae1698ea72d5a9428000b916a67379')) +paddle.fluid.WeightNormParamAttr ('paddle.fluid.param_attr.WeightNormParamAttr', ('document', 'ea029ec9e0dea75f136211c433154f25')) paddle.fluid.WeightNormParamAttr.__init__ (ArgSpec(args=['self', 'dim', 'name', 'initializer', 'learning_rate', 'regularizer', 'trainable', 'gradient_clip', 'do_model_average'], varargs=None, keywords=None, defaults=(None, None, None, 1.0, None, True, None, False)), ('document', '6adf97f83acf6453d4a6a4b1070f3754')) paddle.fluid.DataFeeder ('paddle.fluid.data_feeder.DataFeeder', ('document', 'd9e64be617bd5f49dbb08ac2bc8665e6')) paddle.fluid.DataFeeder.__init__ (ArgSpec(args=['self', 'feed_list', 'place', 'program'], varargs=None, keywords=None, defaults=(None,)), ('document', '6adf97f83acf6453d4a6a4b1070f3754')) diff --git a/paddle/fluid/operators/reorder_lod_tensor_by_rank_op.cc b/paddle/fluid/operators/reorder_lod_tensor_by_rank_op.cc index 7ceb5b58465..d414eff8799 100644 --- a/paddle/fluid/operators/reorder_lod_tensor_by_rank_op.cc +++ b/paddle/fluid/operators/reorder_lod_tensor_by_rank_op.cc @@ -30,7 +30,7 @@ class ReorderLoDTensorByRankTableOpProtoMaker AddInput("RankTable", "(LoDRankTable), the rank table according to which Input(X) is " "reordered."); - AddOutput("Out", "(LoDTensor), the reordered lod tensor."); + AddOutput("Out", "LoDTensor, the reordered lod tensor."); AddComment(R"DOC(ReorderLoDTensorByRankTable operator. Input(X) is a batch of sequences. Input(RankTable) stores new orders of the @@ -57,7 +57,8 @@ X = [Slice0, Slice1, Slice2, Slice3] and its LoD information is empty. The indices in RankTable are [3, 0, 2, 1]. Out = [Slice3, Slice0, Slice2, Slice1] with no LoD information is appended. -NOTE: This operator sorts Input(X) according to a given LoDRankTable which does +**NOTE**: +This operator sorts Input(X) according to a given LoDRankTable which does not need to be calculated according to Input(X). It can be calculated according to another different sequence, and then this operator sorts Input(X) according to the given LoDRankTable. diff --git a/python/paddle/fluid/layers/control_flow.py b/python/paddle/fluid/layers/control_flow.py index 3fdd22ceed7..4b9bf6e4b97 100644 --- a/python/paddle/fluid/layers/control_flow.py +++ b/python/paddle/fluid/layers/control_flow.py @@ -2215,12 +2215,11 @@ def reorder_lod_tensor_by_rank(x, rank_table): ${comment} Args: - - x(${x_type}): ${x_comment} - rank_table(${rank_table_type}): ${rank_table_type} + x(${x_type}): ${x_comment}. + rank_table(${rank_table_type}): ${rank_table_comment}. Returns: - out(${out_type}): ${out_comment} + out(${out_type}): ${out_comment}. Examples: .. code-block:: python diff --git a/python/paddle/fluid/param_attr.py b/python/paddle/fluid/param_attr.py index 94c9af3d1e1..09755405143 100644 --- a/python/paddle/fluid/param_attr.py +++ b/python/paddle/fluid/param_attr.py @@ -183,7 +183,7 @@ class ParamAttr(object): class WeightNormParamAttr(ParamAttr): """ - Used for weight Norm. Weight Norm is a reparameterization of the weight vectors + Parameter of weight Norm. Weight Norm is a reparameterization of the weight vectors in a neural network that decouples the magnitude of those weight vectors from their direction. Weight Norm has been implemented as discussed in this paper: `Weight Normalization: A Simple Reparameterization to Accelerate @@ -191,17 +191,27 @@ class WeightNormParamAttr(ParamAttr): `_. Args: - dim(int): Dimension over which to compute the norm. Default None. - name(str): The parameter's name. Default None. - initializer(Initializer): The method to initial this parameter. Default None. - learning_rate(float): The parameter's learning rate. The learning rate when - optimize is :math:`global\_lr * parameter\_lr * scheduler\_factor`. + dim(int): Dimension over which to compute the norm. Dim is a non-negative + number which is less than the rank of weight Tensor. For Example, dim can + be choosed from 0, 1, 2, 3 for convolution whose weight shape is [cout, cin, kh, kw] + and rank is 4. Default None, meaning that all elements will be normalized. + name(str, optional): The parameter's name. Default None, meaning that the name would + be created automatically. Please refer to :ref:`api_guide_Name` for more details. + initializer(Initializer): The method to initialize this parameter, such as + ``initializer = fluid.initializer.ConstantInitializer(1.0)``. Default None, + meaning that the weight parameter is initialized by Xavier initializer, and + the bias parameter is initialized by 0. + learning_rate(float32): The parameter's learning rate when + optimizer is :math:`global\_lr * parameter\_lr * scheduler\_factor`. Default 1.0. - regularizer(WeightDecayRegularizer): Regularization factor. Default None. - trainable(bool): Whether this parameter is trainable. Default True. - gradient_clip(BaseGradientClipAttr): The method to clip this parameter's - gradient. Default None. - do_model_average(bool): Whether this parameter should do model average. + regularizer(WeightDecayRegularizer): Regularization factor, such as + ``regularizer = fluid.regularizer.L2DecayRegularizer(regularization_coeff=0.1)``. + Default None, meaning that there is no regularization. + trainable(bool, optional): Whether this parameter is trainable. Default True. + gradient_clip: The method to clip this parameter's gradient, such as + ``gradient_clip = fluid.clip.GradientClipByNorm(clip_norm=2.0))`` . + Default None, meaning that there is no gradient clip. + do_model_average(bool, optional): Whether this parameter should do model average. Default False. Examples: @@ -212,8 +222,14 @@ class WeightNormParamAttr(ParamAttr): fc = fluid.layers.fc(input=data, size=1000, param_attr=fluid.WeightNormParamAttr( - dim=None, - name='weight_norm_param')) + dim=None, + name='weight_norm_param', + initializer=fluid.initializer.ConstantInitializer(1.0), + learning_rate=1.0, + regularizer=fluid.regularizer.L2DecayRegularizer(regularization_coeff=0.1), + trainable=True, + gradient_clip=fluid.clip.GradientClipByNorm(clip_norm=2.0), + do_model_average=False)) """ # List to record the parameters reparameterized by weight normalization. diff --git a/python/paddle/reader/decorator.py b/python/paddle/reader/decorator.py index baef5133534..b50e66e4c31 100644 --- a/python/paddle/reader/decorator.py +++ b/python/paddle/reader/decorator.py @@ -60,13 +60,33 @@ def cache(reader): def map_readers(func, *readers): """ Creates a data reader that outputs return value of function using - output of each data readers as arguments. + output of each data reader as arguments. - :param func: function to use. The type of func should be (Sample) => Sample - :type: callable - :param readers: readers whose outputs will be used as arguments of func. - :return: the created data reader. - :rtype: callable + If input readers output the following data entries: 2 3, + and the input func is mul(x, y), + the output of the resulted reader will be 6. + + + Args: + func: a function to read data and compute result, the output of this function + will be set as the output of the resulted data reader. + readers (Reader|list of Reader): list of readers whose outputs will be used as arguments of func. + + Returns: + the resulted data reader (Reader) + + Examples: + + .. code-block:: python + + import paddle.reader + d = {"h": 0, "i": 1} + def func(x): + return d[x] + def reader(): + yield "h" + yield "i" + map_reader_result = paddle.reader.map_readers(func, reader) """ def reader(): @@ -187,16 +207,29 @@ def compose(*readers, **kwargs): The composed reader will output: (1, 2, 3, 4, 5) - :param readers: readers that will be composed together. - :param check_alignment: if True, will check if input readers are aligned - correctly. If False, will not check alignment and trailing outputs - will be discarded. Defaults to True. - :type check_alignment: bool - - :return: the new data reader. - - :raises ComposeNotAligned: outputs of readers are not aligned. - Will not raise when check_alignment is set to False. + Args: + readers (Reader|list of Reader): readers that will be composed together. + check_alignment(bool, optional): Indicates whether the input readers are checked for + alignment. If True, whether input readers are aligned + correctly will be checked, else alignment will not be checkout and trailing outputs + will be discarded. Defaults to True. + + Returns: + the new data reader (Reader). + + Raises: + ComposeNotAligned: outputs of readers are not aligned. This will not raise if check_alignment is set to False. + + Examples: + .. code-block:: python + + import paddle.fluid as fluid + def reader_creator_10(dur): + def reader(): + for i in range(10): + yield i + return reader + reader = fluid.io.compose(reader_creator_10(0), reader_creator_10(0)) """ check_alignment = kwargs.pop('check_alignment', True) -- GitLab