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

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


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

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

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

    Examples:
        .. code-block:: python

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


61 62
def create_parameter(shape,
                     dtype,
X
xuwei06 已提交
63
                     name=None,
64 65 66 67
                     attr=None,
                     is_bias=False,
                     default_initializer=None):
    """
Y
yuyang18 已提交
68 69 70 71 72 73
    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.

74 75 76 77 78 79 80 81 82 83 84
    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 已提交
85 86 87
        the created parameter.

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

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


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

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

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

    Examples:
        .. code-block:: python

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

Q
Qiao Longfei 已提交
145 146 147
    return var


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

    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 已提交
163

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


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

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

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

    Returns:
        Variable: Output variable of the concatenation

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

198
            import paddle.fluid as fluid
199 200 201 202 203
            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 已提交
204 205
    """
    helper = LayerHelper('concat', **locals())
X
Xin Pan 已提交
206
    out = helper.create_variable_for_type_inference(dtype=helper.input_dtype())
Y
Yu Yang 已提交
207 208 209 210 211 212 213 214
    helper.append_op(
        type='concat',
        inputs={'X': input},
        outputs={'Out': [out]},
        attrs={'axis': axis})
    return out


L
li099 已提交
215 216 217 218 219 220
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 已提交
221

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

L
li099 已提交
224 225 226 227 228 229 230 231
        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 已提交
232

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

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

255 256 257
            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 已提交
258
    """
L
li099 已提交
259
    helper = LayerHelper('tensor_array_to_tensor', **locals())
L
li099 已提交
260 261 262
    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 已提交
263
        type='tensor_array_to_tensor',
L
li099 已提交
264 265 266 267 268 269 270
        inputs={'X': input},
        outputs={'Out': [out],
                 'OutIndex': [out_index]},
        attrs={'axis': axis})
    return out, out_index


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

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

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

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

288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304
          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 已提交
305 306 307
    """
    helper = LayerHelper('sum', **locals())
    if out is None:
X
Xin Pan 已提交
308 309
        out = helper.create_variable_for_type_inference(
            dtype=helper.input_dtype())
T
tensor-tang 已提交
310 311 312 313 314
    helper.append_op(
        type='sum',
        inputs={'X': input},
        outputs={'Out': out},
        attrs={'use_mkldnn': False})
Y
Yu Yang 已提交
315 316 317
    return out


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

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

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

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

    Examples:
        .. code-block:: python
333

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

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

Y
Yu Yang 已提交
371 372 373
    return output


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

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

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

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

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

    Examples:
        .. code-block:: python

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

Y
Yu Yang 已提交
400
    helper = LayerHelper("fill_constant", **locals())
401 402 403 404 405 406 407
    if convert_dtype(dtype) not in [
            'bool', 'float16', 'float32', 'float64', 'int32', 'int64'
    ]:
        raise TypeError(
            "The create data type in fill_constant must be one of 'bool', float16, float32,"
            "float64, int32 or int64, but received %s." % convert_dtype(
                (dtype)))
Y
Yu Yang 已提交
408
    if out is None:
X
Xin Pan 已提交
409
        out = helper.create_variable_for_type_inference(dtype=dtype)
410 411 412 413 414 415
    else:
        if not (convert_dtype(dtype) == convert_dtype(out.dtype)):
            raise TypeError(
                "The create data type in op must be same with out type"
                "but received %s and out dtype %s." % (convert_dtype(
                    (dtype), convert_dtype(out.dtype))))
Y
Yu Yang 已提交
416 417 418 419
    helper.append_op(
        type='fill_constant',
        inputs={},
        outputs={'Out': [out]},
Q
QI JUN 已提交
420 421 422 423
        attrs={
            'shape': shape,
            'dtype': out.dtype,
            'value': float(value),
424
            'force_cpu': force_cpu or force_init_on_cpu()
M
minqiyang 已提交
425 426
        },
        stop_gradient=True)
Y
Yu Yang 已提交
427 428 429 430
    out.stop_gradient = True
    return out


Y
yuyang18 已提交
431
@templatedoc()
Y
Yu Yang 已提交
432 433 434 435 436
def fill_constant_batch_size_like(input,
                                  shape,
                                  dtype,
                                  value,
                                  input_dim_idx=0,
437
                                  output_dim_idx=0):
438
    """
Y
yuyang18 已提交
439
    ${comment}
440 441 442 443

    It also sets *stop_gradient* to True.

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

Y
yuyang18 已提交
446
        shape(${shape_type}): ${shape_comment}.
447

Y
yuyang18 已提交
448 449 450
        dtype(${dtype_type}): ${dtype_comment}.

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

Y
yuyang18 已提交
452 453 454 455 456
        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 已提交
457
        ${out_comment}.
H
haowang101779990 已提交
458 459 460 461 462

    Examples:

        .. code-block:: python

463 464
             import paddle.fluid as fluid
             like = fluid.layers.data(name='like', shape=[1], dtype='float32')
W
wangchaochaohu 已提交
465
             data = fluid.layers.fill_constant_batch_size_like(
H
haowang101779990 已提交
466 467
                         input=like, shape=[1], value=0, dtype='int64')

468
    """
Y
Yu Yang 已提交
469
    helper = LayerHelper("fill_constant_batch_size_like", **locals())
X
Xin Pan 已提交
470
    out = helper.create_variable_for_type_inference(dtype=dtype)
Y
Yu Yang 已提交
471 472 473 474 475 476 477 478 479 480 481 482 483 484 485
    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 已提交
486 487 488 489
def argmin(x, axis=0):
    """
    **argmin**

490
    This function computes the indices of the min elements
S
sneaxiy 已提交
491 492 493 494 495 496
    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 已提交
497

S
sneaxiy 已提交
498 499
    Returns:
        Variable: The tensor variable storing the output
F
fengjiayi 已提交
500

S
sneaxiy 已提交
501 502
    Examples:
        .. code-block:: python
F
fengjiayi 已提交
503

504
            import paddle.fluid as fluid
505 506 507
            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 已提交
508 509
    """
    helper = LayerHelper("arg_min", **locals())
X
Xin Pan 已提交
510
    out = helper.create_variable_for_type_inference(VarDesc.VarType.INT64)
S
sneaxiy 已提交
511 512 513 514 515 516 517 518 519 520 521 522
    helper.append_op(
        type='arg_min',
        inputs={'X': x},
        outputs={'Out': [out]},
        attrs={'axis': axis})
    return out


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

523
    This function computes the indices of the max elements
S
sneaxiy 已提交
524 525 526 527 528 529
    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 已提交
530

S
sneaxiy 已提交
531 532
    Returns:
        Variable: The tensor variable storing the output
F
fengjiayi 已提交
533

S
sneaxiy 已提交
534 535
    Examples:
        .. code-block:: python
F
fengjiayi 已提交
536

537
            import paddle.fluid as fluid
538 539 540
            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 已提交
541 542
    """
    helper = LayerHelper("arg_max", **locals())
X
Xin Pan 已提交
543
    out = helper.create_variable_for_type_inference(VarDesc.VarType.INT64)
S
sneaxiy 已提交
544 545 546 547 548 549 550 551
    helper.append_op(
        type='arg_max',
        inputs={'X': x},
        outputs={'Out': [out]},
        attrs={'axis': axis})
    return out


552
def argsort(input, axis=-1, name=None):
Y
Yibing Liu 已提交
553
    """
M
minqiyang 已提交
554 555
    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 已提交
556 557 558
    shape as :attr:`input`.

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

Y
Yibing Liu 已提交
560 561 562 563 564 565 566 567 568 569 570 571
        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 已提交
572
            indices = [[0, 1, 2],
Y
Yibing Liu 已提交
573 574 575 576
                       [0, 2, 1]]

    Args:
        input(Variable): The input Variable for sorting.
M
minqiyang 已提交
577 578
        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 已提交
579
                   rank(:attr:`input`). Default -1, the last dimension.
M
minqiyang 已提交
580
        name(str|None): (optional) A name for this layer. If set None, the
581
                   layer will be named automatically.
Y
Yibing Liu 已提交
582 583 584 585 586 587 588

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

    Examples:
        .. code-block:: python

589
            import paddle.fluid as fluid
590 591
            x = fluid.layers.data(name="x", shape=[3, 4], dtype="float32")
            out, indices = fluid.layers.argsort(input=x, axis=0)
Y
Yibing Liu 已提交
592 593
    """
    helper = LayerHelper("argsort", **locals())
X
Xin Pan 已提交
594 595 596 597
    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 已提交
598 599 600 601
    helper.append_op(
        type='argsort',
        inputs={'X': input},
        outputs={'Out': out,
602 603
                 'Indices': ids},
        attrs={'axis': axis})
Y
Yibing Liu 已提交
604 605 606
    return out, ids


Y
Yang Yu 已提交
607
def ones(shape, dtype, force_cpu=False):
Y
Yu Yang 已提交
608
    """
609 610 611 612 613 614 615 616
    **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 已提交
617
        shape(tuple|list): Shape of output tensor
618
        dtype(np.dtype|core.VarDesc.VarType|str): Data type of output tensor
619 620 621 622 623 624 625

    Returns:
        Variable: The tensor variable storing the output

    Examples:
        .. code-block:: python

626
          import paddle.fluid as fluid
627
          data = fluid.layers.ones(shape=[1], dtype='int64')
Y
Yu Yang 已提交
628
    """
C
chengduozh 已提交
629 630 631 632
    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 已提交
633 634 635
    return fill_constant(value=1.0, **locals())


Y
Yang Yu 已提交
636
def zeros(shape, dtype, force_cpu=False):
Y
Yu Yang 已提交
637
    """
638 639 640 641 642 643 644 645
    **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 已提交
646 647 648
        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.
649 650

    Returns:
W
wanghaoshuang 已提交
651
        Variable: The tensor variable storing the output.
652 653 654 655

    Examples:
        .. code-block:: python

656
          import paddle.fluid as fluid
657
          data = fluid.layers.zeros(shape=[1], dtype='int64')
Y
Yu Yang 已提交
658 659
    """
    return fill_constant(value=0.0, **locals())
660 661


F
fengjiayi 已提交
662 663 664 665 666 667 668 669
def reverse(x, axis):
    """
    **reverse**

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

    Args:
        x(Vairbale): the input to be reversed.
670 671 672
        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 已提交
673 674 675 676 677 678 679

    Returns:
        Variable: The reversed tensor.

    Examples:
        .. code-block:: python

680 681 682
          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 已提交
683
          # or:
684
          out = fluid.layers.reverse(x=data, axis=[0,1])
F
fengjiayi 已提交
685 686 687 688
    """
    if isinstance(axis, int):
        axis = [axis]
    helper = LayerHelper("reverse", **locals())
X
Xin Pan 已提交
689
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
F
fengjiayi 已提交
690 691
    helper.append_op(
        type='reverse',
W
Wu Yi 已提交
692
        inputs={'X': x},
F
fengjiayi 已提交
693 694 695 696 697
        outputs={'Out': [out]},
        attrs={'axis': axis})
    return out


698 699 700 701 702 703 704
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.
705 706 707
        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.
708 709 710 711 712 713 714 715 716 717 718 719 720 721 722
    """
    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:
723 724
        x(list): A list of Tensor/LoDTensor variables to be saved together in
                 a single file.
725
        file_path(str): The file path where variables will be saved.
726
        overwrite(bool): Whether or not cover the given file when it has already
727 728
            existed. If it's set 'False' and the file is existed, a runtime
            error will be thrown.
729 730 731 732 733 734 735 736

    Returns:
        There is no return value.

    Examples:

        .. code-block:: python

737
            import paddle.fluid as fluid
738 739 740 741 742 743 744
            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")
745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768
    """
    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})
769 770 771 772 773 774 775


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

    Args:
776
       x (Variable): The Tensor/LoDTensor to be checked.
777 778

    Returns:
779
       Variable: The tensor variable storing the output, only a bool value, indicating that whether there is infinity number in x or not.
780 781 782 783 784 785 786 787
    
    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)

788 789
    """
    helper = LayerHelper("isinf", **locals())
X
Xin Pan 已提交
790
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
791 792 793 794 795 796 797 798 799
    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:
800
       x (Variable): The Tensor/LoDTensor to be checked.
801 802

    Returns:
803
       Variable: The tensor variable storing the output, only a bool value, indicating that whether there is NAN in x or not.
804 805 806 807 808 809 810 811
    
    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)

812 813
    """
    helper = LayerHelper("isnan", **locals())
X
Xin Pan 已提交
814
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
815 816 817 818 819 820 821 822 823 824 825 826 827 828
    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.
829 830 831 832 833

    Examples:

        .. code-block:: python

834
            import paddle.fluid as fluid
835 836 837
            var = fluid.layers.data(name="data",
                                    shape=(4, 6),
                                    dtype="float32")
石晓伟 已提交
838
            out = fluid.layers.isfinite(var)
839 840
    """
    helper = LayerHelper("isfinite", **locals())
X
Xin Pan 已提交
841
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
842 843
    helper.append_op(type="isfinite", inputs={"X": x}, outputs={"Out": out})
    return out
W
whs 已提交
844 845 846 847 848 849 850 851 852


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 已提交
853 854 855 856
    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 已提交
857
                                 value, except in some cases where step is not an integer
L
Liufang Sang 已提交
858 859 860
                                 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 已提交
861
                                  distance between two adjacent values, out[i+1] - out[i].
L
Liufang Sang 已提交
862
        dtype(str): the data type of the output tensor, can be float32, float64, int32, int64.
W
whs 已提交
863

L
Liufang Sang 已提交
864 865 866
    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 已提交
867 868 869 870 871

    examples:

        .. code-block:: python

872
             import paddle.fluid as fluid
W
whs 已提交
873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892
             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]})
893
    out.stop_gradient = True
W
whs 已提交
894
    return out
Z
zhoukunsheng 已提交
895 896


Z
zhoukunsheng 已提交
897 898
def linspace(start, stop, num, dtype):
    """
899
    This OP return fixed number of evenly spaced values within a given interval.
Z
zhoukunsheng 已提交
900 901

    Args:
902 903 904 905 906 907 908
        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 已提交
909 910

    Returns:
911 912 913
        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 已提交
914

Z
zhoukunsheng 已提交
915
    Examples:
Z
zhoukunsheng 已提交
916 917
        .. code-block:: python

918
             import paddle.fluid as fluid
Z
zhoukunsheng 已提交
919 920
             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 已提交
921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940

    """
    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
941 942


Z
zhoukunsheng 已提交
943 944
def zeros_like(x, out=None):
    """
945
    This OP creates a zeros tensor which has identical shape and dtype 
Z
zhoukunsheng 已提交
946 947 948
    with `x`.

    Args:
949 950 951 952
        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 已提交
953 954

    Returns:
955 956
        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 已提交
957 958 959 960

    Examples:
        .. code-block:: python

961
          import paddle.fluid as fluid
962
          x = fluid.data(name='x', dtype='float32', shape=[3])
Z
zhoukunsheng 已提交
963 964
          data = fluid.layers.zeros_like(x) # [0.0, 0.0, 0.0]

Z
zhoukunsheng 已提交
965 966 967 968 969 970 971 972 973
    """

    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 已提交
974 975 976 977


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

    Args:
981 982
        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 已提交
983 984

    Returns:
985 986
        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 已提交
987 988 989 990 991 992 993

    Examples:
        .. code-block:: python

          # [[3, 0, 0]
          #  [0, 4, 0]
          #  [0, 0, 5] 
994 995 996

          import paddle.fluid as fluid
          import numpy as np
997 998 999
          diagonal = np.arange(3, 6, dtype='int32')
          data = fluid.layers.diag(diagonal)
          # diagonal.shape=(3,) data.shape=(3, 3)
Z
zhoukunsheng 已提交
1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014

    """

    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 已提交
1015 1016


1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028
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.
1029 1030
        dtype(string): The data type of the returned tensor.
                       It should be int32, int64, float16, float32, float64.
1031 1032

    Returns:
1033
        Variable: An identity Tensor or LoDTensor of shape batch_shape + [num_rows, num_columns].
1034 1035 1036 1037 1038

    Examples:
        .. code-block:: python

          import paddle.fluid as fluid
1039 1040
          data = fluid.layers.eye(3, dtype='int32')
          # [[1, 0, 0]
1041
          #  [0, 1, 0]
1042 1043
          #  [0, 0, 1]]

1044
          data = fluid.layers.eye(2, 3, dtype='int32')
1045
          # [[1, 0, 0]
1046
          #  [0, 1, 0]]
1047 1048

          data = fluid.layers.eye(2, batch_shape=[3])
1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088
          # 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 已提交
1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100
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:
1101
        out(Variable): The tensor variable storing the output.
Z
zhoukunsheng 已提交
1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121

    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