Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[DOC] Clarify the difference of paddle.norm and np.linalg.norm #32530

Merged
merged 2 commits into from
Apr 26, 2021
Merged

[DOC] Clarify the difference of paddle.norm and np.linalg.norm #32530

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6c9ed67
[DOC] Clarify the difference of paddle.norm and np.linalg.norm test…
ZHUI Apr 25, 2021
52e0586
[DOC] fix as review commit. test=document_fix
ZHUI Apr 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 45 additions & 35 deletions python/paddle/tensor/linalg.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,8 @@

def matmul(x, y, transpose_x=False, transpose_y=False, name=None):
"""
Applies matrix multiplication to two tensors. `matmul` follows
the complete broadcast rules,
Applies matrix multiplication to two tensors. `matmul` follows
the complete broadcast rules,
and its behavior is consistent with `np.matmul`.

Currently, the input tensors' number of dimensions can be any, `matmul` can be used to
Expand All @@ -50,8 +50,8 @@ def matmul(x, y, transpose_x=False, transpose_y=False, name=None):
flag values of :attr:`transpose_x`, :attr:`transpose_y`. Specifically:

- If a transpose flag is specified, the last two dimensions of the tensor
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
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:
Expand All @@ -60,22 +60,22 @@ def matmul(x, y, transpose_x=False, transpose_y=False, name=None):

- 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.
- 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,

- 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,
- 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.

Args:
Expand Down Expand Up @@ -177,11 +177,17 @@ def norm(x, p='fro', axis=None, keepdim=False, name=None):
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.

.. note::
This norm API is different from `numpy.linalg.norm`.
This api supports high-order input tensors (rank >= 3), and certain axis need to be pointed out to calculate the norm.
But `numpy.linalg.norm` only supports 1-D vector or 2-D matrix as input tensor.
For p-order matrix norm, this api actually treats matrix as a flattened vector to calculate the vector norm, NOT REAL MATRIX NORM.

Args:
x (Tensor): The input tensor could be N-D tensor, and the input data
type could be float32 or float64.
p (float|string, optional): Order of the norm. Supported values are `fro`, `0`, `1`, `2`,
`inf`, `-inf` and any positive real number yielding the corresponding p-norm. Not supported: ord < 0 and nuclear norm.
`inf`, `-inf` and any positive real number yielding the corresponding p-norm. Not supported: ord < 0 and nuclear norm.
Default value is `fro`.
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.
Expand All @@ -198,10 +204,10 @@ def norm(x, p='fro', axis=None, keepdim=False, name=None):
Returns:
Tensor: results of norm operation on the specified axis of input tensor,
it's data type is the same as input's Tensor.

Examples:
.. code-block:: python

import paddle
import numpy as np
shape=[2, 3, 4]
Expand Down Expand Up @@ -344,6 +350,10 @@ def inf_norm(input,
return reduce_out

def p_matrix_norm(input, porder=1., axis=axis, keepdim=False, name=None):
"""
NOTE:
This function actually treats the matrix as flattened vector to calculate vector norm instead of matrix norm.
"""
block = LayerHelper('norm', **locals())
out = block.create_variable_for_type_inference(
dtype=block.input_dtype())
Expand Down Expand Up @@ -548,10 +558,10 @@ def dist(x, y, p=2):
def dot(x, y, name=None):
"""
This operator calculates inner product for vectors.

.. note::
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.
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.

Parameters:
x(Tensor): 1-D or 2-D ``Tensor``. Its dtype should be ``float32``, ``float64``, ``int32``, ``int64``
Expand Down Expand Up @@ -604,17 +614,17 @@ def dot(x, y, name=None):

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
Transpose <=2-D tensor.
0-D and 1-D tensors are returned as it is and 2-D tensor is equal to
the paddle.transpose function which perm dimensions set 0 and 1.

Args:
input (Tensor): The input Tensor. It is a N-D (N<=2) Tensor of data types float16, float32, float64, int32.
name(str, optional): The default value is None. Normally there is no need for
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: A transposed n-D Tensor, with data type being float16, float32, float64, int32, int64.

For Example:

.. code-block:: text
Expand Down Expand Up @@ -679,10 +689,10 @@ def t(input, name=None):
def cross(x, y, axis=None, name=None):
"""
Computes the cross product between two tensors along an axis.

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.

Args:
x (Tensor): The first input tensor.
y (Tensor): The second input tensor.
Expand All @@ -691,7 +701,7 @@ def cross(x, y, axis=None, name=None):

Returns:
Tensor. A Tensor with same data type as `x`.

Examples:
.. code-block:: python

Expand Down Expand Up @@ -737,8 +747,8 @@ def cross(x, y, axis=None, name=None):
def cholesky(x, upper=False, name=None):
r"""
Computes the Cholesky decomposition of one symmetric positive-definite
matrix or batches of symmetric positive-definite matrice.
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
Expand All @@ -755,7 +765,7 @@ def cholesky(x, upper=False, name=None):
Returns:
Tensor: A Tensor with same shape and data type as `x`. It represents \
triangular matrices generated by Cholesky decomposition.

Examples:
.. code-block:: python

Expand Down Expand Up @@ -845,7 +855,7 @@ def bmm(x, y, name=None):

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.
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:
Expand Down