tensor.py 31.1 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
X
xuwei06 已提交
24
import numpy
Y
Yu Yang 已提交
25 26

__all__ = [
L
li099 已提交
27 28 29
    '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 已提交
30
    'argsort', 'ones', 'zeros', 'reverse', 'has_inf', 'has_nan', 'isfinite',
Z
zhoukunsheng 已提交
31
    'range', 'linspace', 'zeros_like', 'diag'
Y
Yu Yang 已提交
32 33 34
]


X
xuwei06 已提交
35
def create_tensor(dtype, name=None, persistable=False):
36
    """
Q
update  
qiaolongfei 已提交
37
    Create an variable, which will hold a LoDTensor with data type dtype.
38 39

    Args:
Q
update  
qiaolongfei 已提交
40
        dtype(string): 'float32'|'int32'|..., the data type of the
41
            created tensor.
Q
update  
qiaolongfei 已提交
42
        name(string): The name of the created tensor, if not set,
43
            the name will be a random unique one.
Q
update  
qiaolongfei 已提交
44
        persistable(bool): Set the persistable flag of the create tensor.
45 46 47 48 49 50 51

    Returns:
        Variable: The tensor variable storing the created tensor.

    Examples:
        .. code-block:: python

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


60 61
def create_parameter(shape,
                     dtype,
X
xuwei06 已提交
62
                     name=None,
63 64 65 66
                     attr=None,
                     is_bias=False,
                     default_initializer=None):
    """
Y
yuyang18 已提交
67 68 69 70 71 72
    Create a parameter. The parameter is a learnable variable, which can have
    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.

73 74 75 76 77 78 79 80 81 82 83
    Args:
        shape(list[int]): shape of the parameter
        dtype(string): element type of the parameter
        attr(ParamAttr): attributes of the parameter
        is_bias(bool): This can affect which default initializer is chosen
                       when default_initializer is None. If is_bias,
                       initializer.Constant(0.0) will be used. Otherwise,
                       Xavier() will be used.
        default_initializer(Initializer): initializer for the parameter

    Returns:
Y
yuyang18 已提交
84 85 86
        the created parameter.

    Examples:
87 88
        .. code-block:: python

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


100 101 102 103 104 105 106
def create_global_var(shape,
                      value,
                      dtype,
                      persistable=False,
                      force_cpu=False,
                      name=None):
    """
X
Xin Pan 已提交
107
    Create a new tensor variable with value in the global block(block 0).
F
fengjiayi 已提交
108

109 110
    Args:
        shape(list[int]): shape of the variable
M
minqiyang 已提交
111
        value(float): the value of the variable. The new created
F
fengjiayi 已提交
112 113
                      variable will be filled with it.
        dtype(string): data type of the variable
M
minqiyang 已提交
114
        persistable(bool): if this variable is persistable.
F
fengjiayi 已提交
115
                           Default: False
M
minqiyang 已提交
116
        force_cpu(bool): force this variable to be on CPU.
F
fengjiayi 已提交
117
                         Default: False
M
minqiyang 已提交
118 119
        name(str|None): The name of the variable. If set to None the variable
                        name will be generated automatically.
F
fengjiayi 已提交
120
                        Default: None
121 122 123

    Returns:
        Variable: the created Variable
F
fengjiayi 已提交
124 125 126 127

    Examples:
        .. code-block:: python

128
            import paddle.fluid as fluid
129 130 131
            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')
132
    """
Q
Qiao Longfei 已提交
133 134
    helper = LayerHelper("global_var", **locals())
    var = helper.create_global_variable(
M
minqiyang 已提交
135 136 137 138 139
        dtype=dtype,
        shape=shape,
        persistable=persistable,
        name=name,
        stop_gradient=True)
M
minqiyang 已提交
140 141 142
    helper.set_variable_initializer(
        var, initializer=Constant(
            value=float(value), force_cpu=force_cpu))
M
minqiyang 已提交
143

Q
Qiao Longfei 已提交
144 145 146
    return var


147
def cast(x, dtype):
Y
Yu Yang 已提交
148
    """
M
minqiyang 已提交
149
    This layer takes in the Variable :attr:`x` with :attr:`x.dtype` and casts
T
tensor-tang 已提交
150 151
    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 已提交
152 153 154 155 156 157 158 159 160 161

    Args:
        x (Variable): The input Variable for casting.
        dtype(np.dtype|core.VarDesc.VarType|str): Data type of the output Variable.

    Returns:
        Variable: The output Variable after casting.

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

163
            import paddle.fluid as fluid
Y
Yibing Liu 已提交
164 165
            data = fluid.layers.data(name='x', shape=[13], dtype='float32')
            result = fluid.layers.cast(x=data, dtype='float64')
Y
Yu Yang 已提交
166 167
    """
    helper = LayerHelper('cast', **locals())
X
Xin Pan 已提交
168
    out = helper.create_variable_for_type_inference(dtype=dtype)
Y
Yu Yang 已提交
169 170 171 172 173 174 175 176 177
    helper.append_op(
        type='cast',
        inputs={'X': [x]},
        outputs={'Out': [out]},
        attrs={'in_dtype': x.dtype,
               'out_dtype': out.dtype})
    return out


178
def concat(input, axis=0, name=None):
Y
Yu Yang 已提交
179
    """
180 181 182
    **Concat**

    This function concatenates the input along the axis mentioned
Y
Yu Yang 已提交
183
    and returns that as the output.
184 185 186 187

    Args:
        input(list): List of tensors to be concatenated
        axis(int): Integer axis along which the tensors will be concatenated
188 189
        name(str|None): A name for this layer(optional). If set None, the layer
                       will be named automatically.
190 191 192 193 194 195

    Returns:
        Variable: Output variable of the concatenation

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

197
            import paddle.fluid as fluid
198 199 200 201 202
            a = fluid.layers.data(name='a', shape=[2, 13], dtype='float32')
            b = fluid.layers.data(name='b', shape=[2, 3], dtype='float32')
            c = fluid.layers.data(name='c', shape=[2, 2], dtype='float32')
            d = fluid.layers.data(name='d', shape=[2, 5], dtype='float32')
            out = fluid.layers.concat(input=[a, b, c, d], axis=2)
Y
Yu Yang 已提交
203 204
    """
    helper = LayerHelper('concat', **locals())
X
Xin Pan 已提交
205
    out = helper.create_variable_for_type_inference(dtype=helper.input_dtype())
Y
Yu Yang 已提交
206 207 208 209 210 211 212 213
    helper.append_op(
        type='concat',
        inputs={'X': input},
        outputs={'Out': [out]},
        attrs={'axis': axis})
    return out


L
li099 已提交
214 215 216 217 218 219
def tensor_array_to_tensor(input, axis=1, name=None):
    """
    This function concatenates the input LodTensorArray along the axis mentioned
    and returns that as the output.

    A simple example as below:
M
minqiyang 已提交
220

L
li099 已提交
221
    .. code-block:: text
M
minqiyang 已提交
222

L
li099 已提交
223 224 225 226 227 228 229 230
        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]]}
M
minqiyang 已提交
231

L
li099 已提交
232
        axis = 1
M
minqiyang 已提交
233

L
li099 已提交
234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253
        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]

    Args:
        input(list): Input LodTensorArray
        axis(int): Integer axis along which the tensors will be concatenated
        name(str|None): A name for this layer(optional). If set None, the layer
                       will be named automatically.

    Returns:
        Variable: Output variable of the concatenation
        Variable: The input LodTensorArray items' dims along the axis

    Examples:
        .. code-block:: python

254 255 256
            import paddle.fluid as fluid
            tensor_array = fluid.layers.create_parameter(shape=[784, 200], dtype='float32')
            output, output_index = fluid.layers.tensor_array_to_tensor(input=tensor_array)
L
li099 已提交
257
    """
L
li099 已提交
258
    helper = LayerHelper('tensor_array_to_tensor', **locals())
L
li099 已提交
259 260 261
    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 已提交
262
        type='tensor_array_to_tensor',
L
li099 已提交
263 264 265 266 267 268 269
        inputs={'X': input},
        outputs={'Out': [out],
                 'OutIndex': [out_index]},
        attrs={'axis': axis})
    return out, out_index


270
def sums(input, out=None):
F
fengjiayi 已提交
271 272
    """
    This function performs the sum operation on the input and returns the
K
kavyasrinet 已提交
273 274 275 276 277
    result as the output.

    Args:
        input (Variable|list): The input tensor that has the elements
                               that need to be summed up.
F
fengjiayi 已提交
278
        out (Variable|None): Output parameter. The sum result.
F
fengjiayi 已提交
279
                             Default: None
K
kavyasrinet 已提交
280 281

    Returns:
F
fengjiayi 已提交
282
        Variable: the sum of input. The same as the argument 'out'
K
kavyasrinet 已提交
283 284

    Examples:
F
fengjiayi 已提交
285
        .. code-block:: python
K
kavyasrinet 已提交
286

287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303
          import paddle.fluid as fluid

          # sum of several tensors
          a0 = fluid.layers.fill_constant(shape=[1], dtype='int64', value=1)
          a1 = fluid.layers.fill_constant(shape=[1], dtype='int64', value=2)
          a2 = fluid.layers.fill_constant(shape=[1], dtype='int64', value=3)
          sums = fluid.layers.sums(input=[a0, a1, a2])

          # sum of a tensor array
          array = fluid.layers.create_array('int64')
          i = fluid.layers.zeros(shape=[1], dtype='int64', force_cpu=True)
          fluid.layers.array_write(a0, array=array, i=i)
          i = fluid.layers.increment(x=i)
          fluid.layers.array_write(a1, array=array, i=i)
          i = fluid.layers.increment(x=i)
          fluid.layers.array_write(a2, array=array, i=i)
          sums = fluid.layers.sums(input=array)
Y
Yu Yang 已提交
304 305 306
    """
    helper = LayerHelper('sum', **locals())
    if out is None:
X
Xin Pan 已提交
307 308
        out = helper.create_variable_for_type_inference(
            dtype=helper.input_dtype())
T
tensor-tang 已提交
309 310 311 312 313
    helper.append_op(
        type='sum',
        inputs={'X': input},
        outputs={'Out': out},
        attrs={'use_mkldnn': False})
Y
Yu Yang 已提交
314 315 316
    return out


F
fengjiayi 已提交
317
def assign(input, output=None):
318 319 320 321 322 323
    """
    **Assign**

    This function copies the *input* Variable to the *output* Variable.

    Args:
X
xuwei06 已提交
324
        input(Variable|numpy.ndarray): The source variable
F
fengjiayi 已提交
325
        output(Variable|None): The destination variable
326 327 328 329 330 331

    Returns:
        Variable: The destination variable that was supplied as the *output*.

    Examples:
        .. code-block:: python
332

333 334
          import paddle.fluid as fluid
          data = fluid.layers.data(name="data", shape=[3, 32, 32], dtype="float32")
335 336 337 338
          out = fluid.layers.create_tensor(dtype='float32')
          hidden = fluid.layers.fc(input=data, size=10)
          fluid.layers.assign(hidden, out)
    """
Y
Yu Yang 已提交
339
    helper = LayerHelper('assign', **locals())
F
fengjiayi 已提交
340
    if output is None:
X
Xin Pan 已提交
341
        output = helper.create_variable_for_type_inference(dtype=input.dtype)
X
xuwei06 已提交
342 343
    if isinstance(input, Variable):
        helper.append_op(
R
robot 已提交
344
            type='assign', inputs={'X': [input]}, outputs={'Out': [output]})
X
xuwei06 已提交
345 346
    elif isinstance(input, numpy.ndarray):
        dtype = convert_np_dtype_to_dtype_(input.dtype)
347
        if dtype == VarDesc.VarType.FP32:
X
xuwei06 已提交
348
            value_name = "fp32_values"
349
            values = [float(v) for v in input.flat]
350
        elif dtype == VarDesc.VarType.INT32:
X
xuwei06 已提交
351
            value_name = "int32_values"
352
            values = [int(v) for v in input.flat]
X
xuwei06 已提交
353 354
        else:
            raise ValueError("Unsupported dtype %s", input.dtype)
355 356 357
        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")
X
xuwei06 已提交
358 359 360 361 362 363 364

        helper.append_op(
            type='assign_value',
            outputs={'Out': [output]},
            attrs={
                'dtype': dtype,
                'shape': list(input.shape),
365
                value_name: values
X
xuwei06 已提交
366 367 368 369
            })
    else:
        raise ValueError("Wrong type for assign input: %s" % type(input))

Y
Yu Yang 已提交
370 371 372
    return output


Q
QI JUN 已提交
373
def fill_constant(shape, dtype, value, force_cpu=False, out=None):
Y
Yu Yang 已提交
374
    """
375 376
    **fill_constant**

377 378
    This function creates a tensor with specified `shape` and `dtype`, and
    initializes it with a constant specifed by `value`.
K
kavyasrinet 已提交
379

380
    The attribute `stop_gradient` of the created tensor is set to True.
381 382

    Args:
383
        shape(tuple|list|None): Shape of the output tensor.
384
        dtype(np.dtype|core.VarDesc.VarType|str): Data type of the output tensor.
385 386
        value(float): The constant value used to initialize the output tensor.
        out(Variable): The output tensor.
387
        force_cpu(True|False): data should be on CPU if set true.
388 389

    Returns:
390
        Variable: The tensor variable storing the output.
391 392 393 394

    Examples:
        .. code-block:: python

395
          import paddle.fluid as fluid
396
          data = fluid.layers.fill_constant(shape=[1], value=0, dtype='int64')
Y
Yu Yang 已提交
397
    """
398

Y
Yu Yang 已提交
399 400
    helper = LayerHelper("fill_constant", **locals())
    if out is None:
X
Xin Pan 已提交
401
        out = helper.create_variable_for_type_inference(dtype=dtype)
Y
Yu Yang 已提交
402 403 404 405
    helper.append_op(
        type='fill_constant',
        inputs={},
        outputs={'Out': [out]},
Q
QI JUN 已提交
406 407 408 409
        attrs={
            'shape': shape,
            'dtype': out.dtype,
            'value': float(value),
410
            'force_cpu': force_cpu or force_init_on_cpu()
M
minqiyang 已提交
411 412
        },
        stop_gradient=True)
Y
Yu Yang 已提交
413 414 415 416
    out.stop_gradient = True
    return out


Y
yuyang18 已提交
417
@templatedoc()
Y
Yu Yang 已提交
418 419 420 421 422
def fill_constant_batch_size_like(input,
                                  shape,
                                  dtype,
                                  value,
                                  input_dim_idx=0,
423
                                  output_dim_idx=0):
424
    """
Y
yuyang18 已提交
425
    ${comment}
426 427 428 429

    It also sets *stop_gradient* to True.

    Args:
Y
yuyang18 已提交
430
        input(${input_type}): ${input_comment}.
431

Y
yuyang18 已提交
432
        shape(${shape_type}): ${shape_comment}.
433

Y
yuyang18 已提交
434 435 436
        dtype(${dtype_type}): ${dtype_comment}.

        value(${value_type}): ${value_comment}.
437

Y
yuyang18 已提交
438 439 440 441 442
        input_dim_idx(${input_dim_idx_type}): ${input_dim_idx_comment}.

        output_dim_idx(${output_dim_idx_type}): ${output_dim_idx_comment}.

    Returns:
Y
yuyang18 已提交
443
        ${out_comment}.
H
haowang101779990 已提交
444 445 446 447 448

    Examples:

        .. code-block:: python

449 450
             import paddle.fluid as fluid
             like = fluid.layers.data(name='like', shape=[1], dtype='float32')
W
wangchaochaohu 已提交
451
             data = fluid.layers.fill_constant_batch_size_like(
H
haowang101779990 已提交
452 453
                         input=like, shape=[1], value=0, dtype='int64')

454
    """
Y
Yu Yang 已提交
455
    helper = LayerHelper("fill_constant_batch_size_like", **locals())
X
Xin Pan 已提交
456
    out = helper.create_variable_for_type_inference(dtype=dtype)
Y
Yu Yang 已提交
457 458 459 460 461 462 463 464 465 466 467 468 469 470 471
    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,
            'output_dim_idx': output_dim_idx
        })
    out.stop_gradient = True
    return out


S
sneaxiy 已提交
472 473 474 475
def argmin(x, axis=0):
    """
    **argmin**

476
    This function computes the indices of the min elements
S
sneaxiy 已提交
477 478 479 480 481 482
    of the input tensor's element along the provided axis.

    Args:
        x(Variable): The input to compute the indices of
                     the min elements.
        axis(int): Axis to compute indices along.
F
fengjiayi 已提交
483

S
sneaxiy 已提交
484 485
    Returns:
        Variable: The tensor variable storing the output
F
fengjiayi 已提交
486

S
sneaxiy 已提交
487 488
    Examples:
        .. code-block:: python
F
fengjiayi 已提交
489

490
            import paddle.fluid as fluid
491 492 493
            x = fluid.layers.data(name="x", shape=[3, 4], dtype="float32")
            out = fluid.layers.argmin(x, axis=0)
            out = fluid.layers.argmin(x, axis=-1)
S
sneaxiy 已提交
494 495
    """
    helper = LayerHelper("arg_min", **locals())
X
Xin Pan 已提交
496
    out = helper.create_variable_for_type_inference(VarDesc.VarType.INT64)
S
sneaxiy 已提交
497 498 499 500 501 502 503 504 505 506 507 508
    helper.append_op(
        type='arg_min',
        inputs={'X': x},
        outputs={'Out': [out]},
        attrs={'axis': axis})
    return out


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

509
    This function computes the indices of the max elements
S
sneaxiy 已提交
510 511 512 513 514 515
    of the input tensor's element along the provided axis.

    Args:
        x(Variable): The input to compute the indices of
                     the max elements.
        axis(int): Axis to compute indices along.
F
fengjiayi 已提交
516

S
sneaxiy 已提交
517 518
    Returns:
        Variable: The tensor variable storing the output
F
fengjiayi 已提交
519

S
sneaxiy 已提交
520 521
    Examples:
        .. code-block:: python
F
fengjiayi 已提交
522

523
            import paddle.fluid as fluid
524 525 526
            x = fluid.layers.data(name="x", shape=[3, 4], dtype="float32")
            out = fluid.layers.argmax(x, axis=0)
            out = fluid.layers.argmax(x, axis=-1)
S
sneaxiy 已提交
527 528
    """
    helper = LayerHelper("arg_max", **locals())
X
Xin Pan 已提交
529
    out = helper.create_variable_for_type_inference(VarDesc.VarType.INT64)
S
sneaxiy 已提交
530 531 532 533 534 535 536 537
    helper.append_op(
        type='arg_max',
        inputs={'X': x},
        outputs={'Out': [out]},
        attrs={'axis': axis})
    return out


538
def argsort(input, axis=-1, name=None):
Y
Yibing Liu 已提交
539
    """
M
minqiyang 已提交
540 541
    Performs sorting on the input Variable along the given axis, and outputs
    sorted data Varibale and its corresponding index Variable with the same
Y
Yibing Liu 已提交
542 543 544
    shape as :attr:`input`.

    .. code-block:: text
M
minqiyang 已提交
545

Y
Yibing Liu 已提交
546 547 548 549 550 551 552 553 554 555 556 557
        For example, the given axis is -1 and the input Variable

            input = [[0.15849551, 0.45865775, 0.8563702 ],
                     [0.12070083, 0.28766365, 0.18776911]],

        after argsort, the sorted Vairable becomes

            out = [[0.15849551, 0.45865775, 0.8563702 ],
                   [0.12070083, 0.18776911, 0.28766365]],

        and the sorted indices along the given axis turn outs to be

M
minqiyang 已提交
558
            indices = [[0, 1, 2],
Y
Yibing Liu 已提交
559 560 561 562
                       [0, 2, 1]]

    Args:
        input(Variable): The input Variable for sorting.
M
minqiyang 已提交
563 564
        axis(int): The axis along which to sort the input Variable. When
                   :attr:`axis` < 0, the actual axis will be :attr:`axis` +
Y
Yibing Liu 已提交
565
                   rank(:attr:`input`). Default -1, the last dimension.
M
minqiyang 已提交
566
        name(str|None): (optional) A name for this layer. If set None, the
567
                   layer will be named automatically.
Y
Yibing Liu 已提交
568 569 570 571 572 573 574

    Returns:
        tuple: A tuple of sorted data Variable and the sorted indices.

    Examples:
        .. code-block:: python

575
            import paddle.fluid as fluid
576 577
            x = fluid.layers.data(name="x", shape=[3, 4], dtype="float32")
            out, indices = fluid.layers.argsort(input=x, axis=0)
Y
Yibing Liu 已提交
578 579
    """
    helper = LayerHelper("argsort", **locals())
X
Xin Pan 已提交
580 581 582 583
    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 已提交
584 585 586 587
    helper.append_op(
        type='argsort',
        inputs={'X': input},
        outputs={'Out': out,
588 589
                 'Indices': ids},
        attrs={'axis': axis})
Y
Yibing Liu 已提交
590 591 592
    return out, ids


Y
Yang Yu 已提交
593
def ones(shape, dtype, force_cpu=False):
Y
Yu Yang 已提交
594
    """
595 596 597 598 599 600 601 602
    **ones**

    This function creates a tensor of specified *shape* and
    *dtype*, and initializes this with 1.

    It also sets *stop_gradient* to True.

    Args:
C
chengduozh 已提交
603
        shape(tuple|list): Shape of output tensor
604
        dtype(np.dtype|core.VarDesc.VarType|str): Data type of output tensor
605 606 607 608 609 610 611

    Returns:
        Variable: The tensor variable storing the output

    Examples:
        .. code-block:: python

612
          import paddle.fluid as fluid
613
          data = fluid.layers.ones(shape=[1], dtype='int64')
Y
Yu Yang 已提交
614
    """
C
chengduozh 已提交
615 616 617 618
    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 已提交
619 620 621
    return fill_constant(value=1.0, **locals())


Y
Yang Yu 已提交
622
def zeros(shape, dtype, force_cpu=False):
Y
Yu Yang 已提交
623
    """
624 625 626 627 628 629 630 631
    **zeros**

    This function creates a tensor of specified *shape* and
    *dtype*, and initializes this with 0.

    It also sets *stop_gradient* to True.

    Args:
W
wanghaoshuang 已提交
632 633 634
        shape(tuple|list|None): Shape of output tensor.
        dtype(np.dtype|core.VarDesc.VarType|str): Data type of output tensor.
        force_cpu(bool, default False): Whether to make output stay on CPU.
635 636

    Returns:
W
wanghaoshuang 已提交
637
        Variable: The tensor variable storing the output.
638 639 640 641

    Examples:
        .. code-block:: python

642
          import paddle.fluid as fluid
643
          data = fluid.layers.zeros(shape=[1], dtype='int64')
Y
Yu Yang 已提交
644 645
    """
    return fill_constant(value=0.0, **locals())
646 647


F
fengjiayi 已提交
648 649 650 651 652 653 654 655
def reverse(x, axis):
    """
    **reverse**

    This function reverse the input 'x' along given axises.

    Args:
        x(Vairbale): the input to be reversed.
656 657 658
        axis(int|tuple|list): Axis that along which order of elements
                    is reversed. If it is a tuple or a list, reversing
                    will be apply on each axis in the tuple or list.
F
fengjiayi 已提交
659 660 661 662 663 664 665

    Returns:
        Variable: The reversed tensor.

    Examples:
        .. code-block:: python

666 667 668
          import paddle.fluid as fluid
          data = fluid.layers.data(name="data", shape=[4, 8], dtype="float32")
          out = fluid.layers.reverse(x=data, axis=0)
F
fengjiayi 已提交
669
          # or:
670
          out = fluid.layers.reverse(x=data, axis=[0,1])
F
fengjiayi 已提交
671 672 673 674
    """
    if isinstance(axis, int):
        axis = [axis]
    helper = LayerHelper("reverse", **locals())
X
Xin Pan 已提交
675
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
F
fengjiayi 已提交
676 677
    helper.append_op(
        type='reverse',
W
Wu Yi 已提交
678
        inputs={'X': x},
F
fengjiayi 已提交
679 680 681 682 683
        outputs={'Out': [out]},
        attrs={'axis': axis})
    return out


684 685 686 687 688 689 690
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.
691 692 693
        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.
694 695 696 697 698 699 700 701 702 703 704 705 706 707 708
    """
    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:
709 710
        x(list): A list of Tensor/LoDTensor variables to be saved together in
                 a single file.
711
        file_path(str): The file path where variables will be saved.
712
        overwrite(bool): Whether or not cover the given file when it has already
713 714
            existed. If it's set 'False' and the file is existed, a runtime
            error will be thrown.
715 716 717 718 719 720 721 722

    Returns:
        There is no return value.

    Examples:

        .. code-block:: python

723
            import paddle.fluid as fluid
724 725 726 727 728 729 730
            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")
731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754
    """
    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})
755 756 757 758 759 760 761 762 763 764 765


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

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

    Returns:
        Variable: The tensor variable storing the output, only a bool value.
766 767 768 769 770 771 772 773
    
    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)

774 775
    """
    helper = LayerHelper("isinf", **locals())
X
Xin Pan 已提交
776
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
777 778 779 780 781 782 783 784 785 786 787 788 789
    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:
       x(variable): The Tensor/LoDTensor to be checked.

    Returns:
        Variable: The tensor variable storing the output, only a bool value.
790 791 792 793 794 795 796 797
    
    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)

798 799
    """
    helper = LayerHelper("isnan", **locals())
X
Xin Pan 已提交
800
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
801 802 803 804 805 806 807 808 809 810 811 812 813 814
    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.
815 816 817 818 819

    Examples:

        .. code-block:: python

820
            import paddle.fluid as fluid
821 822 823 824
            var = fluid.layers.data(name="data",
                                    shape=(4, 6),
                                    dtype="float32")
            out = fluid.layers.isfinite(v)
825 826
    """
    helper = LayerHelper("isfinite", **locals())
X
Xin Pan 已提交
827
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
828 829
    helper.append_op(type="isfinite", inputs={"X": x}, outputs={"Out": out})
    return out
W
whs 已提交
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


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).

    args:
        start(int|float|Variable): Start of interval. The interval includes this value.
        end(int|float|Variable): End of interval. The interval does not include this
                                 value, except in some cases where step is not an integer
                                 and floating point round-off affects the length of out. 
        step(int|float|Variable): Spacing between values. For any output out, this is the
                                  distance between two adjacent values, out[i+1] - out[i].
                                  The default step size is 1.
        dtype(string): 'float32'|'int32'|..., the data type of the output tensor.

    returns:
        Evenly spaced values within a given interval.

    examples:

        .. code-block:: python

856
             import paddle.fluid as fluid
W
whs 已提交
857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877
             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]})
    return out
Z
zhoukunsheng 已提交
878 879


Z
zhoukunsheng 已提交
880 881 882 883 884 885 886 887
def linspace(start, stop, num, dtype):
    """
    Return fixed number of evenly spaced values within a given interval.

    First entry is start, and last entry is stop. In the case when Num is 1, only Start is returned. Like linspace function of numpy.

    Args:
        start(float|Variable): First entry in the sequence. It is a float scalar, or a tensor of shape [1] with type 'float32'|'float64'.
Z
zhoukunsheng 已提交
888
        stop(float|Variable): Last entry in the sequence. It is a float scalar, or a tensor of shape [1] with type 'float32'|'float64'.
Z
zhoukunsheng 已提交
889 890 891 892 893 894
        num(int|Variable): Number of entry in the sequence. It is an int scalar, or a tensor of shape [1] with type int32.
        dtype(string): 'float32'|'float64', the data type of the output tensor.

    Returns:
        Variable: The tensor variable storing a 1-D tensor. 

Z
zhoukunsheng 已提交
895
    Examples:
Z
zhoukunsheng 已提交
896 897
        .. code-block:: python

898
             import paddle.fluid as fluid
Z
zhoukunsheng 已提交
899 900
             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 已提交
901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920

    """
    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
921 922


Z
zhoukunsheng 已提交
923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939
def zeros_like(x, out=None):
    """
    **zeros_like**

    This function creates a zeros 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:
        Variable: The tensor variable storing the output.

    Examples:
        .. code-block:: python

940
          import paddle.fluid as fluid
Z
zhoukunsheng 已提交
941 942 943
          x = fluid.layers.data(name='x', dtype='float32', shape=[3], append_batch_size=False)
          data = fluid.layers.zeros_like(x) # [0.0, 0.0, 0.0]

Z
zhoukunsheng 已提交
944 945 946 947 948 949 950 951 952
    """

    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 已提交
953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972


def diag(diagonal):
    """
    **diag**

    This function creates a square matrix which has diagonal values specified by `diagonal`.

    Args:
        diagonal(Variable|numpy.ndarray): The input tensor specifying diagonal values, should be of rank 1.

    Returns:
        Variable: The tensor variable storing the square matrix.

    Examples:
        .. code-block:: python

          # [[3, 0, 0]
          #  [0, 4, 0]
          #  [0, 0, 5] 
973 974 975 976

          import paddle.fluid as fluid
          import numpy as np
          data = fluid.layers.diag(np.arange(3, 6, dtype='int32')) 
Z
zhoukunsheng 已提交
977 978 979 980 981 982 983 984 985 986 987 988 989 990 991

    """

    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