control_flow.py 62.9 KB
Newer Older
1
#   Copyright (c) 2018 PaddlePaddle Authors. All Rights Reserved.
D
dzhwinter 已提交
2
#
D
dzhwinter 已提交
3 4 5
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
D
dzhwinter 已提交
6
#
D
dzhwinter 已提交
7
#     http://www.apache.org/licenses/LICENSE-2.0
D
dzhwinter 已提交
8
#
D
dzhwinter 已提交
9 10 11 12 13
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
14 15

from __future__ import print_function
S
rename  
sneaxiy 已提交
16
from ..wrapped_decorator import signature_safe_contextmanager
D
dzhwinter 已提交
17

18 19
from .layer_function_generator import autodoc, templatedoc
from .tensor import assign, fill_constant
20
from .. import core
21
from ..framework import Program, Variable, Operator
22
from ..layer_helper import LayerHelper, unique_name
J
JiayiFeng 已提交
23
from ..initializer import force_init_on_cpu
M
minqiyang 已提交
24
from .nn import logical_and, logical_not, logical_or
Y
yuyang18 已提交
25
import numpy
26
import warnings
27
import six
28
from functools import reduce
D
dzhwinter 已提交
29

Q
QI JUN 已提交
30
__all__ = [
Y
ying 已提交
31
    'While',
32
    'Switch',
Y
ying 已提交
33 34 35 36
    'increment',
    'array_write',
    'create_array',
    'less_than',
37
    'equal',
Y
ying 已提交
38 39 40 41 42 43 44
    'array_read',
    'array_length',
    'IfElse',
    'DynamicRNN',
    'StaticRNN',
    'reorder_lod_tensor_by_rank',
    'Print',
45
    'is_empty',
D
dzhwinter 已提交
46 47
]

Y
Yu Yang 已提交
48

49
def split_lod_tensor(input, mask, level=0):
50 51 52 53
    """
    This function takes in an input that contains the complete lod information,
    and takes in a mask which is used to mask certain parts of the input.
    The output is the true branch and the false branch with the mask applied to
Q
qiaolongfei 已提交
54 55
    the input at a certain level in the tensor. Mainly used in IfElse to split
    data into two parts.
56 57 58 59 60

    Args:
        input(tuple|list|None): The input tensor that contains complete
                                lod information needed to construct the output.
        mask(list): A bool column vector which masks the input.
Q
qiaolongfei 已提交
61
        level(int): The specific lod level to split.
62 63

    Returns:
Q
qiaolongfei 已提交
64 65 66 67
        tuple(Variable, Variable):
        The true branch of tensor as per the mask applied to input.

        The false branch of tensor as per the mask applied to input.
68 69 70 71

    Examples:
        .. code-block:: python

Q
qiaolongfei 已提交
72
          x = fluid.layers.data(name='x', shape=[1])
73 74
          x.persistable = True

Q
qiaolongfei 已提交
75
          y = fluid.layers.data(name='y', shape=[1])
76 77
          y.persistable = True

Q
qiaolongfei 已提交
78
          out_true, out_false = fluid.layers.split_lod_tensor(
79
                input=x, mask=y, level=level)
80

81
    """
82
    helper = LayerHelper('split_lod_tensor', **locals())
X
Xin Pan 已提交
83 84
    out_true = helper.create_variable_for_type_inference(dtype=input.dtype)
    out_false = helper.create_variable_for_type_inference(dtype=input.dtype)
85 86 87 88 89 90 91 92 93 94 95 96
    helper.append_op(
        type='split_lod_tensor',
        inputs={
            'X': input,
            'Mask': mask,
        },
        outputs={'OutTrue': out_true,
                 'OutFalse': out_false},
        attrs={'level': level})
    return out_true, out_false


97
def merge_lod_tensor(in_true, in_false, x, mask, level=0):
98 99 100 101 102
    """
    **merge_lod_tensor**

    This function takes in an input :math:`x`, the True branch, the False
    branch and a binary :math:`mask`. Using this information, this function
Q
qiaolongfei 已提交
103 104 105
    merges the True and False branches of the tensor into a single tensor as
    output at a certain lod level indicated by :math:`level`. Used in IfElse
    to merge the output if True block and False Block.
106 107 108 109 110 111 112

    Args:
        in_true(tuple|list|None): The True branch to be merged.
        in_false(tuple|list|None): The False branch to be merged.
        x(tuple|list|None): The input tensor that contains complete
                            lod information needed to construct the output.
        mask(list): A bool column vector which masks the input.
Q
qiaolongfei 已提交
113
        level(int): The specific lod level to merge.
114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132

    Returns:
        Variable: The merged output tensor.

    Examples:
        .. code-block:: python

          x = layers.data(
                      name='x', shape=[1], dtype='float32', stop_gradient=False)
          y = layers.data(
                name='y', shape=[1], dtype='bool', stop_gradient=False)

          level = 0

          out_true, out_false = layers.split_lod_tensor(
                input=x, mask=y, level=level)
          out = layers.merge_lod_tensor(
                in_true=out_true, in_false=out_false, mask=y, x=x, level=level)
    """
133
    helper = LayerHelper('merge_lod_tensor', **locals())
X
Xin Pan 已提交
134
    out = helper.create_variable_for_type_inference(dtype=in_true.dtype)
135 136 137 138 139 140 141 142 143 144 145
    helper.append_op(
        type='merge_lod_tensor',
        inputs={'X': x,
                'Mask': mask,
                'InTrue': in_true,
                'InFalse': in_false},
        outputs={'Out': out},
        attrs={'level': level})
    return out


Y
Yan Chunwei 已提交
146 147 148 149 150 151 152
def Print(input,
          first_n=-1,
          message=None,
          summarize=-1,
          print_tensor_name=True,
          print_tensor_type=True,
          print_tensor_shape=True,
Y
yangyaming 已提交
153 154
          print_tensor_lod=True,
          print_phase='both'):
Y
Yan Chunwei 已提交
155 156 157 158 159 160 161 162 163 164
    '''
    **Print operator**

    This creates a print op that will print when a tensor is accessed.

    Wraps the tensor passed in so that whenever that a tensor is accessed,
    the message `message` is printed, along with the current value of the
    tensor `t`.

    Args:
Y
yangyaming 已提交
165 166 167 168 169 170 171 172 173
        input (Variable): A Tensor to print.
        summarize (int): Print this number of elements in the tensor, will print
                all if left is negative.
        message (str): A string message to print as a prefix.
        first_n (int): Only log `first_n` number of times.
        print_tensor_name (bool): Print the tensor name.
        print_tensor_type (bool): Print the tensor type.
        print_tensor_shape (bool): Print the tensor shape.
        print_tensor_lod (bool): Print the tensor lod.
174
        print_phase (str): Which phase to displace, including 'forward',
Y
yangyaming 已提交
175 176
                'backward' and 'both'. If set to 'backward' or 'both', will
                print the gradients of input tensor.
Y
Yan Chunwei 已提交
177 178

    Returns:
Y
yangyaming 已提交
179
        Variable: Output tensor, same data with input tensor.
Y
Yan Chunwei 已提交
180

Y
Yan Chunwei 已提交
181

Y
Yan Chunwei 已提交
182
    Examples:
Y
Yan Chunwei 已提交
183

Y
Yan Chunwei 已提交
184 185
        .. code-block:: python

Y
Yan Chunwei 已提交
186 187 188
           value = some_layer(...)
           Print(value, summarize=10,
               message="The content of some_layer: ")
Y
Yan Chunwei 已提交
189 190 191 192
    '''
    helper = LayerHelper('print', **locals())
    helper.append_op(
        type='print',
Y
yangyaming 已提交
193
        inputs={'In': input},
Y
Yan Chunwei 已提交
194 195 196 197 198 199 200 201
        attrs={
            'first_n': first_n,
            'summarize': summarize,
            'message': message or "",
            'print_tensor_name': print_tensor_name,
            'print_tensor_type': print_tensor_type,
            'print_tensor_shape': print_tensor_shape,
            'print_tensor_lod': print_tensor_lod,
Y
yangyaming 已提交
202
            'print_phase': print_phase.upper()
Y
Yu Yang 已提交
203
        })
Y
Yan Chunwei 已提交
204 205


Y
Yu Yang 已提交
206 207
class BlockGuard(object):
    """
208 209 210 211
    BlockGuard class.

    BlockGuard class is used to create a sub-block in a program by
    using the Python `with` keyword.
Y
Yu Yang 已提交
212 213
    """

214 215
    def __init__(self, main_program):
        if not isinstance(main_program, Program):
Y
Yu Yang 已提交
216
            raise TypeError("BlockGuard takes a program")
217
        self.main_program = main_program
Y
Yu Yang 已提交
218 219

    def __enter__(self):
W
Wu Yi 已提交
220
        self.main_program._create_block()
Y
Yu Yang 已提交
221 222

    def __exit__(self, exc_type, exc_val, exc_tb):
W
Wu Yi 已提交
223
        self.main_program._rollback()
Y
Yu Yang 已提交
224 225 226 227 228
        if exc_type is not None:
            return False  # re-raise exception
        return True


Y
Yang Yang 已提交
229 230 231 232 233
class BlockGuardWithCompletion(BlockGuard):
    """
    BlockGuardWithCompletion class.

    BlockGuardWithCompletion class is used to create an op with a block in a program.
234 235
    """

Y
Yu Yang 已提交
236
    def __init__(self, rnn):
X
Xin Pan 已提交
237
        if not isinstance(rnn, StaticRNN):
X
Xin Pan 已提交
238
            raise TypeError("BlockGuardWithCompletion takes a StaticRNN")
Y
Yang Yang 已提交
239
        super(BlockGuardWithCompletion, self).__init__(rnn.helper.main_program)
Y
Yu Yang 已提交
240 241 242 243
        self.rnn = rnn

    def __enter__(self):
        self.rnn.status = StaticRNN.IN_RNN_BLOCK
Y
Yang Yang 已提交
244
        return super(BlockGuardWithCompletion, self).__enter__()
Y
Yu Yang 已提交
245 246

    def __exit__(self, exc_type, exc_val, exc_tb):
Y
Yu Yang 已提交
247 248
        if exc_type is not None:
            return False
Y
Yu Yang 已提交
249
        self.rnn.status = StaticRNN.AFTER_RNN_BLOCK
250
        self.rnn._complete_op()
Y
Yang Yang 已提交
251 252
        return super(BlockGuardWithCompletion, self).__exit__(exc_type, exc_val,
                                                              exc_tb)
Y
Yu Yang 已提交
253 254 255 256


class StaticRNNMemoryLink(object):
    """
257 258 259 260
    StaticRNNMemoryLink class.

    StaticRNNMemoryLink class is used to create a link between two
    memory cells of a StaticRNN.
Y
yuyang18 已提交
261 262 263 264 265 266 267 268 269


    NOTE: This is a internal data structure of a very low-level API.
    Please use StaticRNN instead.

    Args:
        init(Variable): the initial variable for Memory.
        pre_mem(Variable): the memory variable in previous time step.
        mem(Variable): the memory variable in current time step.
Y
Yu Yang 已提交
270 271 272 273 274 275 276 277 278
    """

    def __init__(self, init, pre_mem, mem=None):
        self.init = init
        self.pre_mem = pre_mem
        self.mem = mem


class StaticRNN(object):
279 280 281 282 283 284
    """
    StaticRNN class.

    StaticRNN class is used to create a StaticRNN. The RNN will have its
    own parameters like inputs, outputs, memories, status and length.
    """
Y
Yu Yang 已提交
285 286 287 288
    BEFORE_RNN_BLOCK = 0
    IN_RNN_BLOCK = 1
    AFTER_RNN_BLOCK = 2

289 290
    def __init__(self, name=None):
        self.helper = LayerHelper("static_rnn", name=name)
Y
Yu Yang 已提交
291 292 293 294 295 296 297 298
        self.memories = {}  # memory map, from pre_mem.name --> MemoryLink
        self.inputs = []  # input variable list in current block
        self.outputs = []  # output variable list in parent block
        self.status = StaticRNN.BEFORE_RNN_BLOCK  # status flag.
        # sequence length, since it is a static RNN, sequence length are fixed.
        self.seq_len = None

    def step(self):
Y
Yang Yang 已提交
299
        return BlockGuardWithCompletion(self)
Y
Yu Yang 已提交
300 301 302 303 304

    def _assert_in_rnn_block_(self, method):
        if self.status != StaticRNN.IN_RNN_BLOCK:
            raise ValueError("You must invoke {0} in rnn block".format(method))

305 306 307 308 309 310 311
    def memory(self,
               init=None,
               shape=None,
               batch_ref=None,
               init_value=0.0,
               init_batch_dim_idx=0,
               ref_batch_dim_idx=1):
312 313 314 315 316 317 318 319 320
        """
        Args:
            init: boot memory, if not set, a shape, batch_ref must be provided
            shape: shape of the boot memory
            batch_ref: batch size reference variable
            init_value: the init value of boot memory
            init_batch_dim_idx: the index of batch size in init's dimension
            ref_batch_dim_idx: the index of batch size in batch_ref's dimension
        """
Y
Yu Yang 已提交
321 322
        self._assert_in_rnn_block_('memory')
        if init is None:
323
            if shape is None or batch_ref is None:
Y
Yu Yang 已提交
324
                raise ValueError(
325
                    "if init is None, memory at least need shape and batch_ref")
326
            parent_block = self._parent_block()
Y
Yu Yang 已提交
327 328
            var_name = unique_name.generate("@".join(
                [self.helper.name, "memory_boot"]))
Y
Yu Yang 已提交
329
            boot_var = parent_block.create_var(
330 331
                name=var_name,
                shape=shape,
F
fengjiayi 已提交
332
                dtype=batch_ref.dtype,
333
                persistable=False)
Y
Yu Yang 已提交
334 335

            parent_block.append_op(
336 337
                type="fill_constant_batch_size_like",
                inputs={'Input': [batch_ref]},
Y
Yu Yang 已提交
338 339 340
                outputs={'Out': [boot_var]},
                attrs={
                    'value': init_value,
341
                    'shape': boot_var.shape,
F
fengjiayi 已提交
342
                    'dtype': boot_var.dtype,
343 344
                    'input_dim_idx': ref_batch_dim_idx,
                    'output_dim_idx': init_batch_dim_idx
Y
Yu Yang 已提交
345 346 347 348 349
                })

            return self.memory(init=boot_var)
        else:
            pre_mem = self.helper.create_variable(
Y
Yu Yang 已提交
350
                name=unique_name.generate("@".join([self.helper.name, "mem"])),
F
fengjiayi 已提交
351
                dtype=init.dtype,
Y
Yu Yang 已提交
352 353 354 355 356 357 358 359 360 361
                shape=init.shape)
            self.memories[pre_mem.name] = StaticRNNMemoryLink(
                init=init, pre_mem=pre_mem)
            return pre_mem

    def step_input(self, x):
        self._assert_in_rnn_block_('step_input')
        if not isinstance(x, Variable):
            raise TypeError("step input takes a Variable")
        if self.seq_len is None:
Y
Yu Yang 已提交
362 363
            self.seq_len = x.shape[0]
        elif self.seq_len != x.shape[0]:
Y
Yu Yang 已提交
364 365 366
            raise ValueError("Static RNN only take fix seq_len input")

        ipt = self.helper.create_variable(
F
fengjiayi 已提交
367
            name=x.name, dtype=x.dtype, shape=list(x.shape[1:]), type=x.type)
Y
Yu Yang 已提交
368 369 370 371 372 373 374 375
        self.inputs.append(ipt)
        return ipt

    def step_output(self, o):
        self._assert_in_rnn_block_('step_output')
        if not isinstance(o, Variable):
            raise TypeError("step output takes a Variable")

X
Xin Pan 已提交
376
        tmp_o = self.helper.create_variable_for_type_inference(dtype=o.dtype)
Y
Yu Yang 已提交
377 378 379 380
        self.helper.append_op(
            type='rnn_memory_helper',
            inputs={'X': [o]},
            outputs={'Out': tmp_o},
F
fengjiayi 已提交
381
            attrs={'dtype': o.dtype})
Y
Yu Yang 已提交
382

383
        out_var = self._parent_block().create_var(
Y
Yu Yang 已提交
384 385
            name=tmp_o.name,
            shape=[self.seq_len] + list(tmp_o.shape),
F
fengjiayi 已提交
386
            dtype=tmp_o.dtype)
Y
Yu Yang 已提交
387 388 389 390 391 392 393 394 395 396 397 398

        self.outputs.append(out_var)

    def output(self, *outputs):
        for each in outputs:
            self.step_output(each)

    def update_memory(self, mem, var):
        if not isinstance(mem, Variable) or not isinstance(var, Variable):
            raise TypeError("update memory should take variables")
        self.memories[mem.name].mem = var

399
    def _parent_block(self):
400
        prog = self.helper.main_program
Y
Yu Yang 已提交
401 402 403 404 405 406 407 408 409 410 411 412 413 414 415
        parent_idx = prog.current_block().parent_idx
        assert parent_idx >= 0
        parent_block = prog.block(parent_idx)
        return parent_block

    def __call__(self, *args, **kwargs):
        if self.status != StaticRNN.AFTER_RNN_BLOCK:
            raise ValueError("RNN output can only be retrieved after rnn block")
        if len(self.outputs) == 0:
            raise ValueError("RNN has no output")
        elif len(self.outputs) == 1:
            return self.outputs[0]
        else:
            return self.outputs

416
    def _complete_op(self):
417 418
        main_program = self.helper.main_program
        rnn_block = main_program.current_block()
419
        parent_block = self._parent_block()
Y
Yu Yang 已提交
420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452

        local_inputs = set()

        for op in rnn_block.ops:
            assert isinstance(op, Operator)
            for oname in op.output_names:
                for out_var_name in op.output(oname):
                    local_inputs.add(out_var_name)

        for var in self.inputs:
            local_inputs.add(var.name)
        for m in self.memories:
            local_inputs.add(m)

        params = list()
        for op in rnn_block.ops:
            assert isinstance(op, Operator)
            for iname in op.input_names:
                for in_var_name in op.input(iname):
                    if in_var_name not in local_inputs:
                        params.append(in_var_name)

        parameters = [parent_block.var(name) for name in params]

        step_scope = parent_block.create_var(
            type=core.VarDesc.VarType.STEP_SCOPES)

        inlinks = [parent_block.var(i.name) for i in self.inputs]
        outlinks = self.outputs

        boot_memories = []
        pre_memories = []
        memories = []
M
minqiyang 已提交
453
        for _, mem in six.iteritems(self.memories):
Y
Yu Yang 已提交
454 455 456 457
            boot_memories.append(mem.init)
            pre_memories.append(mem.pre_mem.name)
            mem_var = rnn_block.var(mem.mem.name)
            assert isinstance(mem_var, Variable)
X
Xin Pan 已提交
458 459
            new_mem = self.helper.create_variable_for_type_inference(
                dtype=mem_var.dtype)
Y
Yu Yang 已提交
460 461 462 463 464

            rnn_block.append_op(
                type='rnn_memory_helper',
                inputs={'X': [mem_var]},
                outputs={'Out': [new_mem]},
F
fengjiayi 已提交
465
                attrs={'dtype': mem_var.dtype})
Y
Yu Yang 已提交
466 467 468 469 470 471 472 473 474 475 476 477 478 479 480

            memories.append(new_mem.name)

        parent_block.append_op(
            type='recurrent',
            inputs={
                'inputs': inlinks,
                'initial_states': boot_memories,
                'parameters': parameters
            },
            outputs={'outputs': outlinks,
                     'step_scopes': [step_scope]},
            attrs={
                'ex_states': pre_memories,
                'states': memories,
481
                'sub_block': rnn_block
Y
Yu Yang 已提交
482
            })
Y
Yu Yang 已提交
483 484


Y
Yang Yang(Tony) 已提交
485 486 487 488 489 490 491 492 493 494 495 496 497 498 499
class WhileGuard(BlockGuard):
    def __init__(self, while_op):
        if not isinstance(while_op, While):
            raise TypeError("WhileGuard takes a while op")
        super(WhileGuard, self).__init__(while_op.helper.main_program)
        self.while_op = while_op

    def __enter__(self):
        self.while_op.status = While.IN_WHILE_BLOCK
        return super(WhileGuard, self).__enter__()

    def __exit__(self, exc_type, exc_val, exc_tb):
        if exc_type is not None:
            return False
        self.while_op.status = While.AFTER_WHILE_BLOCK
500
        self.while_op._complete()
Y
Yang Yang(Tony) 已提交
501 502 503 504
        return super(WhileGuard, self).__exit__(exc_type, exc_val, exc_tb)


class While(object):
X
Xin Pan 已提交
505 506 507 508
    """
    while loop control flow.

    Args:
509
        cond(Variable): condition used to compare.
C
chengduo 已提交
510
        is_test(bool): A flag indicating whether execution is in test phase.
511
        name(str): The name of this layer.
X
Xin Pan 已提交
512 513 514 515

    Examples:
          .. code-block:: python

X
Xin Pan 已提交
516 517 518
            d0 = layers.data("d0", shape=[10], dtype='float32')
            data_array = layers.array_write(x=d0, i=i)
            array_len = layers.fill_constant(shape=[1],dtype='int64', value=3)
X
Xin Pan 已提交
519

X
Xin Pan 已提交
520 521 522 523 524 525 526
            cond = layers.less_than(x=i, y=array_len)
            while_op = layers.While(cond=cond)
            with while_op.block():
                d = layers.array_read(array=data_array, i=i)
                i = layers.increment(x=i, in_place=True)
                layers.array_write(result, i=i, array=d)
                layers.less_than(x=i, y=array_len, cond=cond)
X
Xin Pan 已提交
527 528
    """

Y
Yang Yang(Tony) 已提交
529 530 531 532
    BEFORE_WHILE_BLOCK = 0
    IN_WHILE_BLOCK = 1
    AFTER_WHILE_BLOCK = 2

C
chengduo 已提交
533
    def __init__(self, cond, is_test=False, name=None):
534
        self.helper = LayerHelper("while", name=name)
Y
Yang Yang(Tony) 已提交
535 536 537 538
        self.status = While.BEFORE_WHILE_BLOCK
        if not isinstance(cond, Variable):
            raise TypeError("condition should be a variable")
        assert isinstance(cond, Variable)
539
        if cond.dtype != core.VarDesc.VarType.BOOL:
Y
Yang Yang(Tony) 已提交
540 541 542 543
            raise TypeError("condition should be a bool variable")
        if reduce(lambda a, b: a * b, cond.shape, 1) != 1:
            raise TypeError("condition should be a bool scalar")
        self.cond_var = cond
C
chengduo 已提交
544
        self.is_test = is_test
Y
Yang Yang(Tony) 已提交
545 546 547 548

    def block(self):
        return WhileGuard(self)

549
    def _complete(self):
Y
Yang Yang(Tony) 已提交
550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568
        main_program = self.helper.main_program
        while_block = main_program.current_block()
        parent_block = main_program.block(main_program.current_block()
                                          .parent_idx)

        inner_outputs = {self.cond_var.name}
        x_name_list = set()
        for op in while_block.ops:
            for iname in op.input_names:
                for in_var_name in op.input(iname):
                    if in_var_name not in inner_outputs:
                        x_name_list.add(in_var_name)

            for oname in op.output_names:
                for out_var_name in op.output(oname):
                    inner_outputs.add(out_var_name)

        out_vars = []
        for inner_out_name in inner_outputs:
X
Xin Pan 已提交
569 570 571
            inner_var = parent_block._find_var_recursive(inner_out_name)
            if inner_var:
                out_vars.append(inner_var)
Y
Yang Yang(Tony) 已提交
572 573 574 575 576 577 578

        step_scope = parent_block.create_var(
            type=core.VarDesc.VarType.STEP_SCOPES)

        parent_block.append_op(
            type='while',
            inputs={
W
Wu Yi 已提交
579 580 581 582
                'X': [
                    parent_block._var_recursive(x_name)
                    for x_name in x_name_list
                ],
Y
Yang Yang(Tony) 已提交
583 584 585 586
                'Condition': [self.cond_var]
            },
            outputs={'Out': out_vars,
                     'StepScopes': [step_scope]},
C
chengduo 已提交
587 588
            attrs={'sub_block': while_block,
                   "is_test": self.is_test})
Y
Yang Yang(Tony) 已提交
589 590


591
def lod_rank_table(x, level=0):
592 593
    """
    LoD Rank Table Operator. Given an input variable **x** and a level number
Y
yangyaming 已提交
594 595
    of LoD, this layer creates a LodRankTable object. A LoDRankTable object
    contains a list of bi-element tuples. Each tuple consists of an index and
596
    a length, both of which are int type. Refering to specified level of LoD,
Y
yangyaming 已提交
597 598 599
    the index is the sequence index number and the length representes the
    sequence length. Please note that the list is ranked in descending order by
    the length. The following is an example:
Y
yangyaming 已提交
600 601 602 603

        .. code-block:: text

            x is a LoDTensor:
604 605
                x.lod = [[2,                1],
                         [5,             1, 1]]
Y
yangyaming 已提交
606 607
                x.data = [a, b, c, d, e, f, g]

Y
yangyaming 已提交
608 609 610
            1. set level to 0:
                Create lod rank table:
                    lod_rank_table_obj = lod_rank_table(x, level=0)
Y
yangyaming 已提交
611

Y
yangyaming 已提交
612 613 614 615 616 617 618 619 620
                Get:
                    lod_rank_table_obj.items() = [(0, 2), (1, 1)]

            2. set level to 1:
                Create lod rank table:
                    lod_rank_table_obj = lod_rank_table(x, level=1)

                Get:
                    lod_rank_table_obj.items() = [(0, 5), (1, 1), (2, 1)]
Y
yangyaming 已提交
621 622 623 624

    Args:
        x (Variable): Input variable, a LoDTensor based which to create the lod
            rank table.
Y
yangyaming 已提交
625 626
        level (int): Specify the LoD level, on which to create the lod rank
            table.
Y
yangyaming 已提交
627 628 629 630 631 632 633 634

    Returns:
        Variable: The created LoDRankTable object.

    Examples:
        .. code-block:: python

            x = fluid.layers.data(name='x', shape=[10],
635
                                  dtype='float32', lod_level=1)
Y
yangyaming 已提交
636
            out = layers.lod_rank_table(x=x, level=0)
637
    """
Y
Yu Yang 已提交
638 639 640
    helper = LayerHelper("lod_rank_table", **locals())
    table = helper.create_variable(
        type=core.VarDesc.VarType.LOD_RANK_TABLE,
Y
Yu Yang 已提交
641
        name=unique_name.generate("lod_rank_table"))
Y
Yu Yang 已提交
642 643 644 645 646 647
    helper.append_op(
        type='lod_rank_table',
        inputs={'X': x},
        outputs={'Out': table},
        attrs={'level': level})
    return table
Y
Yu Yang 已提交
648 649


Y
yuyang18 已提交
650
@templatedoc()
651
def max_sequence_len(rank_table):
Y
yuyang18 已提交
652 653 654 655 656 657 658 659
    """
    ${comment}

    >>> import paddle.fluid as fluid
    >>> x = fluid.layers.data(name='x', shape=[10], dtype='float32',
    >>>                       lod_level=1)
    >>> rank_table = layers.lod_rank_table(x=x, level=0)
    >>> max_seq_len = layers.max_sequence_len(rank_table)
Y
yangyaming 已提交
660 661

    Args:
Y
yuyang18 已提交
662
        rank_table(${rank_table_type}): ${rank_table_comment}.
Y
yangyaming 已提交
663 664

    Returns:
Y
yuyang18 已提交
665
        ${out_comment}.
F
fengjiayi 已提交
666 667
    """
    helper = LayerHelper("max_seqence_len", **locals())
X
Xin Pan 已提交
668
    res = helper.create_variable_for_type_inference(dtype="int64")
F
fengjiayi 已提交
669 670 671 672 673 674 675
    helper.append_op(
        type="max_sequence_len",
        inputs={"RankTable": rank_table},
        outputs={"Out": res})
    return res


676
def lod_tensor_to_array(x, table):
677
    """
F
fengjiayi 已提交
678 679
    Convert a LoDTensor to a LoDTensorArray.

680 681 682 683 684
    This function split a LoDTesnor to a LoDTensorArray according to its LoD
    information. LoDTensorArray is an alias of C++ std::vector<LoDTensor> in
    PaddlePaddle. The generated LoDTensorArray of this function can be further read
    or written by `read_from_array()` and `write_to_array()` operators. However,
    this function is generally an internal component of PaddlePaddle `DynamicRNN`.
F
fengjiayi 已提交
685
    Users should not use it directly.
686 687

    Args:
F
fengjiayi 已提交
688
        x (Variable|list): The LoDTensor to be converted to a LoDTensorArray.
689 690
        table (ParamAttr|list): The variable that stores the level of lod
                                which is ordered by sequence length in
691
                                descending order. It is generally generated
F
fengjiayi 已提交
692
                                by `layers.lod_rank_table()` API.
693 694

    Returns:
F
fengjiayi 已提交
695
        Variable: The LoDTensorArray that has been converted from the input tensor.
696 697 698 699 700 701 702

    Examples:
        .. code-block:: python

          x = fluid.layers.data(name='x', shape=[10])
          table = fluid.layers.lod_rank_table(x, level=0)
          array = fluid.layers.lod_tensor_to_array(x, table)
703
    """
704 705
    helper = LayerHelper("lod_tensor_to_array", **locals())
    array = helper.create_variable(
Y
Yu Yang 已提交
706
        name=unique_name.generate("lod_tensor_to_array"),
707
        type=core.VarDesc.VarType.LOD_TENSOR_ARRAY,
F
fengjiayi 已提交
708
        dtype=x.dtype)
709 710 711 712 713 714 715 716
    helper.append_op(
        type='lod_tensor_to_array',
        inputs={'X': x,
                'RankTable': table},
        outputs={'Out': array})
    return array


717
def array_to_lod_tensor(x, table):
718
    """Convert a LoD_Tensor_Aarry to an LoDTensor.
719 720

    Args:
721
        x (Variable|list): The lod tensor array to be converted to a tensor.
722 723 724 725 726 727 728 729 730 731 732 733 734 735 736
        table (ParamAttr|list): The variable that stores the level of lod
                                which is ordered by sequence length in
                                descending order.

    Returns:
        Variable: The variable of type tensor that has been converted
                  from an array.

    Examples:
        .. code-block:: python

          x = fluid.layers.data(name='x', shape=[10])
          table = fluid.layers.lod_rank_table(x, level=0)
          array = fluid.layers.lod_tensor_to_array(x, table)
          lod_tensor = fluid.layers.array_to_lod_tensor(array, table)
737
    """
738
    helper = LayerHelper("array_to_lod_tensor", **locals())
X
Xin Pan 已提交
739
    tmp = helper.create_variable_for_type_inference(dtype=x.dtype)
740 741 742 743 744 745 746 747
    helper.append_op(
        type="array_to_lod_tensor",
        inputs={'X': x,
                'RankTable': table},
        outputs={'Out': tmp})
    return tmp


748
def increment(x, value=1.0, in_place=True):
749
    """
S
sneaxiy 已提交
750
    This function performs an operation that increments the value in the
751
    input :math:`x` by an amount: :math:`value` as mentioned in the input
S
sneaxiy 已提交
752 753
    parameter. This operation is performed in-place by default. Notice that
    the number of elements in :math:`x` must be equal to 1.
754 755 756 757 758 759 760

    Args:
        x (Variable|list): The tensor that has the input values.
        value (float): The amount by which the values should be incremented.
        in_place (bool): If the increment should be performed in-place.

    Returns:
D
dzhwinter 已提交
761
        Variable: The elementwise-incremented object.
762 763 764 765

    Examples:
        .. code-block:: python

S
sneaxiy 已提交
766 767
          data = fluid.layers.data(name='data', shape=[1], dtype='float32',
                                   append_batch_size=False)
768
          data = fluid.layers.increment(x=data, value=3.0, in_place=True)
769
    """
Y
Yu Yang 已提交
770
    helper = LayerHelper("increment", **locals())
Y
Yang Yang(Tony) 已提交
771
    if not in_place:
X
Xin Pan 已提交
772
        out = helper.create_variable_for_type_inference(dtype=x.dtype)
Y
Yang Yang(Tony) 已提交
773 774
    else:
        out = x
Y
Yu Yang 已提交
775 776 777
    helper.append_op(
        type='increment',
        inputs={'X': [x]},
Y
Yang Yu 已提交
778
        outputs={'Out': [out]},
779
        attrs={'step': float(value)})
Y
Yang Yu 已提交
780
    return out
Y
Yu Yang 已提交
781 782


783
def array_write(x, i, array=None):
784 785 786 787 788
    """
    This function writes the given input variable to the specified position
    indicating by the arrary index to an output LOD_TENSOR_ARRAY. If the
    output LOD_TENSOR_ARRAY is not given(None), a new one will be created and
    returned.
789 790 791

    Args:
        x (Variable|list): The input tensor from which the data will be read.
792 793 794 795 796 797 798 799
        i (Variable|list): The index of the output LOD_TENSOR_ARRAY, pointing to
                           the position to which the input tensor will be
                           written.
        array (Variable|list): The output LOD_TENSOR_ARRAY to which the input
                               tensor will be written. If this parameter is
                               NONE, a new LOD_TENSOR_ARRAY will be created and
                               returned.

800
    Returns:
801
        Variable: The output LOD_TENSOR_ARRAY where the input tensor is written.
802 803

    Examples:
D
dzhwinter 已提交
804
        .. code-block:: python
805 806 807 808

          tmp = fluid.layers.zeros(shape=[10], dtype='int32')
          i = fluid.layers.fill_constant(shape=[1], dtype='int64', value=10)
          arr = layers.array_write(tmp, i=i)
809
    """
Y
Yu Yang 已提交
810 811 812 813 814
    helper = LayerHelper('array_write', **locals())
    if array is None:
        array = helper.create_variable(
            name="{0}.out".format(helper.name),
            type=core.VarDesc.VarType.LOD_TENSOR_ARRAY,
F
fengjiayi 已提交
815
            dtype=x.dtype)
Y
Yu Yang 已提交
816 817 818 819 820 821 822 823
    helper.append_op(
        type='write_to_array',
        inputs={'X': [x],
                'I': [i]},
        outputs={'Out': [array]})
    return array


824
def create_array(dtype):
825
    """
Q
qiaolongfei 已提交
826
    **Create LoDTensorArray**
827

Q
qiaolongfei 已提交
828 829
    This function creates an array of LOD_TENSOR_ARRAY . It is mainly used to
    implement RNN with array_write, array_read and While.
830 831

    Args:
Q
qiaolongfei 已提交
832
        dtype (int|float): The data type of the elements in the lod_tensor_array.
833 834

    Returns:
835
        Variable: The lod_tensor_array variable storing the elements of data type.
836 837 838 839 840 841 842

    Examples:
        .. code-block:: python

          data = fluid.layers.create_array(dtype='float32')

    """
Y
Yang Yang(Tony) 已提交
843 844 845 846 847 848 849
    helper = LayerHelper("array", **locals())
    return helper.create_variable(
        name="{0}.out".format(helper.name),
        type=core.VarDesc.VarType.LOD_TENSOR_ARRAY,
        dtype=dtype)


Y
yuyang18 已提交
850 851
@templatedoc()
def less_than(x, y, force_cpu=None, cond=None, **ignored):
852
    """
Y
yuyang18 已提交
853
    ${comment}
854

Y
yuyang18 已提交
855 856
    >>> import paddle.fluid as fluid
    >>> less = fluid.layers.less_than(x=label, y=limit)
857 858

    Args:
Y
yuyang18 已提交
859 860 861
        x(${x_type}): ${x_comment}.
        y(${y_type}): ${y_comment}.
        force_cpu(${force_cpu_type}): ${force_cpu_comment}.
862 863 864
        cond(Variable|None): Optional output variable to store the result of *less_than*

    Returns:
Y
yuyang18 已提交
865
        ${out_comment}.
866
    """
Y
Yang Yang(Tony) 已提交
867 868
    helper = LayerHelper("less_than", **locals())
    if cond is None:
X
Xin Pan 已提交
869
        cond = helper.create_variable_for_type_inference(dtype='bool')
Y
Yang Yang(Tony) 已提交
870 871
        cond.stop_gradient = True

Y
yuyang18 已提交
872 873 874 875 876 877
    attrs = dict()
    if force_cpu is not None:
        attrs['force_cpu'] = force_cpu
    elif force_init_on_cpu():
        attrs['force_cpu'] = force_init_on_cpu()

Y
Yang Yang(Tony) 已提交
878
    helper.append_op(
J
JiayiFeng 已提交
879 880 881 882
        type='less_than',
        inputs={'X': [x],
                'Y': [y]},
        outputs={'Out': [cond]},
Y
yuyang18 已提交
883
        attrs=attrs)
Y
Yang Yang(Tony) 已提交
884 885 886
    return cond


887
def equal(x, y, cond=None):
888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905
    """
    This layer returns the truth value of :math:`x == y` elementwise.

    Args:
        x(Variable): First operand of *equal*
        y(Variable): Second operand of *equal*
        cond(Variable|None): Optional output variable to store the result of *equal*

    Returns:
        Variable: The tensor variable storing the output of *equal*.

    Examples:
        .. code-block:: python

          less = fluid.layers.equal(x=label, y=limit)
    """
    helper = LayerHelper("equal", **locals())
    if cond is None:
X
Xin Pan 已提交
906
        cond = helper.create_variable_for_type_inference(dtype='bool')
907 908 909 910 911 912 913 914
        cond.stop_gradient = True

    helper.append_op(
        type='equal', inputs={'X': [x],
                              'Y': [y]}, outputs={'Out': [cond]})
    return cond


915
def array_read(array, i):
916 917
    """
    This function performs the operation to read the data in as an
918
    LOD_TENSOR_ARRAY.
919 920 921 922 923 924

    .. code-block:: text

        Given:

        array = [0.6, 0.1, 0.3, 0.1]
925

926
        And:
927

928 929 930 931 932 933
        i = 2

        Then:

        output = 0.3

K
kavyasrinet 已提交
934
    Args:
935 936 937
        array (Variable|list): The input tensor that store data to be read.
        i (Variable|list): The index of the data to be read from input array.

K
kavyasrinet 已提交
938 939
    Returns:
        Variable: The tensor type variable that has the data written to it.
940

K
kavyasrinet 已提交
941
    Examples:
942 943
        .. code-block:: python

Z
zhaoyuchen 已提交
944
          array = fluid.layers.create_array(dtype='float32')
K
kavyasrinet 已提交
945
          i = fluid.layers.fill_constant(shape=[1], dtype='int64', value=10)
Z
zhaoyuchen 已提交
946
          item = fluid.layers.array_read(array, i)
947
    """
Y
Yu Yang 已提交
948 949 950 951 952
    helper = LayerHelper('array_read', **locals())
    if not isinstance(
            array,
            Variable) or array.type != core.VarDesc.VarType.LOD_TENSOR_ARRAY:
        raise TypeError("array should be tensor array vairable")
X
Xin Pan 已提交
953
    out = helper.create_variable_for_type_inference(dtype=array.dtype)
Y
Yu Yang 已提交
954 955 956 957 958 959
    helper.append_op(
        type='read_from_array',
        inputs={'X': [array],
                'I': [i]},
        outputs={'Out': [out]})
    return out
Y
Yang Yu 已提交
960 961


962
def shrink_memory(x, i, table):
963
    """
Y
yuyang18 已提交
964
    This function creates an operator to shrink rnn memory using the RankTable
965
    as mentioned in the input parameter.
Y
yuyang18 已提交
966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985

    NOTE: This API is very low-level API. It is used by DynamicRNN only.

    Since the Dynamic RNN uses no-padding way to implement RNN. The sequence
    will be sorted by order, and the length of valid memory will be shrink after
    each time step.

    Args:
        x(Variable): The memory object in the previous time step.
        i(Variable): The step count variable. A int scalar as LoDTensor.
        table(Variable): The RNNRankTable object.

    Returns:
        the memory variable after shrink.

    Examples:

        Since this API is very low level API. The example is not provided.
        Please reference the implementation of class DynamicRNN for detail
        usage.
986
    """
Y
Yang Yu 已提交
987
    helper = LayerHelper('shrink_memory', **locals())
X
Xin Pan 已提交
988
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
Y
Yang Yu 已提交
989
    helper.append_op(
Y
Yang Yu 已提交
990
        type='shrink_rnn_memory',
Y
Yang Yu 已提交
991 992 993 994 995 996
        inputs={'X': [x],
                'I': [i],
                'RankTable': [table]},
        outputs={'Out': [out]},
        attrs={})
    return out
Y
Yang Yu 已提交
997 998


999
def array_length(array):
1000
    """
Q
qiaolongfei 已提交
1001
    **Get the Length of Input LoDTensorArray**
1002 1003

    This function performs the operation to find the length of the input
1004
    LOD_TENSOR_ARRAY.
K
kavyasrinet 已提交
1005

1006 1007
    Related API: array_read, array_write, While.

K
kavyasrinet 已提交
1008 1009 1010 1011 1012 1013 1014 1015
    Args:
        array (LOD_TENSOR_ARRAY): The input array that will be used
                                  to compute the length.

    Returns:
        Variable: The length of the input LoDTensorArray.

    Examples:
Q
qiaolongfei 已提交
1016
        .. code-block:: python
K
kavyasrinet 已提交
1017 1018 1019 1020 1021

          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)
Q
qiaolongfei 已提交
1022

1023
    """
Y
Yang Yu 已提交
1024
    helper = LayerHelper('array_length', **locals())
X
Xin Pan 已提交
1025
    tmp = helper.create_variable_for_type_inference(dtype='int64')
Y
Yang Yu 已提交
1026 1027 1028 1029
    tmp.stop_gradient = True
    helper.append_op(
        type='lod_array_length', inputs={'X': [array]}, outputs={'Out': [tmp]})
    return tmp
Y
Yu Yang 已提交
1030 1031 1032


class ConditionalBlockGuard(BlockGuard):
F
fengjiayi 已提交
1033
    """
1034 1035 1036
    ConditionalBlockGuard is derived from BlockGuard. It is dedicated for
    holding a ConditionalBlock, and helping users entering and exiting the
    ConditionalBlock via Python's 'with' keyword. However, ConditionalBlockGuard
F
fengjiayi 已提交
1037 1038 1039
    is generally an internal component of IfElse, users should not use it directly.
    """

Y
Yu Yang 已提交
1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055
    def __init__(self, block):
        if not isinstance(block, ConditionalBlock):
            raise TypeError("block should be conditional block")
        super(ConditionalBlockGuard, self).__init__(block.helper.main_program)
        self.block = block

    def __enter__(self):
        return super(ConditionalBlockGuard, self).__enter__()

    def __exit__(self, exc_type, exc_val, exc_tb):
        self.block.complete()
        return super(ConditionalBlockGuard, self).__exit__(exc_type, exc_val,
                                                           exc_tb)


class ConditionalBlock(object):
Y
Yan Chunwei 已提交
1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080
    '''
    **ConditionalBlock**

    ConditionalBlock is an operator that bind a block to a specific condition,
    if the condition matches, the corresponding block will be executed.

    Args:
        inputs (Variable): bool conditions.
        is_scalar_condition (bool): whether the branch is controled by a scalar.
        name(str): name of this ConditionalBlock.

    Examples:
        .. code-block:: python

             cond = layers.less_than(x=label, y=limit)
             true_image, false_image = layers.split_lod_tensor(
                 input=image, mask=cond)
             true_cond = layers.ConditionalBlock([true_image])

             with true_cond.block():
                 ...
             with false_cond.block():
                 ...
    '''

1081
    def __init__(self, inputs, is_scalar_condition=False, name=None):
Y
Yu Yang 已提交
1082 1083 1084 1085
        for each_input in inputs:
            if not isinstance(each_input, Variable):
                raise TypeError("Each input should be variable")
        self.inputs = inputs
1086
        self.is_scalar_condition = is_scalar_condition
1087
        self.helper = LayerHelper('conditional_block', name=name)
Y
Yu Yang 已提交
1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111

    def block(self):
        return ConditionalBlockGuard(self)

    def complete(self):
        inside_block = self.helper.main_program.current_block()
        parent_block = self.helper.main_program.block(inside_block.parent_idx)

        intermediate = set()
        params = set()

        for each_op in inside_block.ops:
            assert isinstance(each_op, Operator)
            for iname in each_op.input_names:
                for in_var_name in each_op.input(iname):
                    if in_var_name not in intermediate:
                        params.add(in_var_name)

            for oname in each_op.output_names:
                for out_var_name in each_op.output(oname):
                    intermediate.add(out_var_name)
        input_set = set([ipt.name for ipt in self.inputs])

        param_list = [
W
Wu Yi 已提交
1112
            parent_block._var_recursive(each_name) for each_name in params
Y
Yu Yang 已提交
1113 1114 1115
            if each_name not in input_set
        ]

X
Xin Pan 已提交
1116 1117 1118 1119 1120
        out_list = []
        for inner_out_name in intermediate:
            inner_var = parent_block._find_var_recursive(inner_out_name)
            if inner_var:
                out_list.append(inner_var)
Y
Yu Yang 已提交
1121 1122

        step_scope = parent_block.create_var(
1123
            type=core.VarDesc.VarType.STEP_SCOPES)
Y
Yu Yang 已提交
1124 1125 1126
        parent_block.append_op(
            type='conditional_block',
            inputs={
1127 1128
                'Cond': self.inputs,
                'Input': param_list,
Y
Yu Yang 已提交
1129 1130 1131
            },
            outputs={'Out': out_list,
                     'Scope': [step_scope]},
1132 1133 1134 1135 1136 1137 1138
            attrs={
                'sub_block': inside_block,
                'is_scalar_condition': self.is_scalar_condition
            })


class Switch(object):
Q
qiaolongfei 已提交
1139
    """
Q
qiaolongfei 已提交
1140 1141
    Switch class works just like a `if-elif-else`. Can be used in learning rate scheduler
    to modify learning rate
Q
qiaolongfei 已提交
1142 1143 1144 1145

    The Semantics:

    1. A `switch` control-flow checks cases one-by-one.
Q
qiaolongfei 已提交
1146

Q
qiaolongfei 已提交
1147
    2. The condition of each case is a boolean value, which is a scalar Variable.
Q
qiaolongfei 已提交
1148 1149 1150 1151

    3. It runs the first matched case, or the default case if there is one.

    4. Once it matches a case, it runs the corresponding branch and only that branch.
Q
qiaolongfei 已提交
1152 1153 1154 1155

    Examples:
        .. code-block:: python

Q
qiaolongfei 已提交
1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167
            lr = fluid.layers.tensor.create_global_var(
                shape=[1],
                value=0.0,
                dtype='float32',
                persistable=True,
                name="learning_rate")
            one_var = tensor.fill_constant(
                shape=[1], dtype='float32', value=1.0)
            two_var = tensor.fill_constant(
                shape=[1], dtype='float32', value=2.0)

            with fluid.layers.control_flow.Switch() as switch:
Q
qiaolongfei 已提交
1168
                with switch.case(global_step == zero_var):
Q
qiaolongfei 已提交
1169 1170 1171
                    fluid.layers.tensor.assign(input=one_var, output=lr)
                with switch.default():
                    fluid.layers.tensor.assign(input=two_var, output=lr)
Q
qiaolongfei 已提交
1172 1173 1174

    """

1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203
    def __init__(self, name=None):
        self.helper = LayerHelper('switch', name=name)
        self.inside_scope = False
        self.pre_not_conditions = []

    def case(self, condition):
        """create a new block for this condition
        """
        if not self.inside_scope:
            raise ValueError("case should be called inside with")

        if len(self.pre_not_conditions) == 0:
            cond_block = ConditionalBlock([condition], is_scalar_condition=True)
            not_cond = logical_not(x=condition)
            self.pre_not_conditions.append(not_cond)
        else:
            pre_cond_num = len(self.pre_not_conditions)
            pre_not_cond = self.pre_not_conditions[pre_cond_num - 1]
            new_not_cond = logical_and(
                x=pre_not_cond, y=logical_not(x=condition))
            self.pre_not_conditions.append(new_not_cond)
            cond_block = ConditionalBlock(
                [logical_and(
                    x=pre_not_cond, y=condition)],
                is_scalar_condition=True)

        return ConditionalBlockGuard(cond_block)

    def default(self):
Q
qiaolongfei 已提交
1204 1205
        """
        create a default case for this switch
1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228
        """
        pre_cond_num = len(self.pre_not_conditions)
        if pre_cond_num == 0:
            raise ValueError("there should be at least one condition")
        cond_block = ConditionalBlock(
            [self.pre_not_conditions[pre_cond_num - 1]],
            is_scalar_condition=True)
        return ConditionalBlockGuard(cond_block)

    def __enter__(self):
        """
        set flag that now is inside switch.block {}
        :return:
        """
        self.inside_scope = True
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        self.inside_scope = False
        if exc_type is not None:
            return False  # re-raise exception

        return True
Y
Yu Yang 已提交
1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264


class IfElseBlockGuard(object):
    def __init__(self, is_true, ifelse):
        if not isinstance(ifelse, IfElse):
            raise TypeError("ifelse must be an instance of IfElse class")

        if ifelse.status != IfElse.OUT_IF_ELSE_BLOCKS:
            raise ValueError("You cannot invoke IfElse.block() inside a block")

        self.is_true = is_true
        self.ie = ifelse
        if is_true:
            self.cond_block = ifelse.conditional_true_block
        else:
            self.cond_block = ifelse.conditional_false_block

        if not isinstance(self.cond_block, ConditionalBlock):
            raise TypeError("Unexpected situation")

        self.cond_block = self.cond_block.block()

    def __enter__(self):
        self.ie.status = IfElse.IN_IF_ELSE_TRUE_BLOCKS if self.is_true else IfElse.IN_IF_ELSE_FALSE_BLOCKS
        self.cond_block.__enter__()

    def __exit__(self, exc_type, exc_val, exc_tb):
        if not self.cond_block.__exit__(exc_type, exc_val, exc_tb):
            # re-raise inside exception
            return False
        if len(self.ie.output_table[1 if self.is_true else 0]) == 0:
            raise ValueError("Must set output inside block")
        self.ie.status = IfElse.OUT_IF_ELSE_BLOCKS


class IfElse(object):
X
Xin Pan 已提交
1265 1266 1267 1268 1269 1270 1271 1272 1273
    """
    if-else control flow.

    Args:
        cond (Variable): condition used to compare.
        name (str, default None): The name of this layer.

    Examples:
          .. code-block:: python
X
Xin Pan 已提交
1274

X
improve  
Xin Pan 已提交
1275
            limit = fluid.layers.fill_constant_batch_size_like(
X
Xin Pan 已提交
1276
                input=label, dtype='int64', shape=[1], value=5.0)
X
improve  
Xin Pan 已提交
1277 1278
            cond = fluid.layers.less_than(x=label, y=limit)
            ie = fluid.layers.IfElse(cond)
X
Xin Pan 已提交
1279 1280
            with ie.true_block():
                true_image = ie.input(image)
X
improve  
Xin Pan 已提交
1281 1282
                hidden = fluid.layers.fc(input=true_image, size=100, act='tanh')
                prob = fluid.layers.fc(input=hidden, size=10, act='softmax')
X
Xin Pan 已提交
1283 1284 1285 1286
                ie.output(prob)

            with ie.false_block():
                false_image = ie.input(image)
X
improve  
Xin Pan 已提交
1287 1288 1289
                hidden = fluid.layers.fc(
                    input=false_image, size=200, act='tanh')
                prob = fluid.layers.fc(input=hidden, size=10, act='softmax')
X
Xin Pan 已提交
1290 1291 1292
                ie.output(prob)
            prob = ie()
    """
Y
Yu Yang 已提交
1293 1294 1295 1296
    OUT_IF_ELSE_BLOCKS = 0
    IN_IF_ELSE_TRUE_BLOCKS = 1
    IN_IF_ELSE_FALSE_BLOCKS = 2

1297
    def __init__(self, cond, name=None):
Y
Yu Yang 已提交
1298 1299
        if not isinstance(cond, Variable):
            raise TypeError("cond must be a Variable")
1300
        self.helper = LayerHelper('ifelse', name=name)
Y
Yu Yang 已提交
1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311
        self.cond = cond
        self.input_table = {}
        self.status = IfElse.OUT_IF_ELSE_BLOCKS
        self.conditional_true_block = ConditionalBlock(inputs=[self.cond])
        self.conditional_false_block = ConditionalBlock(inputs=[self.cond])
        self.output_table = ([], [])  # (true_outs, false_outs)

    def input(self, x):
        if self.status == IfElse.OUT_IF_ELSE_BLOCKS:
            raise ValueError("input must in true/false blocks")
        if id(x) not in self.input_table:
1312
            parent_block = self._parent_block()
Y
Yu Yang 已提交
1313
            out_true = parent_block.create_var(
Y
Yu Yang 已提交
1314
                name=unique_name.generate('ifelse_input' + self.helper.name),
F
fengjiayi 已提交
1315
                dtype=x.dtype)
Y
Yu Yang 已提交
1316 1317

            out_false = parent_block.create_var(
Y
Yu Yang 已提交
1318
                name=unique_name.generate('ifelse_input' + self.helper.name),
F
fengjiayi 已提交
1319
                dtype=x.dtype)
Y
Yu Yang 已提交
1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337
            parent_block.append_op(
                type='split_lod_tensor',
                inputs={
                    'X': x,
                    'Mask': self.cond,
                },
                outputs={'OutTrue': out_true,
                         'OutFalse': out_false},
                attrs={'level': 0})
            self.input_table[id(x)] = (out_true, out_false)
        else:
            out_true, out_false = self.input_table[id(x)]

        if self.status == IfElse.IN_IF_ELSE_TRUE_BLOCKS:
            return out_true
        else:
            return out_false

1338
    def _parent_block(self):
Y
Yu Yang 已提交
1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353
        current_block = self.helper.main_program.current_block()
        return self.helper.main_program.block(current_block.parent_idx)

    def true_block(self):
        return IfElseBlockGuard(True, self)

    def false_block(self):
        return IfElseBlockGuard(False, self)

    def output(self, *outs):
        if self.status == self.OUT_IF_ELSE_BLOCKS:
            raise ValueError("output can only be invoked in the sub-block")

        out_table = self.output_table[1 if self.status ==
                                      self.IN_IF_ELSE_TRUE_BLOCKS else 0]
1354
        parent_block = self._parent_block()
Y
Yu Yang 已提交
1355 1356 1357 1358 1359
        for each_out in outs:
            if not isinstance(each_out, Variable):
                raise TypeError("Each output should be a variable")
            # create outside tensor
            outside_out = parent_block.create_var(
Y
Yu Yang 已提交
1360 1361
                name=unique_name.generate("_".join(
                    [self.helper.name, 'output'])),
F
fengjiayi 已提交
1362
                dtype=each_out.dtype)
Y
Yu Yang 已提交
1363 1364 1365
            out_table.append(outside_out)

            # assign local var to outside
1366
            assign(input=each_out, output=outside_out)
Y
Yu Yang 已提交
1367 1368 1369 1370

    def __call__(self):
        if self.status != self.OUT_IF_ELSE_BLOCKS:
            raise ValueError("IfElse::__call__ must be out of sub-block")
1371
        false_len, true_len = list(map(len, self.output_table))
Y
Yu Yang 已提交
1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389
        if false_len == 0 and true_len == 0:
            raise ValueError("Must invoke true_block/false_block before "
                             "__call__")
        elif false_len != true_len and false_len != 0 and true_len != 0:
            raise ValueError("The output side must be same")
        elif false_len == 0 or true_len == 0:
            return self.output_table[0 if false_len != 0 else 1]

        # else none of false_len/true_len is zero
        # merge together
        rlist = []
        for false_var, true_var in zip(*self.output_table):
            rlist.append(
                merge_lod_tensor(
                    in_true=true_var,
                    in_false=false_var,
                    mask=self.cond,
                    x=self.cond,
1390
                    level=0))
Y
Yu Yang 已提交
1391
        return rlist
1392 1393 1394


class DynamicRNN(object):
Y
yuyang18 已提交
1395
    """
Y
yuyang18 已提交
1396 1397 1398
    The dynamic RNN can process a batch of sequence data. The length of each
    sample sequence can be different. This API automatically process them in
    batch.
Y
yuyang18 已提交
1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425

    The input lod must be set. Please reference `lod_tensor`

    >>> import paddle.fluid as fluid
    >>> data = fluid.layers.data(name='sentence', dtype='int64', lod_level=1)
    >>> embedding = fluid.layers.embedding(input=data, size=[65535, 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)
    >>>
    >>> # last is the last time step of rnn. It is the encoding result.
    >>> last = fluid.layers.sequence_last_step(drnn())

    The dynamic RNN will unfold sequence into timesteps. Users need to define
    how to process each time step during the :code:`with` block.

    The `memory` is used staging data cross time step. The initial value of
    memory can be zero or another variable.

    The dynamic RNN can mark multiple variables as its output. Use `drnn()` to
    get the output sequence.
C
chengduoZH 已提交
1426 1427 1428 1429
    
    NOTES:
        Currently it is not supported that setting is_sparse to True of any 
        layers within DynamicRNN.
Y
yuyang18 已提交
1430
    """
1431 1432 1433 1434
    BEFORE_RNN = 0
    IN_RNN = 1
    AFTER_RNN = 2

1435 1436
    def __init__(self, name=None):
        self.helper = LayerHelper('dynamic_rnn', name=name)
1437 1438 1439 1440
        self.status = DynamicRNN.BEFORE_RNN
        self.lod_rank_table = None
        self.max_seq_len = None
        self.step_idx = None
1441
        self.zero_idx = None
1442 1443 1444
        self.mem_dict = dict()
        self.output_array = []
        self.outputs = []
X
Xin Pan 已提交
1445
        self.cond = self.helper.create_variable_for_type_inference(dtype='bool')
1446 1447 1448 1449 1450 1451
        self.cond.stop_gradient = False
        self.while_op = While(self.cond)
        self.input_array = []
        self.mem_link = []

    def step_input(self, x):
Y
yuyang18 已提交
1452 1453
        """
        Mark a sequence as a dynamic RNN input.
H
haowang101779990 已提交
1454

Y
yuyang18 已提交
1455 1456 1457 1458 1459 1460
        Args:
            x(Variable): The input sequence.

        Returns:
            The current timestep in the input sequence.
        """
1461 1462 1463
        self._assert_in_rnn_block_("step_input")
        if not isinstance(x, Variable):
            raise TypeError(
1464
                "step_input() can only take a Variable as its input.")
1465 1466 1467
        parent_block = self._parent_block_()
        if self.lod_rank_table is None:
            self.lod_rank_table = parent_block.create_var(
Y
Yu Yang 已提交
1468
                name=unique_name.generate('lod_rank_table'),
1469 1470 1471 1472 1473 1474 1475
                type=core.VarDesc.VarType.LOD_RANK_TABLE)
            self.lod_rank_table.stop_gradient = True
            parent_block.append_op(
                type='lod_rank_table',
                inputs={"X": x},
                outputs={"Out": self.lod_rank_table})
            self.max_seq_len = parent_block.create_var(
Y
Yu Yang 已提交
1476 1477
                name=unique_name.generate('dynamic_rnn_max_seq_len'),
                dtype='int64')
1478 1479 1480 1481 1482 1483 1484 1485 1486 1487
            self.max_seq_len.stop_gradient = False
            parent_block.append_op(
                type='max_sequence_len',
                inputs={'RankTable': self.lod_rank_table},
                outputs={"Out": self.max_seq_len})
            self.cond.stop_gradient = True
            parent_block.append_op(
                type='less_than',
                inputs={'X': self.step_idx,
                        'Y': self.max_seq_len},
J
JiayiFeng 已提交
1488 1489
                outputs={'Out': self.cond},
                attrs={'force_cpu': True})
1490 1491

        input_array = parent_block.create_var(
Y
Yu Yang 已提交
1492
            name=unique_name.generate('dynamic_rnn_input_array'),
1493 1494 1495 1496 1497 1498 1499 1500
            type=core.VarDesc.VarType.LOD_TENSOR_ARRAY,
            dtype=x.dtype)
        self.input_array.append((input_array, x.dtype))
        parent_block.append_op(
            type='lod_tensor_to_array',
            inputs={'X': x,
                    'RankTable': self.lod_rank_table},
            outputs={'Out': input_array})
1501
        return array_read(array=input_array, i=self.step_idx)
1502

Y
yangyaming 已提交
1503
    def static_input(self, x):
Y
yuyang18 已提交
1504 1505 1506
        """
        Mark a variable as a RNN input. The input will not be scattered into
        time steps.
H
haowang101779990 已提交
1507

Y
yuyang18 已提交
1508 1509 1510 1511 1512 1513
        Args:
            x(Variable): The input variable.

        Returns:
            The input variable that can access in RNN.
        """
Y
yangyaming 已提交
1514 1515 1516 1517 1518 1519 1520 1521 1522
        self._assert_in_rnn_block_("static_input")
        if not isinstance(x, Variable):
            raise TypeError(
                "static_input() can only take a Variable as its input")
        if self.lod_rank_table is None:
            raise RuntimeError(
                "static_input() must be called after step_input().")
        parent_block = self._parent_block_()
        x_reordered = parent_block.create_var(
Y
Yu Yang 已提交
1523
            name=unique_name.generate("dynamic_rnn_static_input_reordered"),
Y
yangyaming 已提交
1524 1525 1526 1527 1528 1529 1530 1531 1532
            type=core.VarDesc.VarType.LOD_TENSOR,
            dtype=x.dtype)
        parent_block.append_op(
            type='reorder_lod_tensor_by_rank',
            inputs={'X': [x],
                    'RankTable': [self.lod_rank_table]},
            outputs={'Out': [x_reordered]})
        return shrink_memory(x_reordered, self.step_idx, self.lod_rank_table)

S
rename  
sneaxiy 已提交
1533
    @signature_safe_contextmanager
1534
    def block(self):
Y
yuyang18 已提交
1535
        """
1536
        The block for user to define operators in RNN.
Y
yuyang18 已提交
1537
        """
1538 1539
        if self.status != DynamicRNN.BEFORE_RNN:
            raise ValueError("rnn.block() can only be invoke once")
1540 1541
        self.step_idx = fill_constant(
            shape=[1], dtype='int64', value=0, force_cpu=True)
1542 1543 1544 1545
        self.step_idx.stop_gradient = False
        self.status = DynamicRNN.IN_RNN
        with self.while_op.block():
            yield
1546
            increment(x=self.step_idx, value=1.0, in_place=True)
1547 1548

            for new_mem, mem_array in self.mem_link:
1549 1550
                array_write(x=new_mem, i=self.step_idx, array=mem_array)

J
JiayiFeng 已提交
1551 1552 1553 1554 1555
            less_than(
                x=self.step_idx,
                y=self.max_seq_len,
                force_cpu=True,
                cond=self.cond)
1556 1557 1558 1559 1560

        self.status = DynamicRNN.AFTER_RNN
        for each_array in self.output_array:
            self.outputs.append(
                array_to_lod_tensor(
1561
                    x=each_array, table=self.lod_rank_table))
1562 1563

    def __call__(self, *args, **kwargs):
Y
yuyang18 已提交
1564 1565 1566
        """
        Get the output of RNN. This API should only be invoked after RNN.block()
        """
1567
        if self.status != DynamicRNN.AFTER_RNN:
1568 1569
            raise ValueError(("Output of the dynamic RNN can only be visited "
                              "outside the rnn block."))
1570 1571 1572 1573 1574
        if len(self.outputs) == 1:
            return self.outputs[0]
        else:
            return self.outputs

1575 1576 1577 1578 1579 1580
    def memory(self,
               init=None,
               shape=None,
               value=0.0,
               need_reorder=False,
               dtype='float32'):
Y
yuyang18 已提交
1581
        """
Y
yuyang18 已提交
1582
        Create a memory variable for dynamic rnn.
Y
yuyang18 已提交
1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630

        If the :code:`init` is not None, :code:`memory` will be initialized by
        this variable. The :code:`need_reorder` is used to reorder the memory as
        the input variable. It should be set to true when the initialized memory
        depends on the input sample.

        For example,

        >>> import paddle.fluid as fluid
        >>> sentence = fluid.layers.data(
        >>>                 name='sentence', dtype='float32', shape=[32])
        >>> boot_memory = fluid.layers.data(
        >>>                 name='boot', dtype='float32', shape=[10])
        >>>
        >>> 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()


        Otherwise, if :code:`shape`, :code:`value`, :code:`dtype` are set, the
        :code:`memory` will be initialized by this :code:`value`.

        For example,

        >>> import paddle.fluid as fluid
        >>> sentence = fluid.layers.data(
        >>>                 name='sentence', dtype='float32', shape=[32])
        >>>
        >>> 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()


        Args:
            init(Variable|None): The initialized variable.

H
haowang101779990 已提交
1631
            shape(list|tuple): The memory shape. NOTE the shape does not contain batch_size.
Y
yuyang18 已提交
1632 1633 1634

            value(float): the initalized value.

H
haowang101779990 已提交
1635
            need_reorder(bool): True if the initialized memory depends on the input sample.
Y
yuyang18 已提交
1636 1637 1638 1639

            dtype(str|numpy.dtype): The data type of the initialized memory.

        Returns:
1640
            The memory variable.
Y
yuyang18 已提交
1641
        """
1642
        self._assert_in_rnn_block_('memory')
1643
        self._init_zero_idx_()
1644 1645 1646 1647 1648
        if init is not None:
            if not isinstance(init, Variable):
                raise TypeError(
                    "The input arg `init` of memory() must be a Variable")
            parent_block = self._parent_block_()
1649 1650 1651 1652 1653 1654 1655 1656
            init_tensor = init
            if need_reorder == True:
                if self.lod_rank_table is None:
                    raise ValueError(
                        'If set need_reorder to True, make sure step_input be '
                        'invoked before '
                        'memory(init=init, need_reordered=True, ...).')
                init_reordered = parent_block.create_var(
Y
Yu Yang 已提交
1657
                    name=unique_name.generate('dynamic_rnn_mem_init_reordered'),
1658 1659 1660 1661 1662 1663 1664 1665 1666 1667
                    type=core.VarDesc.VarType.LOD_TENSOR,
                    dtype=init.dtype)
                parent_block.append_op(
                    type='reorder_lod_tensor_by_rank',
                    inputs={
                        'X': [init_tensor],
                        'RankTable': [self.lod_rank_table]
                    },
                    outputs={'Out': [init_reordered]})
                init_tensor = init_reordered
1668
            mem_array = parent_block.create_var(
Y
Yu Yang 已提交
1669
                name=unique_name.generate('dynamic_rnn_mem_array'),
1670 1671 1672 1673
                type=core.VarDesc.VarType.LOD_TENSOR_ARRAY,
                dtype=init.dtype)
            parent_block.append_op(
                type='write_to_array',
1674
                inputs={'X': init_tensor,
1675 1676
                        'I': self.zero_idx},
                outputs={'Out': mem_array})
1677
            retv = array_read(array=mem_array, i=self.step_idx)
1678
            retv = shrink_memory(
1679
                x=retv, i=self.step_idx, table=self.lod_rank_table)
1680 1681 1682 1683 1684 1685 1686 1687 1688
            self.mem_dict[retv.name] = mem_array
            return retv
        else:
            if len(self.input_array) == 0:
                raise ValueError(
                    "step_input should be invoked before memory(shape=..., value=...)"
                )
            parent_block = self._parent_block_()
            init = parent_block.create_var(
Y
Yu Yang 已提交
1689
                name=unique_name.generate('mem_init'), dtype=dtype)
1690
            arr, dtype = self.input_array[0]
Y
Yu Yang 已提交
1691 1692
            in0 = parent_block.create_var(
                name=unique_name.generate('in0'), dtype=dtype)
1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709
            parent_block.append_op(
                type='read_from_array',
                inputs={'X': [arr],
                        'I': [self.zero_idx]},
                outputs={'Out': [in0]})
            parent_block.append_op(
                type='fill_constant_batch_size_like',
                inputs={'Input': [in0]},
                outputs={'Out': [init]},
                attrs={
                    'shape': [-1] + shape,
                    'value': float(value),
                    'dtype': init.dtype
                })
            return self.memory(init=init)

    def update_memory(self, ex_mem, new_mem):
Y
yuyang18 已提交
1710 1711 1712
        """
        Update the memory from ex_mem to new_mem. NOTE that the shape and data
        type of :code:`ex_mem` and :code:`new_mem` must be same.
H
haowang101779990 已提交
1713
        
Y
yuyang18 已提交
1714 1715 1716 1717 1718 1719 1720
        Args:
            ex_mem(Variable): the memory variable.
            new_mem(Variable): the plain variable generated in RNN block.

        Returns:
            None
        """
1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737
        self._assert_in_rnn_block_('update_memory')
        if not isinstance(ex_mem, Variable):
            raise TypeError("The input arg `ex_mem` of update_memory() must "
                            "be a Variable")
        if not isinstance(new_mem, Variable):
            raise TypeError("The input arg `new_mem` of update_memory() must "
                            "be a Variable")

        mem_array = self.mem_dict.get(ex_mem.name, None)
        if mem_array is None:
            raise ValueError("Please invoke memory before update_memory")
        if self.lod_rank_table is None:
            raise ValueError("Please invoke step_input before update_memory")

        self.mem_link.append((new_mem, mem_array))

    def output(self, *outputs):
Y
yuyang18 已提交
1738
        """
1739
        Mark the RNN output variables.
Y
yuyang18 已提交
1740 1741 1742 1743 1744 1745 1746

        Args:
            outputs: The output variables.

        Returns:
            None
        """
1747 1748 1749 1750
        self._assert_in_rnn_block_('output')
        parent_block = self._parent_block_()
        for each in outputs:
            outside_array = parent_block.create_var(
Y
Yu Yang 已提交
1751
                name=unique_name.generate("_".join(
1752 1753 1754 1755 1756 1757
                    [self.helper.name, "output_array", each.name])),
                type=core.VarDesc.VarType.LOD_TENSOR_ARRAY,
                dtype=each.dtype)
            array_write(x=each, i=self.step_idx, array=outside_array)
            self.output_array.append(outside_array)

1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773
    def _init_zero_idx_(self):
        if self.zero_idx is None:
            parent_block = self._parent_block_()
            self.zero_idx = parent_block.create_var(
                name=unique_name.generate('zero_idx'), dtype='int64')
            parent_block.append_op(
                type='fill_constant',
                inputs={},
                outputs={'Out': [self.zero_idx]},
                attrs={
                    'shape': [1],
                    'dtype': self.zero_idx.dtype,
                    'value': float(0),
                    'force_cpu': True
                })

1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785
    def _parent_block_(self):
        prog = self.helper.main_program
        parent_idx = prog.current_block().parent_idx
        assert parent_idx >= 0
        parent_block = prog.block(parent_idx)

        return parent_block

    def _assert_in_rnn_block_(self, method):
        if self.status != DynamicRNN.IN_RNN:
            raise ValueError("{0} can only be invoked inside rnn block.".format(
                method))
Y
Yang Yu 已提交
1786 1787


1788
@autodoc()
Y
Yang Yu 已提交
1789 1790 1791 1792 1793
def reorder_lod_tensor_by_rank(x, rank_table):
    helper = LayerHelper('reorder_lod_tensor_by_rank', **locals())
    helper.is_instance('x', Variable)
    helper.is_instance('rank_table', Variable)

X
Xin Pan 已提交
1794
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
Y
Yang Yu 已提交
1795 1796 1797 1798 1799 1800
    helper.append_op(
        type='reorder_lod_tensor_by_rank',
        inputs={'X': [x],
                'RankTable': [rank_table]},
        outputs={'Out': [out]})
    return out
1801 1802 1803 1804


def is_empty(x, cond=None, **ignored):
    """
F
fengjiayi 已提交
1805
    Test whether a Variable is empty.
1806 1807

    Args:
F
fengjiayi 已提交
1808
        x (Variable): The Variable to be tested.
1809
        cond (Variable|None): Output parameter. Returns the test result
F
fengjiayi 已提交
1810
                              of given 'x'. Default: None
1811 1812

    Returns:
F
fengjiayi 已提交
1813
        Variable: A bool scalar. True if 'x' is an empty Variable.
1814 1815 1816

    Raises:
        TypeError: If input cond is not a variable, or cond's dtype is
F
fengjiayi 已提交
1817
                   not bool.
1818 1819 1820 1821

    Examples:
        .. code-block:: python

F
fengjiayi 已提交
1822 1823 1824
          res = fluid.layers.is_empty(x=input)
          # or:
          fluid.layers.is_empty(x=input, cond=res)
1825 1826 1827
    """
    helper = LayerHelper("is_empty", **locals())
    if cond is None:
X
Xin Pan 已提交
1828
        cond = helper.create_variable_for_type_inference(dtype='bool')
1829 1830 1831 1832 1833 1834 1835 1836 1837
        cond.stop_gradient = True
    elif not isinstance(cond, Variable):
        raise TypeError("cond takes a variable")
    elif cond.dtype != 'bool':
        raise TypeError("The data type of cond must be bool")

    helper.append_op(
        type='is_empty', inputs={'X': [x]}, outputs={'Out': [cond]})
    return cond