update api_cn (#954)

* update api_cn; fix the error of reverting layers_cn to 1.4; include previous changes

* update layers_cn; add code example to elementwise_mod

* delete recordio_writer_cn; revert index_cn

* update api_cn after review

* fix io_cn.rst

* update layers_cn

* update io_cn

doc/fluid/api_cn/backward_cn.rst

@@ -25,67 +25,59 @@ append_backward
 
 返回：   成对参数及其相应的梯度。键是参数，值是梯度变量。
 
-返回类型：   	list[(Variable,Variable)]
+返回类型：       list[(Variable,Variable)]
 
 抛出：     
     - ``AssertionError`` - 如果loss不是Variable的实例。
 
 **示例代码**
 
-..  code-block:: python
+.. code-block:: python
 
         # 网络配置
-        # ...
+        # 损失计算
+        x = fluid.layers.data(name='x', shape=[13], dtype='float32')
+        y = fluid.layers.data(name='y', shape=[1], dtype='float32') 
+              
+        y_predict = fluid.layers.fc(input=x, size=1, act=None)
+        loss = fluid.layers.square_error_cost(input=y_predict, label=y)
+        
         avg_loss = fluid.layers.mean(loss)
         param_grad_list = fluid.backward.append_backward(loss=avg_loss)
 
 
 
+.. _cn_api_fluid_backward_gradients:
 
+gradients
+-------------------------------
 
+.. py:function:: paddle.fluid.backward.gradients(targets, inputs, target_gradients=None, no_grad_set=None)
 
+将目标梯度反向传播到输入。
 
+参数：  
+  - **targets** (Variable|list[Variable]) – 目标变量
+  - **inputs** (Variable|list[Variable]) – 输入变量
+  - **target_gradients** (Variable|list[Variable]|None) – 目标的梯度变量，应与目标变量形状相同；如果设置为None，则以1初始化所有梯度变量
+  - **no_grad_sethread** (set[string]) – 在Block 0中不具有梯度的变量，所有block中被设置 ``stop_gradient=True`` 的变量将被自动加入该set
 
 
+返回：数组，包含与输入对应的梯度。如果一个输入不影响目标函数，则对应的梯度变量为None
 
+返回类型：(list[Variable])
 
+**示例代码**
 
+.. code-block:: python
 
+            import paddle.fluid as fluid
 
-
-
-
-
-
-
-
-
-
+            x = fluid.layers.data(name='x', shape=[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)
+            print(z)
\ No newline at end of file
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

doc/fluid/api_cn/clip_cn.rst

@@ -28,8 +28,23 @@ ErrorClipByValue
  
 .. code-block:: python
         
-     var = fluid.framework.Variable(..., error_clip=ErrorClipByValue(max=5.0), ...)
-
+     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)
+     prog_clip = prog.clone()
+     prog_clip.block(0).var(hidden1.name)._set_error_clip(
+        fluid.clip.ErrorClipByValue(
+            max=CLIP_MAX, min=CLIP_MIN)
 
 
 
@@ -70,12 +85,27 @@ GradientClipByGlobalNorm
  
 .. code-block:: python
         
+    import paddle.fluid as fluid
+    prog = fluid.framework.Program()
+    startup_program = fluid.framework.Program()
+    with fluid.program_guard(
+            main_program=prog, startup_program=startup_program):
+        image = fluid.layers.data(name='x', shape=[784], dtype='float32')
+        label = fluid.layers.data(name='y', shape=[1], dtype='int64')
+        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')
+        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_clip = fluid.backward.append_backward(loss=avg_cost_clip)
 
     with fluid.program_guard(main_program=prog_clip):
-         fluid.clip.set_gradient_clip(
-                               fluid.clip.GradientClipByGlobalNorm(clip_norm=2.0))
-         p_g_clip = fluid.clip.append_gradient_clip_ops(p_g_clip)
+        fluid.clip.set_gradient_clip(
+            fluid.clip.GradientClipByGlobalNorm(clip_norm=2.0))
+        p_g_clip = fluid.clip.append_gradient_clip_ops(p_g_clip)
+
 
 
 
@@ -108,12 +138,14 @@ GradientClipByNorm
  
 .. code-block:: python
         
+    import paddle.fluid as fluid
     w_param_attrs = fluid.ParamAttr(name=None,
-                              initializer=fluid.initializer.UniformInitializer(low=-1.0, high=1.0, seed=0),
-                              learning_rate=1.0,
-                              regularizer=fluid.regularizer.L1Decay(1.0),
-                              trainable=True,
-                              clip=fluid.clip.GradientClipByNorm(clip_norm=2.0))
+                                    initializer=fluid.initializer.UniformInitializer(low=-1.0, high=1.0, seed=0),
+                                    learning_rate=1.0,
+                                    regularizer=fluid.regularizer.L1Decay(1.0),
+                                    trainable=True,
+                                    gradient_clip=fluid.clip.GradientClipByNorm(clip_norm=2.0))
+    x = fluid.layers.data(name='x', shape=[10], dtype='float32')
     y_predict = fluid.layers.fc(input=x, size=1, param_attr=w_param_attrs)
 
 
@@ -147,12 +179,14 @@ GradientClipByValue
  
 .. code-block:: python
         
+     import paddle.fluid as fluid
      w_param_attrs = fluid.ParamAttr(name=None,
-                               initializer=fluid.initializer.UniformInitializer(low=-1.0, high=1.0, seed=0),
-                               learning_rate=1.0,
-                               regularizer=fluid.regualrizer.L1Decay(1.0),
-                               trainable=True,
-                               clip=fluid.clip.GradientClipByValue(-1.0, 1.0))
+                                     initializer=fluid.initializer.UniformInitializer(low=-1.0, high=1.0, seed=0),
+                                     learning_rate=1.0,
+                                     regularizer=fluid.regualrizer.L1Decay(1.0),
+                                     trainable=True,
+                                     gradient_clip=fluid.clip.GradientClipByValue(-1.0, 1.0))
+     x = fluid.layers.data(name='x', shape=[10], dtype='float32')
      y_predict = fluid.layers.fc(input=x, size=1, param_attr=w_param_attrs)
      
 

doc/fluid/api_cn/data/data_reader_cn.rst

@@ -19,11 +19,12 @@ DataFeeder将reader返回的数据转换为可以输入Executor和ParallelExecut
 
 ..  code-block:: python
 
-	place = fluid.CPUPlace()
-	img = fluid.layers.data(name='image', shape=[1, 28, 28])
-	label = fluid.layers.data(name='label', shape=[1], dtype='int64')
-	feeder = fluid.DataFeeder([img, label], fluid.CPUPlace())
-	result = feeder.feed([([0] * 784, [9]), ([1] * 784, [1])])
+    import paddle.fluid as fluid
+    place = fluid.CPUPlace()
+    img = fluid.layers.data(name='image', shape=[1, 28, 28])
+    label = fluid.layers.data(name='label', shape=[1], dtype='int64')
+    feeder = fluid.DataFeeder([img, label], fluid.CPUPlace())
+    result = feeder.feed([([0] * 784, [9]), ([1] * 784, [1])])
 
 
 如果您想在使用多个GPU训练模型时预先将数据单独输入GPU端，可以使用decorate_reader函数。
@@ -33,10 +34,16 @@ DataFeeder将reader返回的数据转换为可以输入Executor和ParallelExecut
 
 ..  code-block:: python
 
-	place=fluid.CUDAPlace(0)
-	feeder = fluid.DataFeeder(place=place, feed_list=[data, label])
-	reader = feeder.decorate_reader(
-	    paddle.batch(flowers.train(), batch_size=16))
+    import paddle
+    import paddle.fluid as fluid
+    
+    place=fluid.CUDAPlace(0)
+    data = fluid.layers.data(name='data', shape=[3, 224, 224], dtype='float32')
+    label = fluid.layers.data(name='label', shape=[1], dtype='int64')
+    
+    feeder = fluid.DataFeeder(place=place, feed_list=[data, label])
+    reader = feeder.decorate_reader(
+        paddle.batch(paddle.dataset.flowers.train(), batch_size=16), multi_devices=False)
 
 
 参数：
@@ -44,23 +51,39 @@ DataFeeder将reader返回的数据转换为可以输入Executor和ParallelExecut
     - **place**  (Place) – place表示将数据输入CPU或GPU，如果要将数据输入GPU，请使用fluid.CUDAPlace(i)（i表示GPU的ID），如果要将数据输入CPU，请使用fluid.CPUPlace()。
     - **program**  (Program) –将数据输入的Program，如果Program为None，它将使用default_main_program() 。默认值None。
 
-抛出异常： 	``ValueError`` – 如果某些变量未在Program中出现
+抛出异常：     ``ValueError`` – 如果某些变量未在Program中出现
 
 
 **代码示例**
 
 ..  code-block:: python
 
-	# ...
-	place = fluid.CPUPlace()
-	feed_list = [
-	    main_program.global_block().var(var_name) for var_name in feed_vars_name
-	] # feed_vars_name is a list of variables' name.
-	feeder = fluid.DataFeeder(feed_list, place)
-	for data in reader():
-	    outs = exe.run(program=main_program,
-	                   feed=feeder.feed(data))
+    import numpy as np
+    import paddle
+    import paddle.fluid as fluid
 
+    place = fluid.CPUPlace()
+
+    def reader():
+        yield [np.random.random([4]).astype('float32'), np.random.random([3]).astype('float32')],
+
+    main_program = fluid.Program()
+    startup_program = fluid.Program()
+
+    with fluid.program_guard(main_program, startup_program):
+        data_1 = fluid.layers.data(name='data_1', shape=[1, 2, 2])
+        data_2 = fluid.layers.data(name='data_2', shape=[1, 1, 3])
+        out = fluid.layers.fc(input=[data_1, data_2], size=2)
+        # ...
+
+    feeder = fluid.DataFeeder([data_1, data_2], place)
+
+    exe = fluid.Executor(place)
+    exe.run(startup_program)
+    for data in reader():
+        outs = exe.run(program=main_program,
+                       feed=feeder.feed(data),
+                       fetch_list=[out])
 
 
 .. py:method::  feed(iterable)
@@ -74,6 +97,24 @@ DataFeeder将reader返回的数据转换为可以输入Executor和ParallelExecut
 
 返回类型： dict
 
+**代码示例**
+
+..  code-block:: python
+
+        import numpy.random as random
+        import paddle.fluid as fluid
+        
+        def reader(limit=5):
+            for i in range(limit):
+                    yield random.random([784]).astype('float32'), random.random([1]).astype('int64'), random.random([256]).astype('float32')
+        
+        data_1 = fluid.layers.data(name='data_1', shape=[1, 28, 28])
+        data_2 = fluid.layers.data(name='data_2', shape=[1], dtype='int64')
+        data_3 = fluid.layers.data(name='data_3', shape=[16, 16], dtype='float32')
+        feeder = fluid.DataFeeder(['data_1','data_2', 'data_3'], fluid.CPUPlace())
+        
+        result = feeder.feed(reader())
+
 
 
 .. py:method::  feed_parallel(iterable, num_places=None)
@@ -92,7 +133,35 @@ DataFeeder将reader返回的数据转换为可以输入Executor和ParallelExecut
 
 .. note::
 
-	设备数量和mini-batches数量必须一致。
+    设备数量和mini-batches数量必须一致。
+
+**代码示例**
+
+..  code-block:: python
+
+        import numpy.random as random
+        import paddle.fluid as fluid
+        
+        def reader(limit=10):
+            for i in range(limit):
+                yield [random.random([784]).astype('float32'), random.randint(10)],
+        
+        x = fluid.layers.data(name='x', shape=[1, 28, 28])
+        y = fluid.layers.data(name='y', shape=[1], dtype='int64')
+        
+        feeder = fluid.DataFeeder(['x','y'], fluid.CPUPlace())
+        place_num = 2
+        places = [fluid.CPUPlace() for x in range(place_num)]
+        data = []
+        exe = fluid.Executor(fluid.CPUPlace())
+        exe.run(fluid.default_startup_program())
+        program = fluid.CompiledProgram(fluid.default_main_program()).with_data_parallel(places=places)
+        for item in reader():
+            data.append(item)
+            if place_num == len(data):
+                exe.run(program=program, feed=list(feeder.feed_parallel(data, place_num)), fetch_list=[])
+                data = []
+
 
 .. py:method::  decorate_reader(reader, multi_devices, num_places=None, drop_last=True)
 
@@ -108,7 +177,32 @@ DataFeeder将reader返回的数据转换为可以输入Executor和ParallelExecut
 
 返回类型： dict
 
-抛出异常： 	``ValueError`` – 如果drop_last为False并且数据batch和设备数目不匹配。
+抛出异常：     ``ValueError`` – 如果drop_last为False并且数据batch和设备数目不匹配。
+
+**代码示例**
+
+..  code-block:: python
+
+        import numpy.random as random
+        import paddle
+        import paddle.fluid as fluid
+        
+        def reader(limit=5):
+            for i in range(limit):
+                yield (random.random([784]).astype('float32'), random.random([1]).astype('int64')),
+        
+        place=fluid.CUDAPlace(0)
+        data = fluid.layers.data(name='data', shape=[1, 28, 28], dtype='float32')
+        label = fluid.layers.data(name='label', shape=[1], dtype='int64')
+        
+        feeder = fluid.DataFeeder(place=place, feed_list=[data, label])
+        reader = feeder.decorate_reader(reader, multi_devices=False)
+        
+        exe = fluid.Executor(place)
+        exe.run(fluid.default_startup_program())
+        for data in reader():
+            exe.run(feed=data)
+
 
 
 .. _cn_api_paddle_data_reader_reader:
@@ -118,10 +212,10 @@ Reader
 
 在训练和测试时，PaddlePaddle需要读取数据。为了简化用户编写数据读取代码的工作，我们定义了
 
-	- reader是一个读取数据（从文件、网络、随机数生成器等）并生成数据项的函数。
-	- reader creator是返回reader函数的函数。
-	- reader decorator是一个函数，它接受一个或多个reader，并返回一个reader。
-	- batch reader是一个函数，它读取数据（从reader、文件、网络、随机数生成器等）并生成一批数据项。
+    - reader是一个读取数据（从文件、网络、随机数生成器等）并生成数据项的函数。
+    - reader creator是返回reader函数的函数。
+    - reader decorator是一个函数，它接受一个或多个reader，并返回一个reader。
+    - batch reader是一个函数，它读取数据（从reader、文件、网络、随机数生成器等）并生成一批数据项。
 
 
 Data Reader Interface
@@ -131,7 +225,7 @@ Data Reader Interface
 
 ..  code-block:: python
 
-	iterable = data_reader()
+    iterable = data_reader()
 
 从iterable生成的元素应该是单个数据条目，而不是mini batch。数据输入可以是单个项目，也可以是项目的元组，但应为 :ref:`user_guide_paddle_support_data_types` （如, numpy 1d array of float32, int, list of int）
 
@@ -140,22 +234,22 @@ Data Reader Interface
 
 ..  code-block:: python
 
-	def reader_creator_random_image(width, height):
-	    def reader():
-	        while True:
-	            yield numpy.random.uniform(-1, 1, size=width*height)
-	return reader
+    def reader_creator_random_image(width, height):
+        def reader():
+            while True:
+                yield numpy.random.uniform(-1, 1, size=width*height)
+    return reader
 
 
 多项目数据读取器创建者的示例实现：
 
 ..  code-block:: python
 
-	def reader_creator_random_image_and_label(width, height, label):
-	    def reader():
-	        while True:
-	            yield numpy.random.uniform(-1, 1, size=width*height), label
-	return reader
+    def reader_creator_random_image_and_label(width, height, label):
+        def reader():
+            while True:
+                yield numpy.random.uniform(-1, 1, size=width*height), label
+    return reader
 
 .. py:function::   paddle.reader.map_readers(func, *readers)
 
@@ -198,7 +292,7 @@ Data Reader Interface
 
 返回：新的数据读取器
 
-抛出异常： 	``ComposeNotAligned`` – reader的输出不一致。 当check_alignment设置为False，不会升高。
+抛出异常：     ``ComposeNotAligned`` – reader的输出不一致。 当check_alignment设置为False，不会升高。
 
 
 
@@ -274,32 +368,32 @@ PipeReader通过流从一个命令中读取数据，将它的stdout放到管道
 
 ..  code-block:: python
 
-	def example_reader():
-	    for f in myfiles:
-	        pr = PipeReader("cat %s"%f)
-	        for l in pr.get_line():
-	            sample = l.split(" ")
-	            yield sample
+    def example_reader():
+        for f in myfiles:
+            pr = PipeReader("cat %s"%f)
+            for l in pr.get_line():
+                sample = l.split(" ")
+                yield sample
 
 
 .. py:method:: get_line(cut_lines=True, line_break='\n')
 
 param cut_lines:
- 	cut buffer to lines
+     cut buffer to lines
 
-type cut_lines:	bool
+type cut_lines:    bool
 
 param line_break:
- 	line break of the file, like
+     line break of the file, like
 
 or
 
 type line_break:
- 	string
+     string
 
-return:	one line or a buffer of bytes
+return:    one line or a buffer of bytes
 
-rtype:	string
+rtype:    string
 
 
 
@@ -315,11 +409,11 @@ multiprocess.queue需要/dev/shm的rw访问权限，某些平台不支持。
 
 ..  code-block:: python
 
-	reader0 = reader(["file01", "file02"])
-	reader1 = reader(["file11", "file12"])
-	reader1 = reader(["file21", "file22"])
-	reader = multiprocess_reader([reader0, reader1, reader2],
-	    queue_size=100, use_pipe=False)
+    reader0 = reader(["file01", "file02"])
+    reader1 = reader(["file11", "file12"])
+    reader1 = reader(["file21", "file22"])
+    reader = multiprocess_reader([reader0, reader1, reader2],
+        queue_size=100, use_pipe=False)
 
 
 
@@ -338,11 +432,11 @@ Fakereader将缓存它读取的第一个数据，并将其输出data_num次。
 
 ..  code-block:: python
 
-	def reader():
-	    for i in range(10):
-	        yield i
+    def reader():
+        for i in range(10):
+            yield i
 
-	fake_reader = Fake()(reader, 100)
+    fake_reader = Fake()(reader, 100)
 
 
 Creator包包含一些简单的reader creator，可以在用户Program中使用。
@@ -374,4 +468,4 @@ Creator包包含一些简单的reader creator，可以在用户Program中使用
 
 路径：recordio文件的路径，可以是字符串或字符串列表。
 
-返回： recordio文件的数据读取器
+返回：recordio文件的数据读取器

doc/fluid/api_cn/data/dataset_cn.rst

@@ -18,7 +18,7 @@ MNIST数据集。
 
 MNIST训练数据集的creator。
 
-它返回一个reader creator, reader中的每个样本的图像像素范围是[0，1]，标签范围是[0，9]。
+它返回一个reader creator, reader中的每个样本的图像像素范围是[-1，1]，标签范围是[0，9]。
 
 返回： 训练数据的reader creator
 
@@ -30,7 +30,7 @@ MNIST训练数据集的creator。
 
 MNIST测试数据集的creator。
 
-它返回一个reader creator, reader中的每个样本的图像像素范围是[0，1]，标签范围是[0，9]。
+它返回一个reader creator, reader中的每个样本的图像像素范围是[-1，1]，标签范围是[0，9]。
 
 返回： 测试数据集的reader creator
 

doc/fluid/api_cn/data_feeder_cn.rst

@@ -14,65 +14,107 @@ DataFeeder
 
 
 ``DataFeeder`` 负责将reader(读取器)返回的数据转成一种特殊的数据结构，使它们可以输入到 ``Executor`` 和 ``ParallelExecutor`` 中。
-reader通常返回一个minibatch条目列表。在列表中每一条目都是一个样本（sample）,它是由具有一至多个特征的列表或元组组成的。
+reader通常返回一个minibatch条目列表。在列表中每一条目都是一个样本（sample），它是由具有一至多个特征的列表或元组组成的。
 
 
 以下是简单用法：
 
-..  code-block:: python
-	
-	place = fluid.CPUPlace()
-	img = fluid.layers.data(name='image', shape=[1, 28, 28])
-	label = fluid.layers.data(name='label', shape=[1], dtype='int64')
-	feeder = fluid.DataFeeder([img, label], fluid.CPUPlace())
-	result = feeder.feed([([0] * 784, [9]), ([1] * 784, [1])])
-	
+.. code-block:: python
+    
+    import paddle.fluid as fluid
+    place = fluid.CPUPlace()
+    img = fluid.layers.data(name='image', shape=[1, 28, 28])
+    label = fluid.layers.data(name='label', shape=[1], dtype='int64')
+    feeder = fluid.DataFeeder([img, label], fluid.CPUPlace())
+    result = feeder.feed([([0] * 784, [9]), ([1] * 784, [1])])
+    
 在多GPU模型训练时，如果需要提前分别向各GPU输入数据，可以使用 ``decorate_reader`` 函数。
 
-..  code-block:: python
+.. code-block:: python
+
+    import paddle
+    import paddle.fluid as fluid
 
-	place=fluid.CUDAPlace(0)
-	feeder = fluid.DataFeeder(place=place, feed_list=[data, label])
-	reader = feeder.decorate_reader(
-    		paddle.batch(flowers.train(), batch_size=16))
+    place=fluid.CUDAPlace(0)
+    data = fluid.layers.data(name='data', shape=[3, 224, 224], dtype='float32')
+    label = fluid.layers.data(name='label', shape=[1], dtype='int64')
+
+    feeder = fluid.DataFeeder(place=place, feed_list=[data, label])
+    reader = feeder.decorate_reader(
+            paddle.batch(paddle.dataset.flowers.train(), batch_size=16), multi_devices=False)
 
 
 
 参数：  
-	- **feed_list** (list) – 向模型输入的变量表或者变量表名
-	- **place** (Place) – place表明是向GPU还是CPU中输入数据。如果想向GPU中输入数据, 请使用 ``fluid.CUDAPlace(i)`` (i 代表 the GPU id)；如果向CPU中输入数据, 请使用  ``fluid.CPUPlace()``
-    	- **program** (Program) – 需要向其中输入数据的Program。如果为None, 会默认使用 ``default_main_program()``。 缺省值为None
+    - **feed_list** (list) – 向模型输入的变量表或者变量表名
+    - **place** (Place) – place表明是向GPU还是CPU中输入数据。如果想向GPU中输入数据, 请使用 ``fluid.CUDAPlace(i)`` (i 代表 the GPU id)；如果向CPU中输入数据, 请使用  ``fluid.CPUPlace()``
+    - **program** (Program) – 需要向其中输入数据的Program。如果为None, 会默认使用 ``default_main_program()``。 缺省值为None
 
 
-弹出异常:	  ``ValueError``  – 如果一些变量不在此 Program 中
+弹出异常:   ``ValueError``  – 如果一些变量不在此 Program 中
 
 
 **代码示例**
 
-..  code-block:: python
-
-	# ...
-	place = fluid.CPUPlace()
-	feed_list = [
-    		main_program.global_block().var(var_name) for var_name in feed_vars_name
-	] # feed_vars_name 是一个由变量名组成的列表
-	feeder = fluid.DataFeeder(feed_list, place)
-	for data in reader():
-    		outs = exe.run(program=main_program,
-               		       feed=feeder.feed(data))
-			       
-			       
+.. code-block:: python
+
+    import numpy as np
+    import paddle
+    import paddle.fluid as fluid
+
+    place = fluid.CPUPlace()
+    def reader():
+        yield [np.random.random([4]).astype('float32'), np.random.random([3]).astype('float32')],
+
+    main_program = fluid.Program()
+    startup_program = fluid.Program()   
+    
+    with fluid.program_guard(main_program, startup_program):
+        data_1 = fluid.layers.data(name='data_1', shape=[1, 2, 2])
+        data_2 = fluid.layers.data(name='data_2', shape=[1, 1, 3])
+        out = fluid.layers.fc(input=[data_1, data_2], size=2)
+        # ...
+    feeder = fluid.DataFeeder([data_1, data_2], place)
+    
+    exe = fluid.Executor(place)
+    exe.run(startup_program)
+    for data in reader():
+        outs = exe.run(program=main_program,
+                        feed=feeder.feed(data),
+                        fetch_list=[out])
+
+
+
+
 .. py:method:: feed(iterable)
 
 
 根据feed_list（数据输入表）和iterable（可遍历的数据）提供的信息，将输入数据转成一种特殊的数据结构，使它们可以输入到 ``Executor`` 和 ``ParallelExecutor`` 中。
 
-参数:	
-	- **iterable** (list|tuple) – 要输入的数据
+参数:    
+    - **iterable** (list|tuple) – 要输入的数据
 
 返回：  转换结果
 
-返回类型:	dict
+返回类型: dict
+
+**代码示例**
+
+.. code-block:: python
+
+        import numpy.random as random
+        import paddle.fluid as fluid
+        
+        def reader(limit=5):
+            for i in range(limit):
+                yield random.random([784]).astype('float32'), random.random([1]).astype('int64'), random.random([256]).astype('float32')
+        
+        data_1 = fluid.layers.data(name='data_1', shape=[1, 28, 28])
+        data_2 = fluid.layers.data(name='data_2', shape=[1], dtype='int64')
+        data_3 = fluid.layers.data(name='data_3', shape=[16, 16], dtype='float32')
+        feeder = fluid.DataFeeder(['data_1','data_2', 'data_3'], fluid.CPUPlace())
+        
+        result = feeder.feed(reader())
 
 
 .. py:method:: feed_parallel(iterable, num_places=None)
@@ -80,7 +122,7 @@ reader通常返回一个minibatch条目列表。在列表中每一条目都是
 
 该方法获取的多个minibatch，并把每个minibatch提前输入进各个设备中。
 
-参数:	
+参数:    
     - **iterable** (list|tuple) – 要输入的数据
     - **num_places** (int) – 设备数目。默认为None。
 
@@ -91,12 +133,38 @@ reader通常返回一个minibatch条目列表。在列表中每一条目都是
 .. note::
    设备（CPU或GPU）的数目必须等于minibatch的数目
 
+**代码示例**
+
+.. code-block:: python
+
+    import numpy.random as random
+    import paddle.fluid as fluid
+
+    def reader(limit=10):
+        for i in range(limit):
+            yield [random.random([784]).astype('float32'), random.randint(10)],
+    
+    x = fluid.layers.data(name='x', shape=[1, 28, 28])
+    y = fluid.layers.data(name='y', shape=[1], dtype='int64')
+    
+    feeder = fluid.DataFeeder(['x','y'], fluid.CPUPlace())
+    place_num = 2
+    places = [fluid.CPUPlace() for x in range(place_num)]
+    data = []
+    exe = fluid.Executor(fluid.CPUPlace())
+    exe.run(fluid.default_startup_program())
+    program = fluid.CompiledProgram(fluid.default_main_program()).with_data_parallel(places=places)
+    for item in reader():
+        data.append(item)
+        if place_num == len(data):
+            exe.run(program=program, feed=list(feeder.feed_parallel(data, place_num)), fetch_list=[])
+            data = []
+
 
 
 .. py:method::  decorate_reader(reader, multi_devices, num_places=None, drop_last=True)
 
 
-  
 将reader返回的输入数据batch转换为多个mini-batch，之后每个mini-batch都会被输入进各个设备（CPU或GPU）中。
     
 参数：
@@ -111,9 +179,29 @@ reader通常返回一个minibatch条目列表。在列表中每一条目都是
     
 弹出异常： ValueError – 如果 ``drop_last`` 值为False并且reader返回的minibatch数目与设备数目不相等时，产生此异常
 
+**代码示例**
 
-        
+.. code-block:: python
 
+    import numpy.random as random
+    import paddle
+    import paddle.fluid as fluid
+    
+    def reader(limit=5):
+        for i in range(limit):
+            yield (random.random([784]).astype('float32'), random.random([1]).astype('int64')),
+    
+    place=fluid.CUDAPlace(0)
+    data = fluid.layers.data(name='data', shape=[1, 28, 28], dtype='float32')
+    label = fluid.layers.data(name='label', shape=[1], dtype='int64')
+    
+    feeder = fluid.DataFeeder(place=place, feed_list=[data, label])
+    reader = feeder.decorate_reader(reader, multi_devices=False)
+    
+    exe = fluid.Executor(place)
+    exe.run(fluid.default_startup_program())
+    for data in reader():
+        exe.run(feed=data)
 
 
 

doc/fluid/api_cn/dataset_cn.rst

@@ -14,28 +14,221 @@ DatasetFactory
 
 .. py:class:: paddle.fluid.dataset.DatasetFactory
 
-DatasetFactory是一个按数据集名称创建数据集的 "工厂" ，可以创建“QueueDataset”或“InMemoryDataset”，默认为“QueueDataset”。
+DatasetFactory是一个按数据集名称创建数据集的 "工厂"，可以创建“QueueDataset”，“InMemoryDataset”或“FileInstantDataset”，默认为“QueueDataset”。
+
 
 **代码示例**
 
 .. code-block:: python
 
-    dataset = paddle.fluid.DatasetFactory.create_dataset(“InMemoryDataset”)
+    import paddle.fluid as fluid
+    dataset = paddle.fluid.DatasetFactory().create_dataset("InMemoryDataset")
 
 .. py:method:: create_dataset(datafeed_class='QueueDataset')
 
-创建“QueueDataset”或“InMemoryDataset”，默认为“QueueDataset”。
+创建“QueueDataset”，“InMemoryDataset” 或 “FileInstantDataset”，默认为“QueueDataset”。
+
+
+参数：
+    - **datafeed_class** (str) – datafeed类名，为QueueDataset或InMemoryDataset。默认为QueueDataset。
+
+**代码示例**:
+
+.. code-block:: python
+
+    import paddle.fluid as fluid
+    dataset = fluid.DatasetFactory().create_dataset()
+
+
+
+.. _cn_api_fluid_dataset_InMemoryDataset:
+
+InMemoryDataset
+-------------------------------
+
+.. py:class:: paddle.fluid.dataset.InMemoryDataset
+
+InMemoryDataset会向内存中加载数据并在训练前缓冲数据。此类由DatasetFactory创建。
+
+**代码示例**:
+
+.. code-block:: python
+
+    dataset = paddle.fluid.DatasetFactory().create_dataset(“InMemoryDataset”)
+
+
+.. py:method:: load_into_memory()
+
+向内存中加载数据。
+
+**代码示例**:
+
+.. code-block:: python
+
+    import paddle.fluid as fluid
+    dataset = fluid.DatasetFactory().create_dataset("InMemoryDataset")
+    filelist = ["a.txt", "b.txt"]
+    dataset.set_filelist(filelist)
+    dataset.load_into_memory()
+
+
+.. py:method:: local_shuffle()
+
+局域shuffle。
+
+**代码示例**:
+
+.. code-block:: python
+
+    import paddle.fluid as fluid
+    dataset = fluid.DatasetFactory().create_dataset("InMemoryDataset")
+    filelist = ["a.txt", "b.txt"]
+    dataset.set_filelist(filelist)
+    dataset.load_into_memory()
+    dataset.local_shuffle()
+
+
+.. py:method:: global_shuffle(fleet=None)
+
+全局shuffle。
+
+只能用在分布式模式（单机多进程或多机多进程）中。您如果在分布式模式中运行，应当传递fleet而非None。
+
+**代码示例**:
+
+.. code-block:: python
+
+    import paddle.fluid as fluid
+    from paddle.fluid.incubate.fleet.parameter_server.pslib import fleet
+    dataset = fluid.DatasetFactory().create_dataset("InMemoryDataset")
+    filelist = ["a.txt", "b.txt"]
+    dataset.set_filelist(filelist)
+    dataset.load_into_memory()
+    dataset.global_shuffle(fleet)
+
+参数：
+    - **fleet** (Fleet) – fleet单例。默认为None。
+
 
+.. py:method:: release_memory()
 
+当数据不再使用时，释放InMemoryDataset内存数据。
 
+**代码示例**:
 
+.. code-block:: python
+
+    import paddle.fluid as fluid
+    from paddle.fluid.incubate.fleet.parameter_server.pslib import fleet
+    dataset = fluid.DatasetFactory().create_dataset("InMemoryDataset")
+    filelist = ["a.txt", "b.txt"]
+    dataset.set_filelist(filelist)
+    dataset.load_into_memory()
+    dataset.global_shuffle(fleet)
+    exe = fluid.Executor(fluid.CPUPlace())
+    exe.run(fluid.default_startup_program())
+    exe.train_from_dataset(fluid.default_main_program(), dataset)dataset.release_memory()
+    dataset.release_memory()
+
+.. py:method:: get_memory_data_size(fleet=None)
+
+用户可以调用此函数以了解加载进内存后所有workers中的ins数量。
+
+.. note::
+    该函数可能会导致性能不佳，因为它具有barrier。
+
+参数：
+    - **fleet** (Fleet) – fleet对象。
+
+返回：内存数据的大小。
+
+**代码示例**:
+
+.. code-block:: python
+
+    import paddle.fluid as fluid
+    from paddle.fluid.incubate.fleet.parameter_server.pslib import fleet
+    dataset = fluid.DatasetFactory().create_dataset("InMemoryDataset")
+    filelist = ["a.txt", "b.txt"]
+    dataset.set_filelist(filelist)
+    dataset.load_into_memory()
+    print dataset.get_memory_data_size(fleet)
+
+
+.. py:method:: get_shuffle_data_size(fleet=None)
+
+获取shuffle数据大小，用户可以调用此函数以了解局域/全局shuffle后所有workers中的ins数量。
+
+.. note::
+    该函数可能会导致局域shuffle性能不佳，因为它具有barrier。但其不影响局域shuffle。
+
+参数：
+    - **fleet** (Fleet) – fleet对象。
+
+返回：shuffle数据的大小。
+
+**代码示例**:
+
+.. code-block:: python
+
+    import paddle.fluid as fluid
+    from paddle.fluid.incubate.fleet.parameter_server.pslib import fleet
+    dataset = fluid.DatasetFactory().create_dataset("InMemoryDataset")
+    filelist = ["a.txt", "b.txt"]
+    dataset.set_filelist(filelist)
+    dataset.load_into_memory()
+    dataset.global_shuffle(fleet)
+    print dataset.get_shuffle_data_size(fleet)
 
 
 
 
+.. _cn_api_fluid_dataset_QueueDataset:
 
+QueueDataset
+-------------------------------
+
+.. py:class:: paddle.fluid.dataset.QueueDataset
+
+流式处理数据。
+
+**代码示例**:
+
+.. code-block:: python
+
+    import paddle.fluid as fluid
+    dataset = fluid.DatasetFactory().create_dataset("QueueDataset")
+
+
+
+.. py:method:: local_shuffle()
+
+局域shuffle数据
 
+QueueDataset中不支持局域shuffle，可能抛出NotImplementedError
 
+**代码示例**:
 
+.. code-block:: python
+
+    import paddle.fluid as fluid
+    dataset = fluid.DatasetFactory().create_dataset("QueueDataset")
+    dataset.local_shuffle()
+
+
+
+.. py:method:: global_shuffle(fleet=None)
+
+全局shuffle数据
+
+QueueDataset中不支持全局shuffle，可能抛出NotImplementedError
+
+**代码示例**:
+
+.. code-block:: python
 
+    import paddle.fluid as fluid
+    from paddle.fluid.incubate.fleet.parameter_server.pslib import fleet
+    dataset = fluid.DatasetFactory().create_dataset("QueueDataset")
+    dataset.global_shuffle(fleet)
 

doc/fluid/api_cn/executor_cn.rst

-#################
- fluid.executor
-#################
-
-
-
-.. _cn_api_fluid_executor_Executor:
-
-Executor
--------------------------------
-
-
-.. py:class:: paddle.fluid.executor.Executor (place)
-
-
-
-
-
-
-执行引擎（Executor）使用python脚本驱动，仅支持在单GPU环境下运行。多卡环境下请参考 ``ParallelExecutor`` 。
-Python Executor可以接收传入的program,并根据feed map(输入映射表)和fetch_list(结果获取表)
-向program中添加feed operators(数据输入算子)和fetch operators（结果获取算子)。
-feed map为该program提供输入数据。fetch_list提供program训练结束后用户预期的变量（或识别类场景中的命名）。
-
-应注意，执行器会执行program中的所有算子而不仅仅是依赖于fetch_list的那部分。
-
-Executor将全局变量存储到全局作用域中，并为临时变量创建局部作用域。
-当每一mini-batch上的前向/反向运算完成后，局部作用域的内容将被废弃，
-但全局作用域中的变量将在Executor的不同执行过程中一直存在。
-
-program中所有的算子会按顺序执行。
-
-**示例代码**
-
-.. code-block:: python
-
-    # 新建一个执行引擎Executor名为exe。 
-    place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace()
-    exe = fluid.Executor(place)
-
-    # 仅运行一次startup program.
-    # 不需要优化/编译这个startup program. 
-    exe.run(fluid.default_startup_program())
-
-    # 无需编译，直接运行main program
-    loss, = exe.run(fluid.default_main_program(),
-                        feed=feed_dict,
-                        fetch_list=[loss.name])
-
-    # 另一种方法是，编译这个main program然后运行. 参考CompiledProgram 
-    compiled_prog = compiler.CompiledProgram(
-            fluid.default_main_program()).with_data_parallel(
-            loss_name=loss.name)
-    loss, = exe.run(compiled_prog,
-                        feed=feed_dict,
-                        fetch_list=[loss.name])
-
-
-参数:	
-    - **place** (core.CPUPlace|core.CUDAPlace(n)) – 指明了 ``Executor`` 的执行场所
-
-
-
-提示：你可以用 ``Executor`` 来调试基于并行GPU实现的复杂网络，他们有完全一样的参数也会产生相同的结果。
-
-
-.. py:method:: close()
-
-
-关闭这个执行器(Executor)。调用这个方法后不可以再使用这个执行器。 对于分布式训练, 该函数会释放在PServers上涉及到目前训练器的资源。
-   
-**示例代码**
-
-..  code-block:: python
-    
-    cpu = core.CPUPlace()
-    exe = Executor(cpu)
-    ...
-    exe.close()
-
-
-.. py:method:: run(program=None, feed=None, fetch_list=None, feed_var_name='feed', fetch_var_name='fetch', scope=None, return_numpy=True,use_program_cache=False)
-
-
-调用该执行器对象的此方法可以执行program。通过feed map提供待学习数据，以及借助fetch_list得到相应的结果。
-Python执行器(Executor)可以接收传入的program,并根据输入映射表(feed map)和结果获取表(fetch_list)
-向program中添加数据输入算子(feed operators)和结果获取算子（fetch operators)。
-feed map为该program提供输入数据。fetch_list提供program训练结束后用户预期的变量（或识别类场景中的命名）。
-
-应注意，执行器会执行program中的所有算子而不仅仅是依赖于fetch_list的那部分。
-
-参数：  
-	- **program** (Program|CompiledProgram) – 需要执行的program,如果没有给定那么默认使用default_main_program (未编译的)
-	- **feed** (dict) – 前向输入的变量，数据,词典dict类型, 例如 {“image”: ImageData, “label”: LabelData}
-	- **fetch_list** (list) – 用户想得到的变量或者命名的列表, run会根据这个列表给与结果
-	- **feed_var_name** (str) – 前向算子(feed operator)变量的名称
-	- **fetch_var_name** (str) – 结果获取算子(fetch operator)的输出变量名称
-	- **scope** (Scope) – 执行这个program的域，用户可以指定不同的域。缺省为全局域
-	- **return_numpy** (bool) – 如果为True,则将结果张量（fetched tensor）转化为numpy
-	- **use_program_cache** (bool) – 当program较上次比没有改动则将其置为True
-	
-返回:	根据fetch_list来获取结果
-
-返回类型:	list(numpy.array)
-
-
-**示例代码**
-
-..  code-block:: python
-
-	data = fluid.layers.data(name='X', shape=[1], dtype='float32')
-	out = fluid.layers.create_tensor(dtype='float32')
-	hidden = fluid.layers.fc(input=data, size=10)
-	fluid.layers.assign(hidden,out)
-	loss = fluid.layers.mean(out)
-	adam = fluid.optimizer.Adam()
-	# adam.minimize(loss)
-
-
-..  code-block:: python
-
-	cpu = core.CPUPlace()
-	exe = fluid.Executor(cpu)
-	exe.run(fluid.default_startup_program())
-
-..  code-block:: python
-	
-	x = numpy.random.random(size=(10, 1)).astype('float32')
-	outs = exe.run(
-		feed={'X': x},
-		fetch_list=[loss.name])
-	
-
-
-
-
-
-
-
-
-
-.. _cn_api_fluid_executor_global_scope:
-
-global_scope
--------------------------------
-
-.. py:function:: paddle.fluid.executor.global_scope ()
-
-
-获取全局/默认作用域实例。很多api使用默认 ``global_scope`` ，例如 ``Executor.run`` 。
-
-返回：全局/默认作用域实例
-
-返回类型：Scope
-
-
-
-
-
-
-.. _cn_api_fluid_executor_scope_guard:
-
-scope_guard
--------------------------------
-
-.. py:function:: paddle.fluid.executor.scope_guard (scope)
-
-
-修改全局/默认作用域（scope）,  运行时中的所有变量都将分配给新的scope。
-
-参数：
-	- **scope** - 新的全局/默认 scope。
-
-**代码示例**
-
-..  code-block:: python
-
-	import paddle.fluid as fluid
-	
-	new_scope = fluid.Scope()
-	with fluid.scope_guard(new_scope):
-		...
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+#################
+ fluid.executor
+#################
+
+
+
+.. _cn_api_fluid_executor_Executor:
+
+Executor
+-------------------------------
+
+
+.. py:class:: paddle.fluid.executor.Executor (place)
+
+
+
+
+执行引擎（Executor）使用python脚本驱动，支持在单/多GPU、单/多CPU环境下运行。
+Python Executor可以接收传入的program,并根据feed map(输入映射表)和fetch_list(结果获取表)
+向program中添加feed operators(数据输入算子)和fetch operators（结果获取算子)。
+feed map为该program提供输入数据。fetch_list提供program训练结束后用户预期的变量（或识别类场景中的命名）。
+
+应注意，执行器会执行program中的所有算子而不仅仅是依赖于fetch_list的那部分。
+
+Executor将全局变量存储到全局作用域中，并为临时变量创建局部作用域。
+当每一mini-batch上的前向/反向运算完成后，局部作用域的内容将被废弃，
+但全局作用域中的变量将在Executor的不同执行过程中一直存在。
+
+
+**示例代码**
+
+.. code-block:: python
+    
+    import paddle.fluid as fluid
+    import paddle.fluid.compiler as compiler
+    import numpy
+    import os
+
+    use_cuda = True
+    place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace()
+    exe = fluid.Executor(place)
+
+    train_program = fluid.Program()
+    startup_program = fluid.Program()
+    with fluid.program_guard(train_program, startup_program):
+        data = fluid.layers.data(name='X', shape=[1], dtype='float32')
+        hidden = fluid.layers.fc(input=data, size=10)
+        loss = fluid.layers.mean(hidden)
+        fluid.optimizer.SGD(learning_rate=0.01).minimize(loss)
+
+    # 仅运行一次startup program
+    # 不需要优化/编译这个startup program
+    startup_program.random_seed=1
+    exe.run(startup_program)
+
+    # 无需编译，直接运行main program
+    x = numpy.random.random(size=(10, 1)).astype('float32')
+    loss_data, = exe.run(train_program,
+                     feed={"X": x},
+                     fetch_list=[loss.name])
+
+    # 另一种方法是，编译这个main program然后运行。
+    # 参考CompiledProgram以获取更多信息。
+    # 注意：如果你使用CPU运行程序，需要具体设置CPU_NUM，
+    # 否则fluid会把逻辑核的所有数目设为CPU_NUM，
+    # 在这种情况下，输入的batch size应大于CPU_NUM，
+    # 否则程序会异常中断。
+    if not use_cuda:
+        os.environ['CPU_NUM'] = str(2)
+
+    compiled_prog = compiler.CompiledProgram(
+        train_program).with_data_parallel(
+        loss_name=loss.name)
+    loss_data, = exe.run(compiled_prog,
+                         feed={"X": x},
+                         fetch_list=[loss.name])
+
+
+参数:
+    - **place** (fluid.CPUPlace|fluid.CUDAPlace(n)) – 指明了 ``Executor`` 的执行场所
+
+
+
+.. py:method:: close()
+
+
+关闭这个执行器(Executor)。
+
+调用这个方法后不可以再使用这个执行器。 对于分布式训练, 该函数会释放在PServers上和目前Trainer有关联的资源。
+
+**示例代码**
+
+.. code-block:: python
+    
+    import paddle.fluid as fluid
+
+    cpu = fluid.CPUPlace()
+    exe = fluid.Executor(cpu)
+    # 执行训练或测试过程
+    exe.close()
+
+
+.. py:method:: run(program=None, feed=None, fetch_list=None, feed_var_name='feed', fetch_var_name='fetch', scope=None, return_numpy=True,use_program_cache=False)
+
+
+调用该执行器对象的此方法可以执行program。通过feed map提供待学习数据，以及借助fetch_list得到相应的结果。
+Python执行器(Executor)可以接收传入的program,并根据输入映射表(feed map)和结果获取表(fetch_list)
+向program中添加数据输入算子(feed operators)和结果获取算子（fetch operators)。
+feed map为该program提供输入数据。fetch_list提供program训练结束后用户预期的变量（或识别类场景中的命名）。
+
+应注意，执行器会执行program中的所有算子而不仅仅是依赖于fetch_list的那部分。
+
+**示例代码**
+
+.. code-block:: python
+
+            import paddle.fluid as fluid
+            import numpy
+     
+            #首先创建执行引擎
+            place = fluid.CPUPlace() # fluid.CUDAPlace(0)
+            exe = fluid.Executor(place)
+     
+            data = fluid.layers.data(name='X', shape=[1], dtype='float32')
+            hidden = fluid.layers.fc(input=data, size=10)
+            loss = fluid.layers.mean(hidden)
+            adam = fluid.optimizer.Adam()
+            adam.minimize(loss)
+     
+            #仅运行startup程序一次
+            exe.run(fluid.default_startup_program())
+
+            x = numpy.random.random(size=(10, 1)).astype('float32')
+            outs = exe.run(feed={'X': x},
+                           fetch_list=[loss.name])
+
+参数：  
+  - **program** (Program|CompiledProgram) – 需要执行的program,如果没有给定那么默认使用default_main_program (未编译的)
+  - **feed** (dict) – 前向输入的变量，数据,词典dict类型, 例如 {“image”: ImageData, “label”: LabelData}
+  - **fetch_list** (list) – 用户想得到的变量或者命名的列表, 该方法会根据这个列表给出结果
+  - **feed_var_name** (str) – 前向算子(feed operator)变量的名称
+  - **fetch_var_name** (str) – 结果获取算子(fetch operator)的输出变量名称
+  - **scope** (Scope) – 执行这个program的域，用户可以指定不同的域。缺省为全局域
+  - **return_numpy** (bool) – 如果为True,则将结果张量（fetched tensor）转化为numpy
+  - **use_program_cache** (bool) – 是否跨批使用缓存程序设置。设置为True时，只有当（1）程序没有用数据并行编译，并且（2）program、 feed变量名和fetch_list变量名与上一步相比没有更改时，运行速度才会更快。
+  
+返回: 根据fetch_list来获取结果
+
+返回类型: list(numpy.array)
+
+
+.. py:method:: infer_from_dataset(program=None, dataset=None, scope=None, thread=0, debug=False, fetch_list=None, fetch_info=None, print_period=100)
+
+infer_from_dataset的文档与train_from_dataset几乎完全相同，只是在分布式训练中，推进梯度将在infer_from_dataset中禁用。 infer_from_dataset（）可以非常容易地用于多线程中的评估。
+
+参数：  
+  - **program** (Program|CompiledProgram) – 需要执行的program,如果没有给定那么默认使用default_main_program (未编译的)
+  - **dataset** (paddle.fluid.Dataset) – 在此函数外创建的数据集，用户应当在调用函数前提供完整定义的数据集。必要时请检查Dataset文件。默认为None
+  - **scope** (Scope) – 执行这个program的域，用户可以指定不同的域。默认为全局域
+  - **thread** (int) – 用户想要在这个函数中运行的线程数量。线程的实际数量为min(Dataset.thread_num, thread)，如果thread > 0，默认为0
+  - **debug** (bool) – 是否开启debug模式，默认为False
+  - **fetch_list** (Variable List) – 返回变量列表，每个变量都会在训练过程中被打印出来，默认为None
+  - **fetch_info** (String List) – 每个变量的打印信息，默认为None
+  - **print_period** (int) – 每两次打印之间间隔的mini-batches的数量，默认为100
+
+返回: None
+
+**示例代码**
+
+.. code-block:: python
+
+  import paddle.fluid as fluid
+  place = fluid.CPUPlace() # 使用GPU时可设置place = fluid.CUDAPlace(0)
+  exe = fluid.Executor(place)
+  x = fluid.layers.data(name="x", shape=[10, 10], dtype="int64")
+  y = fluid.layers.data(name="y", shape=[1], dtype="int64", lod_level=1)
+  dataset = fluid.DatasetFactory().create_dataset()
+  dataset.set_use_var([x, y])
+  dataset.set_thread(1)
+  filelist = [] # 您可以设置您自己的filelist，如filelist = ["dataA.txt"]
+  dataset.set_filelist(filelist)
+  exe.run(fluid.default_startup_program())
+  exe.infer_from_dataset(program=fluid.default_main_program(),dataset=dataset)
+     
+
+.. py:method:: train_from_dataset(program=None, dataset=None, scope=None, thread=0, debug=False, fetch_list=None, fetch_info=None, print_period=100)
+
+从预定义的数据集中训练。 数据集在paddle.fluid.dataset中定义。 给定程序（或编译程序），train_from_dataset将使用数据集中的所有数据样本。 输入范围可由用户给出。 默认情况下，范围是global_scope()。训练中的线程总数是thread。 训练中使用的线程数将是数据集中threadnum的最小值，同时也是此接口中线程的值。 可以设置debug，以便执行器显示所有算子的运行时间和当前训练任务的吞吐量。
+
+注意：train_from_dataset将销毁每次运行在executor中创建的所有资源。
+
+参数：  
+  - **program** (Program|CompiledProgram) – 需要执行的program,如果没有给定那么默认使用default_main_program (未编译的)
+  - **dataset** (paddle.fluid.Dataset) – 在此函数外创建的数据集，用户应当在调用函数前提供完整定义的数据集。必要时请检查Dataset文件。默认为None
+  - **scope** (Scope) – 执行这个program的域，用户可以指定不同的域。默认为全局域
+  - **thread** (int) – 用户想要在这个函数中运行的线程数量。线程的实际数量为min(Dataset.thread_num, thread)，如果thread > 0，默认为0
+  - **debug** (bool) – 是否开启debug模式，默认为False
+  - **fetch_list** (Variable List) – 返回变量列表，每个变量都会在训练过程中被打印出来，默认为None
+  - **fetch_info** (String List) – 每个变量的打印信息，默认为None
+  - **print_period** (int) – 每两次打印之间间隔的mini-batches的数量，默认为100
+
+返回: None
+
+**示例代码**
+
+.. code-block:: python
+
+        import paddle.fluid as fluid
+
+        place = fluid.CPUPlace() # 通过设置place = fluid.CUDAPlace(0)使用GPU
+        exe = fluid.Executor(place)
+        x = fluid.layers.data(name="x", shape=[10, 10], dtype="int64")
+        y = fluid.layers.data(name="y", shape=[1], dtype="int64", lod_level=1)
+        dataset = fluid.DatasetFactory().create_dataset()
+        dataset.set_use_var([x, y])
+        dataset.set_thread(1)
+        filelist = [] # 您可以设置您自己的filelist，如filelist = ["dataA.txt"]
+        dataset.set_filelist(filelist)
+        exe.run(fluid.default_startup_program())
+        exe.infer_from_dataset(program=fluid.default_main_program(),
+                               dataset=dataset)
+
+
+.. _cn_api_fluid_executor_global_scope:
+
+global_scope
+-------------------------------
+
+.. py:function:: paddle.fluid.global_scope()
+
+
+获取全局/默认作用域实例。很多api使用默认 ``global_scope`` ，例如 ``Executor.run`` 。
+
+**示例代码**
+
+.. code-block:: python
+
+        import paddle.fluid as fluid
+        import numpy
+
+        fluid.global_scope().var("data").get_tensor().set(numpy.ones((2, 2)), fluid.CPUPlace())
+        numpy.array(fluid.global_scope().find_var("data").get_tensor())
+
+返回：全局/默认作用域实例
+
+返回类型：Scope
+
+
+
+
+
+
+.. _cn_api_fluid_executor_scope_guard:
+
+scope_guard
+-------------------------------
+
+.. py:function:: paddle.fluid.executor.scope_guard (scope)
+
+
+修改全局/默认作用域（scope）,  运行时中的所有变量都将分配给新的scope。
+
+参数：
+    - **scope** - 新的全局/默认 scope。
+
+**代码示例**
+
+.. code-block:: python
+
+    import numpy
+
+    new_scope = fluid.Scope()
+    with fluid.scope_guard(new_scope):
+         fluid.global_scope().var("data").get_tensor().set(numpy.ones((2, 2)), fluid.CPUPlace())
+    numpy.array(new_scope.find_var("data").get_tensor())
+
+
+
+
+
+
+
+
+
+
+
+
+

doc/fluid/api_cn/initializer_cn.rst

@@ -27,14 +27,19 @@ BilinearInitializer
 .. code-block:: python
 
     factor = 2
-    w_attr = ParamAttr(learning_rate=0., regularizer=L2Decay(0.),
-                   initializer=Bilinear())
+    C = 2
+    w_attr = fluid.initializer.ParamAttr(
+        learning_rate=0.,
+        regularizer=fluid.regularizer.L2Decay(0.),
+        initializer=fluid.initializer.Bilinear())
+    x = fluid.layers.data(name="data", shape=[3, 32, 32],
+                          dtype="float32")
     conv_up = fluid.layers.conv2d_transpose(
-        input,
+        input=x,
         num_filters=C,
         output_size=None,
         filter_size=2 * factor - factor % 2,
-        padding=ceil((factor - 1) / 2.),
+        padding=int(math.ceil((factor - 1) / 2.)),
         stride=factor,
         groups=C,
         param_attr=w_attr,
@@ -72,6 +77,7 @@ ConstantInitializer
 
 .. code-block:: python
         
+        x = fluid.layers.data(name="data", shape=[32, 32], dtype="float32")
         fc = fluid.layers.fc(input=x, size=10,
             param_attr=fluid.initializer.Constant(value=2.0))
 
@@ -98,8 +104,8 @@ force_init_on_cpu
 
 .. code-block:: python
 
-    if force_init_on_cpu():
-        create_op('force_cpu': force_init_on_cpu())
+    if fluid.initializer.force_init_on_cpu():
+        step = fluid.layers.create_global_var(shape=[2,3], value=1.0, dtype='float32')
 
 
 
@@ -124,8 +130,8 @@ init_on_cpu
 
 .. code-block:: python
         
-        with init_on_cpu():
-                step = fluid.layers.create_global_var()
+        with fluid.initializer.init_on_cpu():
+            step = fluid.layers.create_global_var(shape=[2,3], value=1.0, dtype='float32')
 
 
 
@@ -156,7 +162,7 @@ MSRAInitializer
 
 .. math::
 
-	x = \sqrt{\frac{6.0}{fan\_in}}
+    x = \sqrt{\frac{6.0}{fan\_in}}
 
 在正态分布中，均值为0，标准差为：
 
@@ -177,9 +183,8 @@ MSRAInitializer
 
 .. code-block:: python
 
-    fc = fluid.layers.fc(
-        input=queries, size=10,
-        param_attr=fluid.initializer.MSRA(uniform=False))
+    x = fluid.layers.data(name="data", shape=[32, 32], dtype="float32")
+    fc = fluid.layers.fc(input=x, size=10, param_attr=fluid.initializer.MSRA(uniform=False))
 
 
 
@@ -214,6 +219,7 @@ NormalInitializer
 
 .. code-block:: python
 
+        x = fluid.layers.data(name="data", shape=[32, 32], dtype="float32")
         fc = fluid.layers.fc(input=x, size=10,
             param_attr=fluid.initializer.Normal(loc=0.0, scale=2.0)
 
@@ -234,6 +240,7 @@ NumpyArrayInitializer
 
 .. code-block:: python
 
+    x = fluid.layers.data(name="x", shape=[5], dtype='float32')
     fc = fluid.layers.fc(input=x, size=10,
         param_attr=fluid.initializer.NumpyArrayInitializer(numpy.array([1,2])))
 
@@ -266,6 +273,8 @@ Random Truncated Normal（高斯）分布初始化器
 
 .. code-block:: python
 
+        import paddle.fluid as fluid
+        x = fluid.layers.data(name='x', shape=[1], dtype='float32')
         fc = fluid.layers.fc(input=x, size=10,
             param_attr=fluid.initializer.TruncatedNormal(loc=0.0, scale=2.0))
 
@@ -305,7 +314,9 @@ UniformInitializer
 **代码示例**
 
 .. code-block:: python
-        
+       
+       import paddle.fluid as fluid
+       x = fluid.layers.data(name='x', shape=[1], dtype='float32')
        fc = fluid.layers.fc(input=x, size=10,
             param_attr=fluid.initializer.Uniform(low=-0.5, high=0.5))
  
@@ -368,6 +379,8 @@ XavierInitializer
 
 .. code-block:: python
 
+    import paddle.fluid as fluid
+    queries = fluid.layers.data(name='x', shape=[1], dtype='float32')
     fc = fluid.layers.fc(
         input=queries, size=10,
         param_attr=fluid.initializer.Xavier(uniform=False))

doc/fluid/api_cn/nets_cn.rst

@@ -30,8 +30,10 @@ he Gated Linear Units(GLU)由切分（split），sigmoid激活函数和按元素
 
 .. code-block:: python
 
-    data = fluid.layers.data(name="words", shape=[3, 6, 9], dtype="float32")
-    output = fluid.nets.glu(input=data, dim=1)  # shape of output: [3, 3, 9]
+    data = fluid.layers.data(
+        name="words", shape=[-1, 6, 3, 9], dtype="float32")
+    # 输出的形状为[-1, 3, 3, 9]
+    output = fluid.nets.glu(input=data, dim=1)  
 
 
 
@@ -70,11 +72,10 @@ Image Convolution Group由Convolution2d，BatchNorm，DropOut和Pool2d组成。
 
 **代码示例**
 
-..  code-block:: python
+.. code-block:: python
 
           img = fluid.layers.data(name='img', shape=[1, 28, 28], dtype='float32')
           conv_pool = fluid.nets.img_conv_group(input=img,
-                                                num_channels=3,
                                                 conv_padding=1,
                                                 conv_num_filter=[3, 3],
                                                 conv_filter_size=3,
@@ -126,8 +127,10 @@ attention运算机制可以被视为将查询和一组键值对映射到输出
 
 **代码示例**
 
-..  code-block:: python
+.. code-block:: python
 
+          import paddle.fluid as fluid
+          
           queries = fluid.layers.data(name="queries",
                                       shape=[3, 5, 9],
                                       dtype="float32",
@@ -181,10 +184,11 @@ sequence_conv_pool由序列卷积和池化组成
 
 .. code-block:: python
 
-    input_dim = len(word_dict)
+    import paddle.fluid as fluid
+    input_dim = 100 #len(word_dict)
     emb_dim = 128
     hid_dim = 512
-    data = fluid.layers.data( ame="words", shape=[1], dtype="int64", lod_level=1)
+    data = fluid.layers.data( name="words", shape=[1], dtype="int64", lod_level=1)
     emb = fluid.layers.embedding(input=data, size=[input_dim, emb_dim], is_sparse=True)
     seq_conv = fluid.nets.sequence_conv_pool(input=emb,
                                          num_filters=hid_dim,
@@ -232,8 +236,9 @@ simple_img_conv_pool
 
 **示例代码**
 
-..  code-block:: python
+.. code-block:: python
 
+    import paddle.fluid as fluid
     img = fluid.layers.data(name='img', shape=[1, 28, 28], dtype='float32')
     conv_pool = fluid.nets.simple_img_conv_pool(input=img,
                                             filter_size=5,

doc/fluid/api_cn/profiler_cn.rst

@@ -27,10 +27,11 @@ CUDA分析器。通过CUDA运行时应用程序编程接口对CUDA程序进行
 **代码示例**
 
 
-..  code-block:: python
+.. code-block:: python
 
     import paddle.fluid as fluid
     import paddle.fluid.profiler as profiler
+    import numpy as np
 
     epoc = 8
     dshape = [4, 3, 28, 28]
@@ -79,18 +80,24 @@ profile interface 。与cuda_profiler不同，此profiler可用于分析CPU和GP
 
 **代码示例**
 
-..  code-block:: python
+.. code-block:: python
 
     import paddle.fluid.profiler as profiler
+    import numpy as np
 
-    with profiler.profiler('All', 'total', '/tmp/profile') as prof:
-        for pass_id in range(pass_num):
-            for batch_id, data in enumerate(train_reader()):
-                exe.run(fluid.default_main_program(),
-                        feed=feeder.feed(data),
-                        fetch_list=[],
-                        use_program_cache=True)
-                # ...
+    epoc = 8
+    dshape = [4, 3, 28, 28]
+    data = fluid.layers.data(name='data', shape=[3, 28, 28], dtype='float32')
+    conv = fluid.layers.conv2d(data, 20, 3, stride=[1, 1], padding=[1, 1])
+
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    exe.run(fluid.default_startup_program())
+
+    with profiler.profiler('CPU', 'total', '/tmp/profile') as prof:
+        for i in range(epoc):
+            input = np.random.random(dshape).astype('float32')
+            exe.run(fluid.default_main_program(), feed={'data': input})
 
 
 
@@ -109,10 +116,10 @@ reset_profiler
 
 **代码示例**
 
-..  code-block:: python
+.. code-block:: python
 
     import paddle.fluid.profiler as profiler
-    with profiler.profiler(state, 'total', '/tmp/profile'):
+    with profiler.profiler('CPU', 'total', '/tmp/profile'):
     for iter in range(10):
         if iter == 2:
             profiler.reset_profiler()
@@ -146,7 +153,7 @@ start_profiler
 
 **代码示例**
 
-..  code-block:: python
+.. code-block:: python
 
     import paddle.fluid.profiler as profiler
 
@@ -186,7 +193,7 @@ stop_profiler
 
 **代码示例**
 
-..  code-block:: python
+.. code-block:: python
 
     import paddle.fluid.profiler as profiler
 

doc/fluid/api_cn/recordio_writer_cn.rst

-#######################
- fluid.recordio_writer
-#######################
-
-
-
-
-.. _cn_api_fluid_recordio_writer_convert_reader_to_recordio_file:
-
-convert_reader_to_recordio_file
--------------------------------
-
-.. py:function::  paddle.fluid.recordio_writer.convert_reader_to_recordio_file(filename, reader_creator, feeder, compressor=Compressor.Snappy, max_num_records=1000, feed_order=None)
-
-将 Python reader 转换为recordio文件
-
-**代码示例：**
-
-.. code-block:: python
-
-	import paddle.fluid as fluid
-	import paddle.dataset.mnist as mnist
-	import paddle
-
-	tmp_program = fluid.Program()
-	with fluid.program_guard(tmp_program):
-	    img = fluid.layers.data(name='img', shape=[784])
-	    label = fluid.layers.data(name='label', shape=[1], dtype='int64')
-	feeder = fluid.DataFeeder(feed_list=[img, label], place=fluid.CPUPlace())
-	# mnist.recordio 会在当前目录生成
-	fluid.recordio_writer.convert_reader_to_recordio_file(
-	                    filename="mnist.recordio",
-	                    reader_creator=paddle.batch(mnist.train(), batch_size=32),
-	                    feeder=feeder)
-
-参数：
-	- **filename** (str) - recordio文件名
-	- **reader_creator** (callable) - Python reader的创造器。可参考 :ref:`api_guide_python_reader`
-	- **feeder** (DataFeeder) - 数据处理实例。用于将 :code:`reader_creator` 转换为 :code:`lod_tensor`
-	- **compressor** – 必须在 :code:`fluid.core.RecordIOWriter.Compressor.Snappy` 或 :code:` fluid.core.RecordIOWriter.Compressor.NoCompress` 中， 默认情况下使用 :code:`Snappy`
-	- **max_num_records** (int) – 一个 chuck 中 records 的最大数量。每个 records 都是 reader 函数的返回值
-	- **feed_order** (list) - reader 返回的变量名的顺序
-
-返回： 保存的 record 的数目
-
-返回类型： int
-
-
-
-
-
-
-
-
-
-.. _cn_api_fluid_recordio_writer_convert_reader_to_recordio_files:
-
-convert_reader_to_recordio_files
--------------------------------
-
-.. py:function:: paddle.fluid.recordio_writer.convert_reader_to_recordio_files(filename, batch_per_file, reader_creator, feeder, compressor=Compressor.Snappy, max_num_records=1000, feed_order=None)
-
-该函数可以将一个python驱动的reader（数据读取器）转变为多个recodio文件。
-
-该API实现的功能和 ``convert_reader_to_recordio_file`` 基本相同，只不过本函数会生成多个recordio文件。
-每个文件最多存储 ``batch_per_file`` 条记录。
-
-请参照 :ref:`cn_api_fluid_recordio_writer_convert_reader_to_recordio_file` 获取更详细的介绍。
-
-
-
-
-
-
-
-
-

doc/fluid/api_cn/regularizer_cn.rst

@@ -33,13 +33,23 @@ L1正则将会稀疏化权重矩阵。
   
 **代码示例**
 
-..  code-block:: python
+.. code-block:: python
     
-    ioptimizer = fluid.optimizer.Adagrad(
-                            learning_rate=1e-4,
-                            regularization=fluid.regularizer.L1DecayRegularizer(
-                             regularization_coeff=0.1))
-    optimizer.minimize(avg_cost)
+    import paddle.fluid as fluid
+    main_prog = fluid.Program()
+    startup_prog = fluid.Program()
+    with fluid.program_guard(main_prog, startup_prog):
+        data = fluid.layers.data(name='image', shape=[3, 28, 28], dtype='float32')
+        label = fluid.layers.data(name='label', shape=[1], dtype='int64')
+        hidden = fluid.layers.fc(input=data, size=128, act='relu')
+        prediction = fluid.layers.fc(input=hidden, size=10, act='softmax')
+        loss = fluid.layers.cross_entropy(input=prediction, label=label)
+        avg_loss = fluid.layers.mean(loss)
+    optimizer = fluid.optimizer.Adagrad(
+        learning_rate=1e-4,
+        regularization=fluid.regularizer.L1DecayRegularizer(
+            regularization_coeff=0.1))
+    optimizer.minimize(avg_loss)
     
   
   
@@ -80,13 +90,23 @@ L2DecayRegularizer
   
 **代码示例**
 
-..  code-block:: python
+.. code-block:: python
     
-   optimizer = fluid.optimizer.Adagrad(
-                            learning_rate=1e-4,
-                            regularization=fluid.regularizer.L2DecayRegularizer(
-                            regularization_coeff=0.1))
-    optimizer.minimize(avg_cost)
+    import paddle.fluid as fluid
+    main_prog = fluid.Program()
+    startup_prog = fluid.Program()
+    with fluid.program_guard(main_prog, startup_prog):
+        data = fluid.layers.data(name='image', shape=[3, 28, 28], dtype='float32')
+        label = fluid.layers.data(name='label', shape=[1], dtype='int64')
+        hidden = fluid.layers.fc(input=data, size=128, act='relu')
+        prediction = fluid.layers.fc(input=hidden, size=10, act='softmax')
+        loss = fluid.layers.cross_entropy(input=prediction, label=label)
+        avg_loss = fluid.layers.mean(loss)
+    optimizer = fluid.optimizer.Adagrad(
+        learning_rate=1e-4,
+        regularization=fluid.regularizer.L2DecayRegularizer(
+            regularization_coeff=0.1))
+    optimizer.minimize(avg_loss)