Fix ErrorClipByValue, GradientClipByGlobalNorm, GradientClipByValue (#1392)

* Fix ErrorClipByValue, GradientClipByGlobalNorm, GradientClipByValue

doc/fluid/api_cn/clip_cn/ErrorClipByValue_cn.rst

@@ -5,42 +5,41 @@ ErrorClipByValue
 
 .. py:class:: paddle.fluid.clip.ErrorClipByValue(max, min=None)
 
-将张量值的范围压缩到 [min, max]。
+给定一个 Tensor  ``t`` （该 Tensor 传入方式见代码示例），对 Tensor 中的元素超出给定最大 ``max`` 和最小界 ``min`` 内区间范围 [min, max] 的元素，重设为所超出界的界值。
 
 
-给定一个张量 ``t`` ，该操作将它的值压缩到 ``min`` 和 ``max``  之间
+- 任何小于min（最小值）的值都被设置为 ``min``
 
-- 任何小于min（最小值）的值都被设置为min
+- 任何大于max（最大值）的值都被设置为 ``max``
 
-- 任何大于max（最大值）的值都被设置为max
 
 参数:
  - **max** (foat) - 要修剪的最大值。
- - **min** (float) - 要修剪的最小值。如果用户没有设置，将被框架默认设置为 ``-max`` 
+ - **min** (float) - 要修剪的最小值。如果用户没有设置，将被框架默认设置为 ``-max`` 。
+
   
 **代码示例**
  
 .. code-block:: python
         
      import paddle.fluid as fluid
+
      BATCH_SIZE = 128
      CLIP_MAX = 2e-6
      CLIP_MIN = -1e-6
      prog = fluid.framework.Program()
+
      with fluid.program_guard(main_program=prog):
-        image = fluid.layers.data(name='x', shape=[784], dtype='float32')
-        hidden1 = fluid.layers.fc(input=image, size=128, act='relu')
-        hidden2 = fluid.layers.fc(input=hidden1, size=64, act='relu')
-        predict = fluid.layers.fc(input=hidden2, size=10, act='softmax')
-        label = fluid.layers.data(name='y', shape=[1], dtype='int64')
-        cost = fluid.layers.cross_entropy(input=predict, label=label)
-        avg_cost = fluid.layers.mean(cost)
+         image = fluid.layers.data(name='x', shape=[784], dtype='float32')
+         hidden1 = fluid.layers.fc(input=image, size=128, act='relu')
+         hidden2 = fluid.layers.fc(input=hidden1, size=64, act='relu')
+         predict = fluid.layers.fc(input=hidden2, size=10, act='softmax')
+         label = fluid.layers.data(name='y', shape=[1], dtype='int64')
+         cost = fluid.layers.cross_entropy(input=predict, label=label)
+         avg_cost = fluid.layers.mean(cost)
      prog_clip = prog.clone()
      prog_clip.block(0).var(hidden1.name)._set_error_clip(
-        fluid.clip.ErrorClipByValue(
-            max=CLIP_MAX, min=CLIP_MIN)）
-
-
+         fluid.clip.ErrorClipByValue(max=CLIP_MAX, min=CLIP_MIN))
 
 
 

doc/fluid/api_cn/clip_cn/GradientClipByGlobalNorm_cn.rst

@@ -5,9 +5,9 @@ GradientClipByGlobalNorm
 
 .. py:class:: paddle.fluid.clip.GradientClipByGlobalNorm(clip_norm, group_name='default_group')
  
-通过多个张量的范数之和的比率来剪切（clip）多个张量。
+通过多个 Tensor 的范数之和的比率，来剪切（clip）多个 Tensor （ Tensor 不是从该类传入， 通过 ``fluid.program_guard`` 的 ``main_program`` 参数传入，即公式中的 :math:`t\_list` 见代码实例）。
 
-给定一个张量列表 :math:`t\_list` 和一个剪切比率 ``clip_norm`` ，返回一个被剪切的张量列表list_clipped和 :math:`t\_list` 中所有张量的全局范数(global_norm)。
+给定一个 Tensor 列表 :math:`t\_list` 和一个剪切比率 ``clip_norm`` ，返回该类的实例作为 ``set_gradient_clip`` 方法的第一个参数， ``set_gradient_clip`` 第二个参数是用来计算被剪切的 Tensor 列表（该值默认为 ``None`` 会基于所有 Tensor 列表来计算全局范数 ``global_norm`` 。
 
 剪切过程如下：
 
@@ -20,9 +20,6 @@ GradientClipByGlobalNorm
             \\global\_norm=\sqrt{\sum_{i=0}^{n-1}(l2norm(t\_list[i]))^2}\\
 
 
-如果 :math:`clip\_norm>global\_norm` ， :math:`t\_list` 中的张量保持不变，否则它们都会按照全局比率缩减。
-
-
 参数:
  - **clip_norm** (float) - 范数最大值
  - **group_name** (str, optional) - 剪切的组名
@@ -32,6 +29,10 @@ GradientClipByGlobalNorm
 .. code-block:: python
         
     import paddle.fluid as fluid
+    import paddle.fluid.core as core
+    import paddle
+
+    place = core.CPUPlace()
     prog = fluid.framework.Program()
     startup_program = fluid.framework.Program()
     with fluid.program_guard(
@@ -43,15 +44,40 @@ GradientClipByGlobalNorm
         predict = fluid.layers.fc(input=hidden2, size=10, act='softmax')
         cost = fluid.layers.cross_entropy(input=predict, label=label)
         avg_cost = fluid.layers.mean(cost)
+
     prog_clip = prog.clone()
     avg_cost_clip = prog_clip.block(0).var(avg_cost.name)
+
+    p_g = fluid.backward.append_backward(loss=avg_cost)
     p_g_clip = fluid.backward.append_backward(loss=avg_cost_clip)
 
-    with fluid.program_guard(main_program=prog_clip):
+    with fluid.program_guard(main_program=prog_clip, startup_program=startup_program):
         fluid.clip.set_gradient_clip(
             fluid.clip.GradientClipByGlobalNorm(clip_norm=2.0))
         p_g_clip = fluid.clip.append_gradient_clip_ops(p_g_clip)
 
+    grad_list = [elem[1] for elem in p_g]
+    grad_clip_list = [elem[1] for elem in p_g_clip]
+
+    train_reader = paddle.batch(
+        paddle.reader.shuffle(
+            paddle.dataset.mnist.train(), buf_size=8192),
+        batch_size=128)
+
+    exe = fluid.Executor(place)
+    feeder = fluid.DataFeeder(feed_list=[image, label], place=place)
+    exe.run(startup_program)
+
+    count = 0
+    for data in train_reader():
+        count += 1
+        print("count:%s" % count)
+        if count > 5:
+            break
+        out = exe.run(prog, feed=feeder.feed(data), fetch_list=grad_list)
+        out_clip = exe.run(prog_clip,
+                           feed=feeder.feed(data),
+                           fetch_list=grad_clip_list)
 
 
 

doc/fluid/api_cn/clip_cn/GradientClipByValue_cn.rst

@@ -8,11 +8,11 @@ GradientClipByValue
 将梯度值(gradient values)的范围压缩到 [min, max]。
 
 
-给定一个张量 ``t`` ，该操作将它的值压缩到 ``min`` 和 ``max`` 之间
+给定一个 Tensor  ``t`` ，该操作将它的值压缩到 ``min`` 和 ``max`` 之间
 
-- 任何小于最小值的值都被设置为最小值
+- 任何小于 ``min`` 的值都被设置为 ``min``
 
-- 任何大于max的值都被设置为max
+- 任何大于 ``max`` 的值都被设置为 ``max``
 
 参数:
  - **max** (foat) - 要修剪的最大值。