tensor.py 50.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
#
Y
yuyang18 已提交
9
# Unlessf required by applicable law or agreed to in writing, software
D
dzhwinter 已提交
10 11 12 13 14
# 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.

15
from __future__ import print_function
16
from six.moves import reduce
Y
Yu Yang 已提交
17
from ..layer_helper import LayerHelper
18
from ..param_attr import ParamAttr
X
xuwei06 已提交
19 20
from ..framework import convert_np_dtype_to_dtype_
from ..framework import Variable
21
from ..initializer import Constant, force_init_on_cpu
22
from ..core import VarDesc
23
from .layer_function_generator import templatedoc
24
from ..data_feeder import check_type_and_dtype, check_type, check_dtype, convert_dtype
X
xuwei06 已提交
25
import numpy
26
import warnings
Y
Yu Yang 已提交
27 28

__all__ = [
L
li099 已提交
29 30 31
    'create_tensor', 'create_parameter', 'create_global_var', 'cast',
    'tensor_array_to_tensor', 'concat', 'sums', 'assign',
    'fill_constant_batch_size_like', 'fill_constant', 'argmin', 'argmax',
Z
zhoukunsheng 已提交
32
    'argsort', 'ones', 'zeros', 'reverse', 'has_inf', 'has_nan', 'isfinite',
33
    'range', 'linspace', 'zeros_like', 'ones_like', 'diag', 'eye'
Y
Yu Yang 已提交
34 35 36
]


X
xuwei06 已提交
37
def create_tensor(dtype, name=None, persistable=False):
38
    """
W
wangchaochaohu 已提交
39
    Create a variable, which will hold a Tensor with data type dtype.
40 41

    Args:
W
wangchaochaohu 已提交
42 43 44 45
        dtype(string|numpy.dtype): the data type of Tensor to be created, the
            data type is bool, float16, float32, float64, int8, int16, int32 and int64.
        name(string, optional): The default value is None.  Normally there is no need for 
            user to set this property.  For more information, please refer to :ref:`api_guide_Name`
Q
update  
qiaolongfei 已提交
46
        persistable(bool): Set the persistable flag of the create tensor.
W
wangchaochaohu 已提交
47
            default value is False.
48 49

    Returns:
W
wangchaochaohu 已提交
50
        Variable: The tensor to be created according to dtype.
51 52 53 54

    Examples:
        .. code-block:: python

55
          import paddle.fluid as fluid
56 57
          tensor = fluid.layers.create_tensor(dtype='float32')
    """
Y
Yu Yang 已提交
58
    helper = LayerHelper("create_tensor", **locals())
X
xuwei06 已提交
59 60
    return helper.create_variable(
        name=helper.name, dtype=dtype, persistable=persistable)
Y
Yu Yang 已提交
61 62


63 64
def create_parameter(shape,
                     dtype,
X
xuwei06 已提交
65
                     name=None,
66 67 68 69
                     attr=None,
                     is_bias=False,
                     default_initializer=None):
    """
70
    This function creates a parameter. The parameter is a learnable variable, which can have
Y
yuyang18 已提交
71 72 73 74 75
    gradient, and can be optimized.

    NOTE: this is a very low-level API. This API is useful when you create
    operator by your self. instead of using layers.

76 77 78 79 80 81 82
    Parameters:
        shape (list of int): Shape of the parameter
        dtype (str): Data type of the parameter
        name (str, optional): For detailed information, please refer to
           :ref:`api_guide_Name` . Usually name is no need to set and None by default.
        attr (ParamAttr, optional): Attributes of the parameter
        is_bias (bool, optional): This can affect which default initializer is chosen
83 84 85
                       when default_initializer is None. If is_bias,
                       initializer.Constant(0.0) will be used. Otherwise,
                       Xavier() will be used.
86
        default_initializer (Initializer, optional): Initializer for the parameter
87 88

    Returns:
89
        The created parameter.
Y
yuyang18 已提交
90 91

    Examples:
92 93
        .. code-block:: python

94
            import paddle.fluid as fluid
95 96
            import paddle.fluid.layers as layers
            W = layers.create_parameter(shape=[784, 200], dtype='float32')
97
    """
Q
Qiao Longfei 已提交
98
    helper = LayerHelper("create_parameter", **locals())
99
    if attr is None:
X
xuwei06 已提交
100
        attr = ParamAttr(name=name)
101 102 103 104
    return helper.create_parameter(attr, shape, dtype, is_bias,
                                   default_initializer)


105 106 107 108 109 110 111
def create_global_var(shape,
                      value,
                      dtype,
                      persistable=False,
                      force_cpu=False,
                      name=None):
    """
112
    This function creates a new tensor variable with value in the global block(block 0).
F
fengjiayi 已提交
113

114 115 116
    Parameters:
        shape (list of int): Shape of the variable
        value (float): The value of the variable. The new created
F
fengjiayi 已提交
117
                      variable will be filled with it.
118 119
        dtype (str): Data type of the variable
        persistable (bool, optional): If this variable is persistable.
F
fengjiayi 已提交
120
                           Default: False
121
        force_cpu (bool, optional): Force this variable to be on CPU.
F
fengjiayi 已提交
122
                         Default: False
123 124
        name (str, optional): For detailed information, please refer to
           :ref:`api_guide_Name` . Usually name is no need to set and None by default.
125 126

    Returns:
127
        Variable: The created Variable
F
fengjiayi 已提交
128 129 130 131

    Examples:
        .. code-block:: python

132
            import paddle.fluid as fluid
133 134 135
            import paddle.fluid.layers as layers
            var = layers.create_global_var(shape=[2,3], value=1.0, dtype='float32',
                                          persistable=True, force_cpu=True, name='new_var')
136
    """
Q
Qiao Longfei 已提交
137 138
    helper = LayerHelper("global_var", **locals())
    var = helper.create_global_variable(
M
minqiyang 已提交
139 140 141 142 143
        dtype=dtype,
        shape=shape,
        persistable=persistable,
        name=name,
        stop_gradient=True)
M
minqiyang 已提交
144 145 146
    helper.set_variable_initializer(
        var, initializer=Constant(
            value=float(value), force_cpu=force_cpu))
M
minqiyang 已提交
147

Q
Qiao Longfei 已提交
148 149 150
    return var


151
def cast(x, dtype):
Y
Yu Yang 已提交
152
    """
153 154 155
    This OP takes in the Variable :attr:`x` with :attr:`x.dtype` and casts it
    to the output with :attr:`dtype`. It's meaningless if the output dtype
    equals the input dtype, but it's fine if you do so.
Y
Yibing Liu 已提交
156 157

    Args:
158 159 160 161
        x(Variable): An input N-D Tensor with data type bool, float16,
            float32, float64, int32, int64, uint8.
        dtype(np.dtype|core.VarDesc.VarType|str): Data type of the output:
            bool, float15, float32, float64, int8, int32, int64, uint8.
Y
Yibing Liu 已提交
162 163

    Returns:
164
        Variable: A Tensor with the same shape as input's.
Y
Yibing Liu 已提交
165 166 167

    Examples:
        .. code-block:: python
F
fengjiayi 已提交
168

169
            import paddle.fluid as fluid
170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191
            import numpy as np

            place = fluid.core.CPUPlace()

            x_lod = fluid.data(name="x", shape=[2,2], lod_level=0)
            cast_res1 = fluid.layers.cast(x=x_lod, dtype="uint8")
            cast_res2 = fluid.layers.cast(x=x_lod, dtype=np.int32)

            exe = fluid.Executor(place)
            exe.run(fluid.default_startup_program())

            x_i_lod = fluid.core.LoDTensor()
            x_i_lod.set(np.array([[1.3,-2.4],[0,4]]).astype("float32"), place)
            x_i_lod.set_recursive_sequence_lengths([[0,2]])
            res1 = exe.run(fluid.default_main_program(), feed={'x':x_i_lod}, fetch_list=[cast_res1], return_numpy=False)
            res2 = exe.run(fluid.default_main_program(), feed={'x':x_i_lod}, fetch_list=[cast_res2], return_numpy=False)
            print(np.array(res1[0]), np.array(res1[0]).dtype)
            # [[  1 254]
            #  [  0   4]] uint8
            print(np.array(res2[0]), np.array(res2[0]).dtype)
            # [[ 1 -2]
            #  [ 0  4]] int32
Y
Yu Yang 已提交
192 193
    """
    helper = LayerHelper('cast', **locals())
194 195 196 197
    check_type_and_dtype(
        x, 'x', Variable,
        ['bool', 'float16', 'float32', 'float64', 'int32', 'int64', 'uint8'],
        'cast')
X
Xin Pan 已提交
198
    out = helper.create_variable_for_type_inference(dtype=dtype)
Y
Yu Yang 已提交
199 200 201 202 203 204 205 206 207
    helper.append_op(
        type='cast',
        inputs={'X': [x]},
        outputs={'Out': [out]},
        attrs={'in_dtype': x.dtype,
               'out_dtype': out.dtype})
    return out


208
def concat(input, axis=0, name=None):
Y
Yu Yang 已提交
209
    """
210 211
    **Concat**

212
    This OP concatenates the input along the axis.
213 214

    Args:
215 216
        input(list): List of input Tensors with data type float32, float64, int32,
            int64.
217
        axis(int32|Variable, optional):  A scalar with type ``int32`` or a ``Tensor`` with shape [1] and type ``int32``. Axis to compute indices along. The effective range
218 219 220 221 222
            is [-R, R), where R is Rank(x). when axis<0, it works the same way
            as axis+R. Default is 0.
        name (str, optional): The default value is None. Normally there is no
            need for user to set this property. For more information, please
            refer to :ref:`api_guide_Name`.
223 224

    Returns:
225
        Variable: A Tensor with the same data type as input's.
226 227 228

    Examples:
        .. code-block:: python
F
fengjiayi 已提交
229

230
            import paddle.fluid as fluid
231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252
            import numpy as np

            in1 = np.array([[1,2,3],
                            [4,5,6]])
            in2 = np.array([[11,12,13],
                            [14,15,16]])
            in3 = np.array([[21,22],
                            [23,24]])
            with fluid.dygraph.guard():
                x1 = fluid.dygraph.to_variable(in1)
                x2 = fluid.dygraph.to_variable(in2)
                x3 = fluid.dygraph.to_variable(in3)
                out1 = fluid.layers.concat(input=[x1,x2,x3], axis=-1)
                out2 = fluid.layers.concat(input=[x1,x2], axis=0)
                print(out1.numpy())
                # [[ 1  2  3 11 12 13 21 22]
                #  [ 4  5  6 14 15 16 23 24]]
                print(out2.numpy())
                # [[ 1  2  3]
                #  [ 4  5  6]
                #  [11 12 13]
                #  [14 15 16]]
Y
Yu Yang 已提交
253 254
    """
    helper = LayerHelper('concat', **locals())
255 256 257 258 259
    if not isinstance(input, list):
        warnings.warn(
            "The type of input in concat should be list, but received %s." %
            (type(input)))
        input = [input]
260 261 262 263 264
    for id, x in enumerate(input):
        check_type_and_dtype(
            x, 'input[' + str(id) + ']', Variable,
            ['float16', 'float32', 'float64', 'int32', 'int64'], 'concat')
    check_type(axis, 'axis', (int, Variable), 'concat')
265 266 267 268 269 270 271 272
    inputs = {'X': input}
    attrs = {}
    if isinstance(axis, Variable):
        axis.stop_gradient = True
        inputs['AxisTensor'] = axis
    else:
        attrs['axis'] = axis

X
Xin Pan 已提交
273
    out = helper.create_variable_for_type_inference(dtype=helper.input_dtype())
Y
Yu Yang 已提交
274
    helper.append_op(
275
        type='concat', inputs=inputs, outputs={'Out': [out]}, attrs=attrs)
Y
Yu Yang 已提交
276 277 278
    return out


G
Guo Sheng 已提交
279
def tensor_array_to_tensor(input, axis=1, name=None, use_stack=False):
L
li099 已提交
280
    """
G
Guo Sheng 已提交
281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330
    This function concatenates or stacks all tensors in the input LoDTensorArray
    along the axis mentioned and returns that as the output.

    For Example:

    .. code-block:: text

        Case 1:

            Given:

                input.data = {[[0.6, 0.1, 0.3],
                               [0.5, 0.3, 0.2]],
                              [[1.3],
                               [1.8]],
                              [[2.3, 2.1],
                               [2.5, 2.4]]}

                axis = 1, use_stack = False

            Then:

                output.data = [[0.6, 0.1, 0.3, 1.3, 2.3, 2.1],
                               [0.5, 0.3, 0.2, 1.8, 2.5, 2.4]]

                output_index.data = [3, 1, 2]

        Case 2:

            Given:

                input.data = {[[0.6, 0.1],
                               [0.5, 0.3]],
                              [[0.3, 1.3],
                               [0.2, 1.8]],
                              [[2.3, 2.1],
                               [2.5, 2.4]]}

                axis = 1, use_stack = True

            Then:

                output.data = [[[0.6, 0.1]
                                [0.3, 1.3]
                                [2.3, 2.1],
                               [[0.5, 0.3]
                                [0.2, 1.8]
                                [2.5, 2.4]]]

                output_index.data = [2, 2, 2]
L
li099 已提交
331 332

    Args:
G
Guo Sheng 已提交
333 334 335 336 337 338 339
        input(Variable): A LodTensorArray variable.
        axis(int): The axis along which the tensors in attr::`input` will be
            concatenated or stacked.
        name(str|None): A name for this layer(optional). If set None, the layer
                       will be named automatically.
        use_stack(bool): Act as concat_op or stack_op. For stack mode, all
            tensors in the tensor array must have the same shape.
L
li099 已提交
340 341

    Returns:
G
Guo Sheng 已提交
342 343 344
        Variable: The concatenated or stacked tensor variable.
        Variable: A 1-D tensor variable with int32 data type. The data in this \
            tensor contains all input including tensors' sizes along the axis.
L
li099 已提交
345 346 347 348

    Examples:
        .. code-block:: python

349
            import paddle.fluid as fluid
350
            import numpy as np
G
Guo Sheng 已提交
351 352 353 354 355 356 357
            x0 = fluid.layers.assign(np.random.rand(2, 2).astype("float32"))
            x1 = fluid.layers.assign(np.random.rand(2, 2).astype("float32"))
            i = fluid.layers.fill_constant(shape=[1], dtype="int64", value=0)
            array = fluid.layers.create_array(dtype='float32')
            fluid.layers.array_write(x0, i, array)
            fluid.layers.array_write(x1, i + 1, array)
            output, output_index = fluid.layers.tensor_array_to_tensor(input=array)
L
li099 已提交
358
    """
L
li099 已提交
359
    helper = LayerHelper('tensor_array_to_tensor', **locals())
L
li099 已提交
360 361 362
    out = helper.create_variable_for_type_inference(dtype=helper.input_dtype())
    out_index = helper.create_variable_for_type_inference(dtype="int32")
    helper.append_op(
L
li099 已提交
363
        type='tensor_array_to_tensor',
L
li099 已提交
364 365 366
        inputs={'X': input},
        outputs={'Out': [out],
                 'OutIndex': [out_index]},
G
Guo Sheng 已提交
367 368
        attrs={'axis': axis,
               'use_stack': use_stack})
L
li099 已提交
369 370 371
    return out, out_index


372
def sums(input, out=None):
F
fengjiayi 已提交
373
    """
374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394
    This function computes the sum of multiple input Tensors elementwisely.

    - Case 1, sum of 3 Tensors

    .. code-block:: text

        # Input Tensors
        x0.shape = [2, 3]
        x0.data = [[1., 2., 3.],
                   [4., 5., 6.]]
        x1.shape = [2, 3]
        x1.data = [[10., 20., 30.],
                   [40., 50., 60.]]
        x2.shape = [2, 3]
        x2.data = [[100., 200., 300.],
                   [400., 500., 600.]]

        # Output Tensor
        out.shape = [2, 3]
        out.data = [[111., 222., 333.],
                    [444., 555., 666.]]
K
kavyasrinet 已提交
395 396

    Args:
397 398 399 400
        input (list): A list of Variables which hold input Tensors with the same
            data type and shape. Optional data types are: float32, float64, int32, int64.
        out (Variable, optional): Output Tensor. It can be any existing Variable.
            The default value is None, then a new Variable will be created and returned.
K
kavyasrinet 已提交
401 402

    Returns:
403 404
        Variable: The sum of inputs. The shape and data type is the same with input. \
            If :code:`out` is not None, the returned value is :code:`out` .
K
kavyasrinet 已提交
405 406

    Examples:
F
fengjiayi 已提交
407
        .. code-block:: python
K
kavyasrinet 已提交
408

409 410 411 412 413 414 415 416 417
            import paddle.fluid as fluid

            x0 = fluid.layers.fill_constant(shape=[16, 32], dtype='int64', value=1)
            x1 = fluid.layers.fill_constant(shape=[16, 32], dtype='int64', value=2)
            x2 = fluid.layers.fill_constant(shape=[16, 32], dtype='int64', value=3)
            x3 = fluid.layers.fill_constant(shape=[16, 32], dtype='int64', value=0)

            # Sum of multiple Tensors, the result is stored to a new Variable sum0 (sum0=x0+x1+x2, the value is [[6, ..., 6], ..., [6, ..., 6]])
            sum0 = fluid.layers.sums(input=[x0, x1, x2])
418

419 420
            # Sum of multiple Tensors, sum1 and x3 represents the same Variable (x3=x0+x1+x2, the value is [[6, ..., 6], ..., [6, ..., 6]])
            sum1 = fluid.layers.sums(input=[x0, x1, x2], out=x3)
Y
Yu Yang 已提交
421 422 423
    """
    helper = LayerHelper('sum', **locals())
    if out is None:
X
Xin Pan 已提交
424 425
        out = helper.create_variable_for_type_inference(
            dtype=helper.input_dtype())
T
tensor-tang 已提交
426 427 428 429 430
    helper.append_op(
        type='sum',
        inputs={'X': input},
        outputs={'Out': out},
        attrs={'use_mkldnn': False})
Y
Yu Yang 已提交
431 432 433
    return out


F
fengjiayi 已提交
434
def assign(input, output=None):
435
    """
436
    The OP copies the :attr:`input` to the :attr:`output`.
437

438 439 440 441 442
    Parameters:
        input (Variable|numpy.ndarray): A tensor or numpy ndarray, its data type supports
            float32, float64, int32 and int64.
        output (Variable, optional): A tensor. If :attr:`output` is None, a new tensor will
            be created as :attr:`output`. Default: None.
443 444

    Returns:
445
        Variable: A tensor with the same shape, data type and value as :attr:`input`.
446 447 448

    Examples:
        .. code-block:: python
449

450
          import paddle.fluid as fluid
451 452 453 454 455 456
          import numpy as np
          data = fluid.layers.fill_constant(shape=[3, 2], value=2.5, dtype='float64') # [[2.5, 2.5], [2.5, 2.5], [2.5, 2.5]]
          result1 = fluid.layers.create_tensor(dtype='float64')
          fluid.layers.assign(data, result1) # result1 = [[2.5, 2.5], [2.5, 2.5], [2.5, 2.5]]
          result2 = fluid.layers.assign(data)  # result2 = [[2.5, 2.5], [2.5, 2.5], [2.5, 2.5]]
          result3 = fluid.layers.assign(np.array([[2.5, 2.5], [2.5, 2.5], [2.5, 2.5]], dtype='float32')) # result3 = [[2.5, 2.5], [2.5, 2.5], [2.5, 2.5]]
457
    """
Y
Yu Yang 已提交
458
    helper = LayerHelper('assign', **locals())
459
    check_type(input, 'input', (Variable, numpy.ndarray), 'assign')
X
xuwei06 已提交
460
    if isinstance(input, Variable):
461 462 463
        check_dtype(input.dtype, 'input',
                    ['float32', 'float64', 'int32', 'int64', 'bool'], 'assign',
                    '(When the type of input in assign is Variable.)')
464 465 466
        if output is None:
            output = helper.create_variable_for_type_inference(
                dtype=input.dtype)
X
xuwei06 已提交
467
        helper.append_op(
R
robot 已提交
468
            type='assign', inputs={'X': [input]}, outputs={'Out': [output]})
X
xuwei06 已提交
469 470
    elif isinstance(input, numpy.ndarray):
        dtype = convert_np_dtype_to_dtype_(input.dtype)
471
        if dtype == VarDesc.VarType.FP32:
X
xuwei06 已提交
472
            value_name = "fp32_values"
473
            values = [float(v) for v in input.flat]
474
        elif dtype == VarDesc.VarType.INT32:
X
xuwei06 已提交
475
            value_name = "int32_values"
476
            values = [int(v) for v in input.flat]
X
xuwei06 已提交
477
        else:
478 479 480 481
            raise TypeError(
                "When the type of 'input' in assign is numpy.ndarray, "
                "the data type of 'input' must be float32 or int32, but "
                "received %s." % convert_dtype(dtype))
482 483 484
        if input.size > 1024 * 1024:
            raise ValueError("The size of input is too big. Please consider "
                             "saving it to file and 'load_op' to load it")
485 486 487
        if output is None:
            output = helper.create_variable_for_type_inference(
                dtype=input.dtype)
X
xuwei06 已提交
488 489 490 491 492 493
        helper.append_op(
            type='assign_value',
            outputs={'Out': [output]},
            attrs={
                'dtype': dtype,
                'shape': list(input.shape),
494
                value_name: values
X
xuwei06 已提交
495 496
            })

Y
Yu Yang 已提交
497 498 499
    return output


Q
QI JUN 已提交
500
def fill_constant(shape, dtype, value, force_cpu=False, out=None):
Y
Yu Yang 已提交
501
    """
W
wangchaochaohu 已提交
502
    This OP creates a Tensor with specified `shape` and `dtype`, and
503
    initializes it with a constant specifed by `value`.
K
kavyasrinet 已提交
504

W
wangchaochaohu 已提交
505
    The attribute `stop_gradient` of the created Tensor is setted to True.
506 507

    Args:
508 509 510 511
        shape(list|tuple|Variable): Shape of the Tensor to be created.
                The data type is ``int32`` or ``int64`` . If ``shape`` is a list or tuple,
                the elements of it should be integers or Tensors with shape [1].
                If ``shape`` is an Variable, it should be an 1-D Tensor .
W
wangchaochaohu 已提交
512 513 514 515 516 517 518
        dtype(np.dtype|core.VarDesc.VarType|str): Data type of the output tensor which can
            be float16, float32, float64, int32, int64.
        value(float): The constant value used to initialize the Tensor to be created.
        force_cpu(True): data should be on CPU if it's true, defalut value is False.
        out(Variable, optional): Optional output which can be any created 
            Variable that meets the requirements to store the result of operation.
            if out is None, a new Varibale will be create to store the result.
519 520

    Returns:
W
wangchaochaohu 已提交
521 522 523 524 525
        Variable: Tensor which is created according to shape and dtype.

    Raise:
        TypeError: The dtype must be one of bool, float16, float32, float64, int32 and int64
        and the data type of out Tensor must be the same as the dtype. 
526 527 528 529

    Examples:
        .. code-block:: python

530
          import paddle.fluid as fluid
531 532 533 534 535 536 537 538 539 540 541 542
          # attr shape is a list which doesn't contain Variable Tensor.
          data1 = fluid.layers.fill_constant(shape=[2,1], value=0, dtype='int64') # data1=[[0],[0]]
          data2 = fluid.layers.fill_constant(shape=[2,1], value=5, dtype='int64', out=data1)
          # data1=[[0], [0]] data2=[[5], [5]]

          # attr shape is a list which contains Variable Tensor.
          positive_2 = fluid.layers.fill_constant([1], "int32", 2)
          data3 = fluid.layers.fill_constant(shape=[1, positive_2], dtype='float32', value=1.5) # data3=[1.5, 1.5]

          # attr shape is an Variable Tensor.
          shape = fluid.layers.fill_constant([1,2], "int32", 2) # shape=[2,2]
          data4 = fluid.layers.fill_constant(shape=shape, dtype='bool', value=True) # data4=[[True,True],[True,True]]
Y
Yu Yang 已提交
543 544
    """
    helper = LayerHelper("fill_constant", **locals())
545 546 547 548
    check_dtype(dtype, 'create data type',
                ['bool', 'float16', 'float32', 'float64', 'int32', 'int64'],
                'fill_constant')
    check_type(shape, 'shape', (Variable, list, tuple), 'fill_constant')
L
liym27 已提交
549 550 551 552 553 554
    inputs = {}
    attrs = {
        'value': float(value),
        'force_cpu': force_cpu or force_init_on_cpu()
    }

555 556 557 558 559
    if convert_dtype(dtype) in ['int64', 'int32']:
        attrs['str_value'] = str(int(value))
    else:
        attrs['str_value'] = str(float(value))

L
liym27 已提交
560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576
    def _contain_var(one_list):
        for ele in one_list:
            if isinstance(ele, Variable):
                return True
        return False

    def _get_attr_shape(list_shape):
        attr_shape = []
        for idx, dim in enumerate(list_shape):
            if isinstance(dim, Variable):
                attr_shape.append(-1)
            else:
                attr_shape.append(dim)
        return attr_shape

    def _get_shape_tensor(list_shape):
        new_shape_tensor = []
577
        for idx, dim in enumerate(list_shape):
L
liym27 已提交
578 579
            if isinstance(dim, Variable):
                dim.stop_gradient = True
580 581 582 583
                check_dtype(
                    dim.dtype, 'shape[' + str(idx) + ']', ['int32', 'int64'],
                    'fill_constant',
                    '(When type of shape in fill_constant is list or tuple.)')
584 585
                if convert_dtype(dim.dtype) == 'int64':
                    dim = cast(x=dim, dtype='int32')
L
liym27 已提交
586 587 588 589 590 591 592 593 594
                new_shape_tensor.append(dim)
            else:
                temp_out = helper.create_variable_for_type_inference('int32')
                fill_constant([1], 'int32', dim, force_cpu=True, out=temp_out)
                new_shape_tensor.append(temp_out)
        return new_shape_tensor

    if isinstance(shape, Variable):
        shape.stop_gradient = True
595 596
        check_dtype(shape.dtype, 'shape', ['int32', 'int64'], 'fill_constant',
                    '(When type of shape in fill_constant is Variable.)')
597 598
        if (convert_dtype(shape.dtype) == 'int64'):
            shape = cast(shape, 'int32')
L
liym27 已提交
599 600 601 602 603 604 605 606 607
        inputs["ShapeTensor"] = shape
    elif isinstance(shape, (list, tuple)):
        assert len(shape) > 0, (
            "The size of 'shape' in fill_constant can't be zero, "
            "but received %s." % len(shape))
        attrs["shape"] = _get_attr_shape(shape)
        if _contain_var(shape):
            inputs['ShapeTensorList'] = _get_shape_tensor(shape)

Y
Yu Yang 已提交
608
    if out is None:
X
Xin Pan 已提交
609
        out = helper.create_variable_for_type_inference(dtype=dtype)
610
    else:
611 612 613 614 615
        check_dtype(
            dtype, 'create data type',
            convert_dtype(out.dtype), 'fill_constant',
            '(The create data type in fill_constant must be the same with out data type.)'
        )
L
liym27 已提交
616
    attrs['dtype'] = out.dtype
Y
Yu Yang 已提交
617 618
    helper.append_op(
        type='fill_constant',
L
liym27 已提交
619
        inputs=inputs,
Y
Yu Yang 已提交
620
        outputs={'Out': [out]},
L
liym27 已提交
621
        attrs=attrs,
M
minqiyang 已提交
622
        stop_gradient=True)
Y
Yu Yang 已提交
623 624 625 626
    out.stop_gradient = True
    return out


Y
yuyang18 已提交
627
@templatedoc()
Y
Yu Yang 已提交
628 629 630 631 632
def fill_constant_batch_size_like(input,
                                  shape,
                                  dtype,
                                  value,
                                  input_dim_idx=0,
G
Guo Sheng 已提交
633 634
                                  output_dim_idx=0,
                                  force_cpu=False):
635
    """
W
wangchaochaohu 已提交
636 637 638 639 640
    This OP creates a Tesnor accroding the shape and dtype, and initializes the
    Tensor with the constants provided in ``value``. When the input is LoDTensor
    and the input_dim_idx is 0, the output_dim_idx dimension is set to the value
    of the batch_size input by the input, the Stop_gradient attribute of the created
    Tensor is False by default.
641 642

    Args:
W
wangchaochaohu 已提交
643 644 645 646 647 648 649 650 651 652 653
        input(Variable): Tensor which data type is float32, float64, int32 and int64.
        shape(list): The shape of Tensor to be created, Tensor's shape may be changed
            according the input.
        dtype(np.dtype|core.VarDesc.VarType|str): The data type of created Tensor which
            can be float32, float64, int32, int64.
        value(float|int): The constant value used to initialize the Tensor to be created. 
        input_dim_idx(int): When the value is 0 and the input is LoDTensor, the output_dim_idx
            dimension of the created Tensor is set to the batch_size value of input.
            The default value is 0.
        output_dim_idx(int): Used to specify which dimension of Tensor is created to be set
            the value of batch_size of input Tensor. The default value is 0.
G
Guo Sheng 已提交
654
        force_cpu(bool): data should be on CPU if it's true, defalut value is False.
Y
yuyang18 已提交
655 656

    Returns:
W
wangchaochaohu 已提交
657
        Variable: Tensor which will be created according to dtype.
H
haowang101779990 已提交
658 659 660 661 662

    Examples:

        .. code-block:: python

663
             import paddle.fluid as fluid
W
wangchaochaohu 已提交
664
             like = fluid.layers.fill_constant(shape=[1,2], value=10, dtype='int64') #like=[[10, 10]]
W
wangchaochaohu 已提交
665
             data = fluid.layers.fill_constant_batch_size_like(
W
wangchaochaohu 已提交
666
                    input=like, shape=[1], value=0, dtype='int64') #like=[[10, 10]] data=[0]
H
haowang101779990 已提交
667

668
    """
Y
Yu Yang 已提交
669
    helper = LayerHelper("fill_constant_batch_size_like", **locals())
X
Xin Pan 已提交
670
    out = helper.create_variable_for_type_inference(dtype=dtype)
Y
Yu Yang 已提交
671 672 673 674 675 676 677 678 679
    helper.append_op(
        type='fill_constant_batch_size_like',
        inputs={'Input': input},
        outputs={'Out': [out]},
        attrs={
            'shape': shape,
            'dtype': out.dtype,
            'value': float(value),
            'input_dim_idx': input_dim_idx,
G
Guo Sheng 已提交
680 681
            'output_dim_idx': output_dim_idx,
            'force_cpu': force_cpu or force_init_on_cpu()
Y
Yu Yang 已提交
682 683 684 685 686
        })
    out.stop_gradient = True
    return out


S
sneaxiy 已提交
687 688 689 690
def argmin(x, axis=0):
    """
    **argmin**

691 692
    This OP computes the indices of the min elements of the input tensor's
    element along the provided axis.
S
sneaxiy 已提交
693 694

    Args:
695 696 697 698 699
        x(Variable): An input N-D Tensor with type float32, float64, int16,
            int32, int64, uint8.
        axis(int, optional): Axis to compute indices along. The effective range
            is [-R, R), where R is Rank(x). when axis<0, it works the same way
            as axis+R. Default is 0.
F
fengjiayi 已提交
700

S
sneaxiy 已提交
701
    Returns:
702
        Variable: A Tensor with data type int64.
F
fengjiayi 已提交
703

S
sneaxiy 已提交
704 705
    Examples:
        .. code-block:: python
F
fengjiayi 已提交
706

707
            import paddle.fluid as fluid
708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734
            import numpy as np

            in1 = np.array([[[5,8,9,5],
                            [0,0,1,7],
                            [6,9,2,4]],
                            [[5,2,4,2],
                            [4,7,7,9],
                            [1,7,0,6]]])
            with fluid.dygraph.guard():
                x = fluid.dygraph.to_variable(in1)
                out1 = fluid.layers.argmin(x=x, axis=-1)
                out2 = fluid.layers.argmin(x=x, axis=0)
                out3 = fluid.layers.argmin(x=x, axis=1)
                out4 = fluid.layers.argmin(x=x, axis=2)
                print(out1.numpy())
                # [[0 0 2]
                #  [1 0 2]]
                print(out2.numpy())
                # [[0 1 1 1]
                #  [0 0 0 0]
                #  [1 1 1 0]]
                print(out3.numpy())
                # [[1 1 1 2]
                #  [2 0 2 0]]
                print(out4.numpy())
                # [[0 0 2]
                #  [1 0 2]]
S
sneaxiy 已提交
735 736
    """
    helper = LayerHelper("arg_min", **locals())
X
Xin Pan 已提交
737
    out = helper.create_variable_for_type_inference(VarDesc.VarType.INT64)
S
sneaxiy 已提交
738 739 740 741 742 743 744 745 746 747 748 749
    helper.append_op(
        type='arg_min',
        inputs={'X': x},
        outputs={'Out': [out]},
        attrs={'axis': axis})
    return out


def argmax(x, axis=0):
    """
    **argmax**

750 751
    This OP computes the indices of the max elements of the input tensor's
    element along the provided axis.
S
sneaxiy 已提交
752 753

    Args:
754 755 756 757 758
        x(Variable): An input N-D Tensor with type float32, float64, int16,
            int32, int64, uint8.
        axis(int, optional): Axis to compute indices along. The effective range
            is [-R, R), where R is Rank(x). when axis<0, it works the same way
            as axis+R. Default is 0.
F
fengjiayi 已提交
759

S
sneaxiy 已提交
760
    Returns:
761
        Variable: A Tensor with data type int64.
F
fengjiayi 已提交
762

S
sneaxiy 已提交
763 764
    Examples:
        .. code-block:: python
F
fengjiayi 已提交
765

766
            import paddle.fluid as fluid
767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793
            import numpy as np

            in1 = np.array([[[5,8,9,5],
                            [0,0,1,7],
                            [6,9,2,4]],
                            [[5,2,4,2],
                            [4,7,7,9],
                            [1,7,0,6]]])
            with fluid.dygraph.guard():
                x = fluid.dygraph.to_variable(in1)
                out1 = fluid.layers.argmax(x=x, axis=-1)
                out2 = fluid.layers.argmax(x=x, axis=0)
                out3 = fluid.layers.argmax(x=x, axis=1)
                out4 = fluid.layers.argmax(x=x, axis=2)
                print(out1.numpy())
                # [[2 3 1]
                #  [0 3 1]]
                print(out2.numpy())
                # [[0 0 0 0]
                #  [1 1 1 1]
                #  [0 0 0 1]]
                print(out3.numpy())
                # [[2 2 0 1]
                #  [0 1 1 1]]
                print(out4.numpy())
                # [[2 3 1]
                #  [0 3 1]]
S
sneaxiy 已提交
794 795
    """
    helper = LayerHelper("arg_max", **locals())
X
Xin Pan 已提交
796
    out = helper.create_variable_for_type_inference(VarDesc.VarType.INT64)
S
sneaxiy 已提交
797 798 799 800 801 802 803 804
    helper.append_op(
        type='arg_max',
        inputs={'X': x},
        outputs={'Out': [out]},
        attrs={'axis': axis})
    return out


805
def argsort(input, axis=-1, name=None):
Y
Yibing Liu 已提交
806
    """
807 808 809
    This OP sorts the input along the given axis, and returns sorted output
    data Varibale and its corresponding index Variable with the same shape as
    :attr:`input`.
Y
Yibing Liu 已提交
810 811

    Args:
812 813 814 815 816 817 818 819
        input(Variable): An input N-D Tensor with type float32, float64, int16,
            int32, int64, uint8.
        axis(int, optional): Axis to compute indices along. The effective range
            is [-R, R), where R is Rank(x). when axis<0, it works the same way
            as axis+R. Default is 0.
        name(str, optional): The default value is None. Normally there is no
            need for user to set this property. For more information, please
            refer to :ref:`api_guide_Name`.
Y
Yibing Liu 已提交
820 821

    Returns:
822 823 824
        tuple: A tuple of sorted data Variable(with the same shape and data
        type as input) and the sorted indices(with the same shape as input's
        and with data type int64).
Y
Yibing Liu 已提交
825 826 827 828

    Examples:
        .. code-block:: python

829
            import paddle.fluid as fluid
830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870
            import numpy as np

            in1 = np.array([[[5,8,9,5],
                            [0,0,1,7],
                            [6,9,2,4]],
                            [[5,2,4,2],
                            [4,7,7,9],
                            [1,7,0,6]]]).astype(np.float32)
            with fluid.dygraph.guard():
                x = fluid.dygraph.to_variable(in1)
                out1 = fluid.layers.argsort(input=x, axis=-1)
                out2 = fluid.layers.argsort(input=x, axis=0)
                out3 = fluid.layers.argsort(input=x, axis=1)
                print(out1[0].numpy())
                # [[[5. 5. 8. 9.]
                #   [0. 0. 1. 7.]
                #   [2. 4. 6. 9.]]
                #  [[2. 2. 4. 5.]
                #   [4. 7. 7. 9.]
                #   [0. 1. 6. 7.]]]
                print(out1[1].numpy())
                # [[[0 3 1 2]
                #   [0 1 2 3]
                #   [2 3 0 1]]
                #  [[1 3 2 0]
                #   [0 1 2 3]
                #   [2 0 3 1]]]
                print(out2[0].numpy())
                # [[[5. 2. 4. 2.]
                #   [0. 0. 1. 7.]
                #   [1. 7. 0. 4.]]
                #  [[5. 8. 9. 5.]
                #   [4. 7. 7. 9.]
                #   [6. 9. 2. 6.]]]
                print(out3[0].numpy())
                # [[[0. 0. 1. 4.]
                #   [5. 8. 2. 5.]
                #   [6. 9. 9. 7.]]
                #  [[1. 2. 0. 2.]
                #   [4. 7. 4. 6.]
                #   [5. 7. 7. 9.]]]
Y
Yibing Liu 已提交
871 872
    """
    helper = LayerHelper("argsort", **locals())
X
Xin Pan 已提交
873 874 875 876
    out = helper.create_variable_for_type_inference(
        dtype=input.dtype, stop_gradient=True)
    ids = helper.create_variable_for_type_inference(
        VarDesc.VarType.INT64, stop_gradient=True)
Y
Yibing Liu 已提交
877 878 879 880
    helper.append_op(
        type='argsort',
        inputs={'X': input},
        outputs={'Out': out,
881 882
                 'Indices': ids},
        attrs={'axis': axis})
Y
Yibing Liu 已提交
883 884 885
    return out, ids


Y
Yang Yu 已提交
886
def ones(shape, dtype, force_cpu=False):
Y
Yu Yang 已提交
887
    """
888 889
    The OP creates a tensor of specified :attr:`shape` and :attr:`dtype`, and fills it with 1.
    Its :attr:`stop_gradient` will be set to True to stop gradient computation.
890

891 892 893 894 895 896 897
    Parameters:
        shape (tuple|list): Shape of output tensor.
        dtype (np.dtype|core.VarDesc.VarType|str): Data type of output tensor, it supports
            bool, float16, float32, float64, int32 and int64.
        force_cpu (bool, optional): Whether force to store the output tensor in CPU memory.
            If :attr:`force_cpu` is False, the output tensor will be stored in running device memory.
            Default: False.
898 899

    Returns:
900
        Variable: A tensor of data type :attr:`dtype` with shape :attr:`shape` and all elements set to 1.
901 902 903 904

    Examples:
        .. code-block:: python

905
          import paddle.fluid as fluid
906
          data = fluid.layers.ones(shape=[2, 4], dtype='float32') # [[1., 1., 1., 1.], [1., 1., 1., 1.]]
Y
Yu Yang 已提交
907
    """
C
chengduozh 已提交
908 909 910 911
    assert isinstance(shape, list) or isinstance(
        shape, tuple), "The shape's type should be list or tuple."
    assert reduce(lambda x, y: x * y,
                  shape) > 0, "The shape is invalid: %s." % (str(shape))
Y
Yu Yang 已提交
912 913 914
    return fill_constant(value=1.0, **locals())


Y
Yang Yu 已提交
915
def zeros(shape, dtype, force_cpu=False):
Y
Yu Yang 已提交
916
    """
917 918
    The OP creates a tensor of specified :attr:`shape` and :attr:`dtype`, and fills it with 0.
    Its :attr:`stop_gradient` will be set to True to stop gradient computation.
919

920 921 922 923 924 925 926
    Parameters:
        shape (tuple|list): Shape of output tensor.
        dtype (np.dtype|core.VarDesc.VarType|str): Data type of output tensor, it supports
            bool, float16, float32, float64, int32 and int64.
        force_cpu (bool, optional): Whether force to store the output tensor in CPU memory.
            If :attr:`force_cpu` is False, the output tensor will be stored in running device memory.
            Default: False.
927 928

    Returns:
929
        Variable: A tensor of data type :attr:`dtype` with shape :attr:`shape` and all elements set to 0.
930 931 932 933

    Examples:
        .. code-block:: python

934
          import paddle.fluid as fluid
935
          data = fluid.layers.zeros(shape=[3, 2], dtype='float32') # [[0., 0.], [0., 0.], [0., 0.]]
Y
Yu Yang 已提交
936
    """
937 938 939
    check_dtype(dtype, 'create data type',
                ['bool', 'float16', 'float32', 'float64', 'int32', 'int64'],
                'zeros')
Y
Yu Yang 已提交
940
    return fill_constant(value=0.0, **locals())
941 942


F
fengjiayi 已提交
943 944
def reverse(x, axis):
    """
945
    The OP reverses the tensor :attr:`x` along the given :attr:`axis`.
F
fengjiayi 已提交
946

947 948 949 950 951
    Parameters:
        x (Variable): A tensor to be reversed, its data type supports bool, float32, float64, int32, int64 and uint8.
        axis (int|tuple|list): A dimension or a set of dimensions of :attr:`x` to reverse. Must be
            in the range [-rank( :attr:`x` ), rank( :attr:`x` )). If it is a tuple or a list, reversing
            will be apply on each axis in the tuple or list.
F
fengjiayi 已提交
952 953

    Returns:
954
        Variable: The reversed tensor with the same shape and data type as :attr:`x`.
F
fengjiayi 已提交
955 956 957 958

    Examples:
        .. code-block:: python

959
          import paddle.fluid as fluid
960 961 962 963
          import numpy as np
          data = fluid.layers.assign(np.array([[0, 1, 2], [3, 4, 5], [6, 7, 8]], dtype='float32')) # [[0., 1., 2.], [3., 4., 5.], [6., 7., 8.]]
          result1 = fluid.layers.reverse(data, 0) # [[6., 7., 8.], [3., 4., 5.], [0., 1., 2.]]
          result2 = fluid.layers.reverse(data, [0, 1]) # [[8., 7., 6.], [5., 4., 3.], [2., 1., 0.]]
F
fengjiayi 已提交
964 965 966 967
    """
    if isinstance(axis, int):
        axis = [axis]
    helper = LayerHelper("reverse", **locals())
X
Xin Pan 已提交
968
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
F
fengjiayi 已提交
969 970
    helper.append_op(
        type='reverse',
W
Wu Yi 已提交
971
        inputs={'X': x},
F
fengjiayi 已提交
972 973 974 975 976
        outputs={'Out': [out]},
        attrs={'axis': axis})
    return out


977 978 979 980 981 982 983
def save(x, file_path, overwrite=True):
    """
    Saves a variable as a file.

    Args:
        x(variable): The Tensor/LoDTensor to be saved.
        file_path(str): The file path where the variable will be saved.
984 985 986
        overwrite(bool): Whether or not cover the given file when it has already
            existed. If it's set 'False' and the file is existed, a runtime
            error will be thrown.
987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001
    """
    helper = LayerHelper("save", **locals())
    helper.append_op(
        type="save",
        inputs={"input": x},
        outputs={},
        args={"file_path": file_path,
              "overwrite": overwrite})


def save_combine(x, file_path, overwrite=True):
    """
    Saves a list of variables into a single file.

    Args:
1002 1003
        x(list): A list of Tensor/LoDTensor variables to be saved together in
                 a single file.
1004
        file_path(str): The file path where variables will be saved.
1005
        overwrite(bool): Whether or not cover the given file when it has already
1006 1007
            existed. If it's set 'False' and the file is existed, a runtime
            error will be thrown.
1008 1009 1010 1011 1012 1013 1014 1015

    Returns:
        There is no return value.

    Examples:

        .. code-block:: python

1016
            import paddle.fluid as fluid
1017 1018 1019 1020 1021 1022 1023
            v1 = fluid.layers.data(name="data",
                                   shape=(4, 6),
                                   dtype="float32")
            v2 = fluid.layers.data(name="data",
                                   shape=(6, 8, 4),
                                   dtype="float32")
            normed = fluid.layers.save_combine([v1, v2], file_path="output")
1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047
    """
    helper = LayerHelper("save_combine", **locals())
    helper.append_op(
        type="save_combine",
        inputs={"input": x},
        outputs={},
        args={"file_path": file_path,
              "overwrite": overwrite})


def load_combine(out, file_path):
    """
    Loads a list of vairables from a single file.

    Args:
        out(list): The list of variables to be read from the disk file.
        file_path(str): The path of the disk file.
    """
    helper = LayerHelper("load_combine", **locals())
    helper.append_op(
        type="load_combine",
        inputs={},
        output={"Out": out},
        args={"file_path": file_path})
1048 1049 1050 1051 1052 1053 1054


def has_inf(x):
    """
    Test if any of x contains an infinity number

    Args:
L
liu zhengxi 已提交
1055
       x (Variable): The Tensor/LoDTensor to be checked.
1056 1057

    Returns:
L
liu zhengxi 已提交
1058
       Variable: The tensor variable storing the output, only a bool value, indicating that whether there is infinity number in x or not.
1059 1060 1061 1062 1063 1064 1065 1066
    
    Examples:
        .. code-block:: python
          
          import paddle.fluid as fluid
          data = fluid.layers.data(name="input", shape=[4, 32, 32], dtype="float32")
          res = fluid.layers.has_inf(data)

1067 1068
    """
    helper = LayerHelper("isinf", **locals())
X
Xin Pan 已提交
1069
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
1070 1071 1072 1073 1074 1075 1076 1077 1078
    helper.append_op(type="isinf", inputs={"X": x}, outputs={"Out": out})
    return out


def has_nan(x):
    """
    Test if any of x contains a NAN

    Args:
L
liu zhengxi 已提交
1079
       x (Variable): The Tensor/LoDTensor to be checked.
1080 1081

    Returns:
L
liu zhengxi 已提交
1082
       Variable: The tensor variable storing the output, only a bool value, indicating that whether there is NAN in x or not.
1083 1084 1085 1086 1087 1088 1089 1090
    
    Examples:
        .. code-block:: python
    
          import paddle.fluid as fluid
          data = fluid.layers.data(name="input", shape=[4, 32, 32], dtype="float32")
          res = fluid.layers.has_nan(data)

1091 1092
    """
    helper = LayerHelper("isnan", **locals())
X
Xin Pan 已提交
1093
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107
    helper.append_op(type="isnan", inputs={"X": x}, outputs={"Out": out})
    return out


def isfinite(x):
    """
    Test if any of x contains an infinity/NAN number. If all the elements are finite,
    returns true, else false.

    Args:
       x(variable): The Tensor/LoDTensor to be checked.

    Returns:
        Variable: The tensor variable storing the output, contains a bool value.
1108 1109 1110 1111 1112

    Examples:

        .. code-block:: python

1113
            import paddle.fluid as fluid
1114 1115 1116
            var = fluid.layers.data(name="data",
                                    shape=(4, 6),
                                    dtype="float32")
石晓伟 已提交
1117
            out = fluid.layers.isfinite(var)
1118 1119
    """
    helper = LayerHelper("isfinite", **locals())
X
Xin Pan 已提交
1120
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
1121 1122
    helper.append_op(type="isfinite", inputs={"X": x}, outputs={"Out": out})
    return out
W
whs 已提交
1123 1124 1125 1126 1127 1128 1129 1130 1131


def range(start, end, step, dtype):
    """
    Return evenly spaced values within a given interval.

    Values are generated within the half-open interval [start, stop) (in other words,
    the interval including start but excluding stop).

L
Liufang Sang 已提交
1132 1133 1134 1135
    Parameters:
        start(float32 | float64 | int32 | int64 | Variable): Start of interval. The interval includes this value.
            when start is Variable, it is a 1-D Tensor with shape [1].
        end(float32 | float64 | int32 | int64 | Variable): End of interval. The interval does not include this
W
whs 已提交
1136
                                 value, except in some cases where step is not an integer
L
Liufang Sang 已提交
1137 1138 1139
                                 and floating point round-off affects the length of out. When end is Variable,
                                 it is a 1-D Tensor with shape [1].
        step(float32 | float64 | int32 | int64 | Variable): Spacing between values. For any output out, this is the
W
whs 已提交
1140
                                  distance between two adjacent values, out[i+1] - out[i].
L
Liufang Sang 已提交
1141
        dtype(str): the data type of the output tensor, can be float32, float64, int32, int64.
W
whs 已提交
1142

L
Liufang Sang 已提交
1143 1144 1145
    Returns: a 1-D Tensor which is evenly spaced values within a given interval. Its data type is set by dtype.
    
    Return type: Variable
W
whs 已提交
1146 1147 1148 1149 1150

    examples:

        .. code-block:: python

1151
             import paddle.fluid as fluid
W
whs 已提交
1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171
             data = fluid.layers.range(0, 10, 2, 'int32')

    """
    helper = LayerHelper("range", **locals())

    if not isinstance(start, Variable):
        start = fill_constant([1], dtype, start)
    if not isinstance(end, Variable):
        end = fill_constant([1], dtype, end)
    if not isinstance(step, Variable):
        step = fill_constant([1], dtype, step)

    out = helper.create_variable_for_type_inference(dtype=start.dtype)

    helper.append_op(
        type='range',
        inputs={'Start': start,
                'End': end,
                'Step': step},
        outputs={'Out': [out]})
1172
    out.stop_gradient = True
W
whs 已提交
1173
    return out
Z
zhoukunsheng 已提交
1174 1175


Z
zhoukunsheng 已提交
1176 1177
def linspace(start, stop, num, dtype):
    """
1178
    This OP return fixed number of evenly spaced values within a given interval.
Z
zhoukunsheng 已提交
1179 1180

    Args:
1181 1182 1183 1184 1185 1186 1187
        start(float|Variable): The input :attr:`start` is start variable of range. It is a float scalar, \
            or a tensor of shape [1] with input data type float32, float64.
        stop(float|Variable): The input :attr:`stop` is start variable of range. It is a float scalar, \
            or a tensor of shape [1] with input data type float32, float64.
        num(int|Variable): The input :attr:`num` is given num of the sequence. It is an int scalar, \
            or a tensor of shape [1] with type int32.
        dtype(string): The data type of output tensor, it could be 'float32' and 'float64'.
Z
zhoukunsheng 已提交
1188 1189

    Returns:
1190 1191 1192
        Variable, the output data type will be float32, float64.: The 1-D tensor with fixed number of evenly spaced values, \
        the data shape of this tensor is :math:`[num]` . If the :attr:`num` is set 1, the output tensor just has \
        the value with input :attr:`start`. 
Z
zhoukunsheng 已提交
1193

Z
zhoukunsheng 已提交
1194
    Examples:
Z
zhoukunsheng 已提交
1195 1196
        .. code-block:: python

1197
             import paddle.fluid as fluid
Z
zhoukunsheng 已提交
1198 1199
             data = fluid.layers.linspace(0, 10, 5, 'float32') # [0.0,  2.5,  5.0,  7.5, 10.0]
             data = fluid.layers.linspace(0, 10, 1, 'float32') # [0.0]
Z
zhoukunsheng 已提交
1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219

    """
    helper = LayerHelper("linspace", **locals())

    if not isinstance(start, Variable):
        start = fill_constant([1], dtype, start)
    if not isinstance(stop, Variable):
        stop = fill_constant([1], dtype, stop)
    if not isinstance(num, Variable):
        num = fill_constant([1], 'int32', num)

    out = helper.create_variable_for_type_inference(dtype=start.dtype)

    helper.append_op(
        type='linspace',
        inputs={'Start': start,
                'Stop': stop,
                'Num': num},
        outputs={'Out': [out]})
    return out
1220 1221


Z
zhoukunsheng 已提交
1222 1223
def zeros_like(x, out=None):
    """
1224
    This OP creates a zeros tensor which has identical shape and dtype 
Z
zhoukunsheng 已提交
1225 1226 1227
    with `x`.

    Args:
1228 1229 1230 1231
        x(Variable): The input tensor which specifies shape and dtype, the input data dtype could be bool, float32, float64, int32, int64.
        out(Variable, optional): If is :attr:`None` , the op will create the variable as output, the data type and shape of \
            this variable will be same as input :attr:`x`. If is a tensor, the data type and shape need to be same as input :attr:`x`. 
            The defalut value is :attr:`None` .
Z
zhoukunsheng 已提交
1232 1233

    Returns:
1234 1235
        Variable: The N-D tensor, the element in tensor is related to input data type, if the input data type is bool, \
            the output value is False, otherwise is zero. The output shape is the same as the input.
Z
zhoukunsheng 已提交
1236 1237 1238 1239

    Examples:
        .. code-block:: python

1240
          import paddle.fluid as fluid
1241
          x = fluid.data(name='x', dtype='float32', shape=[3])
Z
zhoukunsheng 已提交
1242 1243
          data = fluid.layers.zeros_like(x) # [0.0, 0.0, 0.0]

Z
zhoukunsheng 已提交
1244 1245 1246 1247 1248 1249 1250 1251 1252
    """

    helper = LayerHelper("zeros_like", **locals())
    if out is None:
        out = helper.create_variable_for_type_inference(dtype=x.dtype)
    helper.append_op(
        type='fill_zeros_like', inputs={'X': [x]}, outputs={'Out': [out]})
    out.stop_gradient = True
    return out
Z
zhoukunsheng 已提交
1253 1254 1255 1256


def diag(diagonal):
    """
1257
    This OP creates a square matrix which has diagonal values specified by input :attr:`diagonal`.
Z
zhoukunsheng 已提交
1258 1259

    Args:
1260 1261
        diagonal(Variable|numpy.ndarray): The input tensor should be 1D tensor, the input shape is :math:`[ N]` , \
            specifying diagonal values by this input tensor. The input data type should be float32, float64, int32, int64.
Z
zhoukunsheng 已提交
1262 1263

    Returns:
1264 1265
        Variable, the output data type is the same as input data type.: The tensor variable storing the square matrix, \
            the diagonal values specified by input :attr:`diagonal`. the output shape is :math:`[N, N]` with two dims.
Z
zhoukunsheng 已提交
1266 1267 1268 1269 1270 1271 1272

    Examples:
        .. code-block:: python

          # [[3, 0, 0]
          #  [0, 4, 0]
          #  [0, 0, 5] 
1273 1274 1275

          import paddle.fluid as fluid
          import numpy as np
1276 1277 1278
          diagonal = np.arange(3, 6, dtype='int32')
          data = fluid.layers.diag(diagonal)
          # diagonal.shape=(3,) data.shape=(3, 3)
Z
zhoukunsheng 已提交
1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293

    """

    helper = LayerHelper("diag", **locals())

    if not isinstance(diagonal, Variable):
        diagonal = assign(diagonal)

    out = helper.create_variable_for_type_inference(dtype=diagonal.dtype)

    helper.append_op(
        type='diag', inputs={'Diagonal': [diagonal]}, outputs={'Out': [out]})

    out.stop_gradient = True
    return out
Z
zhoukunsheng 已提交
1294 1295


1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307
def eye(num_rows, num_columns=None, batch_shape=None, dtype='float32'):
    """
    **eye**

    This function constructs an identity tensor, or a batch of tensor.

    Args:
        num_rows(int): the number of rows in each batch tensor.
        num_columns(int): the number of columns in each batch tensor.
                          If None, default: num_rows.
        batch_shape(list(int)): If provided, the returned tensor will have a leading
                                batch size of this shape.
1308 1309
        dtype(string): The data type of the returned tensor.
                       It should be int32, int64, float16, float32, float64.
1310 1311

    Returns:
1312
        Variable: An identity Tensor or LoDTensor of shape batch_shape + [num_rows, num_columns].
1313 1314 1315 1316 1317

    Examples:
        .. code-block:: python

          import paddle.fluid as fluid
1318 1319
          data = fluid.layers.eye(3, dtype='int32')
          # [[1, 0, 0]
1320
          #  [0, 1, 0]
1321 1322
          #  [0, 0, 1]]

1323
          data = fluid.layers.eye(2, 3, dtype='int32')
1324
          # [[1, 0, 0]
1325
          #  [0, 1, 0]]
1326 1327

          data = fluid.layers.eye(2, batch_shape=[3])
1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367
          # Construct a batch of 3 identity tensors, each 2 x 2.
          # data[i, :, :] is a 2 x 2 identity tensor, i = 0, 1, 2.

    """

    helper = LayerHelper("eye", **locals())
    if not isinstance(num_rows, int) or num_rows < 0:
        raise TypeError("num_rows should be a non-negative int")
    if num_columns is not None:
        if not isinstance(num_columns, int) or num_columns < 0:
            raise TypeError("num_columns should be a non-negative int")
    else:
        num_columns = num_rows
    out = helper.create_variable_for_type_inference(dtype=dtype)
    c_dtype = convert_np_dtype_to_dtype_(dtype)
    helper.append_op(
        type='eye',
        inputs={},
        outputs={'Out': [out]},
        attrs={
            'num_rows': num_rows,
            'num_columns': num_columns,
            'dtype': c_dtype
        },
        stop_gradient=True)
    out.stop_gradient = True

    if batch_shape is not None:
        if not isinstance(batch_shape, list):
            raise TypeError("batch_shape should be a list")
        from .nn import stack
        for batch_val in reversed(batch_shape):
            if batch_val <= 0:
                raise TypeError("batch_shape should be a positive int list")
            else:
                stack_vars = [out for _ in numpy.arange(batch_val)]
                out = stack(stack_vars, axis=0)
    return out


Z
zhoukunsheng 已提交
1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379
def ones_like(x, out=None):
    """
    **ones_like**

    This function creates a ones tensor which has identical shape and dtype 
    with `x`.

    Args:
        x(Variable): The input tensor which specifies shape and dtype.
        out(Variable): The output tensor.

    Returns:
1380
        out(Variable): The tensor variable storing the output.
Z
zhoukunsheng 已提交
1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400

    Examples:
        .. code-block:: python

          import paddle.fluid as fluid

          x = fluid.layers.data(name='x', dtype='float32', shape=[3], append_batch_size=False)
          data = fluid.layers.ones_like(x) # [1.0, 1.0, 1.0]

    """

    helper = LayerHelper("ones_like", **locals())
    if out is None:
        out = helper.create_variable_for_type_inference(dtype=x.dtype)
    helper.append_op(
        type='fill_any_like',
        inputs={'X': [x]},
        attrs={'value': 1.0},
        outputs={'Out': [out]})
    return out