From b23f00a0d7ea3045323ca88055c5a2070a752daf Mon Sep 17 00:00:00 2001 From: Jiabin Yang Date: Thu, 10 Oct 2019 13:29:03 +0800 Subject: [PATCH] Refine en doc (#20317) * test=develop, fix docker with paddle nccl problem * test=develop, refine en_doc for Variable and Program * test=document_fix, fix English doc for Variable and Program * test=document_fix, refine astype code block style * test=document_fix, add example code for Variable properties --- paddle/fluid/API.spec | 36 +- python/paddle/fluid/framework.py | 374 ++++++++++++++------ python/paddle/fluid/layers/math_op_patch.py | 40 ++- 3 files changed, 313 insertions(+), 137 deletions(-) diff --git a/paddle/fluid/API.spec b/paddle/fluid/API.spec index 4f157d61df7..1b1389e3ab2 100755 --- a/paddle/fluid/API.spec +++ b/paddle/fluid/API.spec @@ -1,13 +1,13 @@ -paddle.fluid.Program ('paddle.fluid.framework.Program', ('document', '4f9e1829c89e0711355820e935d2b447')) +paddle.fluid.Program ('paddle.fluid.framework.Program', ('document', '9d8de4f0398ff2b01d4b572ee412b6aa')) paddle.fluid.Program.__init__ (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', '6adf97f83acf6453d4a6a4b1070f3754')) -paddle.fluid.Program.block (ArgSpec(args=['self', 'index'], varargs=None, keywords=None, defaults=None), ('document', '28d066e432ceda86810b1e7deb8a4afa')) -paddle.fluid.Program.clone (ArgSpec(args=['self', 'for_test'], varargs=None, keywords=None, defaults=(False,)), ('document', '1e910e8c4186e8ff1afb62602f369033')) -paddle.fluid.Program.current_block (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', '365e49ce9f346ac6d54265e29db447b5')) -paddle.fluid.Program.global_block (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', 'dd3f2b49147861d6ae48989a77482f05')) -paddle.fluid.Program.list_vars (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', '757cf8d083dff9507676b17376ac5af1')) -paddle.fluid.Program.parse_from_string (ArgSpec(args=['binary_str'], varargs=None, keywords=None, defaults=None), ('document', '70e063a0a09d5a8ed322db0d5de9edb4')) -paddle.fluid.Program.to_string (ArgSpec(args=['self', 'throw_on_error', 'with_details'], varargs=None, keywords=None, defaults=(False,)), ('document', '6dfb00cd50eb515dcf2548a68ea94bfb')) -paddle.fluid.default_startup_program (ArgSpec(args=[], varargs=None, keywords=None, defaults=None), ('document', 'accb52b28228f8e93a26fabdc960f56c')) +paddle.fluid.Program.block (ArgSpec(args=['self', 'index'], varargs=None, keywords=None, defaults=None), ('document', 'f2b2f468fef697ede6ea5bf7a9ba489c')) +paddle.fluid.Program.clone (ArgSpec(args=['self', 'for_test'], varargs=None, keywords=None, defaults=(False,)), ('document', 'c60aaaa8e2ca192dadffbb6ef0de8f60')) +paddle.fluid.Program.current_block (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', '0efa58429d84407256665cc1ad66a240')) +paddle.fluid.Program.global_block (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', '0a25153e749268585354f8ae7eb2713b')) +paddle.fluid.Program.list_vars (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', '81440aaee8e4cb6c3488e8f9bbf1143e')) +paddle.fluid.Program.parse_from_string (ArgSpec(args=['binary_str'], varargs=None, keywords=None, defaults=None), ('document', 'fc4a5660ff4280278402688f0014ce7f')) +paddle.fluid.Program.to_string (ArgSpec(args=['self', 'throw_on_error', 'with_details'], varargs=None, keywords=None, defaults=(False,)), ('document', '7dde33f16b63aa50d474870a9cebb539')) +paddle.fluid.default_startup_program (ArgSpec(args=[], varargs=None, keywords=None, defaults=None), ('document', 'f53890b2fb8c0642b6047e4fee2d6d58')) paddle.fluid.default_main_program (ArgSpec(args=[], varargs=None, keywords=None, defaults=None), ('document', '853718df675e59aea7104f3d61bbf11d')) paddle.fluid.program_guard (ArgSpec(args=['main_program', 'startup_program'], varargs=None, keywords=None, defaults=(None,)), ('document', '78fb5c7f70ef76bcf4a1862c3f6b8191')) paddle.fluid.name_scope (ArgSpec(args=['prefix'], varargs=None, keywords=None, defaults=(None,)), ('document', '917d313881ff990de5fb18d98a9c7b42')) @@ -16,16 +16,16 @@ paddle.fluid.cpu_places (ArgSpec(args=['device_count'], varargs=None, keywords=N paddle.fluid.cuda_pinned_places (ArgSpec(args=['device_count'], varargs=None, keywords=None, defaults=(None,)), ('document', '567ac29567716fd8e7432b533337d529')) paddle.fluid.in_dygraph_mode (ArgSpec(args=[], varargs=None, keywords=None, defaults=None), ('document', 'df1f4d1ed7e1eefe04f6361efda6b75a')) paddle.fluid.is_compiled_with_cuda (ArgSpec(args=[], varargs=None, keywords=None, defaults=None), ('document', '60c7f107a5050aeb58bb74eb175672b5')) -paddle.fluid.Variable ('paddle.fluid.framework.Variable', ('document', '65ff735c2b96673d7131f5ff6b0db40c')) +paddle.fluid.Variable ('paddle.fluid.framework.Variable', ('document', '8e51f2adcad7ae33aa35a178cceebdf6')) paddle.fluid.Variable.__init__ (ArgSpec(args=['self', 'block', 'type', 'name', 'shape', 'dtype', 'lod_level', 'capacity', 'persistable', 'error_clip', 'stop_gradient', 'is_data', 'need_check_feed'], varargs=None, keywords='kwargs', defaults=(VarType.LOD_TENSOR, None, None, None, None, None, None, None, False, False, False)), ('document', '6adf97f83acf6453d4a6a4b1070f3754')) -paddle.fluid.Variable.astype (ArgSpec(args=['self', 'dtype'], varargs=None, keywords=None, defaults=None), ('document', '78541af4039262ed7ce3c447f8cc9cc1')) -paddle.fluid.Variable.backward (ArgSpec(args=['self', 'backward_strategy'], varargs=None, keywords=None, defaults=(None,)), ('document', 'cb928fa194da09694f4267f0a25268f1')) -paddle.fluid.Variable.clear_gradient (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', '509a96d23c876fc5bfb10e1147e21d5f')) -paddle.fluid.Variable.detach (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', '0730b2d310b014d9b0a903b2034757d7')) -paddle.fluid.Variable.gradient (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', '86b246bfaf20f3058e91927abbcf9fb9')) -paddle.fluid.Variable.numpy (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', '7536e8feb56d827875943e7f01d406fc')) -paddle.fluid.Variable.set_value (ArgSpec(args=['self', 'value'], varargs=None, keywords=None, defaults=None), ('document', 'c424b9e763ff51c38a6917f98026fe7d')) -paddle.fluid.Variable.to_string (ArgSpec(args=['self', 'throw_on_error', 'with_details'], varargs=None, keywords=None, defaults=(False,)), ('document', '31f359a2c074f26dc0ffff296fc3983f')) +paddle.fluid.Variable.astype (ArgSpec(args=['self', 'dtype'], varargs=None, keywords=None, defaults=None), ('document', 'ffc7049afe250829b56986c40cf3cca3')) +paddle.fluid.Variable.backward (ArgSpec(args=['self', 'backward_strategy'], varargs=None, keywords=None, defaults=(None,)), ('document', 'a2fabca0102442aae4d6537028574d07')) +paddle.fluid.Variable.clear_gradient (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', 'c6e511dcccf51a95eeb83447322b4345')) +paddle.fluid.Variable.detach (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', '833afb90a8d9353610e3d671b2de9f4f')) +paddle.fluid.Variable.gradient (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', 'b8fe1354051f3cc953c280c8cabdd3fc')) +paddle.fluid.Variable.numpy (ArgSpec(args=['self'], varargs=None, keywords=None, defaults=None), ('document', '760ab11e4019258b3004fe9002819170')) +paddle.fluid.Variable.set_value (ArgSpec(args=['self', 'value'], varargs=None, keywords=None, defaults=None), ('document', '69deb77a9dedc61f7b731a6a7709fa5b')) +paddle.fluid.Variable.to_string (ArgSpec(args=['self', 'throw_on_error', 'with_details'], varargs=None, keywords=None, defaults=(False,)), ('document', '65cd237e2d30c12e412c9cafbbd00791')) paddle.fluid.load_op_library (ArgSpec(args=['lib_filename'], varargs=None, keywords=None, defaults=None), ('document', 'c009b2ea5fb6520f2d2f53aafec788e0')) paddle.fluid.Executor ('paddle.fluid.executor.Executor', ('document', 'dcb7d6de26088df84b74226bf24f4ae1')) paddle.fluid.Executor.__init__ (ArgSpec(args=['self', 'place'], varargs=None, keywords=None, defaults=None), ('document', '6adf97f83acf6453d4a6a4b1070f3754')) diff --git a/python/paddle/fluid/framework.py b/python/paddle/fluid/framework.py index f0a98d6c451..55844613b63 100644 --- a/python/paddle/fluid/framework.py +++ b/python/paddle/fluid/framework.py @@ -418,18 +418,20 @@ def _debug_string_(proto, throw_on_error=True): class Variable(object): """ - **Notes:** + **Notes**: **The constructor of Variable should not be invoked directly.** + **In Static Graph Mode: Please use** `Block.create_var` **to create a Static variable which has no data until being feed.** - **In Dygraph Mode: Please use** `fluid.dygraph.to_variable()` **to create a dygraph variable with real data** - In Fluid, every input and output of an operator is a variable. In most + **In Dygraph Mode: Please use** :ref:`api_fluid_dygraph_to_variable` **to create a dygraph variable with real data** + + In Fluid, every input and output of an OP is a variable. In most cases, variables are used for holding different kinds of data or training - labels. A variable belongs to a block. All variable has its own name and - two variables in different blocks could have the same name. + labels. A variable belongs to a :ref:`api_guide_Block_en` . All variable has its own name and + two variables in different :ref:`api_guide_Block_en` could have the same name. There are many kinds of variables. Each kind of them has its own attributes - and usages. Please refer to the framework.proto for details. + and usages. Please refer to the `framework.proto `_ for details. Most of a Variable's member variables can be setted to be None. It mean it is not available or will be specified later. @@ -445,7 +447,7 @@ class Variable(object): new_variable = cur_block.create_var(name="X", shape=[-1, 23, 48], dtype='float32') - In Dygraph Mode: + In `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ Mode: .. code-block:: python @@ -577,15 +579,14 @@ class Variable(object): @dygraph_only def detach(self): """ - **Notes: This API is ONLY avaliable in Dygraph mode** + **Notes**: + **This API is ONLY avaliable in Dygraph mode** Returns a new Variable, detached from the current graph. Returns: - Variable: The detached Variable. + ( :ref:`api_guide_Variable_en` | dtype is same as current Variable): The detached Variable. - Returns type: - Variable(Tensor|LoDTensor) dtype is same as current Variable Examples: .. code-block:: python @@ -617,15 +618,16 @@ class Variable(object): @dygraph_only def numpy(self): """ - **Notes: This API is ONLY avaliable in Dygraph mode** + **Notes**: + **This API is ONLY avaliable in Dygraph mode** - Returns a numpy array shows the value of current :ref:`api_guide_Variable` + Returns a numpy array shows the value of current :ref:`api_guide_Variable_en` Returns: ndarray: The numpy value of current Variable. Returns type: - ndarray dtype is same as current Variable + ndarray: dtype is same as current Variable Examples: .. code-block:: python @@ -653,14 +655,14 @@ class Variable(object): @dygraph_only def set_value(self, value): """ + **Notes**: + **This API is ONLY avaliable in Dygraph mode** + Set a new value for this Variable. Args: value (Variable|np.ndarray): the new value. - Returns: - None. - Examples: .. code-block:: python @@ -692,14 +694,16 @@ class Variable(object): @dygraph_only def backward(self, backward_strategy=None): """ - **Notes: This API is ONLY avaliable in Dygraph mode** + **Notes**: + **This API is ONLY avaliable in Dygraph mode** Run backward of current Graph which starts from current Variable - Parameter: - - **backward_strategy** : ( :ref:`api_fluid_dygraph_BackwardStrategy` ) - The Backward Strategy to run backward + Args: + backward_strategy( :ref:`api_fluid_dygraph_BackwardStrategy` ): The Backward Strategy to run backward - Returns: None + Returns: + NoneType: None Examples: .. code-block:: python @@ -712,6 +716,8 @@ class Variable(object): inputs2 = [] for _ in range(10): tmp = fluid.dygraph.base.to_variable(x) + # if we don't set tmp's stop_gradient as False then, all path to loss will has no gradient since + # there is no one need gradient on it. tmp.stop_gradient=False inputs2.append(tmp) ret2 = fluid.layers.sums(inputs2) @@ -735,13 +741,13 @@ class Variable(object): @dygraph_only def gradient(self): """ - **Notes: This API is ONLY avaliable in Dygraph mode** + **Notes**: + **This API is ONLY avaliable in Dygraph mode** Get the Gradient of Current Variable - Returns: Numpy value of the gradient of current Variable - - Returns type: ndarray + Returns: + ndarray: Numpy value of the gradient of current Variable Examples: .. code-block:: python @@ -778,9 +784,12 @@ class Variable(object): @dygraph_only def clear_gradient(self): """ - **Notes: This API is ONLY avaliable in Dygraph mode** + **Notes**: + **1. This API is ONLY avaliable in Dygraph mode** + + **2. Use it only Variable has gradient, normally we use this for Parameters since other temporal Variable will be deleted by Python's GC** - Clear (set to zero) the Gradient of Current Variable + Clear (set to ``0`` ) the Gradient of Current Variable Returns: None @@ -816,19 +825,15 @@ class Variable(object): """ Get debug string. - Parameters: - - **throw_on_error** (bool): True if raise an exception when self is - not initialized. - - **with_details** (bool): more details about variables and parameters - (e.g. trainable, optimize_attr, ...) will be printed when - with_details is True. Default False; + Args: + + throw_on_error (bool): True if raise an exception when self is not initialized. + + with_details (bool): more details about variables and parameters (e.g. trainable, optimize_attr, ...) will be printed when with_details is True. Default value is False; Returns: str: The debug string. - Returns Type: - str - Examples: .. code-block:: python @@ -840,7 +845,7 @@ class Variable(object): shape=[-1, 23, 48], dtype='float32') print(new_variable.to_string(True)) - print("\n=============with detail===============\n") + print("=============with detail===============") print(new_variable.to_string(True, True)) """ if in_dygraph_mode(): @@ -870,6 +875,35 @@ class Variable(object): @property def stop_gradient(self): + """ + Indicating if we stop gradient from current Variable + + **Notes: This Property has default value as** ``True`` **in** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **mode, while Parameter's default value is False. However, in Static Graph Mode all Variable's default stop_gradient value is** ``False`` + + Examples: + .. code-block:: python + + import paddle.fluid as fluid + import numpy as np + + with fluid.dygraph.guard(): + value0 = np.arange(26).reshape(2, 13).astype("float32") + value1 = np.arange(6).reshape(2, 3).astype("float32") + value2 = np.arange(10).reshape(2, 5).astype("float32") + fc = fluid.FC("fc1", size=5, dtype="float32") + fc2 = fluid.FC("fc2", size=3, dtype="float32") + a = fluid.dygraph.to_variable(value0) + b = fluid.dygraph.to_variable(value1) + c = fluid.dygraph.to_variable(value2) + out1 = fc(a) + out2 = fc2(b) + out1.stop_gradient = True + out = fluid.layers.concat(input=[out1, out2, c], axis=1) + out.backward() + + assert (fc._w.gradient() == 0).all() + assert (out1.gradient() == 0).all() + """ if in_dygraph_mode(): return self._ivar.stop_gradient else: @@ -884,6 +918,27 @@ class Variable(object): @property def persistable(self): + """ + Indicating if we current Variable should be long-term alive + + + **Notes: This Property will be deprecated and this API is just to help user understand concept** + + **1. All Variable's persistable is** ``False`` **except Parameters.** + + **2. In** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **mode, this property should not be changed** + + Examples: + .. code-block:: python + + import paddle.fluid as fluid + cur_program = fluid.Program() + cur_block = cur_program.current_block() + new_variable = cur_block.create_var(name="X", + shape=[-1, 23, 48], + dtype='float32') + print("persistable of current Var is: {}".format(new_variable.persistable)) + """ if in_dygraph_mode(): return self._ivar.persistable else: @@ -900,6 +955,22 @@ class Variable(object): @property def name(self): + """ + Indicating name of current Variable + + **Notes: If it has two or more Varaible share the same name in the same** :ref:`api_guide_Block_en` **, it means these Variable will share content in no-** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **mode. This is how we achieve Parameter sharing** + + Examples: + .. code-block:: python + + import paddle.fluid as fluid + cur_program = fluid.Program() + cur_block = cur_program.current_block() + new_variable = cur_block.create_var(name="X", + shape=[-1, 23, 48], + dtype='float32') + print("name of current Var is: {}".format(new_variable.name)) + """ if in_dygraph_mode(): return self._ivar.name else: @@ -914,6 +985,23 @@ class Variable(object): @property def shape(self): + """ + Indicating shape of current Variable + + **Notes: This is a read-only property** + + Examples: + .. code-block:: python + + import paddle.fluid as fluid + cur_program = fluid.Program() + cur_block = cur_program.current_block() + new_variable = cur_block.create_var(name="X", + shape=[-1, 23, 48], + dtype='float32') + print("shape of current Var is: {}".format(new_variable.shape)) + + """ # convert to tuple, make it as same as numpy API. if in_dygraph_mode(): return self._ivar.shape @@ -922,6 +1010,22 @@ class Variable(object): @property def dtype(self): + """ + Indicating data type of current Variable + + **Notes: This is a read-only property** + + Examples: + .. code-block:: python + + import paddle.fluid as fluid + cur_program = fluid.Program() + cur_block = cur_program.current_block() + new_variable = cur_block.create_var(name="X", + shape=[-1, 23, 48], + dtype='float32') + print("Dtype of current Var is: {}".format(new_variable.dtype)) + """ if in_dygraph_mode(): return self._ivar.dtype else: @@ -930,6 +1034,27 @@ class Variable(object): @property @dygraph_not_support def lod_level(self): + """ + Indicating ``LoD`` info of current Variable, please refer to :ref:`api_fluid_LoDTensor_en` to check the meaning + of ``LoD`` + + **Notes**: + + **1. This is a read-only property** + + **2. Don't support this property in** `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ **mode, it's value should be** ``0(int)`` + + Examples: + .. code-block:: python + + import paddle.fluid as fluid + cur_program = fluid.Program() + cur_block = cur_program.current_block() + new_variable = cur_block.create_var(name="X", + shape=[-1, 23, 48], + dtype='float32') + print("LoD Level of current Var is: {}".format(new_variable.lod_level)) + """ # TODO(minqiyang): Support lod_level in dygraph mode if in_dygraph_mode(): raise Exception("Dygraph model DO NOT supprt lod") @@ -937,6 +1062,22 @@ class Variable(object): @property def type(self): + """ + Indicating Type of current Variable + + **Notes: This is a read-only property** + + Examples: + .. code-block:: python + + import paddle.fluid as fluid + cur_program = fluid.Program() + cur_block = cur_program.current_block() + new_variable = cur_block.create_var(name="X", + shape=[-1, 23, 48], + dtype='float32') + print("Type of current Var is: {}".format(new_variable.type)) + """ if in_dygraph_mode(): return self._ivar.type else: @@ -3166,10 +3307,12 @@ class Program(object): control flow op like conditional_block, while :ref:`api_fluid_layers_While` is included, it will contain nested block. - Please reference the framework.proto for details. + Please reference the + `framework.proto `_ + for details. A set of Program usually contains startup program and main program. - A startup program is set to contain some initial work , and the main + A startup program is set to contain some initial work, eg. initialize the ``Parameter``, and the main program will contain the network structure and vars for train. A set of Program can be used for test or train, in train program , @@ -3177,15 +3320,13 @@ class Program(object): program Paddle will prune some content which is irrelevant to test, eg. backward ops and vars. - Notes: we have default_startup_program and default_main_program - by default, a pair of them will shared the parameters. - The default_startup_program only run once to initialize parameters, - default_main_program run in every mini batch and adjust the weights. + **Notes**: + **we have** :ref:`api_fluid_default_startup_program` **and** :ref:`api_fluid_default_main_program` + **by default, a pair of them will shared the parameters. The** :ref:`api_fluid_default_startup_program` **only run once to initialize parameters,** + :ref:`api_fluid_default_main_program` **run in every mini batch and adjust the weights.** Returns: - An empty Program. - - Return type: Program + Program: An empty Program. Examples: .. code-block:: python @@ -3370,20 +3511,17 @@ class Program(object): """ To debug string. - Parameters: - - **throw_on_error** (bool): raise Value error when any of required fields - is not set. + Args: + + throw_on_error (bool): raise Value error when any of required fields is not set. - - **with_details** (bool): True if more details about variables and - parameters, e.g., :code:`trainable`, :code:`optimize_attr`, need - to print. + with_details (bool): True if more details about variables and parameters, e.g., :code:`trainable`, :code:`optimize_attr`, need to print. Returns: - The debug string describe current Program. + str: The debug string describe current Program. Raises: - ValueError: If any of required fields is not set and throw_on_error is - True. + ValueError: If any of required fields is not set and throw_on_error is True. Examples: .. code-block:: python @@ -3392,8 +3530,9 @@ class Program(object): prog = fluid.default_main_program() prog_string = prog.to_string(throw_on_error=True, with_details=False) - print(prog_string) - + print("program string without detial: {}".format(prog_string)) + prog_string_with_detail = prog.to_string(throw_on_error=True, with_details=True) + print("program string with detial: {}".format(prog_string_with_detail)) """ assert isinstance(throw_on_error, bool) and isinstance(with_details, bool) @@ -3425,15 +3564,17 @@ class Program(object): def clone(self, for_test=False): """ **Notes**: - **1.** :code:`Program.clone()` **method DOES NOT clone** :code:`py_reader`. - **2. Recommend you to use** :code:`clone` **before using** :code:`Opimizer.minimize`.** + **1.** :code:`Program.clone()` **method DOES NOT clone** :ref:`api_fluid_io_DataLoader` . + + **2. Recommend you to use** :code:`clone` **before using** :code:`Opimizer.minimize`. + **3. This API has no effect in Dygraph Mode** Create a new Program with forward content of original one when ``for_test=True``. Create a new Program as the same as original one when ``for_test=False`` - Some operators, e.g., :ref:`cn_api_fluid_layers_batch_norm` , behave differently between + Some operators, e.g., :ref:`api_fluid_layers_batch_norm` , behave differently between training and testing. They have an attribute, :code:`is_test`, to control this behaviour. This method will change the :code:`is_test` attribute of them to :code:`True` when :code:`for_test=True`. @@ -3442,32 +3583,31 @@ class Program(object): * Set for_test to True when we want to clone the program for testing. We will prune the backward and optimize part of the program when you use :code:`clone` after :code:`Opimizer.minimize`, but we still - recommend you to use :code:`clone` before using :code:`Opimizer.minimize`. For example: + recommend you to use :code:`clone` before using :code:`Opimizer.minimize`. + For Example: + .. code-block:: python - .. code-block:: python + test_program = fluid.default_main_program().clone(for_test=True) + # Here we use clone before Momentum + optimizer = fluid.optimizer.Momentum(learning_rate=0.01, momentum=0.9) + optimizer.minimize() - test_program = fluid.default_main_program().clone(for_test=True) - # Here we use clone before Momentum - optimizer = fluid.optimizer.Momentum(learning_rate=0.01, momentum=0.9) - optimizer.minimize() + Args: - Parameters: - - **for_test** (bool) - True if change the :code:`is_test` attribute of - operators to :code:`True`. + for_test (bool): True if change the :code:`is_test` attribute of operators to :code:`True`. - Returns: A new Program with forward content of original one when ``for_test=True``. A new Program as the same as original one when ``for_test=False`` + Returns: + Program: A new Program with forward content of original one when ``for_test=True``. A new Program as the same as original one when ``for_test=False`` - Return type: Program Examples: - Notes: The Program's order maybe different after :code:`clone` and + **Notes: The Program's order maybe different after** :code:`clone` **and this will not affect your training or testing progress. In the following - example we give you an simple method :code:`print_prog(program)` to + example we give you an simple method** :code:`print_prog(program)` **to print Program Descs inorder to make sure you have same print result - after :code:`clone`: - + after** :code:`clone`: .. code-block:: python import paddle.fluid as fluid @@ -3777,19 +3917,20 @@ class Program(object): @staticmethod def parse_from_string(binary_str): """ - **Notes:** - **- All information about parameters will be lost after serialization** - **- This API has no effect in Dygraph mode** + **Notes**: + **1. All information about parameters will be lost after serialization** + + **2. This API has no effect in Dygraph mode** Deserialize a Program from `protobuf `_ binary string. This method always use to save and load model - Parameters: - - **binary_str_type** (str) - the binary prootbuf string. + Args: - Returns: Program: A deserialized Program. + binary_str_type (str): the binary prootbuf string. - Return type: Program + Returns: + Program: A deserialized Program. Examples: .. code-block:: python @@ -3839,14 +3980,14 @@ class Program(object): @property def random_seed(self): """ - **Notes: It must be set before the operators have been added.** - - The default random seed for random operators in Program. Zero means get + The default random seed for random operators in Program. ``0`` means get the random seed from random device. - Returns: random seed in current Program + **Notes: It must be set before the operators have been added.** + + Returns: + int64: Random seed in current Program - Return type: int64 Examples: .. code-block:: python @@ -3869,13 +4010,13 @@ class Program(object): @property def num_blocks(self): """ - **Notes: This API has no effect in Dygraph mode** - The number of :ref:`api_guide_Block_en` in this Program. - Returns: num of :ref:`api_guide_Block_en` in current Program + **Notes: This API has no effect in Dygraph mode** + + Returns: + int(Platform-dependent size): num of :ref:`api_guide_Block_en` in current Program - Return type: int(Platform-dependent size) Examples: .. code-block:: python @@ -3901,13 +4042,14 @@ class Program(object): def global_block(self): """ - **Notes: This API has no effect in Dygraph mode** + **Notes**: + **This API has no effect in Dygraph mode** Get the first :ref:`api_guide_Block_en` of this Program. - Returns: The first :ref:`api_guide_Block_en` of this Program. + Returns: + :ref:`api_guide_Block_en`: The first :ref:`api_guide_Block_en` of this Program. - Return type: :ref:`api_guide_Block_en` Examples: .. code-block:: python @@ -3923,16 +4065,16 @@ class Program(object): def block(self, index): """ - **Notes: This API has no effect in Dygraph mode** + **Notes**: + **This API has no effect in Dygraph mode** Get the :code:`index` :ref:`api_guide_Block_en` of this Program - Parameter: - - **index** (int) - The index of :ref:`api_guide_Block_en` to get - - Returns: The :code:`index` block + Args: + index (int) - The index of :ref:`api_guide_Block_en` to get - Return type: :ref:`api_guide_Block_en` + Returns: + :ref:`api_guide_Block_en`: The :code:`index` block Examples: .. code-block:: python @@ -3947,14 +4089,14 @@ class Program(object): def current_block(self): """ - **Notes: This API has no effect in Dygraph mode** - - Get the current block. The :code:`current` block is the block to append - operators. + **Notes**: + **This API has no effect in Dygraph mode** - Returns: The :code:`index` block + Get the current :ref:`api_guide_Block_en` . The :code:`current` :ref:`api_guide_Block_en` + is the :ref:`api_guide_Block_en` to append operators. - Return type: Block + Returns: + :ref:`api_guide_Block_en`: The :code:`index` :ref:`api_guide_Block_en` Examples: .. code-block:: python @@ -3973,6 +4115,7 @@ class Program(object): to new block. Args: + parent_idx(int): The parent block index. Returns: @@ -4081,11 +4224,10 @@ class Program(object): @dygraph_not_support def list_vars(self): """ - Get all :ref:`api_guide_Variable` from this Program. A iterable object is returned. + Get all :ref:`api_guide_Variable_en` from this Program. A iterable object is returned. - Returns: The Generator will yield every variable in this program. - - Return type: iterable :ref:`api_guide_Variable_en` + Returns: + iterable :ref:`api_guide_Variable_en`: The Generator will yield every variable in this program. Examples: .. code-block:: python @@ -4207,17 +4349,17 @@ def default_startup_program(): """ Get default/global startup program. - The layer function in :code:`fluid.layers` will create parameters, readers, - NCCL handles as global variables. The :code:`startup_program` will - initialize them by the operators in startup program. The layer function will + The layer function in :ref:`api_fluid_layers` will create parameters, :ref:`api_paddle_data_reader_reader` , + `NCCL `_ handles as global variables. The :code:`startup_program` will + initialize them by the OPs in startup :ref:`api_fluid_Program` . The :ref:`api_fluid_layers` function will append these initialization operators into startup program. This method will return the :code:`default` or the :code:`current` startup - program. Users can use :code:`fluid.program_guard` to switch program. + program. Users can use :ref:`api_fluid_program_guard` to switch :ref:`api_fluid_Program` . - Returns: current default startup program + Returns: current default startup :ref:`api_fluid_Program` - Returns type: Program + Returns type: :ref:`api_fluid_Program` Examples: .. code-block:: python diff --git a/python/paddle/fluid/layers/math_op_patch.py b/python/paddle/fluid/layers/math_op_patch.py index bd56762f451..d14a39ae58f 100644 --- a/python/paddle/fluid/layers/math_op_patch.py +++ b/python/paddle/fluid/layers/math_op_patch.py @@ -93,14 +93,48 @@ def monkey_patch_variable(): def astype(self, dtype): """ + **Notes**: + **The variable must be a** :ref:`api_fluid_Tensor` + Cast a variable to a specified data type. - NOTE: The variable must be a Tensor + Args: + self(Variable): The source variable - dtype: The target dtype + + dtype: The target data type Returns: - Variable with new dtype + Variable: Variable with new dtype + + Examples: + In Static Graph Mode: + + .. code-block:: python + + import paddle.fluid as fluid + + startup_prog = fluid.Program() + main_prog = fluid.Program() + with fluid.program_guard(startup_prog, main_prog): + original_variable = fluid.data(name = "new_variable", shape=[2,2], dtype='float32') + new_variable = original_variable.astype('int64') + print("new var's dtype is: {}".format(new_variable.dtype)) + + In Dygraph Mode: + + .. code-block:: python + + import paddle.fluid as fluid + import numpy as np + + x = np.ones([2, 2], np.float32) + with fluid.dygraph.guard(): + original_variable = fluid.dygraph.to_variable(x) + print("original var's dtype is: {}, numpy dtype is {}".format(original_variable.dtype, original_variable.numpy().dtype)) + new_variable = original_variable.astype('int64') + print("new var's dtype is: {}, numpy dtype is {}".format(new_variable.dtype, new_variable.numpy().dtype)) + """ block = current_block(self) out = create_new_tmp_var(block, dtype) -- GitLab