add Dropout no_grad_guard train/eval apis (#1936)

* add new apis
quote> test=develop

* refine doc
test=develop

* use p
test=develop

* rm no_grad_guard
test=develop

doc/fluid/api/dygraph.rst

@@ -15,6 +15,7 @@ fluid.dygraph
     dygraph/CosineDecay.rst
     dygraph/DataParallel.rst
     dygraph/disable_dygraph.rst
+    dygraph/Dropout.rst
     dygraph/dygraph_to_static_code.rst
     dygraph/dygraph_to_static_func.rst
     dygraph/dygraph_to_static_output.rst

doc/fluid/api/dygraph/Dropout.rst

+..  THIS FILE IS GENERATED BY `gen_doc.{py|sh}`
+    !DO NOT EDIT THIS FILE MANUALLY!
+
+.. _api_fluid_dygraph_Dropout:
+
+Dropout
+-------
+
+..  autoclass:: paddle.fluid.dygraph.Dropout
+    :members:
+    :noindex:
+

doc/fluid/api_cn/dygraph_cn.rst

@@ -16,6 +16,7 @@ fluid.dygraph
     dygraph_cn/Conv3D_cn.rst
     dygraph_cn/Conv3DTranspose_cn.rst
     dygraph_cn/CosineDecay_cn.rst
+    dygraph_cn/Dropout_cn.rst
     dygraph_cn/Embedding_cn.rst
     dygraph_cn/ExponentialDecay_cn.rst
     dygraph_cn/FC_cn.rst
@@ -34,7 +35,7 @@ fluid.dygraph
     dygraph_cn/NoamDecay_cn.rst
     dygraph_cn/ParallelEnv_cn.rst
     dygraph_cn/ParameterList_cn.rst
-    dygraph_cn/no_grad_cn.rst    
+    dygraph_cn/no_grad_cn.rst
     dygraph_cn/PiecewiseDecay_cn.rst
     dygraph_cn/PolynomialDecay_cn.rst
     dygraph_cn/Pool2D_cn.rst

doc/fluid/api_cn/dygraph_cn/Dropout_cn.rst

+.. _cn_api_fluid_dygraph_Dropout:
+
+Dropout
+-------------------------------
+
+.. py:class:: paddle.fluid.dygraph.Dropout(p=0.5, seed=None, dropout_implementation='downgrade_in_infer', is_test=False)
+
+丢弃或者保持输入的每个元素独立。Dropout是一种正则化手段，通过在训练过程中阻止神经元节点间的相关性来减少过拟合。根据给定的丢弃概率，dropout操作符按丢弃概率随机将一些神经元输出设置为0，其他的仍保持不变。
+
+Dropout层可以删除，提高执行效率。
+
+参数：
+    - **p** (float32，可选) - 输入单元的丢弃概率，即输入单元设置为0的概率。默认值：0.5
+    - **seed** (int，可选) - 整型数据，用于创建随机种子。如果该参数设为None，则使用随机种子。注：如果给定一个整型种子，始终丢弃相同的输出单元。训练过程中勿用固定不变的种子。默认值：None。
+    - **dropout_implementation** (str，可选) - 丢弃单元的方式，有两种'downgrade_in_infer'和'upscale_in_train'两种选择，默认：'downgrade_in_infer'。具体作用可以参考一下描述。
+
+      1. downgrade_in_infer(default), 在预测时减小输出结果
+
+         - train: out = input * mask
+
+         - inference: out = input * (1.0 - p)
+
+         (mask是一个张量，维度和输入维度相同，值为0或1，值为0的比例即为 ``p`` )
+
+      2. upscale_in_train, 增加训练时的结果
+
+         - train: out = input * mask / ( 1.0 - p )
+
+         - inference: out = input
+
+         (mask是一个张量，维度和输入维度相同，值为0或1，值为0的比例即为 ``p`` ）
+
+    - **is_test** (bool，可选) - 标记是否是测试阶段。此标志仅对静态图模式有效。对于动态图模式，请使用 ``eval()`` 接口。默认：False。
+
+返回：无
+
+**代码示例**：
+
+.. code-block:: python
+
+    import paddle.fluid as fluid
+    from paddle.fluid.dygraph.base import to_variable
+    import numpy as np
+
+    x = np.random.random(size=(3, 10, 3, 7)).astype('float32')
+    with fluid.dygraph.guard():
+        x = to_variable(x)
+        m = fluid.dygraph.Dropout(p=0.5)
+        droped_train = m(x)
+        # 切换到 eval 模式
+        m.eval()
+        droped_eval = m(x)
+

doc/fluid/api_cn/dygraph_cn/Layer_cn.rst

@@ -13,6 +13,18 @@ Layer
 
 返回：无
 
+.. py:method:: train()
+
+将此层及其所有子层设置为训练模式。这只会影响某些模块，如Dropout和BatchNorm。
+
+返回：无
+
+.. py:method:: eval()
+
+将此层及其所有子层设置为预测模式。这只会影响某些模块，如Dropout和BatchNorm。
+
+返回：无
+
 .. py:method:: full_name()
 
 Layer的全名。组成方式为： ``name_scope`` + “/” + MyLayer.__class__.__name__ 。

doc/fluid/api_cn/dygraph_cn/no_grad_cn.rst

@@ -5,12 +5,11 @@ no_grad
 
 **注意：该API仅支持【动态图】模式**
 
-.. py:method:: paddle.fluid.dygraph.no_grad(func)
+.. py:method:: paddle.fluid.dygraph.no_grad(func=None)
 
-在动态图模式中，此装饰器将会避免 ``func`` 被装饰时创建反向传播网络。
+创建一个上下文来禁用动态图梯度计算。在此模式下，每次计算的结果都将具有stop_gradient=True。
 
-参数:
-    - **func** (str) – 不需要梯度的函数。
+也可以用作一个装饰器（确保不要用括号来初始化）。
 
 **代码示例**
 
@@ -20,6 +19,22 @@ no_grad
     import numpy as np
     import paddle.fluid as fluid
 
+    # 用作生成器
+    data = np.array([[2, 3], [4, 5]]).astype('float32')
+    with fluid.dygraph.guard():
+        l0 = fluid.Linear(2, 2)  # l0.weight.gradient() is None
+        l1 = fluid.Linear(2, 2)
+        with fluid.dygraph.no_grad():
+            # l1.weight.stop_gradient is False
+            tmp = l1.weight * 2  # tmp.stop_gradient is True
+        x = fluid.dygraph.to_variable(data)
+        y = l0(x) + tmp
+        o = l1(y)
+        o.backward()
+        print(tmp.gradient() is None)  # True
+        print(l0.weight.gradient() is None)  # False
+    
+    # 用作装饰器
     @fluid.dygraph.no_grad
     def test_layer():
         with fluid.dygraph.guard():