api modification (#769)

* api modification

half modification of fluid/io/layers

* Apply suggestions from code review
Co-Authored-By: Nzy0531 <48094155+zy0531@users.noreply.github.com>

* Update fluid_cn.rst

doc/fluid/api_cn/fluid_cn.rst

@@ -91,7 +91,7 @@ download_data是用于分布式训练的默认下载方法，用户可不使用
   - **local_path** （str） - 下载数据路径
   - **fs_default_name** （str） - 文件系统服务器地址
   - **ugi** （str） -  hadoop ugi
-  - **file_cn** （int） - 用户可以指定用于调试的文件号
+  - **file_cnt** （int） - 用户可以指定用于调试的文件号
   - **hadoop_home** （str） -  hadoop home path
   - **process_num** （int） - 下载进程号
 
@@ -188,8 +188,15 @@ str类型。在 ``ParallelExecutor`` 中，存在两种减少策略（reduce str
 
 .. py:attribute:: remove_unnecessary_lock
 
-BOOL类型。如果设置为True, GPU操作中的一些锁将被释放，ParallelExecutor将运行得更快，默认为 False。
+BOOL类型。如果设置为True, GPU操作中的一些锁将被释放，ParallelExecutor将运行得更快，默认为 True。
 
+.. py:attribute:: sync_batch_norm
+
+类型为bool，sync_batch_norm表示是否使用同步的批正则化，即在训练阶段通过多个设备同步均值和方差。
+
+当前的实现不支持FP16培训和CPU。仅在一台机器上进行同步式批正则，不适用于多台机器。
+
+默认为 False。
 
 
 .. _cn_api_fluid_CompiledProgram:
@@ -197,9 +204,9 @@ BOOL类型。如果设置为True, GPU操作中的一些锁将被释放，Paralle
 CompiledProgram
 -------------------------------
 
-.. py:class:: paddle.fluid.CompiledProgram(program)
+.. py:class:: paddle.fluid.CompiledProgram(program_or_graph)
 
-编译一个接着用来执行的Program。
+编译成一个用来执行的Graph。
 
 1. 首先使用layers(网络层)创建程序。
 2. （可选）可使用CompiledProgram来在运行之前优化程序。
@@ -226,9 +233,9 @@ CompiledProgram用于转换程序以进行各种优化。例如，
                                      fetch_list=[loss.name])
 
 参数：
-  - **program** : 一个Program对象，承载着用户定义的模型计算逻辑
+  - **program_or_graph** (Graph|Program): 如果它是Program，那么它将首先被降成一个graph，以便进一步优化。如果它是一个graph（以前可能优化过），它将直接用于进一步的优化。注意：只有使用 with_data_parallel 选项编译时才支持graph。
 
-.. py:method:: with_data_parallel(loss_name=None, build_strategy=None, exec_strategy=None, share_vars_from=None)
+.. py:method:: with_data_parallel(loss_name=None, build_strategy=None, exec_strategy=None, share_vars_from=None, places=None)
 
 配置Program使其以数据并行方式运行。
 
@@ -237,6 +244,7 @@ CompiledProgram用于转换程序以进行各种优化。例如，
   - **build_strategy** （BuildStrategy） -  build_strategy用于构建图，因此它可以在具有优化拓扑的多个设备/核上运行。 有关更多信息，请参阅  ``fluid.BuildStrategy`` 。 默认None。
   - **exec_strategy** （ExecutionStrategy） -  exec_strategy用于选择执行图的方式，例如使用多少线程，每次清理临时变量之前进行的迭代次数。 有关更多信息，请参阅 ``fluid.ExecutionStrategy`` 。 默认None。
   - **share_vars_from** （CompiledProgram） - 如果有，此CompiledProgram将共享来自share_vars_from的变量。 share_vars_from指定的Program必须由此CompiledProgram之前的Executor运行，以便vars准备就绪。
+  - **places** （list(CUDAPlace)|list(CPUPlace)|None） - 如果提供，则仅在给定位置编译程序。否则，编译时使用的位置由Executor确定，使用的位置由环境变量控制：如果使用GPU，则标记FLAGS_selected_gpus或CUDA_VISIBLE_DEVICES设备；如果使用CPU，则标记CPU_NUM。例如，如果要在GPU 0和GPU 1上运行，请设置places=[fluid.CUDAPlace(0), fluid.CUDAPlace(1)]。如果要在2个CPU核心上运行，请设置places=[fluid.CPUPlace()]*2。
 
 返回: self
 
@@ -394,6 +402,7 @@ cuda_places
 创建 ``fluid.CUDAPlace`` 对象列表。
 
 
+
 如果 ``device_ids`` 为None，则首先检查 ``FLAGS_selected_gpus`` 的环境变量。如果 ``FLAGS_selected_gpus=0,1,2`` ，则返回的列表将为[fluid.CUDAPlace(0), fluid.CUDAPlace(1), fluid.CUDAPlace(2)]。如果未设置标志 ``FLAGS_selected_gpus`` ，则将返回所有可见的GPU places。
 
 
@@ -437,6 +446,7 @@ CUDAPlace是一个设备描述符，它代表一个GPU，并且每个CUDAPlace
 
 
 
+
 .. _cn_api_fluid_DataFeedDesc:
 
 DataFeedDesc
@@ -669,7 +679,7 @@ reader通常返回一个minibatch条目列表。在列表中每一条目都是
 参数：
         - **reader** (fun) – 该参数是一个可以生成数据的函数
         - **multi_devices** (bool) – bool型，指明是否使用多个设备
-        - **num_places** (int) – 如果 ``multi_devices`` 为 ``True`` , 可以使用此参数来设置GPU数目。如果 ``num_places`` 为 ``None`` ，该函数默认使用当前训练机所有GPU设备。默认为None。
+        - **num_places** (int) – 如果 ``multi_devices`` 为 ``True`` , 可以使用此参数来设置GPU数目。如果 ``multi_devices`` 为 ``None`` ，该函数默认使用当前训练机所有GPU设备。默认为None。
         - **drop_last** (bool) – 如果最后一个batch的大小比 ``batch_size`` 要小，则可使用该参数来指明是否选择丢弃最后一个batch数据。 默认为 ``True`` 
 
 返回：转换结果
@@ -979,7 +989,7 @@ Executor
 
 
 
-执行引擎（Executor）使用python脚本驱动，仅支持在单GPU环境下运行。多卡环境下请参考 ``ParallelExecutor`` 。
+执行引擎（Executor）使用python脚本驱动，支持在单/多GPU、单/多CPU环境下运行。
 Python Executor可以接收传入的program,并根据feed map(输入映射表)和fetch_list(结果获取表)
 向program中添加feed operators(数据输入算子)和fetch operators（结果获取算子)。
 feed map为该program提供输入数据。fetch_list提供program训练结束后用户预期的变量（或识别类场景中的命名）。
@@ -990,7 +1000,6 @@ Executor将全局变量存储到全局作用域中，并为临时变量创建局
 当每一mini-batch上的前向/反向运算完成后，局部作用域的内容将被废弃，
 但全局作用域中的变量将在Executor的不同执行过程中一直存在。
 
-program中所有的算子会按顺序执行。
 
 **示例代码**
 
@@ -1023,13 +1032,12 @@ program中所有的算子会按顺序执行。
 
 
 
-提示：你可以用 ``Executor`` 来调试基于并行GPU实现的复杂网络，他们有完全一样的参数也会产生相同的结果。
-
-
 .. py:method:: close()
 
 
-关闭这个执行器(Executor)。调用这个方法后不可以再使用这个执行器。 对于分布式训练, 该函数会释放在PServers上涉及到目前训练器的资源。
+关闭这个执行器(Executor)。
+
+调用这个方法后不可以再使用这个执行器。 对于分布式训练, 该函数会释放在PServers上和目前Trainer有关联的资源。
    
 **示例代码**
 
@@ -1054,12 +1062,12 @@ feed map为该program提供输入数据。fetch_list提供program训练结束后
 参数：  
 	- **program** (Program|CompiledProgram) – 需要执行的program,如果没有给定那么默认使用default_main_program (未编译的)
 	- **feed** (dict) – 前向输入的变量，数据,词典dict类型, 例如 {“image”: ImageData, “label”: LabelData}
-	- **fetch_list** (list) – 用户想得到的变量或者命名的列表, run会根据这个列表给与结果
+	- **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) – 当program较上次比没有改动则将其置为True
+	- **use_program_cache** (bool) – 是否跨批使用缓存程序设置。设置为True时，只有当（1）程序没有用数据并行编译，并且（2）program、 feed变量名和fetch_list变量名与上一步相比没有更改时，运行速度才会更快。
 	
 返回:	根据fetch_list来获取结果
 

doc/fluid/api_cn/io_cn.rst

@@ -289,8 +289,6 @@ PyReader
   - **reader** (generator)  – 返回LoDTensor类型的批处理数据的Python生成器
   - **places** (None|list(CUDAPlace)|list(CPUPlace)) –  位置列表。当PyReader可迭代时必须被提供
 
-
-
 .. _cn_api_fluid_io_save_inference_model:
 
 save_inference_model
@@ -313,7 +311,9 @@ save_inference_model
   - **params_filename** (str|None) – 保存所有相关参数的文件名称。如果设置为None，则参数将保存在单独的文件中。
   - **export_for_deployment** (bool) – 如果为真，Program将被修改为只支持直接预测部署的Program。否则，将存储更多的信息，方便优化和再训练。目前只支持True。
 
-返回: None
+返回: 获取的变量名列表
+
+返回类型：target_var_name_list(list)
 
 抛出异常：
  - ``ValueError`` – 如果 ``feed_var_names`` 不是字符串列表
@@ -406,8 +406,9 @@ save_persistables
     exe = fluid.Executor(fluid.CPUPlace())
     param_path = "./my_paddle_model"
     prog = fluid.default_main_program()
+    # `prog` 可以是由用户自定义的program
     fluid.io.save_persistables(executor=exe, dirname=param_path,
-                               main_program=None)
+                               main_program=prog)
     
     
 

doc/fluid/api_cn/layers_cn.rst

@@ -205,12 +205,13 @@ memory用于缓存分段数据。memory的初始值可以是零，也可以是
 .. note::
     目前不支持在DynamicRNN中任何层上配置 is_sparse = True
 
-.. py:method:: step_input(x)
+.. py:method:: step_input(x, level=0)
 
     将序列标记为动态RNN输入。
 
 参数:
     	- **x** (Variable) - 输入序列
+        - **level** (int) - 用于拆分步骤的LOD层级，默认值0
 	
     	
 返回:当前的输入序列中的timestep。
@@ -1087,8 +1088,7 @@ py_reader
 	    except fluid.core.EOFException:
 		reader.reset()
 
-
-
+    fluid.io.save_inference_model(dirname='./model', feeded_var_names=[img, label],target_vars=[loss], executor=fluid.Executor(fluid.CUDAPlace(0)))
 
 
 2.训练和测试应使用不同的名称创建两个不同的py_reader，例如：
@@ -1483,7 +1483,7 @@ add_position_encoding
 affine_channel
 -------------------------------
 
-.. py:function:: paddle.fluid.layers.affine_channel(x, scale=None, bias=None, data_layout='NCHW', name=None)
+.. py:function:: paddle.fluid.layers.affine_channel(x, scale=None, bias=None, data_layout='NCHW', name=None,act=None)
 
 对输入的每个 channel 应用单独的仿射变换。用于将空间批处理范数替换为其等价的固定变换。
 
@@ -1495,6 +1495,7 @@ affine_channel
 	- **bias** (Variable):形状为(C)的一维输入，第C个元素是输入的第C个通道的仿射变换的偏置。
 	- **data_layout** (string, default NCHW): NCHW 或 NHWC，如果输入是一个2D张量，可以忽略该参数
 	- **name** (str, default None): 此层的名称
+        - **act** (str, default None): 应用于该层输出的激活函数
 
 返回： out (Variable): 与x具有相同形状和数据布局的张量。
 
@@ -1680,11 +1681,11 @@ batch_norm
 
 
 参数：
-    - **input** (Variable) - 输入变量，为LoDTensor
+    - **input** (Variable) - 输入变量的排序，可以为 2, 3, 4, 5
     - **act** （string，默认None）- 激活函数类型，linear|relu|prelu|...
-    - **is_test** （bool,默认False） - 标志位，是否用于测试或训练
-    - **momentum** （float，默认0.9）- （暂无说明，待更新）
-    - **epsilon** （float，默认1e-05）- （暂无说明，待更新）
+    - **is_test** （bool,默认False） - 指示它是否在测试阶段。
+    - **momentum** （float，默认0.9）- 此值用于计算 moving_mean and moving_var. 更新公式为:  :math:`\(moving\_mean = moving\_mean * momentum + new\_mean * (1. - momentum)\)` :math:`\(moving\_var = moving\_var * momentum + new\_var * (1. - momentum)\)` ， 默认值0.9.
+    - **epsilon** （float，默认1e-05）- 加在分母上为了数值稳定的值。默认值为1e-5。
     - **param_attr** （ParamAttr|None） - batch_norm参数范围的属性，如果设为None或者是ParamAttr的一个属性，batch_norm创建ParamAttr为param_attr。如果没有设置param_attr的初始化函数，参数初始化为Xavier。默认：None
     - **bias_attr** （ParamAttr|None） - batch_norm bias参数的属性，如果设为None或者是ParamAttr的一个属性，batch_norm创建ParamAttr为bias_attr。如果没有设置bias_attr的初始化函数，参数初始化为0。默认：None
     - **data_layout** （string,默认NCHW) - NCHW|NHWC
@@ -2763,7 +2764,7 @@ ctc_greedy_decoder
 data_norm
 -------------------------------
 
-.. py:function:: paddle.fluid.layers.data_norm(input, act=None, epsilon=1e-05, param_attr=None, data_layout='NCHW', in_place=False, use_mkldnn=False, name=None, moving_mean_name=None, moving_variance_name=None, do_model_average_for_mean_and_var=False)
+.. py:function:: paddle.fluid.layers.data_norm(input, act=None, epsilon=1e-05, param_attr=None, data_layout='NCHW', in_place=False, name=None, moving_mean_name=None, moving_variance_name=None, do_model_average_for_mean_and_var=False)
 
 **数据正则化层**
     
@@ -2790,7 +2791,6 @@ data_norm
   - **param_attr** （ParamAttr） - 参数比例的参数属性。
   - **data_layout** （string，默认NCHW） -  NCHW | NHWC
   - **in_place** （bool，默认值False） - 使data_norm的输入和输出复用同一块内存。
-  - **use_mkldnn** （bool，默认为false） -  是否使用mkldnn
   - **name** （string，默认None） - 此层的名称（可选）。 如果设置为None，则将自动命名该层。
   - **moving_mean_name** （string，Default None） - 存储全局Mean的moving_mean的名称。
   - **moving_variance_name** （string，默认None） - 存储全局Variance的moving_variance的名称。
@@ -2884,7 +2884,7 @@ dropout op可以从Program中删除，提高执行效率。
 
          - train: out = input * mask 
 
-         - inference: out = input * dropout_prob 
+         - inference: out = input * (1.0 - dropout_prob) 
 
          (mask是一个张量，维度和输入维度相同，值为0或1，值为0的比例即为 ``dropout_prob`` )
         
@@ -3111,7 +3111,7 @@ W 代表了权重矩阵(weight matrix)，例如 :math:`W_{xi}` 是从输入门
 
 dynamic_lstmp
 -------------------------------
-.. py:function:: paddle.fluid.layers.dynamic_lstmp(input, size, proj_size, param_attr=None, bias_attr=None, use_peepholes=True, is_reverse=False, gate_activation='sigmoid', cell_activation='tanh', candidate_activation='tanh', proj_activation='tanh', dtype='float32', name=None)
+.. py:function:: paddle.fluid.layers.dynamic_lstmp(input, size, proj_size, param_attr=None, bias_attr=None, use_peepholes=True, is_reverse=False, gate_activation='sigmoid', cell_activation='tanh', candidate_activation='tanh', proj_activation='tanh', dtype='float32', name=None, h_0=None, c_0=None, cell_clip=None, proj_clip=None)
 
 动态LSTMP层(Dynamic LSTMP Layer)
 
@@ -3180,6 +3180,15 @@ LSTMP层(具有循环映射的LSTM)在LSTM层后有一个分离的映射层，
     - **proj_activation** (str) - 投影输出的激活函数。Choices = [“sigmoid”，“tanh”，“relu”，“identity”]，默认“tanh”。
     - **dtype** (str) - 数据类型。Choices = [“float32”，“float64”]，默认“float32”。
     - **name** (str|None) - 该层名称（可选）。若设为None，则自动为该层命名。
+    - **h_0** (Variable) - 初始隐藏状态是可选输入，默认为0。这是一个具有形状的张量(N x D)，其中N是批大小，D是投影大小。 
+    - **c_0** (Variable) - 初始cell状态是可选输入，默认为0。这是一个具有形状(N x D)的张量，其中N是批大小。h_0和c_0可以为空，但只能同时为空。
+    - **cell_clip** (float) - 如果提供该参数，则在单元输出激活之前，单元状态将被此值剪裁。 
+    - **proj_clip** (float) - 如果 num_proj > 0 并且 proj_clip 被提供,那么将投影值沿元素方向剪切到[-proj_clip，proj_clip]内
+
+
+
+
+
 
 返回：含有两个输出变量的元组，隐藏状态（hidden state）的投影和LSTMP的cell状态。投影的shape为（T*P），cell state的shape为（T*D），两者的LoD和输入相同。
 
@@ -3793,9 +3802,17 @@ fc
 
 **全连接层**
 
-该函数在神经网络中建立一个全连接层。 它可以同时将多个tensor（ ``input`` 可使用多个tensor组成的一个list，详见参数说明）作为自己的输入，并为每个输入的tensor创立一个变量，称为“权”（weights），等价于一个从每个输入单元到每个输出单元的全连接权矩阵。FC层用每个tensor和它对应的权相乘得到输出tensor。如果有多个输入tensor，那么多个乘法运算将会加在一起得出最终结果。如果 ``bias_attr`` 非空，则会新创建一个偏向变量（bias variable），并把它加入到输出结果的运算中。最后，如果 ``act`` 非空，它也会加入最终输出的计算中。
+该函数在神经网络中建立一个全连接层。 它可以将一个或多个tensor（ ``input`` 可以是一个list或者Variable，详见参数说明）作为自己的输入，并为每个输入的tensor创立一个变量，称为“权”（weights），等价于一个从每个输入单元到每个输出单元的全连接权矩阵。FC层用每个tensor和它对应的权相乘得到形状为[M, size]输出tensor，M是批大小。如果有多个输入tensor，那么形状为[M, size]的多个输出张量的结果将会被加起来。如果 ``bias_attr`` 非空，则会新创建一个偏向变量（bias variable），并把它加入到输出结果的运算中。最后，如果 ``act`` 非空，它也会加入最终输出的计算中。
 
-这个过程可以通过如下公式表现：
+当输入为单个张量：
+
+.. math::
+
+        \\Out = Act({XW + b})\\
+
+
+
+当输入为多个张量：
 
 .. math::
 
@@ -3803,13 +3820,29 @@ fc
 
 
 上述等式中：
-  - :math:`N` ：输入tensor的数目
-  - :math:`X_i` : 输入的tensor
-  - :math:`W` ：该层创立的权
+  - :math:`N` ：输入的数目,如果输入是变量列表，N等于len（input）
+  - :math:`X_i` : 第i个输入的tensor
+  - :math:`W_i` ：对应第i个输入张量的第i个权重矩阵
   - :math:`b` ：该层创立的bias参数
   - :math:`Act` : activation function(激励函数)
   - :math:`Out` : 输出tensor
 
+::
+
+            Given:
+                data_1.data = [[[0.1, 0.2],
+                               [0.3, 0.4]]]
+                data_1.shape = (1, 2, 2) # 1 is batch_size
+         
+                data_2 = [[[0.1, 0.2, 0.3]]]
+                data_2.shape = (1, 1, 3)
+         
+                out = fluid.layers.fc(input=[data_1, data_2], size=2)
+         
+            Then:
+                out.data = [[0.18669507, 0.1893476]]
+                out.shape = (1, 2)
+
 
 参数:
   - **input** (Variable|list of Variable) – 该层的输入tensor(s)（张量），其维度至少是2
@@ -3832,9 +3865,15 @@ fc
 
 ..  code-block:: python
 
+         # 当输入为单个张量时
+
         data = fluid.layers.data(name="data", shape=[32, 32], dtype="float32")
         fc = fluid.layers.fc(input=data, size=1000, act="tanh")
 
+        # 当输入为多个张量时
+        data_1 = fluid.layers.data(name="data_1", shape=[32, 32], dtype="float32")
+        data_2 = fluid.layers.data(name="data_2", shape=[24, 36], dtype="float32")
+        fc = fluid.layers.fc(input=[data_1, data_2], size=1000, act="tanh")