=================
control_flow
=================
.. _cn_api_fluid_layers_array_length:
array_length
-------------------------------
.. py:function:: paddle.fluid.layers.array_length(array)
**得到输入LoDTensorArray的长度**
此功能用于查找输入数组LOD_TENSOR_ARRAY的长度。
相关API:
- :ref:`cn_api_fluid_layers_array_read`
- :ref:`cn_api_fluid_layers_array_write`
- :ref:`cn_api_fluid_layers_While`
参数：
- **array** (LOD_TENSOR_ARRAY)-输入数组，用来计算数组长度
返回：输入数组LoDTensorArray的长度
返回类型：变量（Variable）
**代码示例**:
.. code-block:: python
import paddle.fluid as fluid
tmp = fluid.layers.zeros(shape=[10], dtype='int32')
i = fluid.layers.fill_constant(shape=[1], dtype='int64', value=10)
arr = fluid.layers.array_write(tmp, i=i)
arr_len = fluid.layers.array_length(arr)
.. _cn_api_fluid_layers_array_read:
array_read
-------------------------------
.. py:function:: paddle.fluid.layers.array_read(array,i)
此函数用于读取数据，数据以LOD_TENSOR_ARRAY数组的形式读入
::
Given:
array = [0.6,0.1,0.3,0.1]
And:
I=2
Then:
output = 0.3
参数：
- **array** (Variable|list)-输入张量，存储要读的数据
- **i** (Variable|list)-输入数组中数据的索引
返回：张量类型的变量，已有数据写入
返回类型：变量（Variable）
**代码示例**：
.. code-block:: python
import paddle.fluid as fluid
array = fluid.layers.create_array(dtype='float32')
i = fluid.layers.fill_constant(shape=[1],dtype='int64',value=10)
item = fluid.layers.array_read(array, i)
.. _cn_api_fluid_layers_array_write:
array_write
-------------------------------
.. py:function:: paddle.fluid.layers.array_write(x, i, array=None)
该函数将给定的输入变量（即 ``x`` ）写入一个作为输出的 ``LOD_TENSOR_ARRAY`` 变量的某一指定位置中，
这一位置由数组下标(即 ``i`` )指明。 如果 ``LOD_TENSOR_ARRAY`` (即 ``array`` )未指定（即为None值）， 一个新的 ``LOD_TENSOR_ARRAY`` 将会被创建并作为结果返回。
参数:
- **x** (Variable|list) – 待从中读取数据的输入张量(tensor)
- **i** (Variable|list) – 输出结果 ``LOD_TENSOR_ARRAY`` 的下标, 该下标指向输入张量 ``x`` 写入输出数组的位置
- **array** (Variable|list) – 会被输入张量 ``x`` 写入的输出结果 ``LOD_TENSOR_ARRAY`` 。如果该项值为None， 一个新的 ``LOD_TENSOR_ARRAY`` 将会被创建并作为结果返回
返回: 输入张量 ``x`` 所写入的输出结果 ``LOD_TENSOR_ARRAY``
返回类型: 变量（Variable）
**代码示例**
.. code-block:: python
import paddle.fluid as fluid
tmp = fluid.layers.zeros(shape=[10], dtype='int32')
i = fluid.layers.fill_constant(shape=[1], dtype='int64', value=10)
arr = fluid.layers.array_write(tmp, i=i)
.. _cn_api_fluid_layers_create_array:
create_array
-------------------------------
.. py:function:: paddle.fluid.layers.create_array(dtype)
创建LoDTensorArray数组。它主要用于实现RNN与array_write, array_read和While。
参数:
- **dtype** (int |float) — lod_tensor_array中存储元素的数据类型。
返回: lod_tensor_array， 元素数据类型为dtype。
返回类型: Variable。
**代码示例**
.. code-block:: python
import paddle.fluid as fluid
data = fluid.layers.create_array(dtype='float32')
.. _cn_api_fluid_layers_DynamicRNN:
DynamicRNN
-------------------------------
.. py:class:: paddle.fluid.layers.DynamicRNN(name=None)
动态RNN可以处理一批序列数据,每个样本序列的长度可以不同。这个API自动批量处理它们。
必须设置输入lod，请参考 ``lod_tensor``
动态RNN将按照timesteps展开开序列。用户需要在with block中定义如何处理处理每个timestep。
memory用于缓存分段数据。memory的初始值可以是零，也可以是其他变量。
动态RNN可以将多个变量标记为其输出。使用drnn()获得输出序列。
.. note::
目前不支持在DynamicRNN中任何层上配置 is_sparse = True
**代码示例**
.. code-block:: python
import paddle.fluid as fluid
sentence = fluid.layers.data(name='sentence', shape=[1], dtype='int64', lod_level=1)
embedding = fluid.layers.embedding(input=sentence, size=[65536, 32], is_sparse=True)
drnn = fluid.layers.DynamicRNN()
with drnn.block():
word = drnn.step_input(embedding)
prev = drnn.memory(shape=[200])
hidden = fluid.layers.fc(input=[word, prev], size=200, act='relu')
drnn.update_memory(prev, hidden) # set prev to hidden
drnn.output(hidden)
# 获得上一个timestep的rnn，该值是一个编码后的结果
rnn_output = drnn()
last = fluid.layers.sequence_last_step(rnn_output)
.. py:method:: step_input(x, level=0)
将序列标记为动态RNN输入。
参数:
- **x** (Variable) - 含lod信息的输入序列
- **level** (int) - 用于拆分步骤的LOD层级，默认值0
返回:当前的输入序列中的timestep。
.. py:method:: static_input(x)
将变量标记为RNN输入。输入不会分散到timestep中。为可选项。
参数:
- **x** (Variable) - 输入序列
返回:可以访问的RNN的输入变量。
**代码示例**
.. code-block:: python
import paddle.fluid as fluid
sentence = fluid.layers.data(name='sentence', dtype='float32', shape=[32], lod_level=1)
encoder_proj = fluid.layers.data(name='encoder_proj', dtype='float32', shape=[32], lod_level=1)
decoder_boot = fluid.layers.data(name='boot', dtype='float32', shape=[10], lod_level=1)
drnn = fluid.layers.DynamicRNN()
with drnn.block():
current_word = drnn.step_input(sentence)
encoder_word = drnn.static_input(encoder_proj)
hidden_mem = drnn.memory(init=decoder_boot, need_reorder=True)
fc_1 = fluid.layers.fc(input=encoder_word, size=30, bias_attr=False)
fc_2 = fluid.layers.fc(input=current_word, size=30, bias_attr=False)
decoder_inputs = fc_1 + fc_2
h, _, _ = fluid.layers.gru_unit(input=decoder_inputs, hidden=hidden_mem, size=30)
drnn.update_memory(hidden_mem, h)
out = fluid.layers.fc(input=h, size=10, bias_attr=True, act='softmax')
drnn.output(out)
rnn_output = drnn()
.. py:method:: block()
用户在RNN中定义operators的block。
.. py:method:: memory(init=None, shape=None, value=0.0, need_reorder=False, dtype='float32')
为动态rnn创建一个memory 变量。
如果 ``init`` 不是None， ``memory`` 将由这个变量初始化。参数 ``need_reorder`` 用于将memory重新排序作为输入变量。当memory初始化依赖于输入样本时，应该将其设置为True。
**代码示例**
.. code-block:: python
import paddle.fluid as fluid
sentence = fluid.layers.data(name='sentence', shape=[32], dtype='float32', lod_level=1)
boot_memory = fluid.layers.data(name='boot', shape=[10], dtype='float32', lod_level=1)
drnn = fluid.layers.DynamicRNN()
with drnn.block():
word = drnn.step_input(sentence)
memory = drnn.memory(init=boot_memory, need_reorder=True)
hidden = fluid.layers.fc(input=[word, memory], size=10, act='tanh')
drnn.update_memory(ex_mem=memory, new_mem=hidden)
drnn.output(hidden)
rnn_output = drnn()
否则，如果已经设置 ``shape`` 、 ``value`` 、 ``dtype`` ，memory将被 ``value`` 初始化
**代码示例**
.. code-block:: python
import paddle.fluid as fluid
sentence = fluid.layers.data(name='sentence', dtype='float32', shape=[32], lod_level=1)
drnn = fluid.layers.DynamicRNN()
with drnn.block():
word = drnn.step_input(sentence)
memory = drnn.memory(shape=[10], dtype='float32', value=0)
hidden = fluid.layers.fc(input=[word, memory], size=10, act='tanh')
drnn.update_memory(ex_mem=memory, new_mem=hidden)
drnn.output(hidden)
rnn_output = drnn()
参数：
- **init** (Variable|None) – 初始化的Variable
- **shape** (list|tuple) – memory shape，形状不包含batch_size
- **value** (float) – 初始化的值
- **need_reorder** (bool) – memory初始化依赖于输入样本时设置为True
- **dtype** (str|numpy.dtype) – 初始化memory的数据类型
返回：memory Variable
.. py:method:: update_memory(ex_mem, new_mem)
将内存从 ``ex_mem`` 更新到 ``new_mem`` 。注意， ``ex_mem`` 和 ``new_mem`` 的 ``shape`` 和数据类型必须相同。
参数：
- **ex_mem** （memory Variable）- memory 变量（Variable）
- **new_mem** （memory Variable）- RNN块中生成的平坦变量（plain variable）
返回：None
.. py:method:: output(*outputs)
标记RNN输出变量。
参数:
- **\*outputs** - 输出变量。
返回:None
.. _cn_api_fluid_layers_equal:
equal
-------------------------------
.. py:function:: paddle.fluid.layers.equal(x,y,cond=None)
**equal**
该层返回 :math:`x==y` 按逐元素运算而得的真值。
参数：
- **x** (Variable)-equal的第一个操作数
- **y** (Variable)-equal的第二个操作数
- **cond** (Variable|None)-输出变量（可选），用来存储equal的结果
返回：张量类型的变量，存储equal的输出结果
返回类型：变量（Variable）
**代码示例**:
.. code-block:: python
import paddle.fluid as fluid
label = fluid.layers.data(name="label", shape=[3,10,32,32], dtype="float32")
limit = fluid.layers.data(name="limit", shape=[3,10,32,32], dtype="float32")
less = fluid.layers.equal(x=label,y=limit)
.. _cn_api_fluid_layers_greater_equal:
greater_equal
-------------------------------
.. py:function:: paddle.fluid.layers.greater_equal(x, y, cond=None)
该层逐元素地返回 :math:`x >= y` 的逻辑值，和重载算子 `>=` 相同。
参数：
- **x** (Variable) - *greater_equal* 的第一个操作数
- **y** (Variable) - *greater_equal* 的第二个操作数
- **cond** (Variable|None) - 可选的输出变量，存储 *greater_equal* 的结果
返回：存储 *greater_equal* 的输出的张量变量。
返回类型：变量（Variable）
**代码示例**:
.. code-block:: python
import paddle.fluid as fluid
out = fluid.layers.greater_equal(x=label, y=limit)
.. _cn_api_fluid_layers_greater_than:
greater_than
-------------------------------
.. py:function:: paddle.fluid.layers.greater_than(x, y, cond=None)
该层逐元素地返回 :math:`x > y` 的逻辑值，和重载算子 `>` 相同。
参数：
- **x** (Variable) - *greater_than* 的第一个操作数
- **y** (Variable) - *greater_than* 的第二个操作数
- **cond** (Variable|None) - 可选的输出变量，存储 *greater_than* 的结果
返回：存储 *greater_than* 的输出的张量变量。
返回类型：变量（Variable）
**代码示例**:
.. code-block:: python
import paddle.fluid as fluid
out = fluid.layers.greater_than(x=label, y=limit)
.. _cn_api_fluid_layers_IfElse:
IfElse
-------------------------------
.. py:class:: paddle.fluid.layers.IfElse(cond, name=None)
if-else控制流。
参数：
- **cond** (Variable)-用于比较的条件
- **Name** (str,默认为空（None）)-该层名称
**代码示例**：
.. code-block:: python
import paddle.fluid as fluid
image = fluid.layers.data(name="X", shape=[2, 5, 5], dtype='float32')
label = fluid.layers.data(name='label', shape=[1], dtype='int64')
limit = fluid.layers.fill_constant_batch_size_like(
input=label, dtype='int64', shape=[1], value=5.0)
cond = fluid.layers.less_than(x=label, y=limit)
ie = fluid.layers.IfElse(cond)
with ie.true_block():
true_image = ie.input(image)
hidden = fluid.layers.fc(input=true_image, size=100, act='tanh')
prob = fluid.layers.fc(input=hidden, size=10, act='softmax')
ie.output(prob)
with ie.false_block():
false_image = ie.input(image)
hidden = fluid.layers.fc(
input=false_image, size=200, act='tanh')
prob = fluid.layers.fc(input=hidden, size=10, act='softmax')
ie.output(prob)
prob = ie()
.. _cn_api_fluid_layers_increment:
increment
-------------------------------
.. py:function:: paddle.fluid.layers.increment(x, value=1.0, in_place=True)
该函数为输入 ``x`` 增加 ``value`` 大小, ``value`` 即函数中待传入的参数。该函数默认直接在原变量 ``x`` 上进行运算。
.. note::
``x`` 中元素个数必须为1
参数:
- **x** (Variable|list) – 含有输入值的张量(tensor)
- **value** (float) – 需要增加在 ``x`` 变量上的值
- **in_place** (bool) – 判断是否在x变量本身执行操作，True原地执行，False时，返回增加后的副本
返回： 每个元素增加后的对象
返回类型：变量(variable)
**代码示例**
.. code-block:: python
import paddle.fluid as fluid
data = fluid.layers.data(name='data', shape=[1], dtype='float32',
append_batch_size=False)
data = fluid.layers.increment(x=data, value=3.0, in_place=True)
.. _cn_api_fluid_layers_is_empty:
is_empty
-------------------------------
.. py:function:: paddle.fluid.layers.is_empty(x, cond=None)
测试变量是否为空
参数：
- **x** (Variable)-测试的变量
- **cond** (Variable|None)-输出参数。返回给定x的测试结果，默认为空（None）
返回：布尔类型的标量。如果变量x为空则值为真
返回类型：变量（Variable）
抛出异常：``TypeError``-如果input不是变量或cond类型不是变量
**代码示例**：
.. code-block:: python
import paddle.fluid as fluid
input = fluid.layers.data(name="input", shape=[4, 32, 32], dtype="float32")
res = fluid.layers.is_empty(x=input)
# or:
# fluid.layers.is_empty(x=input, cond=res)
.. _cn_api_fluid_layers_less_equal:
less_equal
-------------------------------
.. py:function:: paddle.fluid.layers.less_equal(x, y, cond=None)
该层逐元素地返回 :math:`x <= y` 的逻辑值，和重载算子 `<=` 相同。
参数：
- **x** (Variable) - *less_equal* 的第一个操作数
- **y** (Variable) - *less_equal* 的第二个操作数
- **cond** (Variable|None) - 可选的输出变量，存储 *less_equal* 的结果
返回：存储 *less_equal* 的输出的张量变量。
返回类型：变量（Variable）
**代码示例**:
.. code-block:: python
import paddle.fluid as fluid
out = fluid.layers.less_equal(x=label, y=limit)
.. _cn_api_fluid_layers_less_than:
less_than
-------------------------------
.. py:function:: paddle.fluid.layers.less_than(x, y, force_cpu=None, cond=None)
该函数按元素出现顺序依次在X,Y上操作，并返回 ``Out`` ，它们三个都是n维tensor（张量）。
其中，X、Y可以是任何类型的tensor，Out张量的各个元素可以通过 :math:`Out=X
