{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[![在线运行](https://mindspore-website.obs.cn-north-4.myhuaweicloud.com/website-images/r2.0/resource/_static/logo_modelarts.png)](https://authoring-modelarts-cnnorth4.huaweicloud.com/console/lab?share-url-b64=aHR0cHM6Ly9vYnMuZHVhbHN0YWNrLmNuLW5vcnRoLTQubXlodWF3ZWljbG91ZC5jb20vbWluZHNwb3JlLXdlYnNpdGUvbm90ZWJvb2svcjIuMC90dXRvcmlhbHMvemhfY24vYmVnaW5uZXIvbWluZHNwb3JlX3RlbnNvci5pcHluYg==&imageid=e225a9aa-230a-4ea5-a538-b5faed64a6a6) [![下载Notebook](https://mindspore-website.obs.cn-north-4.myhuaweicloud.com/website-images/r2.0/resource/_static/logo_notebook.png)](https://obs.dualstack.cn-north-4.myhuaweicloud.com/mindspore-website/notebook/r2.0/tutorials/zh_cn/beginner/mindspore_tensor.ipynb) [![下载样例代码](https://mindspore-website.obs.cn-north-4.myhuaweicloud.com/website-images/r2.0/resource/_static/logo_download_code.png)](https://obs.dualstack.cn-north-4.myhuaweicloud.com/mindspore-website/notebook/r2.0/tutorials/zh_cn/beginner/mindspore_tensor.py)\n",
    " [![查看源文件](https://mindspore-website.obs.cn-north-4.myhuaweicloud.com/website-images/r2.0/resource/_static/logo_source.png)](https://gitee.com/mindspore/docs/blob/r2.0/tutorials/source_zh_cn/beginner/tensor.ipynb)\n",
    "\n",
    "[基本介绍](https://www.mindspore.cn/tutorials/zh-CN/r2.0/beginner/introduction.html) || [快速入门](https://www.mindspore.cn/tutorials/zh-CN/r2.0/beginner/quick_start.html) || **张量 Tensor** || [数据集 Dataset](https://www.mindspore.cn/tutorials/zh-CN/r2.0/beginner/dataset.html) || [数据变换 Transforms](https://www.mindspore.cn/tutorials/zh-CN/r2.0/beginner/transforms.html) || [网络构建](https://www.mindspore.cn/tutorials/zh-CN/r2.0/beginner/model.html) || [函数式自动微分](https://www.mindspore.cn/tutorials/zh-CN/r2.0/beginner/autograd.html) || [模型训练](https://www.mindspore.cn/tutorials/zh-CN/r2.0/beginner/train.html) || [保存与加载](https://www.mindspore.cn/tutorials/zh-CN/r2.0/beginner/save_load.html)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "# 张量 Tensor\n",
    "\n",
    "张量（Tensor）是一个可用来表示在一些矢量、标量和其他张量之间的线性关系的多线性函数，这些线性关系的基本例子有内积、外积、线性映射以及笛卡儿积。其坐标在 $n$ 维空间内，有  $n^{r}$ 个分量的一种量，其中每个分量都是坐标的函数，而在坐标变换时，这些分量也依照某些规则作线性变换。$r$ 称为该张量的秩或阶（与矩阵的秩和阶均无关系）。\n",
    "\n",
    "张量是一种特殊的数据结构，与数组和矩阵非常相似。张量（[Tensor](https://www.mindspore.cn/docs/zh-CN/r2.0/api_python/mindspore/mindspore.Tensor.html)）是MindSpore网络运算中的基本数据结构，本教程主要介绍张量和稀疏张量的属性及用法。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import mindspore\n",
    "from mindspore import ops\n",
    "from mindspore import Tensor, CSRTensor, COOTensor"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 创建张量\n",
    "\n",
    "张量的创建方式有多种，构造张量时，支持传入`Tensor`、`float`、`int`、`bool`、`tuple`、`list`和`numpy.ndarray`类型。\n",
    "\n",
    "- **根据数据直接生成**\n",
    "\n",
    "    可以根据数据创建张量，数据类型可以设置或者通过框架自动推断。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "data = [1, 0, 1, 0]\n",
    "x_data = Tensor(data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- **从NumPy数组生成**\n",
    "\n",
    "    可以从NumPy数组创建张量。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "np_array = np.array(data)\n",
    "x_np = Tensor(np_array)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- **使用init初始化器构造张量**\n",
    "\n",
    "    当使用`init`初始化器对张量进行初始化时，支持传入的参数有`init`、`shape`、`dtype`。\n",
    "\n",
    "    - `init`: 支持传入[initializer](https://www.mindspore.cn/docs/zh-CN/r2.0/api_python/mindspore.common.initializer.html)的子类。\n",
    "\n",
    "    - `shape`: 支持传入 `list`、`tuple`、 `int`。\n",
    "\n",
    "    - `dtype`: 支持传入[mindspore.dtype](https://www.mindspore.cn/docs/zh-CN/r2.0/api_python/mindspore/mindspore.dtype.html#mindspore.dtype)。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "tensor1:\n",
      " [[1. 1.]\n",
      " [1. 1.]]\n",
      "tensor2:\n",
      " [[-0.00063482 -0.00916224]\n",
      " [ 0.01324238 -0.0171206 ]]\n"
     ]
    }
   ],
   "source": [
    "from mindspore.common.initializer import One, Normal\n",
    "\n",
    "# Initialize a tensor with ones\n",
    "tensor1 = mindspore.Tensor(shape=(2, 2), dtype=mindspore.float32, init=One())\n",
    "# Initialize a tensor from normal distribution\n",
    "tensor2 = mindspore.Tensor(shape=(2, 2), dtype=mindspore.float32, init=Normal())\n",
    "\n",
    "print(\"tensor1:\\n\", tensor1)\n",
    "print(\"tensor2:\\n\", tensor2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`init`主要用于并行模式下的延后初始化，在正常情况下不建议使用init对参数进行初始化。\n",
    "\n",
    "- **继承另一个张量的属性，形成新的张量**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Ones Tensor: \n",
      " [1 1 1 1] \n",
      "\n",
      "Zeros Tensor: \n",
      " [0 0 0 0] \n",
      "\n"
     ]
    }
   ],
   "source": [
    "from mindspore import ops\n",
    "\n",
    "x_ones = ops.ones_like(x_data)\n",
    "print(f\"Ones Tensor: \\n {x_ones} \\n\")\n",
    "\n",
    "x_zeros = ops.zeros_like(x_data)\n",
    "print(f\"Zeros Tensor: \\n {x_zeros} \\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 张量的属性\n",
    "\n",
    "张量的属性包括形状、数据类型、转置张量、单个元素大小、占用字节数量、维数、元素个数和每一维步长。\n",
    "\n",
    "- 形状（shape）：`Tensor`的shape，是一个tuple。\n",
    "\n",
    "- 数据类型（dtype）：`Tensor`的dtype，是MindSpore的一个数据类型。\n",
    "\n",
    "- 单个元素大小（itemsize）： `Tensor`中每一个元素占用字节数，是一个整数。\n",
    "\n",
    "- 占用字节数量（nbytes）： `Tensor`占用的总字节数，是一个整数。\n",
    "\n",
    "- 维数（ndim）： `Tensor`的秩，也就是len(tensor.shape)，是一个整数。\n",
    "\n",
    "- 元素个数（size）： `Tensor`中所有元素的个数，是一个整数。\n",
    "\n",
    "- 每一维步长（strides）： `Tensor`每一维所需要的字节数，是一个tuple。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "x_shape: (2, 2)\n",
      "x_dtype: Int32\n",
      "x_itemsize: 4\n",
      "x_nbytes: 16\n",
      "x_ndim: 2\n",
      "x_size: 4\n",
      "x_strides: (8, 4)\n"
     ]
    }
   ],
   "source": [
    "x = Tensor(np.array([[1, 2], [3, 4]]), mindspore.int32)\n",
    "\n",
    "print(\"x_shape:\", x.shape)\n",
    "print(\"x_dtype:\", x.dtype)\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",
    "Tensor索引与Numpy索引类似，索引从0开始编制，负索引表示按倒序编制，冒号`:`和 `...`用于对数据进行切片。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "First row: [0. 1.]\n",
      "value of bottom right corner: 3.0\n",
      "Last column: [1. 3.]\n",
      "First column: [0. 2.]\n"
     ]
    }
   ],
   "source": [
    "tensor = Tensor(np.array([[0, 1], [2, 3]]).astype(np.float32))\n",
    "\n",
    "print(\"First row: {}\".format(tensor[0]))\n",
    "print(\"value of bottom right corner: {}\".format(tensor[1, 1]))\n",
    "print(\"Last column: {}\".format(tensor[:, -1]))\n",
    "print(\"First column: {}\".format(tensor[..., 0]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 张量运算\n",
    "\n",
    "张量之间有很多运算，包括算术、线性代数、矩阵处理（转置、标引、切片）、采样等，张量运算和NumPy的使用方式类似，下面介绍其中几种操作。\n",
    "\n",
    "> 普通算术运算有：加（+）、减（-）、乘（\\*）、除（/）、取模（%）、整除（//）。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "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: [0. 1. 0.]\n",
      "floordiv: [4. 2. 2.]\n"
     ]
    }
   ],
   "source": [
    "x = Tensor(np.array([1, 2, 3]), mindspore.float32)\n",
    "y = Tensor(np.array([4, 5, 6]), mindspore.float32)\n",
    "\n",
    "output_add = x + y\n",
    "output_sub = x - y\n",
    "output_mul = x * y\n",
    "output_div = y / x\n",
    "output_mod = y % x\n",
    "output_floordiv = y // x\n",
    "\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(\"floordiv:\", output_floordiv)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`Concat`将给定维度上的一系列张量连接起来。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[0. 1.]\n",
      " [2. 3.]\n",
      " [4. 5.]\n",
      " [6. 7.]]\n",
      "shape:\n",
      " (4, 2)\n"
     ]
    }
   ],
   "source": [
    "data1 = Tensor(np.array([[0, 1], [2, 3]]).astype(np.float32))\n",
    "data2 = Tensor(np.array([[4, 5], [6, 7]]).astype(np.float32))\n",
    "output = ops.concat((data1, data2), axis=0)\n",
    "\n",
    "print(output)\n",
    "print(\"shape:\\n\", output.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`Stack`则是从另一个维度上将两个张量合并起来。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[[0. 1.]\n",
      "  [2. 3.]]\n",
      "\n",
      " [[4. 5.]\n",
      "  [6. 7.]]]\n",
      "shape:\n",
      " (2, 2, 2)\n"
     ]
    }
   ],
   "source": [
    "data1 = Tensor(np.array([[0, 1], [2, 3]]).astype(np.float32))\n",
    "data2 = Tensor(np.array([[4, 5], [6, 7]]).astype(np.float32))\n",
    "output = ops.stack([data1, data2])\n",
    "\n",
    "print(output)\n",
    "print(\"shape:\\n\", output.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tensor与NumPy转换\n",
    "\n",
    "Tensor可以和NumPy进行互相转换。\n",
    "\n",
    "### Tensor转换为NumPy\n",
    "\n",
    "与张量创建相同，使用 `asnumpy()` 将Tensor变量转换为NumPy变量。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "t: [1. 1. 1. 1. 1.]\n",
      "n: [1. 1. 1. 1. 1.]\n"
     ]
    }
   ],
   "source": [
    "t = ops.ones(5, mindspore.float32)\n",
    "print(f\"t: {t}\")\n",
    "n = t.asnumpy()\n",
    "print(f\"n: {n}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### NumPy转换为Tensor\n",
    "\n",
    "使用`Tensor()`将NumPy变量转换为Tensor变量。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "n = np.ones(5)\n",
    "t = Tensor.from_numpy(n)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "t: [2. 2. 2. 2. 2.]\n",
      "n: [2. 2. 2. 2. 2.]\n"
     ]
    }
   ],
   "source": [
    "np.add(n, 1, out=n)\n",
    "print(f\"t: {t}\")\n",
    "print(f\"n: {n}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 稀疏张量\n",
    "\n",
    "稀疏张量是一种特殊张量，其中绝大部分元素的值为零。\n",
    "\n",
    "在某些应用场景中（比如推荐系统、分子动力学、图神经网络等），数据的特征是稀疏的，若使用普通张量表征这些数据会引入大量不必要的计算、存储和通讯开销。这时就可以使用稀疏张量来表征这些数据。\n",
    "\n",
    "MindSpore现在已经支持最常用的`CSR`和`COO`两种稀疏数据格式。\n",
    "\n",
    "常用稀疏张量的表达形式是`<indices:Tensor, values:Tensor, shape:Tensor>`。其中，`indices`表示非零下标元素， `values`表示非零元素的值，shape表示的是被压缩的稀疏张量的形状。在这个结构下，我们定义了三种稀疏张量结构：`CSRTensor`、`COOTensor`和`RowTensor`。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### CSRTensor\n",
    "\n",
    "`CSR`（Compressed Sparse Row）稀疏张量格式有着高效的存储与计算的优势。其中，非零元素的值存储在`values`中，非零元素的位置存储在`indptr`（行）和`indices`（列）中。各参数含义如下：\n",
    "\n",
    "- `indptr`: 一维整数张量, 表示稀疏数据每一行的非零元素在`values`中的起始位置和终止位置, 索引数据类型支持int16、int32、int64。\n",
    "\n",
    "- `indices`: 一维整数张量，表示稀疏张量非零元素在列中的位置, 与`values`长度相等，索引数据类型支持int16、int32、int64。\n",
    "\n",
    "- `values`: 一维张量，表示`CSRTensor`相对应的非零元素的值，与`indices`长度相等。\n",
    "\n",
    "- `shape`: 表示被压缩的稀疏张量的形状，数据类型为`Tuple`，目前仅支持二维`CSRTensor`。\n",
    "\n",
    "> `CSRTensor`的详细文档，请参考[mindspore.CSRTensor](https://www.mindspore.cn/docs/zh-CN/r2.0/api_python/mindspore/mindspore.CSRTensor.html)。\n",
    "\n",
    "下面给出一些CSRTensor的使用示例："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Float64\n"
     ]
    }
   ],
   "source": [
    "indptr = Tensor([0, 1, 2])\n",
    "indices = Tensor([0, 1])\n",
    "values = Tensor([1, 2], dtype=mindspore.float32)\n",
    "shape = (2, 4)\n",
    "\n",
    "# Make a CSRTensor\n",
    "csr_tensor = CSRTensor(indptr, indices, values, shape)\n",
    "\n",
    "print(csr_tensor.astype(mindspore.float64).dtype)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "上述代码会生成如下所示的`CSRTensor`:\n",
    "\n",
    "$$\n",
    " \\left[\n",
    " \\begin{matrix}\n",
    "   1 & 0 & 0 & 0 \\\\\n",
    "   0 & 2 & 0 & 0\n",
    "  \\end{matrix}\n",
    "  \\right]\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### COOTensor\n",
    "\n",
    "`COO`（Coordinate Format）稀疏张量格式用来表示某一张量在给定索引上非零元素的集合，若非零元素的个数为`N`，被压缩的张量的维数为`ndims`。各参数含义如下：\n",
    "\n",
    "- `indices`: 二维整数张量，每行代表非零元素下标。形状：`[N, ndims]`， 索引数据类型支持int16、int32、int64。\n",
    "\n",
    "- `values`: 一维张量，表示相对应的非零元素的值。形状：`[N]`。\n",
    "\n",
    "- `shape`: 表示被压缩的稀疏张量的形状，目前仅支持二维`COOTensor`。\n",
    "\n",
    "> `COOTensor`的详细文档，请参考[mindspore.COOTensor](https://www.mindspore.cn/docs/zh-CN/r2.0/api_python/mindspore/mindspore.COOTensor.html)。\n",
    "\n",
    "下面给出一些COOTensor的使用示例："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1. 2.]\n",
      "[[0 1]\n",
      " [1 2]]\n",
      "(3, 4)\n",
      "Float64\n"
     ]
    }
   ],
   "source": [
    "indices = Tensor([[0, 1], [1, 2]], dtype=mindspore.int32)\n",
    "values = Tensor([1, 2], dtype=mindspore.float32)\n",
    "shape = (3, 4)\n",
    "\n",
    "# Make a COOTensor\n",
    "coo_tensor = COOTensor(indices, values, shape)\n",
    "\n",
    "print(coo_tensor.values)\n",
    "print(coo_tensor.indices)\n",
    "print(coo_tensor.shape)\n",
    "print(coo_tensor.astype(mindspore.float64).dtype)  # COOTensor to float64"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "上述代码会生成如下所示的`COOTensor`:\n",
    "\n",
    "$$\n",
    " \\left[\n",
    " \\begin{matrix}\n",
    "   0 & 1 & 0 & 0 \\\\\n",
    "   0 & 0 & 2 & 0 \\\\\n",
    "   0 & 0 & 0 & 0\n",
    "  \\end{matrix}\n",
    "  \\right]\n",
    "$$\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "MindSpore",
   "language": "python",
   "name": "mindspore"
  },
  "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"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}