Merge branch 'develop' of https://github.com/PaddlePaddle/FluidDoc into add-models_io_doc

6c0f21d2 · Zhen Wang · 2c83c8dd · 3aa36c44 · 6c0f21d2 · 6c0f21d2
10 changed file
--- a/doc/fluid/api/api_guides/low_level/executor.rst
+++ b/doc/fluid/api/api_guides/low_level/executor.rst
+..  _api_guide_executor:
+
+########
+Executor
+########
+
+:code:`Executor` 即 :code:`执行器` 。PaddlePaddle Fluid中有两种执行器可以选择。
+:code:`Executor` 实现了一个简易的执行器，所有Operator会被顺序执行。用户可以使用
+Python脚本驱动 :code:`Executor` 执行。默认情况下 :code:`Executor` 是单线程的，如果
+想使用数据并行，请参考另一个执行器， :ref:`api_guide_parallel_executor` 。
+
+:code:`Executor` 的代码逻辑非常简单。建议用户在调试过程中，先使用
+:code:`Executor` 跑通模型，再切换到多设备计算，甚至多机计算。
+
+:code:`Executor` 在构造的时候接受一个 :code:`Place`， 它们可以是 :ref:`api_fluid_CPUPlace`
+或 :ref:`api_fluid_CUDAPlace` 。 :code:`Executor` 在执行的时候可以选择执行的
+:ref:`api_guide_low_level_program` 。
+
+简单的使用方法，请参考 `quick_start_fit_a_line <../../beginners_guide/quick_start/fit_a_line/README.cn.html>`_ , API Reference 请参考
+:ref:`api_fluid_Executor` 。
--- a/doc/fluid/api/api_guides/low_level/layers/control_flow.rst
+++ b/doc/fluid/api/api_guides/low_level/layers/control_flow.rst
+.. api_guide_control_flow:
+
+######
+控制流
+######
+
+在程序语言中，控制流(control flow)决定了语句的执行顺序，常见的控制流包括顺序执行、分支和循环等。PaddlePaddle Fluid继承了这一概念，提供了多种控制流API, 以控制深度学习模型在训练或者预测过程中的执行逻辑。
+
+IfElse
+======
+
+条件分支，允许对同一个batch的输入，根据给定的条件，分别选择 :code:`true_block` 或 :code:`false_block` 中的逻辑进行执行，执行完成之后再将两个分支的输出合并为同一个输出。通常，条件表达式可由 :ref:`api_fluid_layers_less_than`, :ref:`api_fluid_layers_equal` 等逻辑比较 API 产生。
+
+请参考 :ref:`api_fluid_layers_IfElse`            
+
+
+Switch
+======
+
+多分支选择结构，如同程序语言中常见的 :code:`switch-case` 声明, 其根据输入表达式的取值不同，选择不同的分支执行。具体来说，Fluid 所定义的 :code:`Switch` 控制流有如下特性：
+
+* case的条件是个bool类型的值，即在Program中是一个张量类型的Variable；
+* 依次检查逐个case，选择第一个满足条件的case执行，完成执行后即退出所属的block；
+* 如果所有case均不满足条件，会选择默认的case进行执行。
+
+请参考 :ref:`api_fluid_layers_Switch`
+
+While
+=====
+
+While 循环，当条件判断为真时，循环执行 :code:`While` 控制流所属 :code:`block` 内的逻辑，条件判断为假时退出循环。与之相关的API有
+
+* :ref:`api_fluid_layers_increment` ：累加API，通常用于对循环次数进行计数；
+* :ref:`api_fluid_layers_array_read` ：从 :code:`LOD_TENSOR_ARRAY` 中指定的位置读入Variable，进行计算；
+* :ref:`api_fluid_layers_array_write` ：将 Variable 写回到 :code:`LOD_TENSOR_ARRAY` 指定的位置，存储计算结果。
+
+请参考 :ref:`api_fluid_layers_While`
+
+DynamicRNN
+==========
+
+即动态RNN，可处理一个batch不等长的序列数据，其接受 :code:`lod_level=1` 的 Variable 作为输入，在 :code:`DynamicRNN` 的 :code:`block` 内，用户需自定义RNN的单步计算逻辑。在每一个时间步，用户可将需记忆的状态写入到 :code:`DynamicRNN` 的 :code:`memory` 中，并将需要的输出写出到其 :code:`output` 中。
+
+:ref:`api_fluid_layers_sequence_last_step` 可获取 :code:`DynamicRNN` 最后一个时间步的输出。
+
+请参考 :ref:`api_fluid_layers_DynamicRNN`
+
+StaticRNN
+=========
+
+即静态RNN，只能处理固定长度的序列数据，接受 :code:`lod_level=0` 的 Variable 作为输入。与 :code:`DynamicRNN` 类似，在RNN的每单个时间步，用户需自定义计算逻辑，并可将状态和输出写出。
+
+请参考 :ref:`api_fluid_layers_StaticRNN`
--- a/doc/fluid/api/api_guides/low_level/layers/conv.rst
+++ b/doc/fluid/api/api_guides/low_level/layers/conv.rst
+.. _api_guide_conv:
+
+#####
+卷积
+#####
+
+卷积有两组输入：特征图和卷积核，依据输入特征和卷积核的形状、Layout不同、计算方式的不同，在Fluid里，有针对变长序列特征的一维卷积，有针对定长图像特征的二维(2D Conv)、三维卷积(3D Conv)，同时也有卷积计算的逆向过程，下面先介绍Fluid里的2D/3D卷积，再来介绍序列卷积。
+
+
+2D/3D卷积
+==============
+
+1. 卷积输入参数：
+---------------------
+
+卷积需要依据滑动步长(stride)、填充长度(padding)、卷积核窗口大小(filter size)、分组数(groups)、扩张系数(dilation rate)来决定如何计算。groups最早在 `AlexNet <https://www.nvidia.cn/content/tesla/pdf/machine-learning/imagenet-classification-with-deep-convolutional-nn.pdf>`_ 中引入, 可以理解为将原始的卷积分为独立若干组卷积计算。
+  
+  **注意**: 同cuDNN的方式，Fluid目前只支持在特征图上下填充相同的长度，左右也是。
+
+- 输入输出Layout: 
+
+  2D卷积输入特征的Layout为[N, C, H, W]或[N, H, W, C], N即batch size，C是通道数，H、W是特征的高度和宽度，输出特征和输入特征的Layout一致。(相应的3D卷积输入特征的Layout为[N, C, D, H, W]或[N, D, H, W, C]，但**注意**，Fluid的卷积当前只支持[N, C, H, W]，[N, C, D, H, W]。)
+   
+- 卷积核的Layout: 
+  
+  Fluid中2D卷积的卷积核(也称权重)的Layout为[C_o, C_in / groups, f_h, f_w]，C_o、C_in表示输出、输入通道数，f_h、f_w表示卷积核窗口的高度和宽度，按行序存储。(相应的2D卷积的卷积核Layout为[C_o, C_in / groups, f_d, f_h, d_w]，同样按行序存储。)
+  
+- 深度可分离卷积(depthwise separable convolution): 
+   
+  在深度可分离卷积中包括depthwise convolution和pointwise convolution两组，这两个卷积的接口和上述普通卷积接口相同。前者可以通过给普通卷积设置groups来做，后者通过设置卷积核filters的大小为1x1，深度可分离卷积减少参数的同时减少了计算量。
+  
+  对于depthwise convolution，可以设置groups等于输入通道数，此时，2D卷积的卷积核形状为[C_o, 1, f_h, f_w]。
+  对于pointwise convolution，卷积核的形状为[C_o, C_in, 1, 1]。
+  
+  **注意**：Fluid针对depthwise convolution的GPU计算做了高度优化，您可以通过在:code:`fluid.layers.conv2d`接口设置:code:`use_cudnn=False`来使用Fluid自身优化的CUDA程序。
+   
+- 空洞卷积(dilated convolution):
+  
+  空洞卷积相比普通卷积而言，卷积核在特征图上取值时不在连续，而是间隔的，这个间隔数称作dilation，等于1时，即为普通卷积，空洞卷积相比普通卷积的感受野更大。
+  
+- API汇总:
+ - :ref:`api_fluid_layers_conv2d`
+ - :ref:`api_fluid_layers_conv3d`
+ - :ref:`api_fluid_layers_conv2d_transpose`
+ - :ref:`api_fluid_layers_conv3d_transpose`
+
+
+1D序列卷积
+==============
+
+Fluid可以表示变长的序列结构，这里的变长是指不同样本的时间步(step)数不一样，通常是一个2D的Tensor和一个能够区分的样本长度的辅助结构来表示。假定，2D的Tensor的形状是shape，shape[0]是所有样本的总时间步数，shape[1]是序列特征的大小。
+
+基于此数据结构的卷积在Fluid里称作序列卷积，也表示一维卷积。同图像卷积，序列卷积的输入参数有卷积核大小、填充大小、滑动步长，但与2D卷积不同的是，这些参数个数都为1。**注意**，目前仅支持stride为1的情况，输出序列的时间步数和输入序列相同。 
+
+假如：输入序列形状为(T, N)， T即该序列的时间步数，N是序列特征大小；卷积核的上下文步长为K，输出序列长度为M，则卷积核权重形状为(K * N, M），输出序列形状为(T, M)。
+  
+另外，参考DeepSpeech，Fluid实现了行卷积row convolution, 或称
+`look ahead convolution <http://www.cs.cmu.edu/~dyogatam/papers/wang+etal.iclrworkshop2016.pdf>`_ ，
+该卷积相比上述普通序列卷积可以减少参数。
+ 
+
+- API汇总:
+ - :ref:`api_fluid_layers_sequence_conv`
+ - :ref:`api_fluid_layers_row_conv`
--- a/doc/fluid/api/api_guides/low_level/layers/data_in_out.rst
+++ b/doc/fluid/api/api_guides/low_level/layers/data_in_out.rst
+..  _api_guide_data_in_out:
+
+数据输入
+##################
+
+Fluid支持两种数据输入方式，包括：
+
+1. Python Reader: 纯Python的Reader。用户在Python端定义 :code:`fluid.layers.data` 层构建网络，并通过
+:code:`executor.run(feed=...)` 的方式读入数据。数据读取和模型训练/预测的过程是同步进行的。
+
+2. PyReader: 高效灵活的C++ Reader接口。PyReader内部维护容量为 :code:`capacity` 的队列（队列容量由
+:code:`fluid.layers.py_reader` 接口中的 :code:`capacity` 参数设置），Python端调用队列的 :code:`push`
+方法送入训练/预测数据，C++端的训练/预测程序调用队列的 :code:`pop` 方法取出Python端送入的数据。PyReader可与
+:code:`double_buffer` 配合使用，实现数据读取和训练/预测的异步执行。
+
+具体使用方法请参考 :ref:`user_guide_use_py_reader`。
+
+数据输出
+##################
+
+Fluid支持在训练/预测阶段获取当前batch的数据。
+
+用户可通过 :code:`executor.run(fetch_list=[...], return_numpy=...)` 的方式
+fetch期望的输出变量，通过设置 :code:`return_numpy` 参数设置是否将输出数据转为numpy array。
+若 :code:`return_numpy` 为 :code:`False` ，则返回 :code:`LoDTensor` 类型数据。
+
+具体使用方式请参考相关API文档 :ref:`api_fluid_executor_Executor` 和
+:ref:`api_fluid_ParallelExecutor`。
\ No newline at end of file
--- a/doc/fluid/api/api_guides/low_level/layers/index.rst
+++ b/doc/fluid/api/api_guides/low_level/layers/index.rst
+=============
+fluid.layers
+=============
+
+..  toctree::
+    :maxdepth: 1
+    
\ No newline at end of file
--- a/doc/fluid/api/api_guides/low_level/layers/loss_function.rst
+++ b/doc/fluid/api/api_guides/low_level/layers/loss_function.rst
+..  _api_guide_loss_function:
+
+#######
+损失函数
+#######
+
+损失函数定义了拟合结果和真实结果之间的差异，作为优化的目标直接关系模型训练的好坏，很多研究工作的内容也集中在损失函数的设计优化上。
+Paddle Fluid 中提供了面向多种任务的多种类型的损失函数，以下列出了一些 Paddle Fluid 中包含的较为常用的损失函数。
+
+回归
+====
+
+平方误差损失（squared error loss）使用预测值和真实值之间误差的平方作为样本损失，是回归问题中最为基本的损失函数。
+API Reference 请参考 :ref:`api_fluid_layers_square_error_cost`。
+
+平滑 L1 损失（smooth_l1 loss）是一种分段的损失函数，较平方误差损失其对异常点相对不敏感，因而更为鲁棒。
+API Reference 请参考 :ref:`api_fluid_layers_smooth_l1`。
+
+
+分类
+====
+
+`交叉熵（cross entropy） <https://en.wikipedia.org/wiki/Cross_entropy>`_ 是分类问题中使用最为广泛的损失函数，Paddle Fluid 中提供了接受归一化概率值和非归一化分值输入的两种交叉熵损失函数的接口，并支持 soft label 和 hard label 两种样本类别标签。
+API Reference 请参考 :ref:`api_fluid_layers_cross_entropy` 和 :ref:`api_fluid_layers_softmax_with_cross_entropy`。
+
+多标签分类
+---------
+对于多标签分类问题，如一篇文章同属于政治、科技等多个类别的情况，需要将各类别作为独立的二分类问题计算损失，Paddle Fluid 中为此提供了 sigmoid_cross_entropy_with_logits 损失函数，
+API Reference 请参考 :ref:`api_fluid_layers_sigmoid_cross_entropy_with_logits`。
+
+大规模分类
+---------
+对于大规模分类问题，通常需要特殊的方法及相应的损失函数以加速训练，常用的方法有 `噪声对比估计（Noise-contrastive estimation，NCE） <http://proceedings.mlr.press/v9/gutmann10a/gutmann10a.pdf>`_ 和 `层级 sigmoid <http://www.iro.umontreal.ca/~lisa/pointeurs/hierarchical-nnlm-aistats05.pdf>`_ 。
+
+* 噪声对比估计通过将多分类问题转化为学习分类器来判别数据来自真实分布和噪声分布的二分类问题，基于二分类来进行极大似然估计，避免在全类别空间计算归一化因子从而降低了计算复杂度。
+* 层级 sigmoid 通过二叉树进行层级的二分类来实现多分类，每个样本的损失对应了编码路径上各节点二分类交叉熵的和，避免了归一化因子的计算从而降低了计算复杂度。
+这两种方法对应的损失函数在 Paddle Fluid 中均有提供，API Reference 请参考 :ref:`api_fluid_layers_nce` 和 :ref:`api_fluid_layers_hsigmoid`。
+
+序列分类
+-------
+序列分类可以分为以下三种：
+
+* 序列分类（Sequence Classification）问题，整个序列对应一个预测标签，如文本分类。这种即是普通的分类问题，可以使用 cross entropy 作为损失函数。
+* 序列片段分类（Segment Classification）问题，序列中的各个片段对应有自己的类别标签，如命名实体识别。对于这种序列标注问题，`（线性链）条件随机场（Conditional Random Field，CRF） <http://www.cs.columbia.edu/~mcollins/fb.pdf>`_ 是一种常用的模型方法，其使用句子级别的似然概率，序列中不同位置的标签不再是条件独立，能够有效解决标记偏置问题。Paddle Fluid 中提供了 CRF 对应损失函数的支持，API Reference 请参考 :ref:`api_fluid_layers_linear_chain_crf`。
+* 时序分类（Temporal Classification）问题，需要对未分割的序列进行标注，如语音识别。对于这种时序分类问题，`CTC（Connectionist Temporal Classification） <http://people.idsia.ch/~santiago/papers/icml2006.pdf>`_ 损失函数不需要对齐输入数据及标签，可以进行端到端的训练，Paddle Fluid 提供了 warpctc 的接口来计算相应的损失，API Reference 请参考 :ref:`api_fluid_layers_warpctc`。
+
+排序
+====
+
+`排序问题 <https://en.wikipedia.org/wiki/Learning_to_rank>`_ 可以使用 Pointwise、Pairwise 和 Listwise 的学习方法，不同的方法需要使用不同的损失函数：
+
+* Pointwise 的方法通过近似为回归问题解决排序问题，可以使用回归问题的损失函数。
+* Pairwise 的方法需要特殊设计的损失函数，其通过近似为分类问题解决排序问题，使用两篇文档与 query 的相关性得分以偏序作为二分类标签来计算损失。Paddle Fluid 中提供了两种常用的 Pairwise 方法的损失函数，API Reference 请参考 :ref:`api_fluid_layers_rank_loss` 和 :ref:`api_fluid_layers_margin_rank_loss`。
+
+更多
+====
+
+对于一些较为复杂的损失函数，可以尝试使用其他损失函数组合实现；Paddle Fluid 中提供的用于图像分割任务的 :ref:`api_fluid_layers_dice_loss` 即是使用其他 OP 组合（计算各像素位置似然概率的均值）而成；多目标损失函数也可看作这样的情况，如 Faster RCNN 就使用 cross entropy 和 smooth_l1 loss 的加权和作为损失函数。
+
+**注意**，在定义损失函数之后为能够使用 :ref:`api_guide_optimizer` 进行优化，通常需要使用 :ref:`api_fluid_layers_mean` 或其他操作将损失函数返回的高维 Tensor 转换为 Scalar 值。
\ No newline at end of file
--- a/doc/fluid/api/api_guides/low_level/optimizer/optimizer_all.rst
+++ b/doc/fluid/api/api_guides/low_level/optimizer/optimizer_all.rst
@@ -14,9 +14,8 @@ Optimizer
 :code:`SGD` 是实现 `随机梯度下降 <https://arxiv.org/pdf/1609.04747.pdf>`_ 的一个 :code:`Optimizer` 子类，是 `梯度下降 <https://zh.wikipedia.org/zh-hans/梯度下降法>`_ 大类中的一种方法。
 当需要训练大量样本的时候，往往选择 :code:`SGD` 来使损失函数更快的收敛。  

-API Reference 请参考 api_fluid_optimizer_SGDOptimizer_
+API Reference 请参考 :ref:`api_fluid_optimizer_SGDOptimizer`

-.. _api_fluid_optimizer_SGDOptimizer: http://www.paddlepaddle.org/docs/0.14.0/api/fluid/en/optimizer.html#permalink-8-sgdoptimizer

 2.Momentum/MomentumOptimizer
 ----------------------------
@@ -26,35 +25,32 @@ API Reference 请参考 api_fluid_optimizer_SGDOptimizer_
 <https://arxiv.org/pdf/1609.04747.pdf>`_  算法和 `Nesterov accelerated gradient(论文4.2节)
 <https://arxiv.org/pdf/1609.04747.pdf>`_ 算法。

-API Reference 请参考 api_fluid_optimizer_MomentumOptimizer_
+API Reference 请参考 :ref:`api_fluid_optimizer_MomentumOptimizer`

-.. _api_fluid_optimizer_MomentumOptimizer: http://www.paddlepaddle.org/docs/0.14.0/api/fluid/en/optimizer.html#permalink-9-momentumoptimizer

 3. Adagrad/AdagradOptimizer
 ---------------------------
 `Adagrad <http://www.jmlr.org/papers/volume12/duchi11a/duchi11a.pdf>`_ 优化器可以针对不同参数样本数不平均的问题，自适应地为各个参数分配不同的学习率。

-API Reference 请参考 api_fluid_optimizer_AdagradOptimizer_
+API Reference 请参考 :ref:`api_fluid_optimizer_AdagradOptimizer`

-.. _api_fluid_optimizer_AdagradOptimizer: http://www.paddlepaddle.org/docs/0.14.0/api/fluid/en/optimizer.html#permalink-10-adagradoptimizer

 4.RMSPropOptimizer
 ------------------
 `RMSProp优化器 <http://www.cs.toronto.edu/~tijmen/csc321/slides/lecture_slides_lec6.pdf>`_ ，是一种自适应调整学习率的方法，
 主要解决使用Adagrad后，模型训练中后期学习率急剧下降的问题。

-API Reference 请参考 api_fluid_optimizer_RMSPropOptimizer_
+API Reference 请参考 :ref:`api_fluid_optimizer_RMSPropOptimizer`
+

-.. _api_fluid_optimizer_RMSPropOptimizer: http://www.paddlepaddle.org/docs/0.14.0/api/fluid/en/optimizer.html#permalink-14-rmspropoptimizer

 5.Adam/AdamOptimizer
 --------------------
 `Adam <https://arxiv.org/abs/1412.6980>`_ 的优化器是一种自适应调整学习率的方法，
 适用于大多非 `凸优化 <https://zh.wikipedia.org/zh/凸優化>`_ 、大数据集和高维空间的场景。在实际应用中，:code:`Adam` 是最为常用的一种优化方法。

-API Reference 请参考 api_fluid_optimizer_AdamOptimizer_
+API Reference 请参考 :ref:`api_fluid_optimizer_AdamOptimizer`

-.. _api_fluid_optimizer_AdamOptimizer: http://www.paddlepaddle.org/docs/0.14.0/api/fluid/en/optimizer.html#permalink-11-adamoptimizer


 6.Adamax/AdamaxOptimizer
@@ -62,9 +58,8 @@ API Reference 请参考 api_fluid_optimizer_AdamOptimizer_

 `Adamax <https://arxiv.org/abs/1412.6980>`_ 是 :code:`Adam` 算法的一个变体，对学习率的上限提供了一个更简单的范围，使学习率的边界范围更简单。

-API Reference 请参考 api_fluid_optimizer_AdamxOptimizer_
+API Reference 请参考 :ref:`api_fluid_optimizer_AdamaxOptimizer`

-.. _api_fluid_optimizer_AdamxOptimizer: http://www.paddlepaddle.org/docs/0.14.0/api/fluid/en/optimizer.html#permalink-12-adamaxoptimizer


 7.DecayedAdagrad/ DecayedAdagradOptimizer
@@ -72,9 +67,9 @@ API Reference 请参考 api_fluid_optimizer_AdamxOptimizer_

 `DecayedAdagrad <http://www.jmlr.org/papers/volume12/duchi11a/duchi11a.pdf>`_ 优化器，可以看做是引入了衰减速率的 :code:`Adagrad` 算法，解决使用Adagrad后，模型训练中后期学习率急剧下降的问题。

-API Reference 请参考 api_fluid_optimizer_DecayedAdagrad_
+API Reference 请参考 :ref:`api_fluid_optimizer_DecayedAdagrad`
+

-.. _api_fluid_optimizer_DecayedAdagrad: http://www.paddlepaddle.org/docs/0.14.0/api/fluid/en/optimizer.html#permalink-13-decayedadagradoptimizer


 8. Ftrl/FtrlOptimizer
@@ -83,24 +78,15 @@ API Reference 请参考 api_fluid_optimizer_DecayedAdagrad_
 `FtrlOptimizer <https://www.eecs.tufts.edu/~dsculley/papers/ad-click-prediction.pdf>`_ 优化器结合了 `FOBOS算法 <https://stanford.edu/~jduchi/projects/DuchiSi09b.pdf>`_ 的高精度与 `RDA算法
 <http://www1.se.cuhk.edu.hk/~sqma/SEEM5121_Spring2015/dual-averaging.pdf>`_ 的稀疏性，是目前效果非常好的一种 `Online Learning <https://en.wikipedia.org/wiki/Online_machine_learning>`_ 算法。

-API Reference 请参考 api_fluid_optimizer_FtrlOptimizer_
+API Reference 请参考 :ref:`api_fluid_optimizer_FtrlOptimizer`
+

-.. _api_fluid_optimizer_FtrlOptimizer: http://www.paddlepaddle.org/docs/0.14.0/api/fluid/en/optimizer.html#permalink-15-ftrloptimizer

 9.ModelAverage
 -----------------

 :code:`ModelAverage` 优化器，在训练中通过窗口来累计历史 parameter，在预测时使用取平均值后的paramet，整体提高预测的精度。

-API Reference 请参考 api_fluid_optimizer_ModelAverage_
-
-.. _api_fluid_optimizer_ModelAverage: http://www.paddlepaddle.org/docs/0.14.0/api/fluid/en/optimizer.html#permalink-17-modelaverage
-
-
-10.Optimizer
--------------
-:code:`Optimizer` 这个类是 :code:`Fluid` 中优化器的基类。它的作用是定义优化器的公共接口，用户通过该类调用上述经典的优化算法。
+API Reference 请参考 :ref:`api_fluid_optimizer_ModelAverage`

-API Reference 请参考 api_fluid_optimizer_

-.. _api_fluid_optimizer: http://www.paddlepaddle.org/docs/0.14.0/api/fluid/en/optimizer.html#permalink-18-optimizer
--- a/doc/fluid/api/layers.rst
+++ b/doc/fluid/api/layers.rst
@@ -847,6 +847,14 @@ rank_loss
 ..  autofunction:: paddle.fluid.layers.rank_loss
    :noindex:

+.. _api_fluid_layers_margin_rank_loss:
+
+margin_rank_loss
+----------------
+
+..  autofunction:: paddle.fluid.layers.margin_rank_loss
+    :noindex:
+
 .. _api_fluid_layers_elu:

 elu

--- a/doc/fluid/user_guides/howto/prepare_data/index.rst
+++ b/doc/fluid/user_guides/howto/prepare_data/index.rst
@@ -55,3 +55,14 @@ Fluid提供PyReader异步数据传入方式，数据传入与模型训练/预测
   :maxdepth: 2

   use_py_reader.rst
+
+
+LoD-Tensor简介
+#####################
+
+LoD-Tensor是Fluid中特有的概念，它在Tensor基础上附加了序列信息，支持处理变长数据。具体请参考：
+
+..  toctree::
+    :maxdepth:2
+
+    lod_tensor.md
\ No newline at end of file
--- a/doc/fluid/user_guides/howto/prepare_data/lod_tensor.md
+++ b/doc/fluid/user_guides/howto/prepare_data/lod_tensor.md
+# LoD-Tensor
+
+LoD(Level-of-Detail) Tensor是Fluid中特有的概念，它在Tensor基础上附加了序列信息。Fluid中可传输的数据包括：输入、输出、网络中的可学习参数，全部统一使用LoD-Tensor表示。
+
+阅读本文档将帮助您了解 Fluid 中的 LoD-Tensor 设计思想，以便您更灵活的使用这一数据类型。
+
+## 变长序列的挑战
+
+大多数的深度学习框架使用Tensor表示一个mini-batch。
+
+例如一个mini-batch中有10张图片，每幅图片大小为32x32，则这个mini-batch是一个10x32x32的 Tensor。
+
+或者在处理NLP任务中，一个mini-batch包含N个句子，每个字都用一个D维的one-hot向量表示，假设所有句子都用相同的长度L，那这个mini-batch可以被表示为NxLxD的Tensor。
+
+上述两个例子中序列元素都具有相同大小，但是在许多情况下，训练数据是变长序列。基于这一场景，大部分框架采取的方法是确定一个固定长度，对小于这一长度的序列数据以0填充。
+
+在Fluid中，由于LoD-Tensor的存在，我们不要求每个mini-batch中的序列数据必须保持长度一致，因此您不需要执行填充操作，也可以满足处理NLP等具有序列要求的任务需求。
+
+Fluid引入了一个索引数据结构（LoD）来将张量分割成序列。
+
+
+## LoD 索引
+
+为了更好的理解LoD的概念，本节提供了几个例子供您参考：
+
+**句子组成的 mini-batch**
+
+假设一个mini-batch中有3个句子，每个句子中分别包含3个、1个和2个单词。我们可以用(3+1+2)xD维Tensor 加上一些索引信息来表示这个mini-batch:
+
+```
+3       1   2
+| | |   |   | |
+```
+上述表示中，每一个`|` 代表一个D维的词向量，数字3，1，2构成了 1-level LoD。
+
+**递归序列**
+让我们来看另一个2-level LoD-Tensor的例子：假设存在一个mini-batch中包含3个句子、1个句子和2个句子的文章，每个句子都由不同数量的单词组成，则这个mini-batch的样式可以看作：
+```
+3            1 2 
+3   2  4     1 2  3
+||| || ||||  | || |||
+```
+
+表示的LoD信息为：
+```
+[[3，1，2]/*level=0*/，[3，2，4，1，2，3]/*level=1*/]
+```
+
+**视频的mini-batch**
+
+在视觉任务中，时常需要处理视频和图像这些元素是高维的对象，假设现存的一个nimi-batch包含3个视频，分别有3个，1个和2个帧，每个帧都具有相同大小：640x480，则这个mini-batch可以被表示为：
+```
+3     1  2
+口口口 口 口口
+```
+
+最底层tensor大小为（3+1+2）x640x480，每一个`口` 表示一个640x480的图像
+
+**图像的mini-batch**
+
+在传统的情况下，比如有N个固定大小的图像的mini-batch，LoD-Tensor表示为:
+
+```
+1 1 1 1     1
+口口口口 ... 口
+```
+在这种情况下，我们不会因为索引值都为1而忽略信息，仅仅把LoD-Tensor看作是一个普通的张量:
+```
+口口口口 ... 口
+```
+
+**模型参数**
+
+模型参数只是一个普通的张量，在Fluid中它们被表示为一个0-level LoD-Tensor。
+
+<a name="#LoDTensor的偏移表示"></a>
+## LoDTensor的偏移表示 
+
+为了快速访问基本序列，Fluid提供了一种偏移表示的方法——保存序列的开始和结束元素，而不是保存长度。
+
+在上述例子中，您可以计算基本元素的长度：
+```
+3 2 4 1 2 3
+```
+将其转换为偏移表示：
+```
+0  3  5   9   10  12   15
+   =  =   =   =   =    =
+   3  2+3 4+5 1+9 2+10 3+12
+```
+所以我们知道第一个句子是从单词0到单词3，第二个句子是从单词3到单词5。
+
+类似的，LoD的顶层长度
+```
+3 1 2
+```
+可以被转化成偏移形式：
+```
+0 3 4   6
+  = =   =
+  3 3+1 4+2
+```
+
+因此该LoD-Tensor的偏移表示为：
+```
+0       3    4      6
+  3 5 9   10   12 15
+```
+
+## LoD-Tensor
+一个LoD-Tensor可以被看作是一个树的结构，树叶是基本的序列元素，树枝作为基本元素的标识。
+
+在 Fluid 中 LoD-Tensor 的序列信息有两种表述形式：原始长度和偏移量。在 Paddle 内部采用偏移量的形式表述 LoD-Tensor，以获得更快的序列访问速度；在 python API中采用原始长度的形式表述 LoD-Tensor 方便用户理解和计算，并将原始长度称为：`recursive_sequence_lengths` 。
+
+以上文提到的一个2-level LoD-Tensor为例：
+```
+3           1  2
+3   2  4    1  2  3
+||| || |||| |  || |||
+```
+
+- 以偏移量表示此 LoD-Tensor:[ [0,3,4,6] , [0,3,5,9,10,12,15] ]，
+- 以原始长度表达此 Lod-Tensor：recursive_sequence_lengths=[ [3-0 , 4-3 , 6-4] , [3-0 , 5-3 , 9-5 , 10-9 , 12-10 , 15-12] ]。
+
+以文字序列为例： [3,1,2] 可以表示这个mini-batch中有3篇文章，每篇文章分别有3、2、1个句子，[3,2,4,1,2,3] 表示每个句子中分别含有3、2、4、1、2、3个字。
+
+recursive_seq_lens 是一个双层嵌套列表，也就是列表的列表，最外层列表的size表示嵌套的层数，也就是lod-level的大小；内部的每个列表，对应表示每个lod-level下，每个元素的大小。
+```python
+#查看lod-tensor嵌套层数
+print len(recursive_seq_lengths)
+# output：2
+
+#查看最基础元素个数
+print sum(recursive_seq_lengths[-1])
+# output:15 (3+2+4+1+2+3=15)
+
+```
+
+## 代码示例
+
+本节代码将根据指定的级别y-lod，扩充输入变量x。本例综合了LoD-Tensor的多个重要概念，跟随代码实现，您将：
+
+-  直观理解Fluid中 `fluid.layers.sequence_expand` 的实现过程
+-  掌握如何在Fluid中创建LoD-Tensor
+-  学习如何打印LoDTensor内容
+
+
+**创建LoD-Tensor**
+
+Fluid中可以通过`fluid.create_lod_tensor()`创建一个LoD-Tensor，使用说明请参考[API reference](http://paddlepaddle.org/documentation/api/zh/develop/fluid.html#create-lod-tensor)。需要注意的是，这个API只能支持int64的数据，如果您希望处理float32的数据，推荐您使用下述方式创建lod_tensor：
+
+使用fluid.LoDTensor()创建一个LoD-Tensor，并为其指定数据、运算场所和LoD值：
+```python
+import paddle.fluid as fluid
+import numpy as np
+
+def create_lod_tensor(data, lod, place):
+    res = fluid.LoDTensor()
+    res.set(data, place)
+    res.set_lod(lod)
+    return res
+```
+**定义计算过程**
+
+layers.sequence_expand通过获取 y 的 lod 值对 x 的数据进行扩充，关于`fluid.layers.sequence_expand` 的功能说明，请先阅读[API reference](http://www.paddlepaddle.org/documentation/api/zh/0.15.0/layers.html#sequence-expand)。
+
+序列扩充代码实现：
+```python
+x = fluid.layers.data(name='x', shape=[1], dtype='float32', lod_level=0)
+y = fluid.layers.data(name='y', shape=[1], dtype='float32', lod_level=1)
+out = fluid.layers.sequence_expand(x=x, y=y, ref_level=0)
+```
+*说明*：输出LoD-Tensor的维度仅与传入的真实数据维度有关，在定义网络结构阶段为x、y设置的shape值，仅作为占位，并不影响结果。
+
+**创建Executor**
+```python
+place = fluid.CPUPlace()
+exe = fluid.Executor(place)
+exe.run(fluid.default_startup_program())
+```
+<a name="#准备数据"></a>
+
+**准备数据**
+
+这里我们使用[偏移量](#LoDTensor的偏移表示)的方法表示Tensor的LoD索引：
+假使x_d 为一个LoDTensor：
+```
+x.lod = [[0,1,4]]
+x.data = [[1],[2],[3],[4]]
+x.dims = [4,1]
+```	
+y_d 也为一个LoDTensor：
+```
+y.lod = [[0, 1,       4],
+         [0, 2, 3, 5, 6]]
+```
+其中，输出值只与 y 的LoD值有关，y_d 的 data 值在这里并不参与计算，维度上与LoD[-1]一致即可。
+
+预期输出结果为：
+```
+#预期输出lod的原始长度
+out.lod =  [ [1,  3,          3,         3]]
+#预期输出结果
+out.data = [ [1],[2],[3],[4],[2],[3],[4],[2],[3],[4]]
+```
+实现代码如下：
+```python
+x_d = create_lod_tensor(np.array([[1], [2],[3],[4]]), [[0,1,4]], place)
+y_d = create_lod_tensor(np.array([[1],[1],[1],[1],[1],[1]]), [[0,1,4], [0,2,3,5,6]], place)
+```
+**执行运算**
+
+在Fluid中，LoD>1的Tensor与其他类型数据一样，使用feed定义数据传入顺序。此外，由于输出results是带有LoD信息的Tensor，需在exe.run( )中添加`return_numpy=False`参数，获得LoD-Tensor的输出结果。
+```python
+feeder = fluid.DataFeeder(place=place, feed_list=[x, y])
+results = exe.run(fluid.default_main_program(),
+                  feed={'x':x_d, 'y': y_d },
+                  fetch_list=[out],return_numpy=False)
+```
+**查看LodTensor结果**
+
+由于LoDTensor的特殊属性，无法直接print查看内容，常用操作时将LoD-Tensor作为网络的输出fetch出来，然后执行 numpy.array(lod_tensor), 就能转成numpy array：
+
+```python
+np.array(results[0])
+```
+输出结果为：
+```
+array([[1],[2],[3],[4],[2],[3],[4],[2],[3],[4]])
+```
+可以看到与[准备数据](#准备数据)一节中的预期结果一致。
+
+## 总结
+
+至此，相信您已经基本掌握了LoD-Tensor的概念，尝试修改上述代码中的 x_d 与 y_d，观察输出结果，有助于您更好的理解这一灵活的结构。
+
+更多LoDTensor的模型应用，可以参考新手入门中的[词向量](../../../beginners_guide/basics/word2vec/index.html)、[个性化推荐](../../../beginners_guide/basics/recommender_system/index.html)、[情感分析](../../../beginners_guide/basics/understand_sentiment/index.html)等指导教程。
+
+更高阶的应用案例，请参考[模型库](../../../user_guides/models/index.html)中的相关内容。