!26787 Add Chinese document for Tensor, RowTensor and SparseTensor

Merge pull request !26787 from LiangZhibo/code_docs_tensor

docs/api/api_python/mindspore/mindspore.RowTensor.rst

@@ -0,0 +1,51 @@
+mindspore.RowTensor
+===================
+
+.. py:class:: mindspore.RowTensor(indices, values, dense_shape)
+
+    用来表示一组指定索引的张量切片的稀疏表示。
+
+    通常用于表示一个有着形状为[L0, D1, .., DN]的更大的稠密张量（其中L0>>D0）的子集。
+
+    其中，参数`indices`用于指定`RowTensor`从该稠密张量的第一维度的哪些位置来进行切片。
+
+    由`RowTensor`切片表示的稠密张量具有以下属性： `dense[slices.indices[i], :, :, :, ...] = slices.values[i, :, :, :, ...]` 。
+
+    `RowTensor`只能在 `Cell` 的构造方法中使用。
+
+    目前不支持PyNative模式。
+
+    **参数：**
+
+        - **indices** (Tensor)：形状为[D0]的一维整数张量。
+        - **values** (Tensor)：形状为[D0, D1, ..., Dn]中任意类型的张量。
+        - **dense_shape** (tuple(int))：包含相应稠密张量形状的整数元组。
+
+    **返回：**
+
+        RowTensor，由 `indices` 、 `values` 和 `dense_shape` 组成。
+
+    **样例：**
+
+        .. code-block::
+
+            >>> import mindspore as ms
+            >>> import mindspore.nn as nn
+            >>> from mindspore import RowTensor
+            >>> class Net(nn.Cell):
+            ...     def __init__(self, dense_shape)：
+            ...         super(Net, self).__init__()
+            ...         self.dense_shape = dense_shape
+            ...     def construct(self, indices, values)：
+            ...         x = RowTensor(indices, values, self.dense_shape)
+            ...         return x.values, x.indices, x.dense_shape
+            >>>
+            >>> indices = Tensor([0])
+            >>> values = Tensor([[1, 2]], dtype=ms.float32)
+            >>> out = Net((3, 2))(indices, values)
+            >>> print(out[0])
+            [[1.2.]]
+            >>> print(out[1])
+            [0]
+            >>> print(out[2])
+            (3, 2)

docs/api/api_python/mindspore/mindspore.SparseTensor.rst

@@ -0,0 +1,48 @@
+mindspore.SparseTensor
+======================
+
+.. py:class:: mindspore.SparseTensor(indices, values, dense_shape)
+
+    用来表示某一张量在给定索引上非零元素的集合。
+
+    `SparseTensor`只能在 `Cell` 的构造方法中使用。
+
+    目前不支持PyNative模式。
+
+    对于稠密张量，其`SparseTensor(indices, values, dense_shape)`具有 `dense[indices[i]] = values[i]` 。
+
+    **参数：**
+
+        - **indices** (Tensor)：形状为 `[N, ndims]` 的二维整数张量，其中N和ndims分别表示稀疏张量中 `values` 的数量和SparseTensor维度的数量。
+        - **values** (Tensor)：形状为[N]的一维张量，其内部可以为任何数据类型，用来给 `indices` 中的每个元素提供数值。
+        - **dense_shape** (tuple(int))：形状为ndims的整数元组，用来指定稀疏矩阵的稠密形状。
+
+    **返回：**
+
+        SparseTensor，由 `indices` 、 `values` 和 `dense_shape` 组成。
+
+    **样例：**
+
+        .. code-block::
+
+            >>> import mindspore as ms
+            >>> import mindspore.nn as nn
+            >>> from mindspore import SparseTensor
+            >>> class Net(nn.Cell)：
+            ...     def __init__(self, dense_shape)：
+            ...         super(Net, self).__init__()
+            ...         self.dense_shape = dense_shape
+            ...     def construct(self, indices, values)：
+            ...         x = SparseTensor(indices, values, self.dense_shape)
+            ...         return x.values, x.indices, x.dense_shape
+            >>>
+            >>> indices = Tensor([[0, 1], [1, 2]])
+            >>> values = Tensor([1, 2], dtype=ms.float32)
+            >>> out = Net((3, 4))(indices, values)
+            >>> print(out[0])
+            [1.2.]
+            >>> print(out[1])
+            [[0 1]
+            [1 2]]
+            >>> print(out[2])
+            (3, 4)

docs/api/api_python/mindspore/mindspore.Tensor.rst

@@ -0,0 +1,188 @@
+mindspore.Tensor
+================
+
+.. py:class:: mindspore.Tensor(input_data=None, dtype=None, shape=None, init=None)
+
+    用来存储数据。 继承自C++中的`Tensor`对象。有些函数是用C++实现的，有些函数是用Python实现的。
+
+    **参数：**
+
+        - **input_data** (Union[Tensor, float, int, bool, tuple, list, numpy.ndarray])：张量的输入数据。
+        - **dtype** (:class:`mindspore.dtype`)：输入数据应是在 `mindspore.dtype` 中定义的None、bool或numeric类型。该参数用于定义输出张量的数据类型。如果值为None，则输出张量的数据类型与 `input_data` 的相同。默认值：None。
+        - **shape** (Union[tuple, list, int])：用来表示张量的形状，可以是整数列表、整数元组或单一整数。如果 `input_data` 已经被设置，则不需要再设置 `shape` 。默认值：None。
+        - **init** (Initializer)：用来表示初始化数据的信息。init用于在并行模式下的延迟初始化。一般情况下，不建议在其他条件下使用init接口来初始化参数。如果使用init接口来初始化参数，需要调用 `Tensor.init_data` 接口把 `Tensor` 转换为实际数据。
+
+    **返回：**
+
+        Tensor。如果未设置 `dtype` 和 `shape` ，返回与 `input_data` 具有相同数据类型和形状的张量。如果设置了 `dtype` 或 `shape` ，则输出的张量的数据类型或形状与设置的相同。
+
+    **样例：**
+
+        .. code-block::
+
+            >>> import numpy as np
+            >>> import mindspore as ms
+            >>> from mindspore import Tensor
+            >>> from mindspore.common.initializer import One
+            >>> # 用numpy.ndarray初始化张量
+            >>> t1 = Tensor(np.zeros([1, 2, 3]), ms.float32)
+            >>> assert isinstance(t1, Tensor)
+            >>> assert t1.shape == (1, 2, 3)
+            >>> assert t1.dtype == ms.float32
+            >>>
+            >>> # 用float标量初始化张量
+            >>> t2 = Tensor(0.1)
+            >>> assert isinstance(t2, Tensor)
+            >>> assert t2.dtype == ms.float64
+            ...
+            >>> # 用init初始化张量
+            >>> t3 = Tensor(shape = (1, 3), dtype=ms.float32, init=One())
+            >>> assert isinstance(t3, Tensor)
+            >>> assert t3.shape == (1, 3)
+            >>> assert t3.dtype == ms.float32
+
+    .. py:method:: T
+        :property:
+
+        返回转置后的张量。
+
+
+    .. py:method:: abs()
+
+        返回每个元素的绝对值。
+
+        **返回：**
+
+            张量， 含有每个元素的绝对值。
+
+        **支持平台：**
+
+            ``Ascend`` ``GPU`` ``CPU``
+
+        **样例：**
+
+            .. code-block::
+
+                >>> from mindspore import Tensor
+                >>> a = Tensor([1.1, -2.1]).astype("float32")
+                >>> output = a.abs()
+                >>> print(output)
+                [1.1 2.1]
+
+
+    .. py:method:: all(axis=(), keep_dims=False)
+
+        检查在指定轴上所有元素是否均为True。
+
+        **参数：**
+
+            - **axis** (Union[None, int, tuple(int))：被简化的维度。 当`axis`为None或者空元组的时候，简化所有维度。 默认值：()。
+            - **keep_dims** (bool)：是否会保留被简化的维度。 默认值： False。
+
+        **返回：**
+
+            Tensor。如果在指定轴方向上所有数组元素都为True，则其值为True，否则其值为False。如果轴为None或空元组，则简化所有维度。
+
+        **支持平台：**
+
+            ``Ascend`` ``GPU`` ``CPU``
+
+        **样例：**
+
+            .. code-block::
+
+                >>> from mindspore import Tensor
+                >>> a = Tensor([True, True, False])
+                >>> output = a.all()
+                >>> print(output)
+                False
+
+    .. py:method:: any(axis=(), keep_dims=False)
+
+        检查在指定轴方向上是否存在任意为True的数组元素。
+
+        **参数：**
+
+            - **axis** (Union[None, int, tuple(int))：简化的维度。当轴为None或空元组时，简化所有维度。默认值：()。
+            - **keep_dims** (bool)：表示是否保留简化后的维度。默认值：False。
+
+        **返回：**
+
+            Tensor。如果在指定轴方向上所有数组元素都为True，则其值为True，否则其值为False。如果轴为None或空元组，则简化所有维度。
+
+        **支持平台：**
+
+            ``Ascend`` ``GPU`` ``CPU``
+
+        **样例：**
+
+            .. code-block::
+
+                >>> from mindspore import Tensor
+                >>> a = Tensor([True, True, False])
+                >>> output = a.any()
+                >>> print(output)
+                True
+
+    .. py:method:: asnumpy()
+
+        将张量转换为NumPy数组。
+
+    .. py:method:: dtype
+        :property:
+
+        返回张量的数据类型（:class:`mindspore.dtype`）。
+
+    .. py:method:: expand_as(x)
+
+        将目标张量的维度扩展为输入张量的维度。
+
+        **参数：**
+
+            - **x** (Tensor)：输入的张量。该张量的形状必须遵守广播规则。
+
+        **返回：**
+
+            Tensor，维度与输入张量的相同。
+
+    .. py:method:: from_numpy(array)
+        :static:
+
+        将NumPy数组转换为张量，且不需要复制数据。
+
+        **参数：**
+
+            array (numpy.array)：输入数组。
+
+        **返回：**
+
+            Tensor，与输入的张量具有相同的数据类型。
+
+
+    .. py:method:: mean(axis=(), keep_dims=False)
+
+        通过计算出维度中的所有元素的平均值来简化张量的维度。
+
+        **参数：**
+
+            - **axis** (Union[None, int, tuple(int), list(int)])：简化的维度。当轴为None或空元组时，简化所有维度。默认值：()。
+            - **keep_dims** (bool)：表示是否保留简化后的维度。默认值：False。
+
+        **返回：**
+
+            Tensor，与输入的张量具有相同的数据类型。
+
+        **支持平台：**
+
+            ``Ascend`` ``GPU`` ``CPU``
+
+        **样例：**
+
+            .. code-block::
+
+                >>> import numpy as np
+                >>> from mindspore import Tensor
+                >>> input_x = Tensor(np.array([1, 2, 3], dtype=np.float32))
+                >>> output = input_x.mean()
+                >>> print(output)
+                2.0