OpenI
/
MegEngine
Not watched
1
0
Fork 0
Code
Releases 31 Wiki Activity
Issues 0 Pull Requests 0 Datasets Model Cloudbrain
Browse Source

docs(mge/functional): enhance functional statstic func docstring 

GitOrigin-RevId: 1045aecf15
release-1.11.1
Megvii Engine Team 2 years ago
parent
213f40437c
commit
222865799b
2 changed files with 343 additions and 141 deletions
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +327
    -136
      imperative/python/megengine/functional/math.py
  2. +16
    -5
      imperative/python/megengine/functional/tensor.py

+ 327
- 136
imperative/python/megengine/functional/math.py View File

@@ -120,24 +120,58 @@ def sum(
axis: Optional[Union[int, Sequence[int]]] = None,
keepdims: bool = False,
) -> Tensor:
r"""Returns the sum of input tensor along given axis. If axis is a list of dimensions,
reduce over all of them.
r"""Calculates the sum of tensor elements over a given axis (or axes).

Args:
inp: input tensor.
axis: dimension to reduce. If None, all dimensions will be reduced.
Default: None
keepdims: whether the output tensor has axis retained or not.
Default: False
inp: input tensor. Should have a numeric data type.
axis: axis or axes along which sums must be computed.
By default, the sum must be computed over the entire tensor.
If a sequence of integers, sums must be computed over multiple axes.
keepdims: if ``True``, the reduced axes (dimensions) must be included in the result as singleton dimensions,
and, accordingly, the result must be compatible with the input tensor (see :ref:`broadcasting-rule`).
Otherwise, if ``False``, the reduced axes (dimensions) must not be included in the result.

Returns:
output tensor.
if the sum was computed over the entire tensor, a zero-dimensional tensor containing the sum;
otherwise, a tensor containing the sums.
The returned tensor must have a data type determined by :ref:`dtype-promotion`.

.. admonition:: Special Cases

Let ``N`` equal the number of elements over which to compute the sum.

* If ``N`` is 0, the sum is ``0`` (i.e., the empty sum).
* If :math:`x_i` is ``NaN``, the sum is ``NaN`` (i.e., ``NaN`` values propagate).

.. warning::

If the accumulator is too small, overflow occurs:

>>> x = F.ones(128, dtype="int8")
>>> F.sum(x)
Tensor(-128, dtype=int8, device=xpux:0)

Examples:
>>> import numpy as np
>>> x = Tensor(np.arange(1, 7, dtype=np.int32).reshape(2, 3))
>>> F.sum(x)
Tensor(21, dtype=int32, device=xpux:0)
The sum of an empty tensor is the neutral element 0:

>>> F.sum(Tensor([]))
Tensor(0.0, device=xpux:0)

Normal case:

>>> F.sum(Tensor([1, 2, 3]))
Tensor(6, dtype=int32, device=xpux:0)
>>> F.sum(Tensor([0.5, 1.5]))
Tensor(2.0, device=xpux:0)

Along an axis:

>>> F.sum(Tensor([[1, 2, 3], [4, 5, 6]]), axis=0)
Tensor([5 7 9], dtype=int32, device=xpux:0)
>>> F.sum(Tensor([[1, 2, 3], [4, 5, 6]]), axis=1)
Tensor([ 6 15], dtype=int32, device=xpux:0)

"""
return inp.sum(axis=axis, keepdims=keepdims)

@@ -145,22 +179,58 @@ def sum(
def prod(
inp: Tensor, axis: Optional[Union[int, Sequence[int]]] = None, keepdims=False
) -> Tensor:
r"""Returns the product of input tensor along given axis. If axis is a list of dimensions,
reduce over all of them.
r"""Calculates the product of tensor elements over a given axis (or axes).

Args:
inp: input tensor.
axis: dimension to reduce. If None, all dimensions will be reduced. Default: None
keepdims: whether the output tensor has axis retained or not. Default: False
inp: input tensor. Should have a numeric data type.
axis: axis or axes along which products must be computed.
By default, the product must be computed over the entire tensor.
If a sequence of integers, products must be computed over multiple axes.
keepdims: if ``True``, the reduced axes (dimensions) must be included in the result as singleton dimensions,
and, accordingly, the result must be compatible with the input tensor (see :ref:`broadcasting-rule`).
Otherwise, if ``False``, the reduced axes (dimensions) must not be included in the result.

Returns:
output tensor.
if the product was computed over the entire tensor, a zero-dimensional tensor containing the products;
otherwise, a non-zero-dimensional tensor containing the products.
The returned tensor must have a data type determined by :ref:`dtype-promotion`.

.. admonition:: Special Cases

Let ``N`` equal the number of elements over which to compute the product.

* If ``N`` is 0, the product is ``1`` (i.e., the empty product).
* If :math:`x_i` is ``NaN``, the product is ``NaN`` (i.e., ``NaN`` values propagate).

.. warning::
Arithmetic is modular when using integer types, and no error is raised on overflow:

>>> x = Tensor([536870910, 536870910, 536870910, 536870910])
>>> F.prod(x)
Tensor(16, dtype=int32, device=xpux:0)

Examples:
>>> import numpy as np
>>> x = Tensor(np.arange(1, 7, dtype=np.int32).reshape(2, 3))
>>> F.prod(x)
Tensor(720, dtype=int32, device=xpux:0)

The product of an empty tensor is the neutral element 1:

>>> F.prod(Tensor([]))
Tensor(1.0, device=xpux:0)

Normal case:

>>> F.prod(Tensor([1, 2, 3]))
Tensor(6, dtype=int32, device=xpux:0)
>>> F.prod(Tensor([0.5, 1.5]))
Tensor(0.75, device=xpux:0)

Along an axis:

>>> F.prod(Tensor([[1, 2, 3], [4, 5, 6]]), axis=0)
Tensor([ 4 10 18], dtype=int32, device=xpux:0)
>>> F.prod(Tensor([[1, 2, 3], [4, 5, 6]]), axis=1)
Tensor([ 6 120], dtype=int32, device=xpux:0)

"""
return inp.prod(axis=axis, keepdims=keepdims)

@@ -170,24 +240,44 @@ def mean(
axis: Optional[Union[int, Sequence[int]]] = None,
keepdims: bool = False,
) -> Tensor:
r"""Returns the mean value of input tensor along
given axis. If axis is a list of dimensions,
reduce over all of them.
r"""Calculates the mean of tensor elements over a given axis (or axes).

Args:
inp: input tensor.
axis: dimension to reduce. If None, all dimensions will be reduced. Default: None
keepdims: whether the output tensor has axis retained or not. Default: False
inp: input tensor. Should have a numeric data type.
axis: axis or axes along which means must be computed.
By default, the mean must be computed over the entire tensor.
If a sequence of integers, means must be computed over multiple axes.
keepdims: if ``True``, the reduced axes (dimensions) must be included in the result as singleton dimensions,
and, accordingly, the result must be compatible with the input tensor (see :ref:`broadcasting-rule`).
Otherwise, if ``False``, the reduced axes (dimensions) must not be included in the result.

Returns:
output tensor.
if the mean was computed over the entire tensor, a zero-dimensional tensor containing the mean;
otherwise, a non-zero-dimensional tensor containing the means.
The returned tensor must have a data type determined by :ref:`dtype-promotion`.

.. admonition:: Special Cases

Let ``N`` equal the number of elements over which to compute the mean.

* If ``N`` is 0, the mean is ``NaN``.
* If :math:`x_i` is ``NaN``, the mean is ``NaN`` (i.e., ``NaN`` values propagate).

Examples:
>>> F.mean(Tensor([1, 2, 3]))
Tensor(2.0, device=xpux:0)

>>> import numpy as np
>>> x = Tensor(np.arange(1, 7, dtype=np.int32).reshape(2, 3))
>>> out = F.mean(x)
>>> out.numpy()
array(3.5, dtype=float32)
>>> F.mean(Tensor([1, np.nan, 3]))
Tensor(nan, device=xpux:0)

Along an axis:

>>> F.mean(Tensor([[1, 2, 3], [4, 5, 6]]), axis=0)
Tensor([2.5 3.5 4.5], device=xpux:0)
>>> F.mean(Tensor([[1, 2, 3], [4, 5, 6]]), axis=1)
Tensor([2. 5.], device=xpux:0)

"""
return inp.mean(axis=axis, keepdims=keepdims)

@@ -197,24 +287,36 @@ def var(
axis: Optional[Union[int, Sequence[int]]] = None,
keepdims: bool = False,
) -> Tensor:
r"""Returns the variance value of input tensor along
given axis. If axis is a list of dimensions,
reduce over all of them.
r"""Calculates the variance of tensor elements over a given axis (or axes).

Args:
inp: input tensor.
axis: dimension to reduce. If None, all dimensions will be reduced. Default: None
keepdims: whether the output tensor has axis retained or not. Default: False
inp: input tensor. Should have a numeric data type.
axis: axis or axes along which variances must be computed.
By default, the variance must be computed over the entire tensor.
If a sequence of integers, variances must be computed over multiple axes.
keepdims: if ``True``, the reduced axes (dimensions) must be included in the result as singleton dimensions,
and, accordingly, the result must be compatible with the input tensor (see :ref:`broadcasting-rule`).
Otherwise, if ``False``, the reduced axes (dimensions) must not be included in the result.

Returns:
output tensor.
if the variance was computed over the entire tensor, a zero-dimensional tensor containing the variance;
otherwise, a non-zero-dimensional tensor containing the variances.
The returned tensor must have a data type determined by :ref:`dtype-promotion`.

.. note::

The variance is the average of the squared deviations from the mean,
i.e., ``var = mean(x)``, where ``x = abs(a - a.mean())**2``.

Examples:
>>> import numpy as np
>>> data = Tensor(np.arange(1, 7, dtype=np.float32).reshape(2, 3))
>>> out = F.var(data)
>>> out.numpy().round(decimals=4)
2.9167
>>> x = Tensor([[1, 2], [3, 4]])
>>> F.var(x)
Tensor(1.25, device=xpux:0)

>>> x = Tensor([[14, 8, 11, 10], [7, 9, 10, 11], [10, 15, 5, 10]])
>>> F.var(x)
Tensor(6.8333335, device=xpux:0)

"""
if axis is None:
m = mean(inp, axis=axis, keepdims=False)
@@ -229,24 +331,35 @@ def std(
axis: Optional[Union[int, Sequence[int]]] = None,
keepdims: bool = False,
) -> Tensor:
r"""Returns the standard deviation of input tensor along
given axis. If axis is a list of dimensions,
reduce over all of them.
r"""Calculates the standard deviation of tensor elements over a given axis (or axes).

Args:
inp: input tensor.
axis: dimension to reduce. If None, all dimensions will be reduced. Default: None
keepdims: whether the output tensor has axis retained or not. Default: False
inp: input tensor. Should have a numeric data type.
axis: axis or axes along which standard deviations must be computed.
By default, the standard deviation must be computed over the entire tensor.
If a sequence of integers, standard deviations must be computed over multiple axes.
keepdims: if ``True``, the reduced axes (dimensions) must be included in the result as singleton dimensions,
and, accordingly, the result must be compatible with the input tensor (see :ref:`broadcasting-rule`).
Otherwise, if ``False``, the reduced axes (dimensions) must not be included in the result.

Returns:
output tensor.
if the standard deviation was computed over the entire tensor, a zero-dimensional tensor containing the standard deviation;
otherwise, a non-zero-dimensional tensor containing the standard deviations.

.. note::

The standard deviation is the square root of the average of the squared deviations from the mean,
i.e., ``std = sqrt(mean(x))``, where ``x = abs(a - a.mean())**2``.

Examples:
>>> import numpy as np
>>> data = Tensor(np.arange(1, 7, dtype=np.float32).reshape(2, 3))
>>> out = F.std(data, axis=1)
>>> out.numpy().round(decimals=4)
array([0.8165, 0.8165], dtype=float32)
>>> x = Tensor([[1, 2], [3, 4]])
>>> F.std(x)
Tensor(1.118034, device=xpux:0)

>>> x = Tensor([[14, 8, 11, 10], [7, 9, 10, 11], [10, 15, 5, 10]])
>>> F.std(x)
Tensor(2.6140645, device=xpux:0)
"""
return var(inp, axis=axis, keepdims=keepdims) ** 0.5

@@ -256,23 +369,38 @@ def min(
axis: Optional[Union[int, Sequence[int]]] = None,
keepdims: bool = False,
) -> Tensor:
r"""Returns the min value of input tensor along
given axis. If axis is a list of dimensions,
reduce over all of them.
r"""Calculates the minimum of tensor elements over a given axis (or axes).

Args:
inp: input tensor.
axis: dimension to reduce. If None, all dimensions will be reduced. Default: None
keepdims: whether the output tensor has axis retained or not. Default: False

inp: input tensor. Should have a numeric data type.
axis: axis or axes along which minimums must be computed.
By default, the minimum must be computed over the entire tensor.
If a sequence of integers, minimums must be computed over multiple axes.
keepdims: if ``True``, the reduced axes (dimensions) must be included in the result as singleton dimensions,
and, accordingly, the result must be compatible with the input tensor (see :ref:`broadcasting-rule`).
Otherwise, if ``False``, the reduced axes (dimensions) must not be included in the result.
Returns:
output tensor.
if the minimum was computed over the entire tensor, a zero-dimensional tensor containing the minimum;
otherwise, a non-zero-dimensional tensor containing the minimums.

.. admonition:: Special Cases

If :math:`x_i` is ``NaN``, the minimum is ``NaN`` (i.e., ``NaN`` values propagate).

Examples:
>>> import numpy as np
>>> x = Tensor(np.arange(1, 7, dtype=np.int32).reshape(2,3))
>>> x = Tensor([[1, 2], [3, 4]])
>>> F.min(x)
Tensor(1, dtype=int32, device=xpux:0)

Along an axis:

>>> F.min(x, axis=0)
Tensor([1 2], dtype=int32, device=xpux:0)
>>> F.min(x, axis=1)
Tensor([1 3], dtype=int32, device=xpux:0)

"""
return inp.min(axis=axis, keepdims=keepdims)

@@ -282,61 +410,42 @@ def max(
axis: Optional[Union[int, Sequence[int]]] = None,
keepdims: bool = False,
) -> Tensor:
r"""Returns the max value of the input tensor along
given axis. If axis is a list of dimensions,
reduce over all of them.
r"""Calculates the maximum of tensor elements over a given axis (or axes).

Args:
inp: input tensor.
axis: dimension to reduce. If None, all dimensions will be reduced. Default: None
keepdims: whether the output tensor has axis retained or not. Default: False
inp: input tensor. Should have a numeric data type.
axis: axis or axes along which maximums must be computed.
By default, the maximum must be computed over the entire tensor.
If a sequence of integers, maximums must be computed over multiple axes.
keepdims: if ``True``, the reduced axes (dimensions) must be included in the result as singleton dimensions,
and, accordingly, the result must be compatible with the input tensor (see :ref:`broadcasting-rule`).
Otherwise, if ``False``, the reduced axes (dimensions) must not be included in the result.

Returns:
output tensor.
if the maximum was computed over the entire tensor, a zero-dimensional tensor containing the maximum;
otherwise, a non-zero-dimensional tensor containing the maximums.

Examples:
>>> import numpy as np
>>> x = Tensor(np.arange(1, 7, dtype=np.int32).reshape(2,3))
>>> F.max(x)
Tensor(6, dtype=int32, device=xpux:0)
"""
return inp.max(axis=axis, keepdims=keepdims)
.. admonition:: Special Cases

If :math:`x_i` is ``NaN``, the maximum is ``NaN`` (i.e., ``NaN`` values propagate).

def norm(
inp: Tensor, ord: float = None, axis: int = None, keepdims=False,
):
r"""Calculates ``p``-norm of input tensor along
given axis.
Examples:

Args:
inp: input tensor.
ord: power of value applied to inp. Default: 2
axis: dimension to reduce. If None, input must be a vector. Default: None
keepdims: whether the output tensor has axis retained or not. Default: False
>>> x = Tensor([[1, 2], [3, 4]])
>>> F.max(x)
Tensor(4, dtype=int32, device=xpux:0)

Returns:
output tensor.
Along an axis:

Examples:
>>> import numpy as np
>>> x = Tensor(np.arange(-3, 3, dtype=np.float32))
>>> out = F.norm(x)
>>> out.numpy().round(decimals=4)
4.3589
>>> F.max(x, axis=0)
Tensor([3 4], dtype=int32, device=xpux:0)
>>> F.max(x, axis=1)
Tensor([2 4], dtype=int32, device=xpux:0)
"""
if axis is None:
if inp.ndim != 1:
raise TypeError("axis is required unless input is a vector")
if ord is None:
ord = 2
if ord == 0:
return sum(inp != 0, axis=axis, keepdims=keepdims)
if ord == math.inf:
return max(abs(inp))
if ord == -math.inf:
return min(abs(inp))
return sum(abs(inp) ** ord, axis=axis, keepdims=keepdims) ** (1.0 / ord)
return inp.max(axis=axis, keepdims=keepdims)


# searching functions


def argmin(
@@ -433,31 +542,7 @@ def argmax(
return result


def normalize(
inp: Tensor, ord: float = None, axis: int = None, eps: float = 1e-12,
) -> Tensor:
r"""Performs :math:`L_p` normalization of input tensor along
given axis.

For a tensor of shape :math:`(n_0, ..., n_{dim}, ..., n_k)`, each
:math:`n_{dim}` -element vector :math:`v` along dimension :attr:`axis` is transformed as:

.. math::
v = \frac{v}{\max(\lVert v \rVert_p, \epsilon)}.

Args:
inp: input tensor.
ord: power of value applied to input tensor. Default: 2
axis: dimension to reduce.If None, input must be a vector. Default: None
eps: a small value to avoid division by zero. Default: 1e-12

Returns:
normalized output tensor.
"""
if axis is None:
return inp / clip(norm(inp, ord, axis), lower=eps)
else:
return inp / clip(norm(inp, ord, axis, keepdims=True), lower=eps)
# sorting functions


def argsort(inp: Tensor, descending: bool = False) -> Tensor:
@@ -589,6 +674,9 @@ def topk(
return tns, ind


# linear algebra functions


def matinv(inp: Tensor) -> Tensor:
r"""Computes the inverse of a batch of matrices; input must has shape [..., n, n].

@@ -725,6 +813,109 @@ def svd(inp: Tensor, full_matrices=False, compute_uv=True) -> Tensor:
return U, S, Vh


def norm(
inp: Tensor, ord: float = None, axis: int = None, keepdims=False,
):
r"""Calculates the norm of tensor elements over a given axis.

This function is able to return different matrix norms,
or one of an infinite number of vector norms (described below), depending on the value of the ord parameter.

Args:
inp: input tensor. Should have a numeric data type.
ord: Order of the norm (see table under Notes). If not specified, the default is 2.
axis: Axis along which to compute vector norms.
If axis is an integer, it specifies the axis of inp along which to compute the vector norms.
keepdims: If this is set to ``True``,
the axes which are normed over are left in the result as dimensions with size one.

Returns:
Norm of the matrix or vector(s).

.. note::

Now the following norms can be calculated:

* inf: norm-:math:`\infty` (maximum of absolute values).
* -inf: norm-:math:`-\infty` (minimum of absolute values).
* 2: 2-norm (largest singluar value).

The Frobenius norm is given by to ``sum(abs(x)**ord)**(1./ord)``:

.. math::

\|A\|_F=\left[\sum_{i, j} a b s\left(a_{i, j}\right)^2\right]^{1 / 2}

.. seealso:: :func:`numpy.linalg.norm` / :func:`~.functional.normalize`

Examples:

>>> import math
>>> x = Tensor([1, 2, 3])
>>> F.norm(x, ord=math.inf)
Tensor(3, dtype=int32, device=xpux:0)
>>> F.norm(x, ord=-math.inf)
Tensor(1, dtype=int32, device=xpux:0)

>>> x = Tensor([[1, 2, 3], [4, 5, 6]])
>>> F.norm(x, ord=2, axis=0)
Tensor([4.1231 5.3852 6.7082], device=xpux:0)
>>> F.norm(x, ord=2, axis=1)
Tensor([3.7417 8.775 ], device=xpux:0)

"""
if axis is None:
if inp.ndim != 1:
raise TypeError("axis is required unless input is a vector")
if ord is None:
ord = 2
if ord == 0:
return sum(inp != 0, axis=axis, keepdims=keepdims)
if ord == math.inf:
return max(abs(inp))
if ord == -math.inf:
return min(abs(inp))
return sum(abs(inp) ** ord, axis=axis, keepdims=keepdims) ** (1.0 / ord)


def normalize(
inp: Tensor, ord: float = None, axis: int = None, eps: float = 1e-12,
) -> Tensor:
r"""Performs :math:`L_p` normalization of input tensor along given axis.

For a tensor of shape :math:`(n_0, ..., n_{dim}, ..., n_k)`,
each :math:`n_{dim}` -element vector :math:`v` along dimension :attr:`axis` is transformed as:

.. math::
v = \frac{v}{\max(\lVert v \rVert_p, \epsilon)}.

Args:
inp: input tensor.
ord: power of value applied to input tensor.
axis: dimension to reduce.If None, input must be a vector.
eps: a small value to avoid division by zero.

Returns:
normalized output tensor.

seealso:: :func:`numpy.linalg.norm` / :func:`~.functional.norm`

Examples:

>>> x = Tensor([[1, 2, 3], [4, 5, 6]])
>>> F.normalize(x, ord=2, axis=0)
Tensor([[0.2425 0.3714 0.4472]
[0.9701 0.9285 0.8944]], device=xpux:0)
>>> F.normalize(x, ord=2, axis=1)
Tensor([[0.2673 0.5345 0.8018]
[0.4558 0.5698 0.6838]], device=xpux:0)
"""
if axis is None:
return inp / clip(norm(inp, ord, axis), lower=eps)
else:
return inp / clip(norm(inp, ord, axis, keepdims=True), lower=eps)


def _check_non_finite(inps: Iterable[Tensor], scale=1.0) -> Tensor:
r"""Check whether input contains infinite or nan value.



+ 16
- 5
imperative/python/megengine/functional/tensor.py View File

@@ -1126,17 +1126,28 @@ def roll(


def cumsum(inp: Tensor, axis: int):
r"""Computes the cumulative sum of elements along given axis.
r"""Calculates the cumulative sum of tensor elements over a given axis.

Args:
inp: input tensor.
axis: axis along which cumsum is performed.
inp: input tensor. Should have a numeric data type.
axis: axis along which cumulative sums must be computed.

Returns:
a tensor containing the cumulative sums.

Examples:
>>> x = Tensor([[1, 2, 3], [4, 5, 6]], "int32")
>>> F.cumsum(x, 1)

If :math:`x_i` is ``NaN``, the cumulative sums is ``NaN`` (i.e., ``NaN`` values propagate).

Examples:
>>> x = Tensor([[1, 2, 3], [4, 5, 6]])
>>> F.cumsum(x, axis = 0)
Tensor([[1 2 3]
[5 7 9]], dtype=int32, device=xpux:0)
>>> F.cumsum(x, axis = 1)
Tensor([[ 1 3 6]
[ 4 9 15]], dtype=int32, device=xpux:0)

"""
assert isinstance(inp, Tensor), "input of cumsum must be type of Tensor"
op = builtin.Cumsum(axis=axis, exclusive=False, reverse=False)


Write Preview
Loading…
Cancel
Save