creation.py 39.6 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14
#   Copyright (c) 2020 PaddlePaddle Authors. All Rights Reserved.
#
# 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
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# 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.

P
Pei Yang 已提交
15
from __future__ import print_function
16 17
import numpy as np

18
from ..fluid.layers import tensor
L
Li Fuchen 已提交
19
from ..fluid.framework import Variable
20
from ..fluid.framework import unique_name
21
from ..fluid.framework import _current_expected_place, _get_paddle_place
22
from ..fluid.framework import dygraph_only
P
Pei Yang 已提交
23 24 25 26 27
from ..fluid.initializer import Constant
from ..fluid.layers import core
from ..fluid.layer_helper import LayerHelper
from ..fluid.data_feeder import check_variable_and_dtype, check_type, check_dtype, convert_dtype
from ..fluid.framework import convert_np_dtype_to_dtype_, in_dygraph_mode, _varbase_creator, device_guard, OpProtoHolder
28 29
from paddle.common_ops_import import *
# TODO: define functions to get create a tensor  
30
from ..fluid.layers import linspace  #DEFINE_ALIAS
31
import paddle
32

W
wangchaochaohu 已提交
33
__all__ = [
34
    'to_tensor',
35 36
    'diag',
    #       'get_tensor_from_selected_rows',
37
    'linspace',
38 39 40 41
    'ones',
    'ones_like',
    'zeros',
    'zeros_like',
42
    'arange',
43
    'eye',
W
wangchaochaohu 已提交
44
    'full',
P
Pei Yang 已提交
45
    'full_like',
46
    'empty',
47
    'empty_like',
W
WuHaobo 已提交
48 49
    'triu',
    'tril',
50 51
    'meshgrid',
    'assign',
W
wangchaochaohu 已提交
52 53 54
]


55 56
@dygraph_only
def to_tensor(data, dtype=None, place=None, stop_gradient=True):
57
    r"""
C
chentianyu03 已提交
58 59
    Constructs a ``paddle.Tensor`` from ``data`` , 
    which can be scalar, tuple, list, numpy\.ndarray, paddle\.Tensor.
60 61 62

    If the ``data`` is already a tensor, and ``dtype`` or ``place`` does't change, no copy 
    will be performed and return origin tensor, otherwise a new tensor will be constructed
L
Leo Chen 已提交
63
    and returned. 
64 65

    Args:
C
chentianyu03 已提交
66 67
        data(scalar|tuple|list|ndarray|Tensor): Initial data for the tensor.
            Can be a scalar, list, tuple, numpy\.ndarray, paddle\.Tensor.
68
        dtype(str|np.dtype, optional): The desired data type of returned tensor. Can be 'bool' , 'float16' , 
C
chentianyu03 已提交
69 70
            'float32' , 'float64' , 'int8' , 'int16' , 'int32' , 'int64' , 'uint8',
            'complex64' , 'complex128'. Default: None, infers dtype from ``data`` 
71
            except for python float number which gets dtype from ``get_default_type`` .
72 73 74
        place(CPUPlace|CUDAPinnedPlace|CUDAPlace|str, optional): The place to allocate Tensor. Can be  
            CPUPlace, CUDAPinnedPlace, CUDAPlace. Default: None, means global place. If ``place`` is 
            string, It can be ``cpu``, ``gpu:x`` and ``gpu_pinned``, where ``x`` is the index of the GPUs. 
75 76 77
        stop_gradient(bool, optional): Whether to block the gradient propagation of Autograd. Default: True.

    Returns:
C
chentianyu03 已提交
78
        Tensor: A Tensor constructed from ``data`` .
79 80

    Raises:
C
chentianyu03 已提交
81
        TypeError: If the data type of ``data`` is not scalar, list, tuple, numpy.ndarray, paddle.Tensor
82 83
        ValueError: If ``data`` is tuple|list, it can't contain nested tuple|list with different lengths , such as: [[1, 2], [3, 4, 5]]
        TypeError: If ``dtype`` is not bool, float16, float32, float64, int8, int16, int32, int64, uint8, complex64, complex128
84
        ValueError: If ``place`` is not paddle.CPUPlace, paddle.CUDAPinnedPlace, paddle.CUDAPlace or specified pattern string. 
85 86 87 88 89 90 91 92 93 94 95

    Examples:

    .. code-block:: python

        import paddle
                
        type(paddle.to_tensor(1))
        # <class 'paddle.Tensor'>

        paddle.to_tensor(1)
96 97
        # Tensor(shape=[1], dtype=int64, place=CUDAPlace(0), stop_gradient=True,
        #        [1])
98 99 100

        x = paddle.to_tensor(1)
        paddle.to_tensor(x, dtype='int32', place=paddle.CPUPlace()) # A new tensor will be constructed due to different dtype or place
101 102
        # Tensor(shape=[1], dtype=int32, place=CPUPlace, stop_gradient=True,
        #        [1])
103 104

        paddle.to_tensor((1.1, 2.2), place=paddle.CUDAPinnedPlace())
105 106
        # Tensor(shape=[1], dtype=float32, place=CUDAPinnedPlace, stop_gradient=True,
        #        [1])
107 108

        paddle.to_tensor([[0.1, 0.2], [0.3, 0.4]], place=paddle.CUDAPlace(0), stop_gradient=False)
109 110 111
        # Tensor(shape=[2, 2], dtype=float32, place=CUDAPlace(0), stop_gradient=False,
        #        [[0.10000000, 0.20000000],
        #         [0.30000001, 0.40000001]])
112

C
chentianyu03 已提交
113 114
        type(paddle.to_tensor([[1+1j, 2], [3+2j, 4]], dtype='complex64'))
        # <class 'paddle.VarBase'>
115 116

        paddle.to_tensor([[1+1j, 2], [3+2j, 4]], dtype='complex64')
C
chentianyu03 已提交
117 118 119
        # Tensor(shape=[2, 2], dtype=complex64, place=CUDAPlace(0), stop_gradient=True,
        #        [[(1+1j), (2+0j)],
        #         [(3+2j), (4+0j)]])
120 121
    """

122
    place = _get_paddle_place(place)
123 124
    if place is None:
        place = _current_expected_place()
125 126 127
    elif not isinstance(
            place,
        (core.Place, core.CPUPlace, core.CUDAPinnedPlace, core.CUDAPlace)):
128
        raise ValueError(
129
            "'place' must be any of paddle.Place, paddle.CPUPlace, paddle.CUDAPinnedPlace, paddle.CUDAPlace"
130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157
        )

    #Todo(zhouwei): Support allocate tensor on any other specified card
    if isinstance(place, core.CUDAPlace) and isinstance(
            _current_expected_place(), core.CUDAPlace) and place._get_device_id(
            ) != _current_expected_place()._get_device_id():
        place = _current_expected_place()

    if not isinstance(data, np.ndarray):
        if np.isscalar(data) and not isinstance(data, str):
            data = np.array([data])
        elif isinstance(data, (list, tuple)):
            data = np.array(data)
            if data.dtype == np.object:
                raise ValueError(
                    "\n\tFaild to convert input data to a regular ndarray :\n\t - Usually "
                    "this means the input data contains nested lists with different lengths. "
                )
        elif isinstance(data, paddle.Tensor):
            data.stop_gradient = stop_gradient
            if not data.place._equals(place):
                data = data._copy_to(place, False)
            if dtype:
                if convert_dtype(dtype) != convert_dtype(data.dtype):
                    return data.astype(convert_dtype(dtype))
            return data
        else:
            raise TypeError(
C
chentianyu03 已提交
158
                "Can't constructs a 'paddle.Tensor' with data type {}, data type must be scalar|list|tuple|numpy.ndarray|paddle.Tensor".
159
                format(type(data)))
160 161 162 163 164 165 166 167 168 169 170 171
        if not dtype and data.dtype in [
                'float16', 'float32', 'float64', 'complex64', 'complex128'
        ]:
            default_type = paddle.get_default_dtype()
            if np.iscomplexobj(data):
                default_type = 'complex64' if default_type in [
                    'float16', 'float32'
                ] else 'complex128'
            data = data.astype(default_type)

    if dtype and convert_dtype(dtype) != data.dtype:
        data = data.astype(dtype)
172

C
chentianyu03 已提交
173 174 175 176 177 178
    return paddle.Tensor(
        value=data,
        place=place,
        persistable=False,
        zero_copy=False,
        stop_gradient=stop_gradient)
179 180


181
def full_like(x, fill_value, dtype=None, name=None):
P
Pei Yang 已提交
182
    """
S
swtkiwi 已提交
183

184 185
    This function creates a tensor filled with ``fill_value`` which has identical shape of ``x`` and ``dtype``.
    If the ``dtype`` is None, the data type of Tensor is same with ``x``.
186

P
Pei Yang 已提交
187
    Args:
188 189
        x(Tensor): The input tensor which specifies shape and data type. The data type can be bool, float16, float32, float64, int32, int64.
        fill_value(bool|float|int): The value to fill the tensor with. Note: this value shouldn't exceed the range of the output data type.
W
wangchaochaohu 已提交
190
        dtype(np.dtype|str, optional): The data type of output. The data type can be one
191 192
            of bool, float16, float32, float64, int32, int64. The default value is None, which means the output 
            data type is the same as input.
193 194
        name(str, optional): The default value is None. Normally there is no need for user to set this property. For more information, please refer to :ref:`api_guide_Name`
    
P
Pei Yang 已提交
195
    Returns:
196
        Tensor: Tensor which is created according to ``x``, ``fill_value`` and ``dtype``.
197
    
P
Pei Yang 已提交
198 199
    Examples:
        .. code-block:: python
200

P
Pei Yang 已提交
201 202
          import paddle
          import numpy as np
203 204
          
          input = paddle.full(shape=[2, 3], fill_value=0.0, dtype='float32', name='input')
P
Pei Yang 已提交
205
          output = paddle.full_like(input, 2.0)
206 207
          # [[2. 2. 2.]
          #  [2. 2. 2.]]
P
Pei Yang 已提交
208 209 210
    """

    if dtype is None:
211
        dtype = x.dtype
212
    else:
213 214 215 216 217
        if not isinstance(dtype, core.VarDesc.VarType):
            dtype = convert_np_dtype_to_dtype_(dtype)

    if in_dygraph_mode():
        return core.ops.fill_any_like(x, 'value', fill_value, 'dtype', dtype)
P
Pei Yang 已提交
218

219
    helper = LayerHelper("full_like", **locals())
220 221 222
    check_variable_and_dtype(
        x, 'x', ['bool', 'float16', 'float32', 'float64', 'int32', 'int64'],
        'full_like')
223 224
    check_dtype(dtype, 'dtype',
                ['bool', 'float16', 'float32', 'float64', 'int32', 'int64'],
225
                'full_like/zeros_like/ones_like')
226
    out = helper.create_variable_for_type_inference(dtype=dtype)
227

P
Pei Yang 已提交
228 229
    helper.append_op(
        type='fill_any_like',
230
        inputs={'X': [x]},
231
        attrs={'value': fill_value,
232
               "dtype": dtype},
P
Pei Yang 已提交
233
        outputs={'Out': [out]})
234
    out.stop_gradient = True
P
Pei Yang 已提交
235 236 237
    return out


238
def ones(shape, dtype=None, name=None):
239
    """
S
swtkiwi 已提交
240

241 242 243
    The OP creates a tensor of specified :attr:`shape` and :attr:`dtype`, and fills it with 1.

    Args:
244
        shape(tuple|list|Tensor): Shape of the Tensor to be created, the data type of shape is int32 or int64.
W
wangchaochaohu 已提交
245
        dtype(np.dtype|str, optional): Data type of output Tensor, it supports
246 247 248
            bool, float16, float32, float64, int32 and int64. Default: if None, the data type is 'float32'.
        name(str, optional): The default value is None. Normally there is no need for user to set this property. For more information, please refer to :ref:`api_guide_Name`
    
249
    Returns:
250
        Tensor: A tensor of data type :attr:`dtype` with shape :attr:`shape` and all elements set to 1.
251 252 253 254

    Examples:
        .. code-block:: python

255 256
          import paddle 
          
257
          # default dtype for ones OP
258 259 260 261 262 263 264 265 266
          data1 = paddle.ones(shape=[3, 2]) 
          # [[1. 1.]
          #  [1. 1.]
          #  [1. 1.]]
          
          data2 = paddle.ones(shape=[2, 2], dtype='int32') 
          # [[1 1]
          #  [1 1]]
          
267
          # shape is a Tensor
268
          shape = paddle.full(shape=[2], dtype='int32', fill_value=2)
269 270 271
          data3 = paddle.ones(shape=shape, dtype='int32') 
          # [[1 1]
          #  [1 1]]
272
    """
273 274 275
    if dtype is None:
        dtype = 'float32'
    return fill_constant(value=1.0, shape=shape, dtype=dtype, name=name)
276 277


278
def ones_like(x, dtype=None, name=None):
279
    """
280 281
    This OP returns a Tensor filled with the value 1, with the same shape and
    data type (use ``dtype`` if ``dtype`` is not None) as ``x``.
282 283

    Args:
284 285 286 287 288 289 290 291 292 293
        x(Tensor): The input tensor which specifies shape and dtype. The
            dtype of ``x`` can be bool, float16, float32, float64, int32, int64.
        dtype(str|np.dtype|core.VarDesc.VarType, optional): The data type of the
            output tensor. Supported data types: bool, float16, float32, float64,
            int32, int64. If ``dtype`` is None, the data type is the same as ``x``.
            Default is None.
        name(str, optional): The default value is None. Normally there is no
            need for user to set this property. For more information, please
            refer to :ref:`api_guide_Name`.

294
    Returns:
295 296 297 298 299
        Tensor: A Tensor filled with the value 1, with the same shape and
        data type (use ``dtype`` if ``dtype`` is not None) as ``x``.

    Raise:
        TypeError: If ``dtype`` is not None and is not bool, float16, float32,
Z
zhupengyang 已提交
300
        float64, int32 or int64.
301 302 303 304

    Examples:
        .. code-block:: python

305
            import paddle
306

307
            x = paddle.to_tensor([1,2,3])
Z
zhupengyang 已提交
308 309
            out1 = paddle.ones_like(x) # [1., 1., 1.]
            out2 = paddle.ones_like(x, dtype='int32') # [1, 1, 1]
310

311 312
    """
    return full_like(x=x, fill_value=1, dtype=dtype, name=name)
313 314


315
def zeros(shape, dtype=None, name=None):
316 317 318 319
    """
    The OP creates a tensor of specified :attr:`shape` and :attr:`dtype`, and fills it with 0.

    Args:
320
        shape(tuple|list|Tensor): Shape of the Tensor to be created, the data type of ``shape`` is int32 or int64.
W
wangchaochaohu 已提交
321
        dtype(np.dtype|str, optional): Data type of output Tensor, it supports
322 323 324
            bool, float16, float32, float64, int32 and int64. Default: if None, the date type is float32.
        name(str, optional): The default value is None.  Normally there is no need for user to set this
            property.  For more information, please refer to :ref:`api_guide_Name`.
325 326

    Returns:
327
        Tensor: A tensor of data type :attr:`dtype` with shape :attr:`shape` and all elements set to 0.
328 329 330 331 332

    Examples:
        .. code-block:: python

          import paddle
333
          
334 335 336 337 338 339 340 341 342
          data = paddle.zeros(shape=[3, 2], dtype='float32') 
          # [[0. 0.]
          #  [0. 0.]
          #  [0. 0.]]
          data = paddle.zeros(shape=[2, 2]) 
          # [[0. 0.]
          #  [0. 0.]]
          
          # shape is a Tensor
343
          shape = paddle.full(shape=[2], dtype='int32', fill_value=2)
344
          data3 = paddle.zeros(shape=shape, dtype='int32') 
345 346
          # [[0 0]
          #  [0 0]]
347
    """
348 349 350
    if dtype is None:
        dtype = 'float32'
    return fill_constant(value=0.0, shape=shape, dtype=dtype, name=name)
351 352


353
def zeros_like(x, dtype=None, name=None):
354
    """
355 356
    This OP returns a Tensor filled with the value 0, with the same shape and
    data type (use ``dtype`` if ``dtype`` is not None) as ``x``.
357 358

    Args:
359 360 361 362 363 364
        x(Tensor): The input tensor which specifies shape and dtype. The
            dtype of ``x`` can be bool, float16, float32, float64, int32, int64.
        dtype(str|np.dtype|core.VarDesc.VarType, optional): The data type of the
            output tensor. Supported data types: bool, float16, float32, float64,
            int32, int64. If ``dtype`` is None, the data type is the same as ``x``.
            Default is None.
365 366 367
        name(str, optional): The default value is None. Normally there is no
            need for user to set this property. For more information, please
            refer to :ref:`api_guide_Name`.
368 369

    Returns:
370 371
        Tensor: A Tensor filled with the value 0, with the same shape and
        data type (use ``dtype`` if ``dtype`` is not None) as ``x``.
372

373
    Raise:
374
        TypeError: If ``dtype`` is not None and is not bool, float16, float32,
Z
zhupengyang 已提交
375
        float64, int32 or int64.
376

377 378 379
    Examples:
        .. code-block:: python

380
            import paddle
381

Z
zhupengyang 已提交
382
            x = paddle.to_tensor([1, 2, 3])
383 384
            out1 = paddle.zeros_like(x) # [0., 0., 0.]
            out2 = paddle.zeros_like(x, dtype='int32') # [0, 0, 0]
385

386 387
    """
    return full_like(x=x, fill_value=0, dtype=dtype, name=name)
388 389


390
def eye(num_rows, num_columns=None, dtype=None, name=None):
391
    """
392
    
393
    This function constructs 2-D Tensor with ones on the diagonal and zeros elsewhere.
394

395
    Args:
396 397
        num_rows(int): the number of rows in each batch Tensor.
        num_columns(int, optional): the number of columns in each batch Tensor.
398
            If None, default: num_rows.
W
wangchaochaohu 已提交
399
        dtype(np.dtype|str, optional): The data type of the returned Tensor.
400 401
            It should be int32, int64, float16, float32, float64. Default: if None, the data type
            is float32.
402 403
        name(str, optional): The default value is None.  Normally there is no need for 
            user to set this property.  For more information, please refer to :ref:`api_guide_Name`
404

405
    Returns:
406
        Tensor: An identity Tensor or LoDTensor of shape [num_rows, num_columns].
407

408 409
    Examples:
        .. code-block:: python
410
          
411
          import paddle
412

413
          data = paddle.eye(3, dtype='int32')
414 415 416
          # [[1 0 0]
          #  [0 1 0]
          #  [0 0 1]]
417
          data = paddle.eye(2, 3, dtype='int32')
418 419
          # [[1 0 0]
          #  [0 1 0]]
420 421
    """

422 423 424
    if dtype is None:
        dtype = 'float32'
    if num_columns is None:
425
        num_columns = num_rows
426 427 428 429 430
    return paddle.fluid.layers.eye(num_rows=num_rows,
                                   num_columns=num_columns,
                                   batch_shape=None,
                                   dtype=dtype,
                                   name=name)
431 432


433
def full(shape, fill_value, dtype=None, name=None):
W
wangchaochaohu 已提交
434
    """
S
swtkiwi 已提交
435

436
    This Op return a Tensor with the ``fill_value`` which size is same as ``shape``.
W
wangchaochaohu 已提交
437 438
    
    Args:
439
        shape(list|tuple|Tensor): Shape of the Tensor to be created.
W
wangchaochaohu 已提交
440 441
                The data type is ``int32`` or ``int64`` . If ``shape`` is a list or tuple,
                the elements of it should be integers or Tensors with shape [1].
442 443 444
                If ``shape`` is an Tensor, it should be an 1-D Tensor .
        fill_value(bool|float|int|Tensor): The constant value
            used to initialize the Tensor to be created. If ``fill_value`` is an Tensor, it must be an 1-D Tensor.
W
wangchaochaohu 已提交
445
        dtype(np.dtype|str, optional): Data type of the output Tensor
W
wangchaochaohu 已提交
446
            which can be float16, float32, float64, int32, int64, if dytpe is `None`, the data
447
            type of created Tensor is `float32`
W
wangchaochaohu 已提交
448 449 450
        name(str, optional): The default value is None.  Normally there is no need for user to set this
            property.  For more information, please refer to :ref:`api_guide_Name`.
    
451
    Returns:
452
        Tensor: Tensor which is created according to ``shape``, ``fill_value`` and ``dtype``.
453

W
wangchaochaohu 已提交
454 455 456
    Examples:
        .. code-block:: python

457
          import paddle
W
wangchaochaohu 已提交
458

459 460 461
          data1 = paddle.full(shape=[2,1], fill_value=0, dtype='int64') 
          #[[0]
          # [0]]
W
wangchaochaohu 已提交
462

463
          # attr shape is a list which contains Tensor.
464
          positive_2 = paddle.full([1], 2, "int32")
465 466
          data3 = paddle.full(shape=[1, positive_2], dtype='float32', fill_value=1.5)
          # [[1.5 1.5]]
W
wangchaochaohu 已提交
467

468
          # attr shape is a Tensor.
469
          shape = paddle.full([2], 2, "int32")
470 471 472
          data4 = paddle.full(shape=shape, dtype='bool', fill_value=True) 
          # [[True True] 
          #  [True True]]
473
          
474
          # attr fill_value is a Tensor.
475
          val = paddle.full([1], 2.0, "float32")
476 477 478
          data5 = paddle.full(shape=[2,1], fill_value=val, dtype='float32')
          # [[2.0] 
          #  [2.0]]
W
wangchaochaohu 已提交
479 480 481 482 483
    """

    if dtype is None:
        dtype = 'float32'

484
    return fill_constant(shape=shape, dtype=dtype, value=fill_value, name=name)
485 486


487
def arange(start=0, end=None, step=1, dtype=None, name=None):
488
    """
489
    This OP returns a 1-D Tensor with spaced values within a given interval.
490

491 492
    Values are generated into the half-open interval [``start``, ``end``) with
    the ``step``. (the interval including ``start`` but excluding ``end``).
493

494 495
    If ``dtype`` is float32 or float64, we advise adding a small epsilon to
    ``end`` to avoid floating point rounding errors when comparing against ``end``.
496 497

    Parameters:
498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515
        start(float|int|Tensor): Start of interval. The interval includes this
            value. If ``end`` is None, the half-open interval is [0, ``start``).
            If ``start`` is a Tensor, it is a 1-D Tensor with shape [1], with
            data type int32, int64, float32, float64. Default is 0.
        end(float|int|Tensor, optional): End of interval. The interval does not
            include this value. If ``end`` is a Tensor, it is a 1-D Tensor with
            shape [1], with data type int32, int64, float32, float64. If ``end``
            is None, the half-open interval is [0, ``start``). Default is None.
        step(float|int|Tensor, optional): Spacing between values. For any out,
            it is the istance between two adjacent values, out[i+1] - out[i].
            If ``step`` is a Tensor, it is a 1-D Tensor with shape [1], with
            data type int32, int64, float32, float64. Default is 1.
        dtype(str|np.dtype|core.VarDesc.VarType, optional): The data type of the
            output tensor. Supported data types: int32, int64, float32, float64.
            If ``dytpe`` is None, the data type is float32. Default is None.
        name(str, optional): The default value is None. Normally there is no
            need for user to set this property. For more information, please
            refer to :ref:`api_guide_Name`.
516

517 518
    Returns: 
        Tensor: A 1-D Tensor with values from the interval [``start``, ``end``)
Z
zhupengyang 已提交
519 520
        taken with common difference ``step`` beginning from ``start``. Its
        data type is set by ``dtype``.
521

522
    Raises:
523
        TypeError: If ``dtype`` is not int32, int64, float32, float64.
524

Z
zhupengyang 已提交
525
    Examples:
526 527
        .. code-block:: python

Z
zhupengyang 已提交
528
            import paddle
529

Z
zhupengyang 已提交
530 531
            out1 = paddle.arange(5)
            # [0, 1, 2, 3, 4]
532

Z
zhupengyang 已提交
533 534
            out2 = paddle.arange(3, 9, 2.0)
            # [3, 5, 7]
535

Z
zhupengyang 已提交
536 537 538
            # use 4.999 instead of 5.0 to avoid floating point rounding errors
            out3 = paddle.arange(4.999, dtype='float32')
            # [0., 1., 2., 3., 4.]
539

Z
zhupengyang 已提交
540 541 542
            start_var = paddle.to_tensor([3])
            out4 = paddle.arange(start_var, 7)
            # [3, 4, 5, 6]
543 544 545 546 547 548 549
             
    """
    if dtype is None:
        dtype = 'int64'
    if end is None:
        end = start
        start = 0
550

551
    return paddle.fluid.layers.range(start, end, step, dtype, name)
W
WuHaobo 已提交
552 553 554 555 556 557


def _tril_triu_op(helper):
    """Base op of tril_op and triu_op
    """
    op_type = helper.layer_type
Y
yaoxuefeng 已提交
558
    x = helper.kwargs.get('x', None)
W
WuHaobo 已提交
559 560

    assert x is not None, 'x cannot be None in {}'.format(op_type)
561 562
    check_variable_and_dtype(
        x, 'x', ['float16', 'float32', 'float64', 'int32', 'int64'], op_type)
W
WuHaobo 已提交
563
    if len(x.shape) < 2:
Y
yaoxuefeng 已提交
564
        raise ValueError("x shape in {} must be at least 2-D".format(op_type))
W
WuHaobo 已提交
565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587
    diagonal = helper.kwargs.get('diagonal', 0)
    if not isinstance(diagonal, (int, )):
        raise TypeError("diagonal in {} must be a python Int".format(op_type))
    name = helper.kwargs.get('name', None)

    if name is None:
        out = helper.create_variable_for_type_inference(dtype=x.dtype)
    else:
        out = helper.create_variable(
            name=name, dtype=x.dtype, persistable=False)

    helper.append_op(
        type="tril_triu",
        inputs={"X": x},
        attrs={
            "diagonal": diagonal,
            "lower": True if op_type == 'tril' else False,
        },
        outputs={"Out": out}, )

    return out


Y
yaoxuefeng 已提交
588
def tril(x, diagonal=0, name=None):
589
    r"""
W
WuHaobo 已提交
590
    This op returns the lower triangular part of a matrix (2-D tensor) or batch
Y
yaoxuefeng 已提交
591
    of matrices :attr:`x`, the other elements of the result tensor are set 
W
WuHaobo 已提交
592 593 594 595
    to 0. The lower triangular part of the matrix is defined as the elements 
    on and below the diagonal.

    Args:
Y
yaoxuefeng 已提交
596
        x (Tensor): The input x which is a Tensor.
W
WuHaobo 已提交
597 598 599 600 601 602 603 604 605 606 607 608
            Support data types: ``float64``, ``float32``, ``int32``, ``int64``.
        diagonal (int, optional): The diagonal to consider, default value is 0.
            If :attr:`diagonal` = 0, all elements on and below the main diagonal are
            retained. A positive value includes just as many diagonals above the main
            diagonal, and similarly a negative value excludes just as many diagonals below
            the main diagonal. The main diagonal are the set of indices
            :math:`\{(i, i)\}` for :math:`i \in [0, \min\{d_{1}, d_{2}\} - 1]` where
            :math:`d_{1}, d_{2}` are the dimensions of the matrix.
        name (str, optional): The default value is None. Normally there is no need for
            user to set this property. For more information, please refer to :ref:`api_guide_Name`.

    Returns:
Y
yaoxuefeng 已提交
609
        Tensor: Results of lower triangular operation by the specified diagonal of input tensor x,
Y
yaoxuefeng 已提交
610
        it's data type is the same as x's Tensor.
W
WuHaobo 已提交
611 612 613

    Raises:
        TypeError: diagonal is not a int type.
Y
yaoxuefeng 已提交
614
        ValueError: dimension of :attr:`x` is less than 2.
W
WuHaobo 已提交
615 616 617 618 619

    Examples:
        .. code-block:: python

            import numpy as np
Y
yaoxuefeng 已提交
620
            import paddle
W
WuHaobo 已提交
621 622 623 624 625 626

            data = np.arange(1, 13, dtype="int64").reshape(3,-1)
            # array([[ 1,  2,  3,  4],
            #        [ 5,  6,  7,  8],
            #        [ 9, 10, 11, 12]])

Y
yaoxuefeng 已提交
627

628
            x = paddle.to_tensor(data)
Y
yaoxuefeng 已提交
629 630
            
            tril1 = paddle.tensor.tril(x)
W
WuHaobo 已提交
631 632 633 634 635
            # array([[ 1,  0,  0,  0],
            #        [ 5,  6,  0,  0],
            #        [ 9, 10, 11,  0]])

            # example 2, positive diagonal value
Y
yaoxuefeng 已提交
636
            tril2 = paddle.tensor.tril(x, diagonal=2)
W
WuHaobo 已提交
637 638 639 640 641
            # array([[ 1,  2,  3,  0], 
            #        [ 5,  6,  7,  8],
            #        [ 9, 10, 11, 12]])

            # example 3, negative diagonal value
Y
yaoxuefeng 已提交
642
            tril3 = paddle.tensor.tril(x, diagonal=-1)
W
WuHaobo 已提交
643 644 645 646
            # array([[ 0,  0,  0,  0],
            #        [ 5,  0,  0,  0],
            #        [ 9, 10,  0,  0]])

647 648 649
    """
    if in_dygraph_mode():
        op = getattr(core.ops, 'tril_triu')
Y
yaoxuefeng 已提交
650
        return op(x, 'diagonal', diagonal, "lower", True)
W
WuHaobo 已提交
651 652 653 654

    return _tril_triu_op(LayerHelper('tril', **locals()))


Y
yaoxuefeng 已提交
655
def triu(x, diagonal=0, name=None):
656
    r"""
W
WuHaobo 已提交
657
    This op returns the upper triangular part of a matrix (2-D tensor) or batch of matrices
Y
yaoxuefeng 已提交
658
    :attr:`x`, the other elements of the result tensor are set to 0.
W
WuHaobo 已提交
659 660 661 662
    The upper triangular part of the matrix is defined as the elements on and
    above the diagonal.

    Args:
Y
yaoxuefeng 已提交
663
        x (Tensor): The input x which is a Tensor.
W
WuHaobo 已提交
664 665 666 667 668 669 670 671 672 673 674 675
            Support data types: ``float64``, ``float32``, ``int32``, ``int64``.
        diagonal (int, optional): The diagonal to consider, default value is 0.
            If :attr:`diagonal` = 0, all elements on and above the main diagonal are
            retained. A positive value excludes just as many diagonals above the main
            diagonal, and similarly a negative value includes just as many diagonals below
            the main diagonal. The main diagonal are the set of indices
            :math:`\{(i, i)\}` for :math:`i \in [0, \min\{d_{1}, d_{2}\} - 1]` where
            :math:`d_{1}, d_{2}` are the dimensions of the matrix.
        name (str, optional): The default value is None. Normally there is no need for
            user to set this property. For more information, please refer to :ref:`api_guide_Name`.

    Returns:
Y
yaoxuefeng 已提交
676
        Tensor: Results of upper triangular operation by the specified diagonal of input tensor x,
Y
yaoxuefeng 已提交
677
        it's data type is the same as x's Tensor.
W
WuHaobo 已提交
678 679 680

    Raises:
        TypeError: diagonal is not a int type.
Y
yaoxuefeng 已提交
681
        ValueError: dimension of :attr:`x` is less than 2.
W
WuHaobo 已提交
682 683 684 685 686

    Examples:
        .. code-block:: python

            import numpy as np
Y
yaoxuefeng 已提交
687
            import paddle
W
WuHaobo 已提交
688 689 690 691 692

            data = np.arange(1, 13, dtype="int64").reshape(3,-1)
            # array([[ 1,  2,  3,  4],
            #        [ 5,  6,  7,  8],
            #        [ 9, 10, 11, 12]])
Y
yaoxuefeng 已提交
693

W
WuHaobo 已提交
694 695

            # example 1, default diagonal
696
            x = paddle.to_tensor(data)
Y
yaoxuefeng 已提交
697
            triu1 = paddle.tensor.triu(x)
W
WuHaobo 已提交
698 699 700 701 702
            # array([[ 1,  2,  3,  4],
            #        [ 0,  6,  7,  8],
            #        [ 0,  0, 11, 12]])

            # example 2, positive diagonal value
Y
yaoxuefeng 已提交
703
            triu2 = paddle.tensor.triu(x, diagonal=2)
W
WuHaobo 已提交
704 705 706 707 708
            # array([[0, 0, 3, 4],
            #        [0, 0, 0, 8],
            #        [0, 0, 0, 0]])

            # example 3, negative diagonal value
Y
yaoxuefeng 已提交
709
            triu3 = paddle.tensor.triu(x, diagonal=-1)
W
WuHaobo 已提交
710 711 712 713 714
            # array([[ 1,  2,  3,  4],
            #        [ 5,  6,  7,  8],
            #        [ 0, 10, 11, 12]])

    """
715 716
    if in_dygraph_mode():
        op = getattr(core.ops, 'tril_triu')
Y
yaoxuefeng 已提交
717
        return op(x, 'diagonal', diagonal, "lower", False)
W
WuHaobo 已提交
718 719

    return _tril_triu_op(LayerHelper('triu', **locals()))
S
suytingwan 已提交
720 721


722
def meshgrid(*args, **kwargs):
S
suytingwan 已提交
723
    """
724
    This op takes a list of N tensors as input *args, each of which is 1-dimensional 
S
suytingwan 已提交
725 726 727
    vector, and creates N-dimensional grids.
    
    Args:
Y
yaoxuefeng 已提交
728
        *args(Tensor|list of Tensor) : tensors (tuple(list) of tensor): the shapes of input k tensors are (N1,), 
S
suytingwan 已提交
729
            (N2,),..., (Nk,). Support data types: ``float64``, ``float32``, ``int32``, ``int64``.
730 731
        **kwargs (optional): Currently, we only accept name in **kwargs 
            The default value is None. Normally there is no need for
S
suytingwan 已提交
732 733 734
            user to set this property. For more information, please refer to :ref:`api_guide_Name`.
 
    Returns:
Y
yaoxuefeng 已提交
735
         Tensor: k tensors. The shape of each tensor is (N1, N2, ..., Nk)
S
suytingwan 已提交
736 737 738 739 740 741

    Examples:
      .. code-block:: python

          import paddle

Y
yaoxuefeng 已提交
742 743 744 745
          x = paddle.randint(low=0, high=100, shape=[100])
          y = paddle.randint(low=0, high=100, shape=[200])

          grid_x, grid_y = paddle.meshgrid(x, y)
S
suytingwan 已提交
746

Y
yaoxuefeng 已提交
747 748
          print(grid_x.shape)
          print(grid_y.shape)
S
suytingwan 已提交
749 750 751 752 753 754

          #the shape of res_1 is (100, 200)
          #the shape of res_2 is (100, 200)

    """

755 756
    if len(args) == 1 and isinstance(args[0], (list, tuple)):
        args = args[0]
S
suytingwan 已提交
757
    if in_dygraph_mode():
758 759
        num = len(args)
        out = core.ops.meshgrid(list(args), num)
S
suytingwan 已提交
760 761
        return out

762
    name = kwargs.get("name", None)
S
suytingwan 已提交
763 764
    helper = LayerHelper('meshgrid', **locals())

765 766
    if not isinstance(args, (list, tuple)):
        raise TypeError("The type of input args in meshgrid should be list.")
S
suytingwan 已提交
767

768
    for id, input_ in enumerate(args):
S
suytingwan 已提交
769 770 771 772
        check_dtype(input_.dtype, 'create data type',
                    ['float16', 'float32', 'float64', 'int32', 'int64'],
                    'meshgrid')

773
    num = len(args)
S
suytingwan 已提交
774
    out = [
775
        helper.create_variable_for_type_inference(dtype=args[i].dtype)
S
suytingwan 已提交
776 777
        for i in range(num)
    ]
778 779
    helper.append_op(
        type='meshgrid', inputs={'X': list(args)}, outputs={'Out': out})
S
suytingwan 已提交
780 781

    return out
782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 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


def diag(x, offset=0, padding_value=0, name=None):
    """
    If ``x`` is a vector (1-D tensor), a 2-D square tensor whth the elements of ``x`` as the diagonal is returned.

    If ``x`` is a matrix (2-D tensor), a 1-D tensor with the diagonal elements of ``x`` is returned.

    The argument ``offset`` controls the diagonal offset:

    If ``offset`` = 0, it is the main diagonal.

    If ``offset`` > 0, it is superdiagonal.

    If ``offset`` < 0, it is subdiagonal.

    Args:
        x (Tensor): The input tensor. Its shape is either 1-D or 2-D. Its data type should be float32, float64, int32, int64.
        offset (int, optional): The diagonal offset. A positive value represents superdiagonal, 0 represents the main diagonal, and a negative value represents subdiagonal.
        padding_value (int|float, optional): Use this value to fill the area outside the specified diagonal band. Only takes effect when the input is a 1-D Tensor. The default value is 0.
        name (str, optional): Name for the operation (optional, default is None). For more information, please refer to :ref:`api_guide_Name`.

    Returns:
        Tensor, a square matrix or a vector. The output data type is the same as input data type.

    Examples:
        .. code-block:: python

          import paddle

          paddle.disable_static()
          x = paddle.to_tensor([1, 2, 3])
          y = paddle.diag(x)
          print(y.numpy())
          # [[1 0 0]
          #  [0 2 0]
          #  [0 0 3]]

          y = paddle.diag(x, offset=1)
          print(y.numpy())
          # [[0 1 0 0]
          #  [0 0 2 0]
          #  [0 0 0 3]
          #  [0 0 0 0]]

          y = paddle.diag(x, padding_value=6)
          print(y.numpy())
          # [[1 6 6]
          #  [6 2 6]
          #  [6 6 3]]

        .. code-block:: python

          import paddle

          paddle.disable_static()
          x = paddle.to_tensor([[1, 2, 3], [4, 5, 6]])
          y = paddle.diag(x)
          print(y.numpy())
          # [1 5]

          y = paddle.diag(x, offset=1)
          print(y.numpy())
          # [2 6]

          y = paddle.diag(x, offset=-1)
          print(y.numpy())
          # [4]
    """
    if in_dygraph_mode():
        return core.ops.diag_v2(x, "offset", offset, "padding_value",
                                padding_value)

    check_type(x, 'x', (Variable), 'diag_v2')
    check_dtype(x.dtype, 'x', ['float32', 'float64', 'int32', 'int64'],
                'diag_v2')
858 859 860 861 862 863 864
    check_type(offset, 'offset', (int), 'diag_v2')
    check_type(padding_value, 'padding_value', (int, float), 'diag_v2')
    if len(x.shape) != 1 and len(x.shape) != 2:
        raise ValueError(
            "The dimension of input x must be either 1 or 2, but received {}".
            format(len(x.shape)))

865 866 867 868 869 870 871 872 873 874 875 876 877
    helper = LayerHelper("diag_v2", **locals())

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

    helper.append_op(
        type='diag_v2',
        inputs={'X': x},
        outputs={'Out': out},
        attrs={'offset': offset,
               'padding_value': padding_value})

    out.stop_gradient = True
    return out
878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 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


def empty(shape, dtype=None, name=None):
    """
    This Op returns a Tensor with uninitialized data which size is same as ``shape``.
    
    Args:
        shape(list|tuple|Tensor): Shape of the Tensor to be created.
                The data type of dimension of shape is ``int32`` or ``int64`` . If ``shape`` is a list or tuple,
                the elements of it should be integers or Tensors with shape [1].
                If ``shape`` is an Tensor, it should be an 1-D Tensor.
        dtype(np.dtype|str, optional): Data type of the output Tensor
            which can be bool, float16, float32, float64, int32, int64, if dytpe is `None`, the data
            type of created Tensor use global default dtype (see ``get_default_dtype``
            for details).
        name(str, optional): The default value is None. Normally there is no need for user to set this
            property. For more information, please refer to :ref:`api_guide_Name`.
    
    Returns:
        Tensor: Tensor which is created according to ``shape`` and ``dtype``, and is uninitialized.

    Examples:
        .. code-block:: python

          import paddle
          import numpy as np

          paddle.set_device("cpu")  # and use cpu device

          # example 1: argument ``shape`` is a list which doesn't contain Tensor.
          data1 = paddle.empty(shape=[2,3], dtype='float32')
          #[[4.3612203e+27 1.8176809e+31 1.3555911e-19]     # uninitialized
          # [1.1699684e-19 1.3563156e-19 3.6408321e-11]]    # uninitialized

          # example 2: argument ``shape`` is a Tensor, the data type must be int64 or int32.
          shape_data = np.array([2, 3]).astype('int32')
          shape = paddle.to_tensor(shape_data)
          data2 = paddle.empty(shape=shape, dtype='float32')
          #[[1.7192326e-37 4.8125365e-38 1.9866003e-36]     # uninitialized
          # [1.3284029e-40 7.1117408e-37 2.5353012e+30]]    # uninitialized

          # example 3: argument ``shape`` is a list which contains Tensor.
          dim2_data = np.array([3]).astype('int32')
          dim2 = paddle.to_tensor(dim2_data)
          data3 = paddle.empty(shape=[2, dim2], dtype='float32')
          #[[1.1024214e+24 7.0379409e+22 6.5737699e-34]     # uninitialized
          # [7.5563101e+31 7.7130405e+31 2.8020654e+20]]    # uninitialized
    """

    if dtype is None:
        dtype = paddle.get_default_dtype()

    dtype = convert_dtype(dtype)

    if in_dygraph_mode():
        shape = utils.convert_shape_to_list(shape)
        out = core.ops.empty('shape', shape, 'dtype',
                             convert_np_dtype_to_dtype_(dtype))
        out.stop_gradient = True
        return out

    helper = LayerHelper("empty", **locals())
    inputs = {}

    check_dtype(dtype, 'dtype',
                ['bool', 'float16', 'float32', 'float64', 'int32', 'int64'],
                'empty')
    check_type(shape, 'shape', (Variable, list, tuple), 'empty')

    if isinstance(shape, Variable):
        check_dtype(shape.dtype, 'shape', ['int32', 'int64'], 'empty')

    attrs = {}
    utils.get_shape_tensor_inputs(
        inputs=inputs, attrs=attrs, shape=shape, op_type='empty')

    out = helper.create_variable_for_type_inference(dtype=dtype)
    attrs['dtype'] = convert_np_dtype_to_dtype_(dtype)
    helper.append_op(
        type='empty',
        inputs=inputs,
        outputs={'Out': [out]},
        attrs=attrs,
        stop_gradient=True)
    out.stop_gradient = True
    return out
964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029


def empty_like(x, dtype=None, name=None):
    """
    This Op returns a Tensor with uninitialized data which has identical shape of ``x`` and ``dtype``.
    If the ``dtype`` is None, the data type of Tensor is same with ``x``.
    
    Args:
        x(Tensor): The input tensor which specifies shape and data type. The data type can be bool, float16, float32, float64, int32, int64.
        dtype(np.dtype|str, optional): The data type of output. The data type can be one
            of bool, float16, float32, float64, int32, int64. The default value is None, which means the output 
            data type is the same as input.
        name(str, optional): The default value is None. Normally there is no need for user to set this
            property. For more information, please refer to :ref:`api_guide_Name`.
    
    Returns:
        Tensor: Tensor which is created according to ``x`` and ``dtype``, and is uninitialized.

    Examples:
        .. code-block:: python

          import paddle
          import numpy as np

          paddle.set_device("cpu")  # and use cpu device

          x = paddle.randn([2, 3], 'float32')
          output = paddle.empty_like(x)
          #[[1.8491974e+20 1.8037303e+28 1.7443726e+28]     # uninitialized
          # [4.9640171e+28 3.0186127e+32 5.6715899e-11]]    # uninitialized
    """

    if dtype is None:
        dtype = x.dtype
    dtype = convert_dtype(dtype)

    if in_dygraph_mode():
        out = core.ops.empty('shape', x.shape, 'dtype',
                             convert_np_dtype_to_dtype_(dtype))
        out.stop_gradient = True
        return out

    helper = LayerHelper("empty_like", **locals())
    check_variable_and_dtype(
        x, 'x', ['bool', 'float16', 'float32', 'float64', 'int32', 'int64'],
        'empty_like')
    check_dtype(dtype, 'dtype',
                ['bool', 'float16', 'float32', 'float64', 'int32', 'int64'],
                'empty_like')
    out = helper.create_variable_for_type_inference(dtype=dtype)

    inputs = {}
    attrs = {}
    attrs['dtype'] = convert_np_dtype_to_dtype_(dtype)
    shape = paddle.shape(x)
    utils.get_shape_tensor_inputs(
        inputs=inputs, attrs=attrs, shape=shape, op_type='empty_like')

    helper.append_op(
        type='empty',
        inputs=inputs,
        outputs={'Out': [out]},
        attrs=attrs,
        stop_gradient=True)
    out.stop_gradient = True
    return out
1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061


def assign(x, output=None):
    """
 
 
    The OP copies the :attr:`x` to the :attr:`output`.
 
    Parameters:
        x (Tensor|numpy.ndarray): A tensor or numpy ndarray, its data type supports
            float16, float32, float64, int32 and int64.
        output (Tensor, optional): A tensor. If :attr:`output` is None, a new tensor will
            be created as :attr:`output`. Default: None.
 
    Returns:
        Tensor: A tensor with the same shape, data type and value as :attr:`x`.
 
    Examples:
        .. code-block:: python
 
          import paddle
          import numpy as np
          data = paddle.full(shape=[3, 2], fill_value=2.5, dtype='float64') # [[2.5, 2.5], [2.5, 2.5], [2.5, 2.5]]
          array = np.array([[1, 1],
                            [3, 4],
                            [1, 3]]).astype(np.int64)
          result1 = paddle.zeros(shape=[3, 3], dtype='float32')
          paddle.assign(array, result1) # result1 = [[1, 1], [3 4], [1, 3]]
          result2 = paddle.assign(data)  # result2 = [[2.5, 2.5], [2.5, 2.5], [2.5, 2.5]]
          result3 = paddle.assign(np.array([[2.5, 2.5], [2.5, 2.5], [2.5, 2.5]], dtype='float32')) # result3 = [[2.5, 2.5], [2.5, 2.5], [2.5, 2.5]]
    """
    check_type(x, 'x', (Variable, numpy.ndarray), 'assign')
1062
    return tensor.assign(x, output)