creation.py 42.0 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
import numpy as np
17 18
from paddle.common_ops_import import fill_constant
from ..fluid.layers import utils
19

20
from ..fluid.layers import tensor
L
Li Fuchen 已提交
21
from ..fluid.framework import Variable
22
from ..fluid.framework import unique_name
23
from ..fluid.framework import _current_expected_place, _get_paddle_place
24
from ..fluid.framework import dygraph_only
P
Pei Yang 已提交
25 26 27 28 29
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
30
# TODO: define functions to get create a tensor  
31
from ..fluid.layers import linspace  # noqa: F401
32
import paddle
33

34 35
__all__ = []

W
wangchaochaohu 已提交
36

37 38
@dygraph_only
def to_tensor(data, dtype=None, place=None, stop_gradient=True):
39
    r"""
C
chentianyu03 已提交
40 41
    Constructs a ``paddle.Tensor`` from ``data`` , 
    which can be scalar, tuple, list, numpy\.ndarray, paddle\.Tensor.
42

43 44
    If the ``data`` is already a Tensor, copy will be performed and return a new tensor.
    If you only want to change stop_gradient property, please call ``Tensor.stop_gradient = stop_gradient`` directly.
45 46

    Args:
C
chentianyu03 已提交
47 48
        data(scalar|tuple|list|ndarray|Tensor): Initial data for the tensor.
            Can be a scalar, list, tuple, numpy\.ndarray, paddle\.Tensor.
49
        dtype(str|np.dtype, optional): The desired data type of returned tensor. Can be 'bool' , 'float16' , 
C
chentianyu03 已提交
50 51
            'float32' , 'float64' , 'int8' , 'int16' , 'int32' , 'int64' , 'uint8',
            'complex64' , 'complex128'. Default: None, infers dtype from ``data`` 
52
            except for python float number which gets dtype from ``get_default_type`` .
53 54 55
        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. 
56 57 58
        stop_gradient(bool, optional): Whether to block the gradient propagation of Autograd. Default: True.

    Returns:
C
chentianyu03 已提交
59
        Tensor: A Tensor constructed from ``data`` .
60 61

    Raises:
C
chentianyu03 已提交
62
        TypeError: If the data type of ``data`` is not scalar, list, tuple, numpy.ndarray, paddle.Tensor
63 64
        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
65
        ValueError: If ``place`` is not paddle.CPUPlace, paddle.CUDAPinnedPlace, paddle.CUDAPlace or specified pattern string. 
66 67 68 69 70 71 72 73 74 75 76

    Examples:

    .. code-block:: python

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

        paddle.to_tensor(1)
77
        # Tensor(shape=[1], dtype=int64, place=CPUPlace, stop_gradient=True,
78
        #        [1])
79

80 81 82
        x = paddle.to_tensor(1, stop_gradient=False)
        print(x)
        # Tensor(shape=[1], dtype=int64, place=CPUPlace, stop_gradient=False,
83
        #        [1])
84

85 86 87
        paddle.to_tensor(x)  # A new tensor will be created with default stop_gradient=True
        # Tensor(shape=[1], dtype=int64, place=CPUPlace, stop_gradient=True,
        #        [1])        
88

89 90
        paddle.to_tensor([[0.1, 0.2], [0.3, 0.4]], place=paddle.CPUPlace(), stop_gradient=False)
        # Tensor(shape=[2, 2], dtype=float32, place=CPUPlace, stop_gradient=False,
91 92
        #        [[0.10000000, 0.20000000],
        #         [0.30000001, 0.40000001]])
93

C
chentianyu03 已提交
94
        type(paddle.to_tensor([[1+1j, 2], [3+2j, 4]], dtype='complex64'))
95
        # <class 'paddle.Tensor'>
96 97

        paddle.to_tensor([[1+1j, 2], [3+2j, 4]], dtype='complex64')
98
        # Tensor(shape=[2, 2], dtype=complex64, place=CPUPlace, stop_gradient=True,
C
chentianyu03 已提交
99 100
        #        [[(1+1j), (2+0j)],
        #         [(3+2j), (4+0j)]])
101
    """
102
    place = _get_paddle_place(place)
103 104
    if place is None:
        place = _current_expected_place()
105 106 107
    elif not isinstance(
            place,
        (core.Place, core.CPUPlace, core.CUDAPinnedPlace, core.CUDAPlace)):
108
        raise ValueError(
109
            "'place' must be any of paddle.Place, paddle.CPUPlace, paddle.CUDAPinnedPlace, paddle.CUDAPlace"
110 111 112 113 114 115 116 117 118
        )

    #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):
119

120
        def _handle_dtype(data, dtype):
121 122 123 124 125
            if dtype:
                if convert_dtype(dtype) != convert_dtype(data.dtype):
                    return data.astype(convert_dtype(dtype))
            return data

126 127 128 129 130 131 132 133 134 135
        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):
136 137 138 139 140 141
            data = data._copy_to(place, False)
            ata = _handle_dtype(data, dtype)
            data.stop_gradient = stop_gradient
        elif isinstance(data, core.LoDTensor):
            # convert LoDTensor to VarBase first
            # Currenly, LoDTensor does no copy when places are same
142
            data = paddle.Tensor(data)
143 144 145 146
            if not data.place._equals(place):
                data = data._copy_to(place, False)
            data = _handle_dtype(data, dtype)
            data.stop_gradient = stop_gradient
147 148
        else:
            raise TypeError(
C
chentianyu03 已提交
149
                "Can't constructs a 'paddle.Tensor' with data type {}, data type must be scalar|list|tuple|numpy.ndarray|paddle.Tensor".
150
                format(type(data)))
151 152 153 154 155 156 157 158 159 160 161
        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:
162
        data = data.astype(convert_dtype(dtype))
163

C
chentianyu03 已提交
164 165 166 167 168 169
    return paddle.Tensor(
        value=data,
        place=place,
        persistable=False,
        zero_copy=False,
        stop_gradient=stop_gradient)
170 171


172
def full_like(x, fill_value, dtype=None, name=None):
P
Pei Yang 已提交
173
    """
S
swtkiwi 已提交
174

175 176
    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``.
177

P
Pei Yang 已提交
178
    Args:
179 180
        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 已提交
181
        dtype(np.dtype|str, optional): The data type of output. The data type can be one
182 183
            of bool, float16, float32, float64, int32, int64. The default value is None, which means the output 
            data type is the same as input.
184 185
        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 已提交
186
    Returns:
187
        Tensor: Tensor which is created according to ``x``, ``fill_value`` and ``dtype``.
188
    
P
Pei Yang 已提交
189 190
    Examples:
        .. code-block:: python
191

P
Pei Yang 已提交
192 193
          import paddle
          import numpy as np
194 195
          
          input = paddle.full(shape=[2, 3], fill_value=0.0, dtype='float32', name='input')
P
Pei Yang 已提交
196
          output = paddle.full_like(input, 2.0)
197 198
          # [[2. 2. 2.]
          #  [2. 2. 2.]]
P
Pei Yang 已提交
199 200 201
    """

    if dtype is None:
202
        dtype = x.dtype
203
    else:
204 205 206 207 208
        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 已提交
209

210
    helper = LayerHelper("full_like", **locals())
211 212 213
    check_variable_and_dtype(
        x, 'x', ['bool', 'float16', 'float32', 'float64', 'int32', 'int64'],
        'full_like')
214 215
    check_dtype(dtype, 'dtype',
                ['bool', 'float16', 'float32', 'float64', 'int32', 'int64'],
216
                'full_like/zeros_like/ones_like')
217
    out = helper.create_variable_for_type_inference(dtype=dtype)
218

P
Pei Yang 已提交
219 220
    helper.append_op(
        type='fill_any_like',
221
        inputs={'X': [x]},
222
        attrs={'value': fill_value,
223
               "dtype": dtype},
P
Pei Yang 已提交
224
        outputs={'Out': [out]})
225
    out.stop_gradient = True
P
Pei Yang 已提交
226 227 228
    return out


229
def ones(shape, dtype=None, name=None):
230
    """
S
swtkiwi 已提交
231

232 233 234
    The OP creates a tensor of specified :attr:`shape` and :attr:`dtype`, and fills it with 1.

    Args:
235
        shape(tuple|list|Tensor): Shape of the Tensor to be created, the data type of shape is int32 or int64.
W
wangchaochaohu 已提交
236
        dtype(np.dtype|str, optional): Data type of output Tensor, it supports
237 238 239
            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`
    
240
    Returns:
241
        Tensor: A tensor of data type :attr:`dtype` with shape :attr:`shape` and all elements set to 1.
242 243 244 245

    Examples:
        .. code-block:: python

246 247
          import paddle 
          
248
          # default dtype for ones OP
249 250 251 252 253 254 255 256 257
          data1 = paddle.ones(shape=[3, 2]) 
          # [[1. 1.]
          #  [1. 1.]
          #  [1. 1.]]
          
          data2 = paddle.ones(shape=[2, 2], dtype='int32') 
          # [[1 1]
          #  [1 1]]
          
258
          # shape is a Tensor
259
          shape = paddle.full(shape=[2], dtype='int32', fill_value=2)
260 261 262
          data3 = paddle.ones(shape=shape, dtype='int32') 
          # [[1 1]
          #  [1 1]]
263
    """
264 265 266
    if dtype is None:
        dtype = 'float32'
    return fill_constant(value=1.0, shape=shape, dtype=dtype, name=name)
267 268


269
def ones_like(x, dtype=None, name=None):
270
    """
271 272
    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``.
273 274

    Args:
275 276 277 278 279 280 281 282 283 284
        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`.

285
    Returns:
286 287 288 289 290
        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 已提交
291
        float64, int32 or int64.
292 293 294 295

    Examples:
        .. code-block:: python

296
            import paddle
297

298
            x = paddle.to_tensor([1,2,3])
Z
zhupengyang 已提交
299 300
            out1 = paddle.ones_like(x) # [1., 1., 1.]
            out2 = paddle.ones_like(x, dtype='int32') # [1, 1, 1]
301

302 303
    """
    return full_like(x=x, fill_value=1, dtype=dtype, name=name)
304 305


306
def zeros(shape, dtype=None, name=None):
307 308 309 310
    """
    The OP creates a tensor of specified :attr:`shape` and :attr:`dtype`, and fills it with 0.

    Args:
311
        shape(tuple|list|Tensor): Shape of the Tensor to be created, the data type of ``shape`` is int32 or int64.
W
wangchaochaohu 已提交
312
        dtype(np.dtype|str, optional): Data type of output Tensor, it supports
313 314 315
            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`.
316 317

    Returns:
318
        Tensor: A tensor of data type :attr:`dtype` with shape :attr:`shape` and all elements set to 0.
319 320 321 322 323

    Examples:
        .. code-block:: python

          import paddle
324
          
325 326 327 328 329 330 331 332 333
          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
334
          shape = paddle.full(shape=[2], dtype='int32', fill_value=2)
335
          data3 = paddle.zeros(shape=shape, dtype='int32') 
336 337
          # [[0 0]
          #  [0 0]]
338
    """
339 340 341
    if dtype is None:
        dtype = 'float32'
    return fill_constant(value=0.0, shape=shape, dtype=dtype, name=name)
342 343


344
def zeros_like(x, dtype=None, name=None):
345
    """
346 347
    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``.
348 349

    Args:
350 351 352 353 354 355
        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.
356 357 358
        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`.
359 360

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

364
    Raise:
365
        TypeError: If ``dtype`` is not None and is not bool, float16, float32,
Z
zhupengyang 已提交
366
        float64, int32 or int64.
367

368 369 370
    Examples:
        .. code-block:: python

371
            import paddle
372

Z
zhupengyang 已提交
373
            x = paddle.to_tensor([1, 2, 3])
374 375
            out1 = paddle.zeros_like(x) # [0., 0., 0.]
            out2 = paddle.zeros_like(x, dtype='int32') # [0, 0, 0]
376

377 378
    """
    return full_like(x=x, fill_value=0, dtype=dtype, name=name)
379 380


381
def eye(num_rows, num_columns=None, dtype=None, name=None):
382
    """
383
    
384
    This function constructs 2-D Tensor with ones on the diagonal and zeros elsewhere.
385

386
    Args:
387 388
        num_rows(int): the number of rows in each batch Tensor.
        num_columns(int, optional): the number of columns in each batch Tensor.
389
            If None, default: num_rows.
W
wangchaochaohu 已提交
390
        dtype(np.dtype|str, optional): The data type of the returned Tensor.
391 392
            It should be int32, int64, float16, float32, float64. Default: if None, the data type
            is float32.
393 394
        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`
395

396
    Returns:
397
        Tensor: An identity Tensor or LoDTensor of shape [num_rows, num_columns].
398

399 400
    Examples:
        .. code-block:: python
401
          
402
          import paddle
403

404
          data = paddle.eye(3, dtype='int32')
405 406 407
          # [[1 0 0]
          #  [0 1 0]
          #  [0 0 1]]
408
          data = paddle.eye(2, 3, dtype='int32')
409 410
          # [[1 0 0]
          #  [0 1 0]]
411 412
    """

413 414 415
    if dtype is None:
        dtype = 'float32'
    if num_columns is None:
416
        num_columns = num_rows
417 418 419 420 421
    return paddle.fluid.layers.eye(num_rows=num_rows,
                                   num_columns=num_columns,
                                   batch_shape=None,
                                   dtype=dtype,
                                   name=name)
422 423


424
def full(shape, fill_value, dtype=None, name=None):
W
wangchaochaohu 已提交
425
    """
S
swtkiwi 已提交
426

427
    This Op return a Tensor with the ``fill_value`` which size is same as ``shape``.
W
wangchaochaohu 已提交
428 429
    
    Args:
430
        shape(list|tuple|Tensor): Shape of the Tensor to be created.
W
wangchaochaohu 已提交
431 432
                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].
433 434 435
                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 已提交
436
        dtype(np.dtype|str, optional): Data type of the output Tensor
W
wangchaochaohu 已提交
437
            which can be float16, float32, float64, int32, int64, if dytpe is `None`, the data
438
            type of created Tensor is `float32`
W
wangchaochaohu 已提交
439 440 441
        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`.
    
442
    Returns:
443
        Tensor: Tensor which is created according to ``shape``, ``fill_value`` and ``dtype``.
444

W
wangchaochaohu 已提交
445 446 447
    Examples:
        .. code-block:: python

448
          import paddle
W
wangchaochaohu 已提交
449

450 451 452
          data1 = paddle.full(shape=[2,1], fill_value=0, dtype='int64') 
          #[[0]
          # [0]]
W
wangchaochaohu 已提交
453

454
          # attr shape is a list which contains Tensor.
455
          positive_2 = paddle.full([1], 2, "int32")
456 457
          data3 = paddle.full(shape=[1, positive_2], dtype='float32', fill_value=1.5)
          # [[1.5 1.5]]
W
wangchaochaohu 已提交
458

459
          # attr shape is a Tensor.
460
          shape = paddle.full([2], 2, "int32")
461 462 463
          data4 = paddle.full(shape=shape, dtype='bool', fill_value=True) 
          # [[True True] 
          #  [True True]]
464
          
465
          # attr fill_value is a Tensor.
466
          val = paddle.full([1], 2.0, "float32")
467 468 469
          data5 = paddle.full(shape=[2,1], fill_value=val, dtype='float32')
          # [[2.0] 
          #  [2.0]]
W
wangchaochaohu 已提交
470 471 472 473 474
    """

    if dtype is None:
        dtype = 'float32'

475
    return fill_constant(shape=shape, dtype=dtype, value=fill_value, name=name)
476 477


478
def arange(start=0, end=None, step=1, dtype=None, name=None):
479
    """
480
    This OP returns a 1-D Tensor with spaced values within a given interval.
481

482 483
    Values are generated into the half-open interval [``start``, ``end``) with
    the ``step``. (the interval including ``start`` but excluding ``end``).
484

485 486
    If ``dtype`` is float32 or float64, we advise adding a small epsilon to
    ``end`` to avoid floating point rounding errors when comparing against ``end``.
487 488

    Parameters:
489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506
        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`.
507

508 509
    Returns: 
        Tensor: A 1-D Tensor with values from the interval [``start``, ``end``)
Z
zhupengyang 已提交
510 511
        taken with common difference ``step`` beginning from ``start``. Its
        data type is set by ``dtype``.
512

513
    Raises:
514
        TypeError: If ``dtype`` is not int32, int64, float32, float64.
515

Z
zhupengyang 已提交
516
    Examples:
517 518
        .. code-block:: python

Z
zhupengyang 已提交
519
            import paddle
520

Z
zhupengyang 已提交
521 522
            out1 = paddle.arange(5)
            # [0, 1, 2, 3, 4]
523

Z
zhupengyang 已提交
524 525
            out2 = paddle.arange(3, 9, 2.0)
            # [3, 5, 7]
526

Z
zhupengyang 已提交
527 528 529
            # 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.]
530

Z
zhupengyang 已提交
531 532 533
            start_var = paddle.to_tensor([3])
            out4 = paddle.arange(start_var, 7)
            # [3, 4, 5, 6]
534 535 536 537 538 539 540
             
    """
    if dtype is None:
        dtype = 'int64'
    if end is None:
        end = start
        start = 0
541

542
    return paddle.fluid.layers.range(start, end, step, dtype, name)
W
WuHaobo 已提交
543 544 545 546 547 548


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

    assert x is not None, 'x cannot be None in {}'.format(op_type)
552 553
    check_variable_and_dtype(
        x, 'x', ['float16', 'float32', 'float64', 'int32', 'int64'], op_type)
W
WuHaobo 已提交
554
    if len(x.shape) < 2:
Y
yaoxuefeng 已提交
555
        raise ValueError("x shape in {} must be at least 2-D".format(op_type))
W
WuHaobo 已提交
556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578
    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 已提交
579
def tril(x, diagonal=0, name=None):
580
    r"""
W
WuHaobo 已提交
581
    This op returns the lower triangular part of a matrix (2-D tensor) or batch
Y
yaoxuefeng 已提交
582
    of matrices :attr:`x`, the other elements of the result tensor are set 
W
WuHaobo 已提交
583 584 585 586
    to 0. The lower triangular part of the matrix is defined as the elements 
    on and below the diagonal.

    Args:
Y
yaoxuefeng 已提交
587
        x (Tensor): The input x which is a Tensor.
L
liuyuhui 已提交
588
            Support data types: ``bool``, ``float64``, ``float32``, ``int32``, ``int64``.
W
WuHaobo 已提交
589 590 591 592 593 594 595 596 597 598 599
        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 已提交
600
        Tensor: Results of lower triangular operation by the specified diagonal of input tensor x,
Y
yaoxuefeng 已提交
601
        it's data type is the same as x's Tensor.
W
WuHaobo 已提交
602 603 604

    Raises:
        TypeError: diagonal is not a int type.
Y
yaoxuefeng 已提交
605
        ValueError: dimension of :attr:`x` is less than 2.
W
WuHaobo 已提交
606 607 608 609 610

    Examples:
        .. code-block:: python

            import numpy as np
Y
yaoxuefeng 已提交
611
            import paddle
W
WuHaobo 已提交
612 613 614 615 616 617

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

619
            x = paddle.to_tensor(data)
Y
yaoxuefeng 已提交
620 621
            
            tril1 = paddle.tensor.tril(x)
W
WuHaobo 已提交
622 623 624 625 626
            # array([[ 1,  0,  0,  0],
            #        [ 5,  6,  0,  0],
            #        [ 9, 10, 11,  0]])

            # example 2, positive diagonal value
Y
yaoxuefeng 已提交
627
            tril2 = paddle.tensor.tril(x, diagonal=2)
W
WuHaobo 已提交
628 629 630 631 632
            # array([[ 1,  2,  3,  0], 
            #        [ 5,  6,  7,  8],
            #        [ 9, 10, 11, 12]])

            # example 3, negative diagonal value
Y
yaoxuefeng 已提交
633
            tril3 = paddle.tensor.tril(x, diagonal=-1)
W
WuHaobo 已提交
634 635 636 637
            # array([[ 0,  0,  0,  0],
            #        [ 5,  0,  0,  0],
            #        [ 9, 10,  0,  0]])

638 639 640
    """
    if in_dygraph_mode():
        op = getattr(core.ops, 'tril_triu')
Y
yaoxuefeng 已提交
641
        return op(x, 'diagonal', diagonal, "lower", True)
W
WuHaobo 已提交
642 643 644 645

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


Y
yaoxuefeng 已提交
646
def triu(x, diagonal=0, name=None):
647
    r"""
W
WuHaobo 已提交
648
    This op returns the upper triangular part of a matrix (2-D tensor) or batch of matrices
Y
yaoxuefeng 已提交
649
    :attr:`x`, the other elements of the result tensor are set to 0.
W
WuHaobo 已提交
650 651 652 653
    The upper triangular part of the matrix is defined as the elements on and
    above the diagonal.

    Args:
Y
yaoxuefeng 已提交
654
        x (Tensor): The input x which is a Tensor.
W
WuHaobo 已提交
655 656 657 658 659 660 661 662 663 664 665 666
            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 已提交
667
        Tensor: Results of upper triangular operation by the specified diagonal of input tensor x,
Y
yaoxuefeng 已提交
668
        it's data type is the same as x's Tensor.
W
WuHaobo 已提交
669 670 671

    Raises:
        TypeError: diagonal is not a int type.
Y
yaoxuefeng 已提交
672
        ValueError: dimension of :attr:`x` is less than 2.
W
WuHaobo 已提交
673 674 675 676 677

    Examples:
        .. code-block:: python

            import numpy as np
Y
yaoxuefeng 已提交
678
            import paddle
W
WuHaobo 已提交
679 680 681 682 683

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

W
WuHaobo 已提交
685 686

            # example 1, default diagonal
687
            x = paddle.to_tensor(data)
Y
yaoxuefeng 已提交
688
            triu1 = paddle.tensor.triu(x)
W
WuHaobo 已提交
689 690 691 692 693
            # array([[ 1,  2,  3,  4],
            #        [ 0,  6,  7,  8],
            #        [ 0,  0, 11, 12]])

            # example 2, positive diagonal value
Y
yaoxuefeng 已提交
694
            triu2 = paddle.tensor.triu(x, diagonal=2)
W
WuHaobo 已提交
695 696 697 698 699
            # array([[0, 0, 3, 4],
            #        [0, 0, 0, 8],
            #        [0, 0, 0, 0]])

            # example 3, negative diagonal value
Y
yaoxuefeng 已提交
700
            triu3 = paddle.tensor.triu(x, diagonal=-1)
W
WuHaobo 已提交
701 702 703 704 705
            # array([[ 1,  2,  3,  4],
            #        [ 5,  6,  7,  8],
            #        [ 0, 10, 11, 12]])

    """
706 707
    if in_dygraph_mode():
        op = getattr(core.ops, 'tril_triu')
Y
yaoxuefeng 已提交
708
        return op(x, 'diagonal', diagonal, "lower", False)
W
WuHaobo 已提交
709 710

    return _tril_triu_op(LayerHelper('triu', **locals()))
S
suytingwan 已提交
711 712


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

    Examples:
      .. code-block:: python

          import paddle

Y
yaoxuefeng 已提交
733 734 735 736
          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 已提交
737

Y
yaoxuefeng 已提交
738 739
          print(grid_x.shape)
          print(grid_y.shape)
S
suytingwan 已提交
740 741 742 743 744 745

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

    """

746 747
    if len(args) == 1 and isinstance(args[0], (list, tuple)):
        args = args[0]
S
suytingwan 已提交
748
    if in_dygraph_mode():
749 750
        num = len(args)
        out = core.ops.meshgrid(list(args), num)
S
suytingwan 已提交
751 752
        return out

753
    name = kwargs.get("name", None)
S
suytingwan 已提交
754 755
    helper = LayerHelper('meshgrid', **locals())

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

759
    for id, input_ in enumerate(args):
S
suytingwan 已提交
760 761 762 763
        check_dtype(input_.dtype, 'create data type',
                    ['float16', 'float32', 'float64', 'int32', 'int64'],
                    'meshgrid')

764
    num = len(args)
S
suytingwan 已提交
765
    out = [
766
        helper.create_variable_for_type_inference(dtype=args[i].dtype)
S
suytingwan 已提交
767 768
        for i in range(num)
    ]
769 770
    helper.append_op(
        type='meshgrid', inputs={'X': list(args)}, outputs={'Out': out})
S
suytingwan 已提交
771 772

    return out
773 774 775 776 777 778 779 780 781 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


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')
849 850 851 852 853 854 855
    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)))

856 857 858 859 860 861 862 863 864 865 866 867 868
    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
869 870 871 872 873 874 875 876 877 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


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
955 956 957 958 959 960 961 962 963 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


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
1021 1022 1023 1024 1025 1026 1027 1028 1029


def assign(x, output=None):
    """
 
 
    The OP copies the :attr:`x` to the :attr:`output`.
 
    Parameters:
1030 1031 1032 1033
        x (Tensor|numpy.ndarray|list|tuple|scalar): A tensor, numpy ndarray, tuple/list of scalar,
            or scalar. Its data type supports float16, float32, float64, int32, int64, and bool.
            Note: the float64 data will be converted to float32 because of current platform protobuf
            data limitation.
1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053
        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]]
    """
1054
    check_type(x, 'x', (Variable, np.ndarray, list, tuple, float, int, bool),
1055
               'assign')
1056
    return tensor.assign(x, output)
1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117


#NOTE(zhiqiu): not public 
def _memcpy(input, place=None, output=None):
    """

    The OP copies the :attr:`input` to the :attr:`output`.
    NOTE: currently, only support CUDAPlace <-> CUDAPinnedPlace or NPUPlace <-> CPUPlace.

    Parameters:
        input (Tensor): A tensor. Its data type supports float16, float32, float64, int32, int64, and bool.
        device (Place): Target place for the output.
        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:`input`.

    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]]
          result = paddle._memcpy(data, place=paddle.CPUPlace())  # result2 = [[2.5, 2.5], [2.5, 2.5], [2.5, 2.5]]
    """
    helper = LayerHelper('memcpy', **locals())
    check_type(input, 'input', (Variable), 'memcpy')

    if isinstance(input, (Variable, core.VarBase)):
        check_dtype(input.dtype, 'input', [
            'float16', 'uint16', 'float32', 'float64', 'int32', 'int64',
            'uint8', 'bool'
        ], 'memcpy', '(When the type of input in memcpy is Variable.)')
    if output is None:
        output = helper.create_variable_for_type_inference(dtype=input.dtype)

    dst_place_type = -1
    if place is None:
        dst_place_type = -1
    else:
        p = core.Place()
        p.set_place(place)
        if p.is_cpu_place():
            dst_place_type = 0
        elif p.is_gpu_place():
            dst_place_type = 1
        elif p.is_cuda_pinned_place():
            dst_place_type = 2
        elif p.is_xpu_place():
            dst_place_type = 3
        elif p.is_npu_place():
            dst_place_type = 4

    attrs = {'dst_place_type': dst_place_type}
    helper.append_op(
        type='memcpy',
        inputs={'X': [input]},
        outputs={'Out': [output]},
        attrs=attrs)
    return output