{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 算子使用方式\n",
    "\n",
    "[![](https://gitee.com/mindspore/docs/raw/r1.3/resource/_static/logo_source.png)](https://gitee.com/mindspore/docs/blob/r1.3/docs/mindspore/programming_guide/source_zh_cn/operators_usage.ipynb) [![](https://gitee.com/mindspore/docs/raw/r1.3/resource/_static/logo_notebook.png)](https://obs.dualstack.cn-north-4.myhuaweicloud.com/mindspore-website/notebook/r1.3/programming_guide/zh_cn/mindspore_operators_usage.ipynb) [![](https://gitee.com/mindspore/docs/raw/r1.3/resource/_static/logo_modelarts.png)](https://authoring-modelarts-cnnorth4.huaweicloud.com/console/lab?share-url-b64=aHR0cHM6Ly9vYnMuZHVhbHN0YWNrLmNuLW5vcnRoLTQubXlodWF3ZWljbG91ZC5jb20vbWluZHNwb3JlLXdlYnNpdGUvbm90ZWJvb2svbW9kZWxhcnRzL3Byb2dyYW1taW5nX2d1aWRlL21pbmRzcG9yZV9vcGVyYXRvcnNfdXNhZ2UuaXB5bmI=&imageid=65f636a0-56cf-49df-b941-7d2a07ba8c8c)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 概述\n",
    "\n",
    "算子相关接口主要包括operations、functional和composite，可通过ops直接获取到这三类算子。\n",
    "\n",
    "- operations提供单个的Primitive算子。一个算子对应一个原语，是最小的执行对象，需要实例化之后使用。\n",
    "\n",
    "- composite提供一些预定义的组合算子，以及复杂的涉及图变换的算子，如`GradOperation`。\n",
    "\n",
    "- functional提供operations和composite实例化后的对象，简化算子的调用流程。\n",
    "\n",
    "## mindspore.ops.operations\n",
    "\n",
    "operations提供了所有的Primitive算子接口，是开放给用户的最低阶算子接口。算子支持情况可查询[算子支持列表](https://www.mindspore.cn/docs/note/zh-CN/r1.3/operator_list.html)。\n",
    "\n",
    "Primitive算子也称为算子原语，它直接封装了底层的Ascend、GPU、AICPU、CPU等多种算子的具体实现，为用户提供基础算子能力。\n",
    "\n",
    "Primitive算子接口是构建高阶接口、自动微分、网络模型等能力的基础。\n",
    "\n",
    "代码样例如下："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "output = [ 1.  8. 64.]\n"
     ]
    }
   ],
   "source": [
    "import numpy as np\n",
    "import mindspore\n",
    "from mindspore import Tensor\n",
    "import mindspore.ops.operations as P\n",
    "\n",
    "input_x = mindspore.Tensor(np.array([1.0, 2.0, 4.0]), mindspore.float32)\n",
    "input_y = 3.0\n",
    "pow = P.Pow()\n",
    "output = pow(input_x, input_y)\n",
    "print(\"output =\", output)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## mindspore.ops.functional\n",
    "\n",
    "为了简化没有属性的算子的调用流程，MindSpore提供了一些算子的functional版本。入参要求参考原算子的输入输出要求。算子支持情况可以查询[算子支持列表](https://www.mindspore.cn/docs/note/zh-CN/r1.3/operator_list_ms.html#mindspore-ops-functional)。\n",
    "\n",
    "例如`P.Pow`算子，我们提供了functional版本的`F.tensor_pow`算子。\n",
    "\n",
    "使用functional的代码样例如下："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "output = [ 1.  8. 64.]\n"
     ]
    }
   ],
   "source": [
    "import numpy as np\n",
    "import mindspore\n",
    "from mindspore import Tensor\n",
    "from mindspore.ops import functional as F\n",
    "\n",
    "input_x = mindspore.Tensor(np.array([1.0, 2.0, 4.0]), mindspore.float32)\n",
    "input_y = 3.0\n",
    "output = F.tensor_pow(input_x, input_y)\n",
    "print(\"output =\", output)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## mindspore.ops.composite\n",
    "\n",
    "composite提供了一些算子的组合，包括`clip_by_value`和`random`相关的一些算子，以及涉及图变换的函数（`GradOperation`、`HyperMap`和`Map`等）。\n",
    "\n",
    "算子的组合可以直接像一般函数一样使用，例如使用`normal`生成一个随机分布："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "output = [[2.4911082 0.7941146 1.3117087]\n",
      " [0.3058231 1.7729738 1.525996 ]]\n"
     ]
    }
   ],
   "source": [
    "from mindspore import dtype as mstype\n",
    "from mindspore.ops import composite as C\n",
    "from mindspore import Tensor\n",
    "\n",
    "mean = Tensor(1.0, mstype.float32)\n",
    "stddev = Tensor(1.0, mstype.float32)\n",
    "output = C.normal((2, 3), mean, stddev, seed=5)\n",
    "print(\"output =\", output)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> 以上代码运行于MindSpore的GPU版本。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## operations、functional和composite三类算子合并用法\n",
    "\n",
    "为了在使用过程中更加简便，除了以上介绍的几种用法外，我们还将`operations`，`functional`和`composite`三种算子封装到了`mindspore.ops`中，推荐直接调用`mindspore.ops`下的接口。\n",
    "\n",
    "代码样例如下：\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "import mindspore.ops.operations as P\n",
    "pow = P.Pow()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "import mindspore.ops as ops\n",
    "pow = ops.Pow()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> 以上两种写法效果相同。"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "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.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}