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

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

Y
Yu Yang 已提交
363 364 365
    return output


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

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

373
    The attribute `stop_gradient` of the created tensor is set to True.
374 375

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

    Returns:
383
        Variable: The tensor variable storing the output.
384 385 386 387

    Examples:
        .. code-block:: python

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

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


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

    It also sets *stop_gradient* to True.

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

Y
yuyang18 已提交
425
        shape(${shape_type}): ${shape_comment}.
426

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

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

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

    Examples:

        .. code-block:: python

442 443 444
             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 已提交
445 446
                         input=like, shape=[1], value=0, dtype='int64')

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

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

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

S
sneaxiy 已提交
480 481
    Examples:
        .. code-block:: python
F
fengjiayi 已提交
482

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


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

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

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

S
sneaxiy 已提交
512 513
    Examples:
        .. code-block:: python
F
fengjiayi 已提交
514

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


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

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

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

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

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

    Examples:
        .. code-block:: python

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


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

    Returns:
        Variable: The tensor variable storing the output

    Examples:
        .. code-block:: python

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


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

    Returns:
W
wanghaoshuang 已提交
626
        Variable: The tensor variable storing the output.
627 628 629 630 631

    Examples:
        .. code-block:: python

          data = fluid.layers.zeros(shape=[1], dtype='int64')
Y
Yu Yang 已提交
632 633
    """
    return fill_constant(value=0.0, **locals())
634 635


F
fengjiayi 已提交
636 637 638 639 640 641 642 643
def reverse(x, axis):
    """
    **reverse**

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

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

    Returns:
        Variable: The reversed tensor.

    Examples:
        .. code-block:: python

          out = fluid.layers.reverse(x=in, axis=0)
          # or:
          out = fluid.layers.reverse(x=in, axis=[0,1])
    """
    if isinstance(axis, int):
        axis = [axis]
    helper = LayerHelper("reverse", **locals())
X
Xin Pan 已提交
661
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
F
fengjiayi 已提交
662 663
    helper.append_op(
        type='reverse',
W
Wu Yi 已提交
664
        inputs={'X': x},
F
fengjiayi 已提交
665 666 667 668 669
        outputs={'Out': [out]},
        attrs={'axis': axis})
    return out


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

    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")
716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739
    """
    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})
740 741 742 743 744 745 746 747 748 749 750


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.
751 752 753 754 755 756 757 758
    
    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)

759 760
    """
    helper = LayerHelper("isinf", **locals())
X
Xin Pan 已提交
761
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
762 763 764 765 766 767 768 769 770 771 772 773 774
    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.
775 776 777 778 779 780 781 782
    
    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)

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

    Examples:

        .. code-block:: python

            var = fluid.layers.data(name="data",
                                    shape=(4, 6),
                                    dtype="float32")
            out = fluid.layers.isfinite(v)
809 810
    """
    helper = LayerHelper("isfinite", **locals())
X
Xin Pan 已提交
811
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
812 813
    helper.append_op(type="isfinite", inputs={"X": x}, outputs={"Out": out})
    return out
W
whs 已提交
814 815 816 817 818 819 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


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 已提交
861 862


Z
zhoukunsheng 已提交
863 864 865 866 867 868 869 870
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 已提交
871
        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 已提交
872 873 874 875 876 877
        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 已提交
878
    Examples:
Z
zhoukunsheng 已提交
879 880
        .. code-block:: python

Z
zhoukunsheng 已提交
881 882
             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 已提交
883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902

    """
    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
903 904


Z
zhoukunsheng 已提交
905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921
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 已提交
922 923 924
          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 已提交
925 926 927 928 929 930 931 932 933
    """

    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 已提交
934 935 936 937 938 939 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


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