tensor.py 30.5 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 52 53

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

    Examples:
        .. code-block:: python

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


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

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

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

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


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

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

    Returns:
        Variable: the created Variable
F
fengjiayi 已提交
122 123 124 125

    Examples:
        .. code-block:: python

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

Q
Qiao Longfei 已提交
141 142 143
    return var


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

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

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


174
def concat(input, axis=0, name=None):
Y
Yu Yang 已提交
175
    """
176 177 178
    **Concat**

    This function concatenates the input along the axis mentioned
Y
Yu Yang 已提交
179
    and returns that as the output.
180 181 182 183

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

    Returns:
        Variable: Output variable of the concatenation

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

193 194 195 196 197
            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 已提交
198 199
    """
    helper = LayerHelper('concat', **locals())
X
Xin Pan 已提交
200
    out = helper.create_variable_for_type_inference(dtype=helper.input_dtype())
Y
Yu Yang 已提交
201 202 203 204 205 206 207 208
    helper.append_op(
        type='concat',
        inputs={'X': input},
        outputs={'Out': [out]},
        attrs={'axis': axis})
    return out


L
li099 已提交
209 210 211 212 213 214
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 已提交
215

L
li099 已提交
216
    .. code-block:: text
M
minqiyang 已提交
217

L
li099 已提交
218 219 220 221 222 223 224 225
        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 已提交
226

L
li099 已提交
227
        axis = 1
M
minqiyang 已提交
228

L
li099 已提交
229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248
        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

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


265
def sums(input, out=None):
F
fengjiayi 已提交
266 267
    """
    This function performs the sum operation on the input and returns the
K
kavyasrinet 已提交
268 269 270 271 272
    result as the output.

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

    Returns:
F
fengjiayi 已提交
277
        Variable: the sum of input. The same as the argument 'out'
K
kavyasrinet 已提交
278 279

    Examples:
F
fengjiayi 已提交
280
        .. code-block:: python
K
kavyasrinet 已提交
281

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


F
fengjiayi 已提交
312
def assign(input, output=None):
313 314 315 316 317 318
    """
    **Assign**

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

    Args:
X
xuwei06 已提交
319
        input(Variable|numpy.ndarray): The source variable
F
fengjiayi 已提交
320
        output(Variable|None): The destination variable
321 322 323 324 325 326

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

    Examples:
        .. code-block:: python
327

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

        helper.append_op(
            type='assign_value',
            outputs={'Out': [output]},
            attrs={
                'dtype': dtype,
                'shape': list(input.shape),
360
                value_name: values
X
xuwei06 已提交
361 362 363 364
            })
    else:
        raise ValueError("Wrong type for assign input: %s" % type(input))

Y
Yu Yang 已提交
365 366 367
    return output


Q
QI JUN 已提交
368
def fill_constant(shape, dtype, value, force_cpu=False, out=None):
Y
Yu Yang 已提交
369
    """
370 371
    **fill_constant**

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

375
    The attribute `stop_gradient` of the created tensor is set to True.
376 377

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

    Returns:
385
        Variable: The tensor variable storing the output.
386 387 388 389

    Examples:
        .. code-block:: python

390
          import paddle.fluid as fluid
391
          data = fluid.layers.fill_constant(shape=[1], value=0, dtype='int64')
Y
Yu Yang 已提交
392
    """
393

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


Y
yuyang18 已提交
412
@templatedoc()
Y
Yu Yang 已提交
413 414 415 416 417
def fill_constant_batch_size_like(input,
                                  shape,
                                  dtype,
                                  value,
                                  input_dim_idx=0,
418
                                  output_dim_idx=0):
419
    """
Y
yuyang18 已提交
420
    ${comment}
421 422 423 424

    It also sets *stop_gradient* to True.

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

Y
yuyang18 已提交
427
        shape(${shape_type}): ${shape_comment}.
428

Y
yuyang18 已提交
429 430 431
        dtype(${dtype_type}): ${dtype_comment}.

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

Y
yuyang18 已提交
433 434 435 436 437
        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 已提交
438
        ${out_comment}.
H
haowang101779990 已提交
439 440 441 442 443

    Examples:

        .. code-block:: python

444 445 446
             import paddle.fluid as fluid
             like = fluid.layers.data(name='like', shape=[1], dtype='float32')
             data = fluid.lgyers.fill_constant_batch_size_like(
H
haowang101779990 已提交
447 448
                         input=like, shape=[1], value=0, dtype='int64')

449
    """
Y
Yu Yang 已提交
450
    helper = LayerHelper("fill_constant_batch_size_like", **locals())
X
Xin Pan 已提交
451
    out = helper.create_variable_for_type_inference(dtype=dtype)
Y
Yu Yang 已提交
452 453 454 455 456 457 458 459 460 461 462 463 464 465 466
    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 已提交
467 468 469 470
def argmin(x, axis=0):
    """
    **argmin**

471
    This function computes the indices of the min elements
S
sneaxiy 已提交
472 473 474 475 476 477
    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 已提交
478

S
sneaxiy 已提交
479 480
    Returns:
        Variable: The tensor variable storing the output
F
fengjiayi 已提交
481

S
sneaxiy 已提交
482 483
    Examples:
        .. code-block:: python
F
fengjiayi 已提交
484

485 486 487
            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 已提交
488 489
    """
    helper = LayerHelper("arg_min", **locals())
X
Xin Pan 已提交
490
    out = helper.create_variable_for_type_inference(VarDesc.VarType.INT64)
S
sneaxiy 已提交
491 492 493 494 495 496 497 498 499 500 501 502
    helper.append_op(
        type='arg_min',
        inputs={'X': x},
        outputs={'Out': [out]},
        attrs={'axis': axis})
    return out


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

503
    This function computes the indices of the max elements
S
sneaxiy 已提交
504 505 506 507 508 509
    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 已提交
510

S
sneaxiy 已提交
511 512
    Returns:
        Variable: The tensor variable storing the output
F
fengjiayi 已提交
513

S
sneaxiy 已提交
514 515
    Examples:
        .. code-block:: python
F
fengjiayi 已提交
516

517 518 519
            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 已提交
520 521
    """
    helper = LayerHelper("arg_max", **locals())
X
Xin Pan 已提交
522
    out = helper.create_variable_for_type_inference(VarDesc.VarType.INT64)
S
sneaxiy 已提交
523 524 525 526 527 528 529 530
    helper.append_op(
        type='arg_max',
        inputs={'X': x},
        outputs={'Out': [out]},
        attrs={'axis': axis})
    return out


531
def argsort(input, axis=-1, name=None):
Y
Yibing Liu 已提交
532
    """
M
minqiyang 已提交
533 534
    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 已提交
535 536 537
    shape as :attr:`input`.

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

Y
Yibing Liu 已提交
539 540 541 542 543 544 545 546 547 548 549 550
        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 已提交
551
            indices = [[0, 1, 2],
Y
Yibing Liu 已提交
552 553 554 555
                       [0, 2, 1]]

    Args:
        input(Variable): The input Variable for sorting.
M
minqiyang 已提交
556 557
        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 已提交
558
                   rank(:attr:`input`). Default -1, the last dimension.
M
minqiyang 已提交
559
        name(str|None): (optional) A name for this layer. If set None, the
560
                   layer will be named automatically.
Y
Yibing Liu 已提交
561 562 563 564 565 566 567

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

    Examples:
        .. code-block:: python

568 569
            x = fluid.layers.data(name="x", shape=[3, 4], dtype="float32")
            out, indices = fluid.layers.argsort(input=x, axis=0)
Y
Yibing Liu 已提交
570 571
    """
    helper = LayerHelper("argsort", **locals())
X
Xin Pan 已提交
572 573 574 575
    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 已提交
576 577 578 579
    helper.append_op(
        type='argsort',
        inputs={'X': input},
        outputs={'Out': out,
580 581
                 'Indices': ids},
        attrs={'axis': axis})
Y
Yibing Liu 已提交
582 583 584
    return out, ids


Y
Yang Yu 已提交
585
def ones(shape, dtype, force_cpu=False):
Y
Yu Yang 已提交
586
    """
587 588 589 590 591 592 593 594
    **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 已提交
595
        shape(tuple|list): Shape of output tensor
596
        dtype(np.dtype|core.VarDesc.VarType|str): Data type of output tensor
597 598 599 600 601 602 603

    Returns:
        Variable: The tensor variable storing the output

    Examples:
        .. code-block:: python

604
          import paddle.fluid as fluid
605
          data = fluid.layers.ones(shape=[1], dtype='int64')
Y
Yu Yang 已提交
606
    """
C
chengduozh 已提交
607 608 609 610
    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 已提交
611 612 613
    return fill_constant(value=1.0, **locals())


Y
Yang Yu 已提交
614
def zeros(shape, dtype, force_cpu=False):
Y
Yu Yang 已提交
615
    """
616 617 618 619 620 621 622 623
    **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 已提交
624 625 626
        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.
627 628

    Returns:
W
wanghaoshuang 已提交
629
        Variable: The tensor variable storing the output.
630 631 632 633

    Examples:
        .. code-block:: python

634
          import paddle.fluid as fluid
635
          data = fluid.layers.zeros(shape=[1], dtype='int64')
Y
Yu Yang 已提交
636 637
    """
    return fill_constant(value=0.0, **locals())
638 639


F
fengjiayi 已提交
640 641 642 643 644 645 646 647
def reverse(x, axis):
    """
    **reverse**

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

    Args:
        x(Vairbale): the input to be reversed.
648 649 650
        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 已提交
651 652 653 654 655 656 657

    Returns:
        Variable: The reversed tensor.

    Examples:
        .. code-block:: python

658 659 660
          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 已提交
661
          # or:
662
          out = fluid.layers.reverse(x=data, axis=[0,1])
F
fengjiayi 已提交
663 664 665 666
    """
    if isinstance(axis, int):
        axis = [axis]
    helper = LayerHelper("reverse", **locals())
X
Xin Pan 已提交
667
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
F
fengjiayi 已提交
668 669
    helper.append_op(
        type='reverse',
W
Wu Yi 已提交
670
        inputs={'X': x},
F
fengjiayi 已提交
671 672 673 674 675
        outputs={'Out': [out]},
        attrs={'axis': axis})
    return out


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

    Returns:
        There is no return value.

    Examples:

        .. code-block:: python

            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")
722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745
    """
    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})
746 747 748 749 750 751 752 753 754 755 756


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.
757 758 759 760 761 762 763 764
    
    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)

765 766
    """
    helper = LayerHelper("isinf", **locals())
X
Xin Pan 已提交
767
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
768 769 770 771 772 773 774 775 776 777 778 779 780
    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.
781 782 783 784 785 786 787 788
    
    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)

789 790
    """
    helper = LayerHelper("isnan", **locals())
X
Xin Pan 已提交
791
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
792 793 794 795 796 797 798 799 800 801 802 803 804 805
    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.
806 807 808 809 810 811 812 813 814

    Examples:

        .. code-block:: python

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


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

             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 已提交
867 868


Z
zhoukunsheng 已提交
869 870 871 872 873 874 875 876
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 已提交
877
        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 已提交
878 879 880 881 882 883
        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 已提交
884
    Examples:
Z
zhoukunsheng 已提交
885 886
        .. code-block:: python

Z
zhoukunsheng 已提交
887 888
             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 已提交
889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908

    """
    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
909 910


Z
zhoukunsheng 已提交
911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927
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

Z
zhoukunsheng 已提交
928 929 930
          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 已提交
931 932 933 934 935 936 937 938 939
    """

    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 已提交
940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975


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] 
          data = fluid.layers.diag(np.arange(3, 6)) 

    """

    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