[API 2.0]migrate example for gradients/append_backward/program_guard (#2685)

* migrate 2.0 api doc

* migrate program_guard

* variable -> Tensor

doc/paddle/api/paddle/fluid/backward/append_backward_cn.rst

@@ -4,70 +4,73 @@ append_backward
 -------------------------------
 
 
-.. py:function:: paddle.fluid.backward.append_backward(loss, parameter_list=None, no_grad_set=None, callbacks=None)
+.. py:function:: paddle.static.append_backward(loss, parameter_list=None, no_grad_set=None, callbacks=None)
 
 
 
 
-该接口将向主程序（``main_program``）追加反向部分 。
+该接口将向主程序（``main_program``）添加反向部分 。
 
-完整的神经网络训练由前向和反向传播组成。但是当我们配置网络时，我们只需要指定其前向部分。
+完整的神经网络训练由前向和反向传播两部分组成。但是当我们配置网络时，我们只需要指定其前向部分。
 该接口使用链式法则，能够根据前向部分自动生成反向部分。
 
 在大多数情况下，用户无需手动调用此接口，它将由优化器（``Optimizer``）的 ``minimize`` 函数自动调用。
 
 参数：
-    - **loss** ( :ref:`api_guide_Variable` ) - 网络的损失变量。
-    - **parameter_list** （list [Variable|str]，可选）- 指定优化器需要更新的参数或参数名称列表。如果为 ``None`` ，则将更新所有参数。默认值为 ``None``。
-    - **no_grad_set** （set [Variable|str]，可选）-  在 `block0` ( :ref:`api_guide_Block` ) 中要忽略梯度的 :ref:`api_guide_Variable` 的名字的集合。所有的 :ref:`api_guide_Block` 中带有 ``stop_gradient = True`` 的所有 :ref:`api_guide_Variable` 的名字都会被自动添加到此集合中。如果该参数不为 ``None``，则会将该参数集合的内容添加到默认的集合中。默认值为 ``None``。
-    - **callbacks** （list [callable object]，可选）- 回调函数列表。用于在反向传播构建中执行一些自定义作业。每次将新的梯度OP添加到程序中时，将调用其中的所有可调用对象。可调用对象必须有两个输入参数： :ref:`api_guide_Block` 和 ``context`` 。 :ref:`api_guide_Block` 是将被添加到新梯度算子的块。 ``context`` 是一个映射，其键是梯度 :ref:`api_guide_Variable` 名，值是对应的原始 :ref:`api_guide_Variable` 。除此之外， ``context`` 还有另一个特殊的键值对：键是字符串 ``__ current_op_desc__`` ，值是刚刚触发可调用对象的梯度OP的 ``op_desc`` 。默认值为 ``None``。
+    - **loss** (Tensor) - 表示网络损失的 Tensor 。
+    - **parameter_list** （list [Tensor|str]，可选）- 指定优化器需要更新的参数或参数名称列表。如果为 ``None`` ，则将更新所有参数。默认值为 ``None``。
+    - **no_grad_set** （set [Tensor|str]，可选）-  在 `block0` ( :ref:`api_guide_Block` ) 中要忽略梯度的 Tensor 的名字的集合。所有的 :ref:`api_guide_Block` 中带有 ``stop_gradient = True`` 的所有 Tensor 的名字都会被自动添加到此集合中。如果该参数不为 ``None``，则会将该参数集合的内容添加到默认的集合中。默认值为 ``None``。
+    - **callbacks** （list [callable object]，可选）- 回调函数列表。用于在反向传播构建中执行一些自定义作业。每次将新的梯度 OP 添加到程序中时，将调用其中的所有可调用对象。可调用对象必须有两个输入参数： :ref:`api_guide_Block` 和 ``context`` 。 :ref:`api_guide_Block` 是将被添加到新梯度算子的块。 ``context`` 是一个映射，其键是梯度 Tensor 名，值是对应的原始 Tensor 。除此之外， ``context`` 还有另一个特殊的键值对：键是字符串 ``__ current_op_desc__`` ，值是刚刚触发可调用对象的梯度 OP 的 ``op_desc`` 。默认值为 ``None``。
 
-返回：   参数及其梯度 :ref:`api_guide_Variable` 的元组的列表。元组的第一个值为参数，第二个值为该参数的梯度 :ref:`api_guide_Variable` 。
+返回：   参数及其梯度 Tensor 的元组的列表。元组的第一个值为参数，第二个值为该参数的梯度 Tensor 。
 
-返回类型：       list[( :ref:`api_guide_Variable` , :ref:`api_guide_Variable` )]
+返回类型：       list[(Tensor , Tensor)]
 
 抛出：     
-    - ``AssertionError`` - 如果 loss 不是 :ref:`api_guide_Variable` 的实例。
+    - ``AssertionError`` - 如果 loss 不是 Tensor 的实例。
 
 **示例代码**
 
 .. code-block:: python
 
-        import paddle.fluid as fluid
+        import paddle
+        import paddle.nn.functional as F
 
-        x = fluid.data(name='x', shape=[None, 13], dtype='int64')
-        y = fluid.data(name='y', shape=[None, 1], dtype='float32')
-        x_emb = fluid.embedding(x, size=[100, 256])
-        y_predict = fluid.layers.fc(input=x_emb, size=1, act=None, name='my_fc')
-        loss = fluid.layers.square_error_cost(input=y_predict, label=y)
-        avg_loss = fluid.layers.mean(loss)
+        paddle.enable_static()
 
-        # 获取main_program中所有weight参数, 不包括bias.
-        all_weights = [param for param in fluid.default_main_program().block(0).all_parameters() if 'w_' in param.name]
+        x = paddle.static.data(name='x', shape=[None, 13], dtype='int64')
+        y = paddle.static.data(name='y', shape=[None, 1], dtype='float32')
+        x_emb = paddle.static.nn.embedding(x, size=[100, 256])
+        y_predict = paddle.static.nn.fc(input=x_emb, size=1, act=None, name='my_fc')
+        loss = F.square_error_cost(input=y_predict, label=y)
+        avg_loss = paddle.mean(loss)
+
+        # Get all weights in main_program, not include bias.
+        all_weights = [param for param in paddle.static.default_main_program().block(0).all_parameters() if 'w_' in param.name]
         all_weights_name = [w.name for w in all_weights]
 
-        # 若parameter_list为默认值(None), 则返回包含所有param_grad的list
-        p_g_list1 = fluid.backward.append_backward(loss=avg_loss)
+        # return all param_grads needed to be updated if parameter_list set default None.
+        p_g_list1 = paddle.static.append_backward(loss=avg_loss)
         # output: [(embedding_0.w_0, embedding_0.w_0@GRAD), (my_fc.w_0, my_fc.w_0@GRAD), (my_fc.b_0, my_fc.b_0@GRAD)]
 
-        # 返回与传入parameter_list对应的param_grad的list, 传入的parameter_list可以是 param(Variable类型)的list
-        p_g_list2 = fluid.backward.append_backward(loss=avg_loss, parameter_list=all_weights)
+        # return the param_grads corresponding to parameter_list that can be list of param (Tensor).
+        p_g_list2 = paddle.static.append_backward(loss=avg_loss, parameter_list=all_weights)
         # output: [(embedding_0.w_0, embedding_0.w_0@GRAD), (my_fc.w_0, my_fc.w_0@GRAD)]
 
-        # 传入的parameter_list也可以是值为param.name(str类型)的list
-        p_g_list3 = fluid.backward.append_backward(loss=avg_loss, parameter_list=all_weights_name)
+        # parameter_list can be list of param.name (str).
+        p_g_list3 = paddle.static.append_backward(loss=avg_loss, parameter_list=all_weights_name)
         # output: [(embedding_0.w_0, embedding_0.w_0@GRAD), (my_fc.w_0, my_fc.w_0@GRAD)]
 
-        # no_grad_set可以是set[Variables]类型，表示梯度将在这些Variables处截断
-        p_g_list4 = fluid.backward.append_backward(loss=avg_loss, no_grad_set=set([x_emb]))
+        # no_grad_set can be set of Tensors that means grad will be cut off from these Tensors.
+        p_g_list4 = paddle.static.append_backward(loss=avg_loss, no_grad_set=set([x_emb]))
         # output: [(my_fc.w_0, my_fc.w_0@GRAD), (my_fc.b_0, my_fc.b_0@GRAD)]
 
-        # no_grad_set也可以是set[Variable.names]类型。当参数Variable是在layers内部创建，且不方便显式地指定时，可以使用set[Variable.names]
-        p_g_list5 = fluid.backward.append_backward(loss=avg_loss, no_grad_set=set(['my_fc.b_0']))
+        # no_grad_set can be set of Tensor.name when the Tensors is created inside layers and can't be specified explicitly.
+        p_g_list5 = paddle.static.append_backward(loss=avg_loss, no_grad_set=set(['my_fc.b_0']))
         # output: [(embedding_0.w_0, embedding_0.w_0@GRAD), (my_fc.w_0, my_fc.w_0@GRAD)]
 
-        # 返回为[], 因为所有的param_grad均被传入的no_grad_set过滤掉了
-        p_g_list6 = fluid.backward.append_backward(loss=avg_loss, parameter_list=all_weights, no_grad_set=set(all_weights))
+        # return [] because all param_grads are filtered by no_grad_set.
+        p_g_list6 = paddle.static.append_backward(loss=avg_loss, parameter_list=all_weights, no_grad_set=set(all_weights))
 
 
 

doc/paddle/api/paddle/fluid/backward/gradients_cn.rst

@@ -4,35 +4,36 @@ gradients
 -------------------------------
 
 
-.. py:function:: paddle.fluid.backward.gradients(targets, inputs, target_gradients=None, no_grad_set=None)
+.. py:function:: paddle.static.gradients(targets, inputs, target_gradients=None, no_grad_set=None)
 
 
 
 
-将目标梯度反向传播到输入。
+将目标 Tensor 的梯度反向传播到输入 Tensor。
 
 参数：  
-  - **targets** (Variable|list[Variable]) – 目标变量
-  - **inputs** (Variable|list[Variable]) – 输入变量
-  - **target_gradients** (Variable|list[Variable]，可选) – 目标的梯度变量，应与目标变量形状相同；如果设置为None，则以1初始化所有梯度变量
-  - **no_grad_set** (set[Variable|str]，可选) – 在 `block0` ( :ref:`api_guide_Block` ) 中要忽略梯度的 :ref:`api_guide_Variable` 的名字的集合。所有的 :ref:`api_guide_Block` 中带有 ``stop_gradient = True`` 的所有 :ref:`api_guide_Variable` 的名字都会被自动添加到此集合中。如果该参数不为 ``None``，则会将该参数集合的内容添加到默认的集合中。默认值为 ``None``。
+  - **targets** (Tensor|list[Tensor]) – 目标 Tensor 或包含 Tensor 的列表
+  - **inputs** (Tensor|list[Tensor]) – 输入 Tensor 或包含 Tensor 的列表
+  - **target_gradients** (Tensor|list[Tensor]，可选) – 目标的梯度 Tensor，应与目标 Tensor 的形状相同；如果设置为None，则以 1 初始化所有梯度 Tensor
+  - **no_grad_set** (set[Tensor|str]，可选) – 在 `block0` ( :ref:`api_guide_Block` ) 中要忽略梯度的 Tensor 的名字的集合。所有的 :ref:`api_guide_Block` 中带有 ``stop_gradient = True`` 的所有 Tensor 的名字都会被自动添加到此集合中。如果该参数不为 ``None`` ，则会将该参数集合的内容添加到默认的集合中。默认值为 ``None`` 。
 
 
-返回：数组，包含与输入对应的梯度。如果一个输入不影响目标函数，则对应的梯度变量为None
+返回：数组，包含与输入对应的梯度。如果一个输入不影响目标函数，则对应的梯度 Tensor 为 None 。
 
-返回类型：(list[Variable])
+返回类型：(list[Tensor])
 
 **示例代码**
 
 .. code-block:: python
 
-            import paddle.fluid as fluid
+            import paddle
+            import paddle.nn.functional as F
 
-            x = fluid.data(name='x', shape=[None,2,8,8], dtype='float32')
+            paddle.enable_static()
+
+            x = paddle.static.data(name='x', shape=[None, 2, 8, 8], dtype='float32')
             x.stop_gradient=False
-            y = fluid.layers.conv2d(x, 4, 1, bias_attr=False)
-            y = fluid.layers.relu(y)
-            y = fluid.layers.conv2d(y, 4, 1, bias_attr=False)
-            y = fluid.layers.relu(y)
-            z = fluid.gradients([y], x)
+            y = paddle.static.nn.conv2d(x, 4, 1, bias_attr=False)
+            y = F.relu(y)
+            z = paddle.static.gradients([y], x)
+            print(z) # [var x@GRAD : fluid.VarType.LOD_TENSOR.shape(-1L, 2L, 8L, 8L).astype(VarType.FP32)]
\ No newline at end of file
-            print(z)
\ No newline at end of file

doc/paddle/api/paddle/fluid/framework/program_guard_cn.rst

@@ -4,39 +4,43 @@ program_guard
 -------------------------------
 
 
-.. py:function:: paddle.fluid.program_guard(main_program, startup_program=None)
+.. py:function:: paddle.static.program_guard(main_program, startup_program=None)
 
 
 
 
 该接口应配合使用python的 ``with`` 语句来将 ``with`` block 里的算子和变量添加进指定的全局主程序（main program）和启动程序（startup program）。
 
-``with`` 语句块中的fluid.layers下各接口将在新的main program（主程序）中添加operators（算子）和variables（变量）。
+``with`` 语句块下的各接口将在新的main program（主程序）中添加 operators（算子）和 Tensors（张量）。
 
 参数：
-    - **main_program** (Program) – “with”语句中将使用的新的main program。
-    - **startup_program** (Program，可选) – “with”语句中将使用的新的startup program。若传入 ``None`` 则不改变当前的启动程序，即仍使用default_startup_program。默认值为None。
+    - **main_program** (Program) – ``with`` 语句中将使用的新的 main program。
+    - **startup_program** (Program，可选) – ``with`` 语句中将使用的新的 startup program。若传入 ``None`` 则不改变当前的启动程序，即仍使用 default_startup_program。默认值为 None。
 
 **代码示例**
 
 .. code-block:: python
 
-    import paddle.fluid as fluid
-    main_program = fluid.Program()
-    startup_program = fluid.Program()
-    with fluid.program_guard(main_program, startup_program):
-        data = fluid.data(name='image', shape=[None, 784, 784], dtype='float32')
-        hidden = fluid.layers.fc(input=data, size=10, act='relu')
+    import paddle
     
-例如，当组的网不需要startup_program初始化各变量时，可以传入一个临时的program。
+    paddle.enable_static()
+    main_program = paddle.static.Program()
+    startup_program = paddle.static.Program()
+    with paddle.static.program_guard(main_program, startup_program):
+        data = paddle.static.data(name='image', shape=[None, 784, 784], dtype='float32')
+        hidden = paddle.static.nn.fc(input=data, size=10, act='relu')
+
+例如，当组的网不需要 startup_program 初始化各变量时，可以传入一个临时的 program。
 
 **代码示例**
 
 .. code-block:: python
 
-    import paddle.fluid as fluid
-    main_program = fluid.Program()
-    # 如果您不需要关心startup program,传入一个临时值即可
-    with fluid.program_guard(main_program, fluid.Program()):
-        data = fluid.data(name='image', shape=[None, 784, 784], dtype='float32')
+    import paddle
+
+    paddle.enable_static()
+    main_program = paddle.static.Program()
+    # does not care about startup program. Just pass a temporary value.
+    with paddle.static.program_guard(main_program, paddle.static.Program()):
+        data = paddle.static.data(name='image', shape=[None, 784, 784], dtype='float32')