{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tensor\n",
    "\n",
    "`Ascend` `GPU` `CPU` `入门`\n",
    "\n",
    "[![在线运行](https://gitee.com/mindspore/docs/raw/r1.6/resource/_static/logo_modelarts.png)](https://authoring-modelarts-cnnorth4.huaweicloud.com/console/lab?share-url-b64=aHR0cHM6Ly9taW5kc3BvcmUtd2Vic2l0ZS5vYnMuY24tbm9ydGgtNC5teWh1YXdlaWNsb3VkLmNvbS9ub3RlYm9vay9tb2RlbGFydHMvcHJvZ3JhbW1pbmdfZ3VpZGUvbWluZHNwb3JlX3RlbnNvci5pcHluYg==&imageid=65f636a0-56cf-49df-b941-7d2a07ba8c8c) [![下载Notebook](https://gitee.com/mindspore/docs/raw/r1.6/resource/_static/logo_notebook.png)](https://obs.dualstack.cn-north-4.myhuaweicloud.com/mindspore-website/notebook/r1.6/programming_guide/zh_cn/mindspore_tensor.ipynb) [![下载样例代码](https://gitee.com/mindspore/docs/raw/r1.6/resource/_static/logo_download_code.png)](https://obs.dualstack.cn-north-4.myhuaweicloud.com/mindspore-website/notebook/r1.6/programming_guide/zh_cn/mindspore_tensor.py) [![查看源文件](https://gitee.com/mindspore/docs/raw/r1.6/resource/_static/logo_source.png)](https://gitee.com/mindspore/docs/blob/r1.6/docs/mindspore/programming_guide/source_zh_cn/tensor.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 概述\n",
    "\n",
    "张量（Tensor）是MindSpore网络运算中的基本数据结构。张量中的数据类型可参考[dtype](https://www.mindspore.cn/docs/programming_guide/zh-CN/r1.6/dtype.html)。\n",
    "\n",
    "不同维度的张量分别表示不同的数据，0维张量表示标量，1维张量表示向量，2维张量表示矩阵，3维张量可以表示彩色图像的RGB三通道等等。\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 张量构造\n",
    "\n",
    "构造张量时，支持传入`Tensor`、`float`、`int`、`bool`、`tuple`、`list`、`complex`、`numpy.array`和`numpy.str`类型，其中`tuple`和`list`里只能存放`float`、`int`、`bool`、`complex`类型数据， 其中`complex`表示复数数据类型，其中`numpy.str`仅支持数据透传使用，不支持在算子侧运行。\n",
    "\n",
    "`Tensor`初始化时，可指定dtype。如果没有指定dtype，初始值`int`、`float`、`bool`、`complex`分别生成数据类型为`mindspore.int32`、`mindspore.float64`、`mindspore.bool_`、`mindspore.complex128`的0维Tensor，\n",
    "初始值`tuple`和`list`生成的1维`Tensor`数据类型与`tuple`和`list`里存放的数据类型相对应，如果包含多种不同类型的数据，则按照优先级：`bool` < `int` < `float` < `complex`，选择相对优先级最高类型所对应的mindspore数据类型。\n",
    "如果初始值是`Tensor`，则生成的`Tensor`数据类型与其一致；如果初始值是`NumPy.array`，则生成的`Tensor`数据类型与之对应。\n",
    "\n",
    "代码样例如下："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-02-03T02:59:50.340750Z",
     "start_time": "2021-02-03T02:59:49.571048Z"
    },
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[1 2]\n",
      " [3 4]] \n",
      "\n",
      " 1 \n",
      "\n",
      " 2 \n",
      "\n",
      " True \n",
      "\n",
      " [1 2 3] \n",
      "\n",
      " [4. 5. 6.] \n",
      "\n",
      " [4. 5. 6.]\n"
     ]
    }
   ],
   "source": [
    "import numpy as np\n",
    "from mindspore import Tensor\n",
    "from mindspore import dtype as mstype\n",
    "\n",
    "x = Tensor(np.array([[1, 2], [3, 4]]), mstype.int32)\n",
    "y = Tensor(1.0, mstype.int32)\n",
    "z = Tensor(2, mstype.int32)\n",
    "m = Tensor(True, mstype.bool_)\n",
    "n = Tensor((1, 2, 3), mstype.int16)\n",
    "p = Tensor([4.0, 5.0, 6.0], mstype.float64)\n",
    "q = Tensor(p, mstype.float64)\n",
    "\n",
    "print(x, \"\\n\\n\", y, \"\\n\\n\", z, \"\\n\\n\", m, \"\\n\\n\", n, \"\\n\\n\", p, \"\\n\\n\", q)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 张量的运算、属性和方法"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 运算\n",
    "\n",
    "张量支持多种操作符运算，包括算术运算、逻辑运算等。当不同形状的两个数组进行运算时，提供与`Numpy`相似的`broadcast`广播机制。以下是一些常用运算操作符：\n",
    "\n",
    "- 算术运算：加（`+`）、减（`-`）、乘（`*`）、除（`/`）、取模（`%`）、幂次方（`**`）、整除（`//`）\n",
    "\n",
    "- 逻辑运算：等于（`==`）、不等于（`!=`）、大于（`>`）、大于等于（`>=`）、小于（`<`）、小于等于（`<=`）\n",
    "\n",
    "代码样例如下："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-02-03T02:59:50.347520Z",
     "start_time": "2021-02-03T02:59:50.342826Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "add: [5. 7. 9.]\n",
      "sub: [-3. -3. -3.]\n",
      "mul: [ 4. 10. 18.]\n",
      "div: [4. 2.5 2. ]\n",
      "mod: [1. 2. 3.]\n",
      "pow: [1. 4. 9.]\n",
      "floordiv: [4. 2. 2.]\n",
      "equal: [False True False]\n",
      "not equal: [ True False True]\n",
      "greater than: [ True False False]\n",
      "greater or equal: [ True True False]\n",
      "less than: [False False True]\n",
      "less or equal: [False True True]\n"
     ]
    }
   ],
   "source": [
    "import numpy as np\n",
    "from mindspore import Tensor\n",
    "from mindspore import dtype as mstype\n",
    "\n",
    "x = Tensor(np.array([1, 2, 3]), mstype.float32)\n",
    "y = Tensor(np.array([4, 5, 6]), mstype.float32)\n",
    "output_add = x + y\n",
    "output_sub = x - y\n",
    "output_mul = x * y\n",
    "output_div = y / x\n",
    "output_mod = x % y\n",
    "output_pow = x ** 2\n",
    "output_floordiv = y // x\n",
    "print(\"add:\", output_add)\n",
    "print(\"sub:\", output_sub)\n",
    "print(\"mul:\", output_mul)\n",
    "print(\"div:\", output_div)\n",
    "print(\"mod:\", output_mod)\n",
    "print(\"pow:\", output_pow)\n",
    "print(\"floordiv:\", output_floordiv)\n",
    "\n",
    "a = Tensor(np.array([2, 2, 2]), mstype.int32)\n",
    "b = Tensor(np.array([1, 2, 3]), mstype.int32)\n",
    "output_eq = a == b\n",
    "output_ne = a != b\n",
    "output_gt = a > b\n",
    "output_gq = a >= b\n",
    "output_lt = a < b\n",
    "output_lq = a <= b\n",
    "print(\"equal:\", output_eq)\n",
    "print(\"not equal:\", output_ne)\n",
    "print(\"greater than:\", output_gt)\n",
    "print(\"greater or equal:\", output_gq)\n",
    "print(\"less than:\", output_lt)\n",
    "print(\"less or equal:\", output_lq)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 属性\n",
    "\n",
    "张量的属性包括形状、数据类型、转置张量、单个元素大小、占用字节数量、维数、元素个数、每一维步长。\n",
    "\n",
    "- 形状（shape）：`Tensor`的shape，是一个tuple。\n",
    "\n",
    "- 数据类型（dtype）：`Tensor`的dtype，是MindSpore的一个数据类型。\n",
    "\n",
    "- 转置张量（T）：`Tensor`的转置，也是一个`Tensor`。\n",
    "\n",
    "- 单个元素大小（itemsize）： `Tensor`中每一个元素占用字节数，是一个整数。\n",
    "\n",
    "- 占用字节数量（nbytes）： `Tensor`占用的总字节数，是一个整数。\n",
    "\n",
    "- 维数（ndim）： `Tensor`的秩，也就是len(tensor.shape)，是一个整数。\n",
    "\n",
    "- 元素个数（size）： `Tensor`中所有元素的个数，是一个整数。\n",
    "\n",
    "- 每一维步长（strides）： `Tensor`中每一维中进行遍历所需要经过的字节数。\n",
    "\n",
    "代码样例如下："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-02-03T02:59:50.347520Z",
     "start_time": "2021-02-03T02:59:50.342826Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "x_shape: (2, 2)\n",
      "x_dtype: Int32\n",
      "x_transposed: [[1 3]\n",
      " [2 4]]\n",
      "x_itemsize: 4\n",
      "x_nbytes: 16\n",
      "x_ndim: 2\n",
      "x_size: 4\n",
      "x_strides: (8, 4)\n"
     ]
    }
   ],
   "source": [
    "import numpy as np\n",
    "from mindspore import Tensor\n",
    "from mindspore import dtype as mstype\n",
    "\n",
    "x = Tensor(np.array([[1, 2], [3, 4]]), mstype.int32)\n",
    "x_shape = x.shape\n",
    "x_dtype = x.dtype\n",
    "x_transposed = x.T\n",
    "x_itemsize = x.itemsize\n",
    "x_nbytes = x.nbytes\n",
    "x_ndim = x.ndim\n",
    "x_size = x.size\n",
    "x_strides = x.strides\n",
    "print(\"x_shape:\", x_shape)\n",
    "print(\"x_dtype:\", x_dtype)\n",
    "print(\"x_transposed:\", x_transposed)\n",
    "print(\"x_itemsize:\", x_itemsize)\n",
    "print(\"x_nbytes:\", x_nbytes)\n",
    "print(\"x_ndim:\", x_ndim)\n",
    "print(\"x_size:\", x_size)\n",
    "print(\"x_strides:\", x_strides)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 方法\n",
    "\n",
    "张量的方法包括`len`、`str`、`repr`、`hash`、`all`、`any`和`asnumpy`等，我们同时提供了与`Numpy`的`ndarray`使用方式类似的Tensor方法来提升用户体验。详细的方法列表，使用方式以及支持后端请参考[Tensor类方法API](https://www.mindspore.cn/docs/api/zh-CN/r1.6/api_python/mindspore/mindspore.Tensor.html)，以下是一些类方法的简单介绍：\n",
    "\n",
    "- `len()`：返回张量的长度。\n",
    "\n",
    "- `str()`：返回张量的字符串表达。\n",
    "\n",
    "- `repr()`：返回张量的字符串表达，供解释器读取。\n",
    "\n",
    "- `hash()`：获取张量的哈希值。\n",
    "\n",
    "- `all(axis, keep_dims)`：在指定维度上通过`and`操作进行归约，`axis`代表归约维度，`keep_dims`表示是否保留归约后的维度。\n",
    "\n",
    "- `any(axis, keep_dims)`：在指定维度上通过`or`操作进行归约，参数含义同`all`。\n",
    "\n",
    "- `asnumpy()`：将`Tensor`转换为`NumPy`的`array`。\n",
    "\n",
    "- `sum(axis, dtype, keepdims, initial)`: 在指定维度上对张量进行归约求和，`axis`代表归约维度，`dtype`代表输出的数据的类型，`keepdims`表示是否保留归约后的维度, `initial`表示规约求和开始前的初始值。\n",
    "\n",
    "代码样例如下："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-02-03T02:59:50.374128Z",
     "start_time": "2021-02-03T02:59:50.349665Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "t_len: 3\n",
      "t_str: [1 2 3]\n",
      "t_repr: Tensor(shape=[3], dtype=Int32, value= [1, 2, 3])\n",
      "t_hash: 281470264268272\n",
      "x_all: False\n",
      "x_any: True\n",
      "x_array: [[ True  True]\n",
      " [False False]]\n",
      "y_sum_tensor: 10.0\n",
      "y_sum_mnp: 10.0\n"
     ]
    }
   ],
   "source": [
    "import numpy as np\n",
    "from mindspore import Tensor\n",
    "from mindspore import dtype as mstype\n",
    "\n",
    "t = Tensor(np.array([1, 2, 3]), mstype.int32)\n",
    "t_len = len(t)\n",
    "t_str = str(t)\n",
    "t_repr = repr(t)\n",
    "t_hash = hash(t)\n",
    "print(\"t_len:\", t_len)\n",
    "print(\"t_str:\", t_str)\n",
    "print(\"t_repr:\", t_repr)\n",
    "print(\"t_hash:\", t_hash)\n",
    "\n",
    "x = Tensor(np.array([[True, True], [False, False]]), mstype.bool_)\n",
    "x_all = x.all()\n",
    "x_any = x.any()\n",
    "x_array = x.asnumpy()\n",
    "print(\"x_all:\", x_all)\n",
    "print(\"x_any:\", x_any)\n",
    "print(\"x_array:\", x_array)\n",
    "\n",
    "import mindspore.numpy as mnp\n",
    "y = Tensor(np.array([[1., 2.], [3., 4.]]), mstype.float32)\n",
    "# y.sum() and mindspore.numpy.sum(y) are equivalent methods\n",
    "y_sum_tensor = y.sum()\n",
    "y_sum_mnp = mnp.sum(y)\n",
    "print(\"y_sum_tensor:\", y_sum_tensor)\n",
    "print(\"y_sum_mnp:\", y_sum_mnp)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 稀疏张量\n",
    "\n",
    "稀疏张量是一种特殊张量，其中绝大部分元素的值为零。在某些应用场景中（比如推荐系统），数据的特征是稀疏的，若使用普通张量表征这些数据会引入大量不必要的计算、存储和通讯开销。在这种时候就可以使用稀疏张量来表征这些数据。\n",
    "\n",
    "常用稀疏张量的表达形式是`<indices:Tensor, values:Tensor, dense_shape:Tensor>`。其中，`indices`表示非零下标元素， `values`表示非零元素的值，dense_shape表示的是被压缩的稀疏张量的形状。 在这个结构下，我们定义了`RowTensor`和`SparseTensor`两种稀疏张量结构。\n",
    "\n",
    "> PyNative模式暂不支持稀疏张量。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### RowTensor\n",
    "\n",
    "`RowTensor`用于压缩第零个维度稀疏的张量。若`RowTensor`的维度为`[L0, D1, D2, ..., DN ]`。第零维度的非零元素个数为`D0`, 则有`L0 >> D0`。\n",
    "\n",
    "- `indices`: 一维整数张量，表示稀疏张量第零维度中非零元素的位置。形状：`[D0]`\n",
    "\n",
    "- `values`: 表示相对应的非零元素的值。形状：`[D0, D1, D2, ..., DN]`\n",
    "\n",
    "- `dense_shape`: 表示的是被压缩的稀疏张量的形状。\n",
    "\n",
    "`RowTensor`只能在`Cell`的构造方法中使用。详细内容，请参考[mindspore.RowTensor](https://www.mindspore.cn/docs/api/zh-CN/r1.6/api_python/mindspore/mindspore.RowTensor.html)。代码样例如下："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[1. 2.]]\n",
      "[0]\n",
      "(3, 2)"
     ]
    }
   ],
   "source": [
    "import mindspore as ms\n",
    "import mindspore.nn as nn\n",
    "from mindspore import Tensor\n",
    "from mindspore import RowTensor\n",
    "\n",
    "class Net(nn.Cell):\n",
    "    def __init__(self, dense_shape):\n",
    "        super(Net, self).__init__()\n",
    "        self.dense_shape = dense_shape\n",
    "    def construct(self, indices, values):\n",
    "        x = RowTensor(indices, values, self.dense_shape)\n",
    "        return x.values, x.indices, x.dense_shape\n",
    "\n",
    "indices = Tensor([0])\n",
    "values = Tensor([[1, 2]], dtype=ms.float32)\n",
    "out = Net((3, 2))(indices, values)\n",
    "print(out[0])\n",
    "print(out[1])\n",
    "print(out[2])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### SparseTensor\n",
    "\n",
    "`SparseTensor`用于压缩非零元素位置分布不规则的Tensor，若非零元素的个数为`N`，被压缩的张量的维数为`ndims`，则有：\n",
    "\n",
    "- `indices`: 二维整数张量，每行代表非零元素下标。形状：`[N, ndims]`\n",
    "\n",
    "- `values`: 一维张量，表示相对应的非零元素的值。形状：`[N]`\n",
    "\n",
    "- `dense_shape`: 表示的是被压缩的稀疏张量的形状。\n",
    "\n",
    "`SparseTensor`只能在`Cell`的构造方法中使用。详细内容，请参考[mindspore.SparseTensor](https://www.mindspore.cn/docs/api/zh-CN/r1.6/api_python/mindspore/mindspore.SparseTensor.html)。代码样例如下："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1. 2.]\n",
      "[[0 1]\n",
      " [1 2]]\n",
      "(3, 4)"
     ]
    }
   ],
   "source": [
    "import mindspore as ms\n",
    "import mindspore.nn as nn\n",
    "from mindspore import Tensor\n",
    "from mindspore import SparseTensor\n",
    "\n",
    "class Net(nn.Cell):\n",
    "    def __init__(self, dense_shape):\n",
    "        super(Net, self).__init__()\n",
    "        self.dense_shape = dense_shape\n",
    "    def construct(self, indices, values):\n",
    "        x = SparseTensor(indices, values, self.dense_shape)\n",
    "        return x.values, x.indices, x.dense_shape\n",
    "\n",
    "indices = Tensor([[0, 1], [1, 2]])\n",
    "values = Tensor([1, 2], dtype=ms.float32)\n",
    "out = Net((3, 4))(indices, values)\n",
    "print(out[0])\n",
    "print(out[1])\n",
    "print(out[2])"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "metadata": {
    "interpreter": {
     "hash": "875445de5dd7c586490cddad65077f7a4acd26e265832f538fdbbee59bc2bd79"
    }
   },
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.5-final"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}