linalg.py 34.4 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13
#   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.
14

myq406450149's avatar
myq406450149 已提交
15
import numpy as np
16
from paddle.common_ops_import import *
Z
Zhang Ting 已提交
17 18
from ..fluid.layer_helper import LayerHelper
from ..fluid.data_feeder import check_variable_and_dtype, check_type
19
from ..fluid.framework import in_dygraph_mode, _varbase_creator
20

21 22
from ..fluid.layers import transpose  #DEFINE_ALIAS

23 24
__all__ = [
    'matmul',
L
liuwei1031 已提交
25
    'dot',
26
    #       'einsum',
27
    'norm',
28
    'transpose',
Z
Zhang Ting 已提交
29
    'dist',
30
    't',
31
    'cross',
G
Guo Sheng 已提交
32
    'cholesky',
33
    #       'tensordot',
Q
Qi Li 已提交
34
    'bmm',
35 36
    'histogram',
    'mv'
37 38 39
]


S
ShenLiang 已提交
40
def matmul(x, y, transpose_x=False, transpose_y=False, name=None):
41
    """
S
ShenLiang 已提交
42 43 44
    Applies matrix multiplication to two tensors. `matmul` follows 
    the complete broadcast rules, 
    and its behavior is consistent with `np.matmul`.
S
swtkiwi 已提交
45

S
ShenLiang 已提交
46 47
    Currently, the input tensors' number of dimensions can be any, `matmul` can be used to
    achieve the `dot`, `matmul` and `batchmatmul`.
48 49 50 51 52

    The actual behavior depends on the shapes of :math:`x`, :math:`y` and the
    flag values of :attr:`transpose_x`, :attr:`transpose_y`. Specifically:

    - If a transpose flag is specified, the last two dimensions of the tensor
S
ShenLiang 已提交
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79
      are transposed. If the tensor is ndim-1 of shape, the transpose is invalid. If the tensor 
      is ndim-1 of shape :math:`[D]`, then for :math:`x` it is treated as :math:`[1, D]`, whereas 
      for :math:`y` it is the opposite: It is treated as :math:`[D, 1]`.

    The multiplication behavior depends on the dimensions of `x` and `y`. Specifically:

    - If both tensors are 1-dimensional, the dot product result is obtained.

    - If both tensors are 2-dimensional, the matrix-matrix product is obtained.

    - If the `x` is 1-dimensional and the `y` is 2-dimensional, 
      a `1` is prepended to its dimension in order to conduct the matrix multiply. 
      After the matrix multiply, the prepended dimension is removed.
      
    - If the `x` is 2-dimensional and `y` is 1-dimensional, 
      the matrix-vector product is obtained.

    - If both arguments are at least 1-dimensional and at least one argument 
      is N-dimensional (where N > 2), then a batched matrix multiply is obtained. 
      If the first argument is 1-dimensional, a 1 is prepended to its dimension 
      in order to conduct the batched matrix multiply and removed after. 
      If the second argument is 1-dimensional, a 1 is appended to its 
      dimension for the purpose of the batched matrix multiple and removed after. 
      The non-matrix (exclude the last two dimensions) dimensions are 
      broadcasted according the broadcast rule. 
      For example, if input is a (j, 1, n, m) tensor and the other is a (k, m, p) tensor, 
      out will be a (j, k, n, p) tensor.
80 81

    Args:
S
ShenLiang 已提交
82 83
        x (Tensor): The input tensor which is a Tensor.
        y (Tensor): The input tensor which is a Tensor.
84 85 86 87 88 89
        transpose_x (bool): Whether to transpose :math:`x` before multiplication.
        transpose_y (bool): Whether to transpose :math:`y` before multiplication.
        name(str|None): A name for this layer(optional). If set None, the layer
            will be named automatically.

    Returns:
S
ShenLiang 已提交
90
        Tensor: The output Tensor.
91 92 93

    Examples:

S
ShenLiang 已提交
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143
    .. code-block:: python

        import paddle
        import numpy as np

        paddle.disable_static()
        # vector * vector
        x_data = np.random.random([10]).astype(np.float32)
        y_data = np.random.random([10]).astype(np.float32)
        x = paddle.to_tensor(x_data)
        y = paddle.to_tensor(y_data)
        z = paddle.matmul(x, y)
        print(z.numpy().shape)
        # [1]

        # matrix * vector
        x_data = np.random.random([10, 5]).astype(np.float32)
        y_data = np.random.random([5]).astype(np.float32)
        x = paddle.to_tensor(x_data)
        y = paddle.to_tensor(y_data)
        z = paddle.matmul(x, y)
        print(z.numpy().shape)
        # [10]

        # batched matrix * broadcasted vector
        x_data = np.random.random([10, 5, 2]).astype(np.float32)
        y_data = np.random.random([2]).astype(np.float32)
        x = paddle.to_tensor(x_data)
        y = paddle.to_tensor(y_data)
        z = paddle.matmul(x, y)
        print(z.numpy().shape)
        # [10, 5]

        # batched matrix * batched matrix
        x_data = np.random.random([10, 5, 2]).astype(np.float32)
        y_data = np.random.random([10, 2, 5]).astype(np.float32)
        x = paddle.to_tensor(x_data)
        y = paddle.to_tensor(y_data)
        z = paddle.matmul(x, y)
        print(z.numpy().shape)
        # [10, 5, 5]

        # batched matrix * broadcasted matrix
        x_data = np.random.random([10, 1, 5, 2]).astype(np.float32)
        y_data = np.random.random([1, 3, 2, 5]).astype(np.float32)
        x = paddle.to_tensor(x_data)
        y = paddle.to_tensor(y_data)
        z = paddle.matmul(x, y)
        print(z.numpy().shape)
        # [10, 3, 5, 5]
144 145

    """
S
ShenLiang 已提交
146 147 148 149 150
    op_type = 'matmul_v2'
    if in_dygraph_mode():
        op = getattr(core.ops, op_type)
        return op(x, y, 'trans_x', transpose_x, 'trans_y', transpose_y)

151
    attrs = {
S
ShenLiang 已提交
152 153
        'trans_x': transpose_x,
        'trans_y': transpose_y,
154 155 156 157 158
    }

    def __check_input(x, y):
        var_names = {'x': x, 'y': y}
        for name, val in var_names.items():
S
ShenLiang 已提交
159 160
            check_variable_and_dtype(
                val, name, ['float16', 'float32', 'float64'], 'matmul')
161 162 163

    __check_input(x, y)

S
ShenLiang 已提交
164
    helper = LayerHelper('matmul_v2', **locals())
165 166
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
    helper.append_op(
S
ShenLiang 已提交
167
        type='matmul_v2',
168 169 170 171 172
        inputs={'X': x,
                'Y': y},
        outputs={'Out': out},
        attrs=attrs)
    return out
Z
Zhang Ting 已提交
173 174


myq406450149's avatar
myq406450149 已提交
175
def norm(x, p='fro', axis=None, keepdim=False, name=None):
176
    """
177 178
	:alias_main: paddle.norm
	:alias: paddle.norm,paddle.tensor.norm,paddle.tensor.linalg.norm
S
swtkiwi 已提交
179

180 181 182 183
    Returns the matrix norm (Frobenius) or vector norm (the 1-norm, the Euclidean
    or 2-norm, and in general the p-norm for p > 0) of a given tensor.

    Args:
myq406450149's avatar
myq406450149 已提交
184
        x (Tensor): The input tensor could be N-D tensor, and the input data
185
            type could be float32 or float64.
myq406450149's avatar
myq406450149 已提交
186
        p (float|string, optional): Order of the norm. Supported values are `fro`, `0`, `1`, `2`,
myq406450149's avatar
myq406450149 已提交
187 188
            `inf`, `-inf` and any positive real number yielding the corresponding p-norm. Not supported: ord < 0 and nuclear norm. 
            Default value is `fro`.
myq406450149's avatar
myq406450149 已提交
189 190
        axis (int|list|tuple, optional): The axis on which to apply norm operation. If axis is int
            or list(int)/tuple(int)  with only one element, the vector norm is computed over the axis.
191
            If `axis < 0`, the dimension to norm operation is rank(input) + axis.
myq406450149's avatar
myq406450149 已提交
192
            If axis is a list(int)/tuple(int) with two elements, the matrix norm is computed over the axis.
myq406450149's avatar
myq406450149 已提交
193
            Defalut value is `None`.
194 195 196 197 198 199 200 201
        keepdim (bool, optional): Whether to reserve the reduced dimension in the
            output Tensor. The result tensor will have fewer dimension
            than the :attr:`input` unless :attr:`keepdim` is true, default
            value is False.
        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:
myq406450149's avatar
myq406450149 已提交
202
        Tensor: results of norm operation on the specified axis of input tensor,
203 204 205 206 207 208
        it's data type is the same as input's Tensor.
 
    Examples:
        .. code-block:: python
            
            import paddle
myq406450149's avatar
myq406450149 已提交
209 210 211 212 213 214 215 216 217
            import numpy as np
            paddle.disable_static()
            shape=[2, 3, 4]
            np_input = np.arange(24).astype('float32') - 12
            np_input = np_input.reshape(shape)
            x = paddle.to_tensor(np_input)
            #[[[-12. -11. -10.  -9.] [ -8.  -7.  -6.  -5.] [ -4.  -3.  -2.  -1.]]
            # [[  0.   1.   2.   3.] [  4.   5.   6.   7.] [  8.   9.  10.  11.]]]

218
            # compute frobenius norm along last two dimensions.
myq406450149's avatar
myq406450149 已提交
219 220 221
            out_fro = paddle.norm(x, p='fro', axis=[0,1])
            # out_fro.numpy() [17.435596 16.911535 16.7332   16.911535]

222 223
            # compute 2-order vector norm along last dimension.
            out_pnorm = paddle.norm(x, p=2, axis=-1)
myq406450149's avatar
myq406450149 已提交
224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241
            #out_pnorm.numpy(): [[21.118711  13.190906   5.477226]
            #                    [ 3.7416575 11.224972  19.131126]]

            # compute 2-order  norm along [0,1] dimension.
            out_pnorm = paddle.norm(x, p=2, axis=[0,1])
            #out_pnorm.numpy(): [17.435596 16.911535 16.7332   16.911535]

            # compute inf-order  norm
            out_pnorm = paddle.norm(x, p=np.inf)
            #out_pnorm.numpy()  = [12.]
            out_pnorm = paddle.norm(x, p=np.inf, axis=0)
            #out_pnorm.numpy(): [[12. 11. 10. 9.] [8. 7. 6. 7.] [8. 9. 10. 11.]]

            # compute -inf-order  norm
            out_pnorm = paddle.norm(x, p=-np.inf)
            #out_pnorm.numpy(): [0.]
            out_pnorm = paddle.norm(x, p=-np.inf, axis=0)
            #out_pnorm.numpy(): [[0. 1. 2. 3.] [4. 5. 6. 5.] [4. 3. 2. 1.]]
242 243
    """

myq406450149's avatar
myq406450149 已提交
244
    def frobenius_norm(input, dim=None, keepdim=False, name=None):
245 246 247 248 249 250 251 252 253 254 255
        """
        The frobenius norm OP is to calculate the frobenius norm of certain two dimensions of Tensor `input`.
        Args:
          input (Variable): Tensor, data type float32, float64.
          dim (list, optional): None for last two dimensions.
          keepdim (bool, optional): Whether keep the dimensions as the `input`, Default False.
        """
        if dim is not None and not (isinstance(dim, list) and len(dim) == 2):
            raise ValueError(
                "The dim of frobenius norm op should be None or two elements list!"
            )
myq406450149's avatar
myq406450149 已提交
256
        if in_dygraph_mode():
myq406450149's avatar
myq406450149 已提交
257 258 259 260 261 262 263
            if dim is None:
                return core.ops.frobenius_norm(input, 'keep_dim', keepdim,
                                               'reduce_all', True)
            return core.ops.frobenius_norm(input, 'dim', dim, 'keep_dim',
                                           keepdim, 'reduce_all', False)
        attrs = {'dim': dim, 'keep_dim': keepdim, 'reduce_all': False}
        if dim is None:
264 265 266 267 268
            attrs['reduce_all'] = True
        check_variable_and_dtype(input, 'input', ['float32', 'float64'],
                                 'frobenius_norm')

        helper = LayerHelper('frobenius_norm', **locals())
myq406450149's avatar
myq406450149 已提交
269 270
        out = helper.create_variable_for_type_inference(
            dtype=helper.input_dtype())
271 272 273 274 275 276 277 278 279 280 281 282

        helper.append_op(
            type='frobenius_norm',
            inputs={'X': input},
            outputs={'Out': out},
            attrs=attrs)
        return out

    def vector_norm(input,
                    porder=None,
                    axis=None,
                    keepdim=False,
myq406450149's avatar
myq406450149 已提交
283
                    asvector=False,
284 285 286 287 288 289 290 291 292
                    name=None):
        """
        Calculate the p-order vector norm for certain  dimension of Tensor `input`.
        Args:
          input (Variable): Tensor, data type float32, float64.
          porder (float, optional): None for porder=2.0.
          axis (int, optional): None for last dimension.
          keepdim (bool, optional): Whether keep the dimensions as the `input`, Default False.
        """
myq406450149's avatar
myq406450149 已提交
293 294 295 296
        if in_dygraph_mode():
            if axis is None: axis = -1
            return core.ops.p_norm(input, 'porder', porder, 'axis', axis,
                                   'keepdim', keepdim, 'asvector', asvector)
297 298 299 300
        if porder is not None:
            check_type(porder, 'porder', (float, int), 'p_norm')
        if axis is not None:
            check_type(axis, 'axis', (int), 'p_norm')
myq406450149's avatar
myq406450149 已提交
301 302 303
        check_variable_and_dtype(input, 'input', ['float32', 'float64'],
                                 'p_norm')

304 305 306 307
        attrs = {
            'axis': axis if axis is not None else -1,
            'porder': float(porder) if porder is not None else 2.0,
            'keepdim': keepdim,
myq406450149's avatar
myq406450149 已提交
308
            'asvector': asvector,
309 310 311
            'epsilon': 1e-12,
        }
        helper = LayerHelper('p_norm', **locals())
myq406450149's avatar
myq406450149 已提交
312 313
        out = helper.create_variable_for_type_inference(
            dtype=helper.input_dtype())
314 315 316 317 318 319 320 321

        helper.append_op(
            type='p_norm',
            inputs={'X': input},
            outputs={'Out': out},
            attrs=attrs)
        return out

myq406450149's avatar
myq406450149 已提交
322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384
    def inf_norm(input,
                 porder=None,
                 axis=axis,
                 keepdim=False,
                 asvector=False,
                 name=None):
        helper = LayerHelper('frobenius_norm', **locals())
        out = helper.create_variable_for_type_inference(
            dtype=helper.input_dtype())
        helper.append_op(type='abs', inputs={'X': input}, outputs={'Out': out})
        reduce_out = helper.create_variable_for_type_inference(
            dtype=helper.input_dtype())

        reduce_all = True if axis == None or axis == [] or asvector == True else False
        axis = axis if axis != None and axis != [] else [0]

        reduce_type = 'reduce_max' if porder == np.float(
            'inf') else 'reduce_min'
        helper.append_op(
            type=reduce_type,
            inputs={'X': out},
            outputs={'Out': reduce_out},
            attrs={'dim': axis,
                   'keep_dim': keepdim,
                   'reduce_all': reduce_all})

        return reduce_out

    def p_matrix_norm(input, porder=1., axis=axis, keepdim=False, name=None):
        block = LayerHelper('norm', **locals())
        out = block.create_variable_for_type_inference(
            dtype=block.input_dtype())
        abs_out = block.create_variable_for_type_inference(
            dtype=block.input_dtype())
        block.append_op(
            type='abs', inputs={'X': input}, outputs={'Out': abs_out})
        pow_out = block.create_variable_for_type_inference(
            dtype=block.input_dtype())

        block.append_op(
            type='pow',
            inputs={'X': abs_out},
            outputs={'Out': pow_out},
            attrs={'factor': porder})
        sum_out = block.create_variable_for_type_inference(
            dtype=block.input_dtype())
        block.append_op(
            type='reduce_sum',
            inputs={'X': pow_out},
            outputs={'Out': sum_out},
            attrs={
                'dim': axis,
                'keep_dim': keepdim,
                'reduce_all': True if axis is None else False
            })
        porder
        block.append_op(
            type='pow',
            inputs={'X': sum_out},
            outputs={'Out': out},
            attrs={'factor': float(1. / porder)})
        return out

385 386 387
    if axis is None and p is not None:
        if isinstance(p, str):
            if p == "fro":
myq406450149's avatar
myq406450149 已提交
388
                return frobenius_norm(x, dim=axis, keepdim=keepdim, name=name)
389 390 391 392 393
            else:
                raise ValueError(
                    "only valid string values are 'fro', found {}".format(p))
        elif isinstance(p, (int, float)):
            return vector_norm(
myq406450149's avatar
myq406450149 已提交
394 395 396 397 398 399
                x,
                porder=p,
                axis=axis,
                keepdim=keepdim,
                asvector=True,
                name=name)
400 401 402 403
        else:
            raise ValueError("only valid p type is string or float, found {}".
                             format(type(p)))

myq406450149's avatar
myq406450149 已提交
404 405
    if isinstance(axis, tuple):
        axis = list(axis)
406 407 408 409 410
    if isinstance(axis, list) and len(axis) == 1:
        axis = axis[0]

    #calculate vector norm, where axis is int or list with only one integer
    if isinstance(axis, int):
myq406450149's avatar
myq406450149 已提交
411 412 413 414 415 416 417 418 419 420 421 422 423 424
        if isinstance(p, str):
            if p == "fro":
                return vector_norm(
                    x,
                    porder=2,
                    axis=axis,
                    keepdim=keepdim,
                    asvector=False,
                    name=name)

            else:
                raise ValueError(
                    "only valid string values are 'fro', found {}".format(p))
        elif isinstance(p, (int, float)):
425
            return vector_norm(
myq406450149's avatar
myq406450149 已提交
426 427 428 429 430 431
                x,
                axis=axis,
                porder=p,
                keepdim=keepdim,
                asvector=False,
                name=name)
432 433 434 435 436 437 438
        else:
            raise ValueError(
                "unspport p for p-order vector norm. except float, found {}".
                format(p))
    #calculate matrix norm, where axis is list with two integers
    elif isinstance(axis, list) and len(axis) == 2:
        if p == "fro":
myq406450149's avatar
myq406450149 已提交
439 440 441
            return frobenius_norm(x, dim=axis, keepdim=keepdim, name=name)
        elif p == np.inf or p == -np.inf:
            return inf_norm(x, porder=p, axis=axis, keepdim=keepdim, name=name)
myq406450149's avatar
myq406450149 已提交
442 443 444 445
        elif p == 0:
            raise ValueError(
                "just suport axis type int or list (length of list <=1) if p = 0, found {}".
                format(axis))
446
        else:
myq406450149's avatar
myq406450149 已提交
447 448
            return p_matrix_norm(
                x, porder=p, axis=axis, keepdim=keepdim, name=name)
449 450 451 452 453 454
    else:
        raise ValueError(
            "except axis type int or list (length of list <=2), found {}".
            format(axis))


Z
Zhang Ting 已提交
455 456
def dist(x, y, p=2):
    """
S
swtkiwi 已提交
457

Z
Zhang Ting 已提交
458
    This OP returns the p-norm of (x - y). It is not a norm in a strict sense, only as a measure
459 460
    of distance. The shapes of x and y must be broadcastable. The definition is as follows, for
    details, please refer to the `numpy's broadcasting <https://docs.scipy.org/doc/numpy/user/basics.broadcasting.html>`_:
Z
Zhang Ting 已提交
461

462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484
    - Each input has at least one dimension.
    - Match the two input dimensions from back to front, the dimension sizes must either be equal, one of them is 1, or one of them does not exist.

    Where, z = x - y, the shapes of x and y are broadcastable, then the shape of z can be
    obtained as follows:

    1. If the number of dimensions of x and y are not equal, prepend 1 to the dimensions of the
    tensor with fewer dimensions.

    For example, The shape of x is [8, 1, 6, 1], the shape of y is [7, 1, 5], prepend 1 to the
    dimension of y.

    x (4-D Tensor):  8 x 1 x 6 x 1

    y (4-D Tensor):  1 x 7 x 1 x 5

    2. Determine the size of each dimension of the output z: choose the maximum value from the
    two input dimensions.

    z (4-D Tensor):  8 x 7 x 6 x 5

    If the number of dimensions of the two inputs are the same, the size of the output can be
    directly determined in step 2. When p takes different values, the norm formula is as follows:
Z
Zhang Ting 已提交
485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510

    When p = 0, defining $0^0=0$, the zero-norm of z is simply the number of non-zero elements of z.

    .. math::

        ||z||_{0}=\lim_{p \\rightarrow 0}\sum_{i=1}^{m}|z_i|^{p}

    When p = inf, the inf-norm of z is the maximum element of z.

    .. math::

        ||z||_\infty=\max_i |z_i|

    When p = -inf, the negative-inf-norm of z is the minimum element of z.

    .. math::

        ||z||_{-\infty}=\min_i |z_i|

    Otherwise, the p-norm of z follows the formula,

    .. math::

        ||z||_{p}=(\sum_{i=1}^{m}|z_i|^p)^{\\frac{1}{p}}

    Args:
511 512
        x (Tensor): 1-D to 6-D Tensor, its data type is float32 or float64.
        y (Tensor): 1-D to 6-D Tensor, its data type is float32 or float64.
Z
Zhang Ting 已提交
513 514 515
        p (float, optional): The norm to be computed, its data type is float32 or float64. Default: 2.

    Returns:
516
        Tensor: Tensor that is the p-norm of (x - y).
Z
Zhang Ting 已提交
517 518 519 520 521 522 523

    Examples:
        .. code-block:: python

            import paddle
            import numpy as np

524 525 526 527
            x = paddle.to_tensor(np.array([[3, 3],[3, 3]]), "float32")
            y = paddle.to_tensor(np.array([[3, 3],[3, 1]]), "float32")
            out = paddle.dist(x, y, 0)
            print(out) # out = [1.]
Z
Zhang Ting 已提交
528

529 530
            out = paddle.dist(x, y, 2)
            print(out) # out = [2.]
Z
Zhang Ting 已提交
531

532 533
            out = paddle.dist(x, y, float("inf"))
            print(out) # out = [2.]
Z
Zhang Ting 已提交
534

535 536
            out = paddle.dist(x, y, float("-inf"))
            print(out) # out = [0.]
Z
Zhang Ting 已提交
537 538 539 540 541 542 543 544 545 546 547 548 549
    """
    check_variable_and_dtype(x, 'dtype', ['float32', 'float64'], 'dist')
    check_variable_and_dtype(y, 'dtype', ['float32', 'float64'], 'dist')
    check_type(p, 'p', (float, int), 'dist')
    helper = LayerHelper("dist", **locals())
    out = helper.create_variable_for_type_inference(x.dtype)

    inputs = {"X": [x], "Y": [y]}
    outputs = {'Out': [out]}
    attrs = {"p": float(p)}
    helper.append_op(
        type='dist', inputs=inputs, outputs={'Out': out}, attrs=attrs)
    return out
L
liuwei1031 已提交
550 551 552 553 554 555 556


def dot(x, y, name=None):
    """
    This operator calculates inner product for vectors.
   
    .. note::
S
ShenLiang 已提交
557 558
       Support 1-d and 2-d Tensor. When it is 2d, the first dimension of this matrix 
       is the batch dimension, which means that the vectors of multiple batches are dotted. 
L
liuwei1031 已提交
559 560

    Parameters:
S
ShenLiang 已提交
561 562
        x(Tensor): 1-D or 2-D ``Tensor``. Its dtype should be ``float32``, ``float64``, ``int32``, ``int64``
        y(Tensor): 1-D or 2-D ``Tensor``. Its dtype soulde be ``float32``, ``float64``, ``int32``, ``int64``
L
liuwei1031 已提交
563 564
        name(str, optional): Name of the output. Default is None. It's used to print debug info for developers. Details: :ref:`api_guide_Name`

565
    Returns:
566
        Variable: the calculated result Tensor.
567

L
liuwei1031 已提交
568 569 570 571 572 573
    Examples:

    .. code-block:: python

        import paddle
        import numpy as np
574 575 576 577

        paddle.disable_static()
        x_data = np.random.uniform(0.1, 1, [10]).astype(np.float32)
        y_data = np.random.uniform(1, 3, [10]).astype(np.float32)
S
ShenLiang 已提交
578 579
        x = paddle.to_tensor(x_data)
        y = paddle.to_tensor(y_data)
580 581
        z = paddle.dot(x, y)
        print(z.numpy())
L
liuwei1031 已提交
582 583 584

    """
    op_type = 'dot'
585 586 587 588 589
    # skip var type check in dygraph mode to improve efficiency
    if in_dygraph_mode():
        op = getattr(core.ops, op_type)
        return op(x, y)

L
liuwei1031 已提交
590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607
    assert x is not None, 'x cannot be None in {}'.format(op_type)
    assert y is not None, 'y cannot be None in {}'.format(op_type)

    check_variable_and_dtype(x, 'x', ['float32', 'float64', 'int32', 'int64'],
                             op_type)
    check_variable_and_dtype(y, 'y', ['float32', 'float64', 'int32', 'int64'],
                             op_type)

    helper = LayerHelper(op_type, **locals())
    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="dot", inputs={'X': x,
                            'Y': y}, attrs={}, outputs={"Out": out})
    return out
608 609 610 611 612 613


def t(input, name=None):
    """
    Transpose <=2-D tensor. 
    0-D and 1-D tensors are returned as it is and 2-D tensor is equal to 
614
    the paddle.transpose function which perm dimensions set 0 and 1.
615 616
    
    Args:
617
        input (Tensor): The input Tensor. It is a N-D (N<=2) Tensor of data types float16, float32, float64, int32.
618 619 620
        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:
621
        Tensor: A transposed n-D Tensor, with data type being float16, float32, float64, int32, int64.
622 623
    
    For Example:
624

625
        .. code-block:: text
626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641

             # Example 1 (0-D tensor)
             x = tensor([0.79])
             paddle.t(x) = tensor([0.79])

             # Example 2 (1-D tensor)
             x = tensor([0.79, 0.84, 0.32])
             paddle.t(x) = tensor([0.79, 0.84, 0.32])

             # Example 3 (2-D tensor)
             x = tensor([0.79, 0.84, 0.32],
                        [0.64, 0.14, 0.57])
             paddle.t(x) = tensor([0.79, 0.64],
                                  [0.84, 0.14],
                                  [0.32, 0.57])

642
     Examples:
643

644
        .. code-block:: python
645

646
            import paddle
647
            x = paddle.ones(shape=[2, 3], dtype='int32')
648
            x_transposed = paddle.t(x)
649 650
            print(x_transposed.shape)
            # [3, 2]
651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681
    """
    if len(input.shape) > 2:
        raise ValueError(
            "Input(input) only support N-D (N<=2) tensor, but received "
            "length of Input(input) is %s. Perhaps you can use paddle."
            "tensor.transpose() instead." % len(input.shape))
    if in_dygraph_mode():
        if len(input.shape) == 1:
            return input
        # 2-D tensor
        perm = [1, 0]
        out, _ = core.ops.transpose2(input, 'axis', perm)
        return out

    check_variable_and_dtype(
        input, 'input', ['float16', 'float32', 'float64', 'int32', 'int64'],
        'transpose')

    helper = LayerHelper('t', **locals())
    out = helper.create_variable_for_type_inference(input.dtype)
    input_shape = helper.create_variable_for_type_inference(input.dtype)
    if len(input.shape) == 1:
        out = input
    else:
        helper.append_op(
            type='transpose2',
            inputs={'X': [input]},
            outputs={'Out': [out],
                     'XShape': [input_shape]},
            attrs={'axis': [1, 0]})
    return out
682 683


684
def cross(x, y, axis=None, name=None):
685
    """
686
    Computes the cross product between two tensors along an axis.
687
    
688 689
    Inputs must have the same shape, and the length of their axes should be equal to 3.
    If `axis` is not given, it defaults to the first axis found with the length 3.
690 691
    
    Args:
692 693
        x (Tensor): The first input tensor.
        y (Tensor): The second input tensor.
694
        axis (int, optional): The axis along which to compute the cross product. It defaults to the first axis found with the length 3.
695
        name (str, optional): Name for the operation (optional, default is None). For more information, please refer to :ref:`api_guide_Name`.
696 697

    Returns:
698
        Tensor. A Tensor with same data type as `x`.
699 700 701
        
    Examples:
        .. code-block:: python
702

703
            import paddle
704

Z
Zhou Wei 已提交
705 706 707 708 709 710
            x = paddle.to_tensor([[1.0, 1.0, 1.0],
                                  [2.0, 2.0, 2.0],
                                  [3.0, 3.0, 3.0]])
            y = paddle.to_tensor([[1.0, 1.0, 1.0],
                                  [1.0, 1.0, 1.0],
                                  [1.0, 1.0, 1.0]])
711

712 713 714 715 716 717 718 719 720
            z1 = paddle.cross(x, y)
            # [[-1. -1. -1.]
            #  [ 2.  2.  2.]
            #  [-1. -1. -1.]]

            z2 = paddle.cross(x, y, axis=1)
            # [[0. 0. 0.]
            #  [0. 0. 0.]
            #  [0. 0. 0.]]
721 722
    """
    if in_dygraph_mode():
723
        if axis is not None:
724
            return core.ops.cross(x, y, 'dim', axis)
725
        else:
726
            return core.ops.cross(x, y)
727

728 729
    helper = LayerHelper("cross", **locals())
    out = helper.create_variable_for_type_inference(x.dtype)
730
    attrs = dict()
731
    attrs['dim'] = axis
732 733 734

    helper.append_op(
        type='cross',
735 736
        inputs={'X': x,
                'Y': y},
737 738 739
        outputs={'Out': out},
        attrs=attrs)
    return out
740 741


742
def cholesky(x, upper=False, name=None):
G
Guo Sheng 已提交
743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769
    """
    Computes the Cholesky decomposition of one symmetric positive-definite
    matrix or batches of symmetric positive-definite matrice. 
    
    If `upper` is `True`, the decomposition has the form :math:`A = U^{T}U` ,
    and the returned matrix :math:`U` is upper-triangular. Otherwise, the
    decomposition has the form  :math:`A = LL^{T}` , and the returned matrix
    :math:`L` is lower-triangular.

    Args:
        x (Variable): The input tensor. Its shape should be `[*, M, M]`,
            where * is zero or more batch dimensions, and matrices on the
            inner-most 2 dimensions all should be symmetric positive-definite.
            Its data type should be float32 or float64.
        upper (bool): The flag indicating whether to return upper or lower
            triangular matrices. Default: False.

    Returns:
        Variable: A Tensor with same shape and data type as `x`. It represents \
            triangular matrices generated by Cholesky decomposition.
        
    Examples:
        .. code-block:: python

            import paddle
            import numpy as np

770 771 772 773
            paddle.disable_static()
            a = np.random.rand(3, 3)
            a_t = np.transpose(a, [1, 0])
            x_data = np.matmul(a, a_t) + 1e-03
774
            x = paddle.to_tensor(x_data)
775 776 777 778 779
            out = paddle.cholesky(x, upper=False)
            print(out.numpy())
            # [[1.190523   0.         0.        ]
            #  [0.9906703  0.27676893 0.        ]
            #  [1.25450498 0.05600871 0.06400121]]
G
Guo Sheng 已提交
780 781

    """
782 783
    if in_dygraph_mode():
        return core.ops.cholesky(x, "upper", upper)
G
Guo Sheng 已提交
784 785 786 787 788 789 790 791 792 793 794 795
    check_variable_and_dtype(x, 'dtype', ['float32', 'float64'], 'cholesky')
    check_type(upper, 'upper', bool, 'cholesky')
    helper = LayerHelper('cholesky', **locals())
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
    helper.append_op(
        type='cholesky',
        inputs={'X': [x]},
        outputs={'Out': out},
        attrs={'upper': upper})
    return out


796 797
def bmm(x, y, name=None):
    """
798 799
	:alias_main: paddle.bmm
	:alias: paddle.bmm,paddle.tensor.bmm,paddle.tensor.linalg.bmm
S
swtkiwi 已提交
800

801 802 803 804 805 806 807
    Applies batched matrix multiplication to two tensors.

    Both of the two input tensors must be three-dementional and share the same batch size.

    if x is a (b, m, k) tensor, y is a (b, k, n) tensor, the output will be a (b, m, n) tensor.

    Args:
Y
yaoxuefeng 已提交
808 809
        x (Tensor): The input Tensor.
        y (Tensor): The input Tensor.
810 811 812 813
        name(str|None): A name for this layer(optional). If set None, the layer
            will be named automatically.

    Returns:
Y
yaoxuefeng 已提交
814
        Tensor: The product Tensor.
815 816 817

    Examples:
        import paddle
Y
yaoxuefeng 已提交
818

819 820 821 822 823 824 825 826
        # In imperative mode:
        # size x: (2, 2, 3) and y: (2, 3, 2)
        x = paddle.to_tensor([[[1.0, 1.0, 1.0],
                               [2.0, 2.0, 2.0]],
                              [[3.0, 3.0, 3.0],
                               [4.0, 4.0, 4.0]]])
        y = paddle.to_tensor([[[1.0, 1.0],[2.0, 2.0],[3.0, 3.0]],
                              [[4.0, 4.0],[5.0, 5.0],[6.0, 6.0]]])
Y
yaoxuefeng 已提交
827 828 829 830 831
        out = paddle.bmm(x, y)
        #output size: (2, 2, 2)
        #output value:
        #[[[6.0, 6.0],[12.0, 12.0]],[[45.0, 45.0],[60.0, 60.0]]]
        out_np = out.numpy()
832
    """
Y
yaoxuefeng 已提交
833 834 835 836 837 838 839 840 841 842
    x_shape = x.shape
    y_shape = y.shape
    if not len(x_shape) == len(y_shape) == 3:
        raise ValueError(
            "x and y should be 3-dimensional. But received x's dimention: {}, y's dimention: {}".
            format(x_shape, y_shape))
    if x_shape[2] != y_shape[1]:
        raise ValueError(
            "x's width must be equal with y's height. But received x's shape: {}, y's shape: {}".
            format(x_shape, y_shape))
843 844 845 846
    if x_shape[0] != y_shape[0]:
        raise ValueError(
            "x's batch (shape[0]) must be equal with y's batch (shape[0]). But received x's shape: {}, y's shape: {}".
            format(x_shape, y_shape))
847 848 849 850 851 852
    helper = LayerHelper('bmm', **locals())
    if in_dygraph_mode():
        return core.ops.bmm(x, y)
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
    helper.append_op(type='bmm', inputs={'X': x, 'Y': y}, outputs={'Out': out})
    return out
Q
Qi Li 已提交
853 854 855 856 857 858 859 860


def histogram(input, bins=100, min=0, max=0):
    """
    Computes the histogram of a tensor. The elements are sorted into equal width bins between min and max. 
    If min and max are both zero, the minimum and maximum values of the data are used.

    Args:
861
        input (Tensor): A Tensor(or LoDTensor) with shape :math:`[N_1, N_2,..., N_k]` . The data type of the input Tensor
Q
Qi Li 已提交
862 863 864 865 866 867
            should be float32, float64, int32, int64.
        bins (int): number of histogram bins
        min (int): lower end of the range (inclusive)
        max (int): upper end of the range (inclusive)

    Returns:
868
        Tensor: data type is int64, shape is (nbins,).
Q
Qi Li 已提交
869

870
    Examples:
Q
Qi Li 已提交
871
        .. code-block:: python
872

Q
Qi Li 已提交
873
            import paddle
874

875
            inputs = paddle.to_tensor([1, 2, 1])
876 877
            result = paddle.histogram(inputs, bins=4, min=0, max=3)
            print(result) # [0, 2, 1, 0]
Q
Qi Li 已提交
878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893
    """
    if in_dygraph_mode():
        return core.ops.histogram(input, "bins", bins, "min", min, "max", max)

    helper = LayerHelper('histogram', **locals())
    check_variable_and_dtype(
        input, 'X', ['int32', 'int64', 'float32', 'float64'], 'histogram')
    out = helper.create_variable_for_type_inference(VarDesc.VarType.INT64)
    helper.append_op(
        type='histogram',
        inputs={'X': input},
        outputs={'Out': out},
        attrs={'bins': bins,
               'min': min,
               'max': max})
    return out
894 895 896 897 898 899 900


def mv(x, vec, name=None):
    """
    Performs a matrix-vector product of the matrix x and the vector vec.

    Args:
F
furnace 已提交
901
        x (Tensor): A tensor with shape :math:`[M, N]` , The data type of the input Tensor x
902
            should be one of float32, float64.
F
furnace 已提交
903
        vec (Tensor): A tensor with shape :math:`[N]` , The data type of the input Tensor x
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
            should be one of float32, float64.
        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: The tensor which is producted by x and vec.

    Examples:
        .. code-block:: python

            # x: [M, N], vec: [N]
            # paddle.mv(x, vec)  # out: [M]

            import numpy as np
            import paddle

            x_data = np.array([[2, 1, 3], [3, 0, 1]]).astype("float64")
            x = paddle.to_tensor(x_data)
            vec_data = np.array([3, 5, 1])
            vec = paddle.to_tensor(vec_data).astype("float64")
            out = paddle.mv(x, vec)
    """
    if in_dygraph_mode():
        out = core.ops.mv(x, vec)
        return out

    def __check_input(x, vec):
        var_names = {'x': x, 'vec': vec}
        for name, val in var_names.items():
            check_variable_and_dtype(val, name, ['float32', 'float64'], 'mv')
        x_shape = list(x.shape)
        vec_shape = list(vec.shape)
        if len(x_shape) != 2:
            raise ValueError(
                "x should be 2-dimensional. But received x's dimention: {}".
                format(x_shape))
        if len(vec_shape) != 1:
            raise ValueError(
                "vec should be 1-dimensional. But received vec's dimention: {}".
                format(vec_shape))

    __check_input(x, vec)

    helper = LayerHelper('mv', **locals())
    out = helper.create_variable_for_type_inference(dtype=x.dtype)
    helper.append_op(
        type='mv', inputs={'X': x,
                           'Vec': vec}, outputs={'Out': out})
    return out