From 7d3a6db0efd8dd421c2f23a363bc804feffd5fd9 Mon Sep 17 00:00:00 2001 From: Megvii Engine Team Date: Fri, 25 Feb 2022 17:01:15 +0800 Subject: [PATCH] docs(tensor): add more introduction about Tensor GitOrigin-RevId: 4eba1e6c03a639fe91670619024805099d49ef66 --- .../megengine/core/tensor/array_method.py | 155 +----------------- imperative/python/megengine/tensor.py | 36 +++- 2 files changed, 37 insertions(+), 154 deletions(-) diff --git a/imperative/python/megengine/core/tensor/array_method.py b/imperative/python/megengine/core/tensor/array_method.py index b37a085e4..3285fd6ee 100644 --- a/imperative/python/megengine/core/tensor/array_method.py +++ b/imperative/python/megengine/core/tensor/array_method.py @@ -614,166 +614,21 @@ class ArrayMethodMixin(abc.ABC): return reshape_cpp(self, (-1,)) def sum(self, axis=None, keepdims: bool = False): - r"""Returns the sum of each row of the input tensor in the given dimension ``axis``. - - If ``axis`` is a list of axises, reduce over all of them. - If ``keepdims`` is ``True``, the shape of output tensor is the same as the input tensor, - except in the dimension(s) ``axis`` where it is of size 1. - Otherwise, ``axis`` is squeezed (see :func:`~.squeeze`). - - Args: - axis: the dimension or dimensions to reduce. - keepdims: whether the output tensor has ndim retained or not. - - Returns: - output tensor. - - Examples: - .. testcode:: - - from megengine import tensor - a = tensor([False, True, True, False]) - b = tensor([1.0, 2.0, 3.0, 4.0]) - print(a.sum().numpy()) - print(b.sum().numpy()) - - Outputs: - - .. testoutput:: - - 2 - 10.0 - """ + r"""See :func:`~.sum`.""" return _reduce("sum")(self, axis, keepdims) def prod(self, axis=None, keepdims: bool = False): - r"""Returns the product of each row of the input tensor in the given dimension ``axis``. - - If ``axis`` is a list of axises, reduce over all of them. - If ``keepdims`` is ``True``, the shape of output tensor is the same as the input tensor, - except in the dimension(s) ``axis`` where it is of size 1. - Otherwise, ``axis`` is squeezed (see :func:`~.squeeze`). - - Args: - axis: the dimension or dimensions to reduce. - keepdims: whether the output tensor has ndim retained or not. - - Returns: - output tensor. - - Examples: - .. testcode:: - - from megengine import tensor - a = tensor([False, True, True, False]) - b = tensor([1.0, 2.0, 3.0, 4.0]) - print(a.prod().numpy()) - print(b.prod().numpy()) - - Outputs: - - .. testoutput:: - - 0 - 24.0 - """ + r"""See :func:`~.prod`.""" return _reduce("product")(self, axis, keepdims) def min(self, axis=None, keepdims: bool = False): - r"""Returns the min value of each row of the input tensor in the given dimension ``axis``. - - If ``axis`` is a list of axises, reduce over all of them. - If ``keepdims`` is ``True``, the shape of output tensor is the same as the input tensor, - except in the dimension(s) ``axis`` where it is of size 1. - Otherwise, ``axis`` is squeezed (see :func:`~.squeeze`). - - Args: - axis: the dimension or dimensions to reduce. - keepdims: whether the output tensor has ndim retained or not. - - Returns: - output tensor. - - Examples: - .. testcode:: - - from megengine import tensor - a = tensor([False, True, True, False]) - b = tensor([1.0, 2.0, 3.0, 4.0]) - print(a.min().numpy()) - print(b.min().numpy()) - - Outputs: - - .. testoutput:: - - False - 1.0 - """ + r"""See :func:`~.min`.""" return _reduce("min")(self, axis, keepdims) def max(self, axis=None, keepdims: bool = False): - r"""Returns the max value of each row of the input tensor in the given dimension ``axis``. - - If ``axis`` is a list of axises, reduce over all of them. - If ``keepdims`` is ``True``, the shape of output tensor is the same as the input tensor, - except in the dimension(s) ``axis`` where it is of size 1. - Otherwise, ``axis`` is squeezed (see :func:`~.squeeze`). - - Args: - axis: the dimension or dimensions to reduce. - keepdims: whether the output tensor has ndim retained or not. - - Returns: - output tensor. - - Examples: - .. testcode:: - - from megengine import tensor - a = tensor([False, True, True, False]) - b = tensor([1.0, 2.0, 3.0, 4.0]) - print(a.max().numpy()) - print(b.max().numpy()) - - Outputs: - - .. testoutput:: - - True - 4.0 - """ + r"""See :func:`~.max`.""" return _reduce("max")(self, axis, keepdims) def mean(self, axis=None, keepdims: bool = False): - r"""Returns the mean value of each row of the input tensor in the given dimension ``axis``. - - If ``axis`` is a list of axises, reduce over all of them. - If ``keepdims`` is ``True``, the shape of output tensor is the same as the input tensor, - except in the dimension(s) ``axis`` where it is of size 1. - Otherwise, ``axis`` is squeezed (see :func:`~.squeeze`). - - Args: - axis: the dimension or dimensions to reduce. - keepdims: whether the output tensor has ndim retained or not. - - Returns: - output tensor. - - Examples: - .. testcode:: - - from megengine import tensor - a = tensor([False, True, True, False]) - b = tensor([1.0, 2.0, 3.0, 4.0]) - print(a.mean().numpy()) - print(b.mean().numpy()) - - Outputs: - - .. testoutput:: - - 0.5 - 2.5 - """ + r"""See :func:`~.mean`.""" return _reduce("mean")(self, axis, keepdims) diff --git a/imperative/python/megengine/tensor.py b/imperative/python/megengine/tensor.py index 9c060ac86..33daff406 100644 --- a/imperative/python/megengine/tensor.py +++ b/imperative/python/megengine/tensor.py @@ -27,13 +27,41 @@ logger = get_logger(__name__) class Tensor(_Tensor, ArrayMethodMixin): r"""A tensor object represents a multidimensional, homogeneous array of fixed-size items. + Tensor is the primary MegEngine data structure. + Data type(dtype) describes the format of each element, such as ``float32``, ``int8`` and so on, + see :ref:`tensor-dtype` for more details. + It is similar to :class:`numpy.ndarray` but not the same in the design. + For example, GPU devices can be used to store Tensors and execute calculations in MegEngine. + The concept of `view `_ + does not exist in MegEngine so indexing and other behaviors might be different with NumPy. + All manipulations and operations on/between Tensors could be found in the :mod:`~.megengine.functional` module. + Keep in mind that they are **not in-place**, a new Tensor will always be returned and + the original data will remain constant. + + For more information, refer to the :ref:`tensor-guide` topic. + Args: - data(Tensor, :class:`~.numpy.ndarray`, :class:`list` or python number.): The value of returned Tensor. - dtype: The dtype of returned Tensor. Uses data's dtype if not specified. - device: The desired device of returned Tensor. Uses :func:`get_default_device` if not specified. - is_const: Whether make it a ``ImutableTensor`` in tracing mode. + data(Tensor, :class:`~.numpy.ndarray`, :class:`list` or Python number): + The data used for construcing Tensor. + Tensor could be constructed from a Python :class:`list` / :class:`tuple` or sequence; + a NumPy :class:`~.numpy.ndarray` data structure; MegEngine builtin methods and so on. + Refer to :ref:`tensor-creation` for more details. + + dtype(:attr:`~.Tensor.dtype`): The data type of returned Tensor. Infer from ``data`` if not specified. + device(:attr:`~.Tensor.device`): The desired device of returned Tensor. Uses :func:`get_default_device` if not specified. + is_const: Whether make it a ``ImutableTensor`` in tracing mode, refer to :class:`.jit.trace`. no_cache: Whether cache it for memory sharing. name: Used to improve convenience in graph operation on dumped model. + + .. note:: + + There are some methods like :meth:`~.Tensor.reshape` / :meth:`~.Tensor.flatten` / + :meth:`~.Tensor.transpose` / :meth:`~.Tensor.min` / :meth:`~.Tensor.max` / + :meth:`~.Tensor.mean` / :meth:`~.Tensor.sum` / :meth:`~.Tensor.prod` implemented + in ``Tensor`` class for convenience and historical reasons. + But other methods implemented in the :mod:`~.megengine.functional` module will not be added here anymore, + it is hard for maintaining and too many candidates will affect code completion experience. + """ grad = None -- GitLab