{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This tutorial describes two fundamental user APIs:\n",
    "\n",
    "* Operator.apply\n",
    "* Operator.arguments\n",
    "\n",
    "We will use a trivial `Operator` that, at each time step, increments by 1 all points in the physical domain."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from devito import Grid, TimeFunction, Eq, Operator\n",
    "\n",
    "grid = Grid(shape=(4, 4))\n",
    "u = TimeFunction(name='u', grid=grid, save=3)\n",
    "op = Operator(Eq(u.forward, u + 1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To run `op`, we have to \"`apply`\" it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Operator `Kernel` run in 0.00 s\n"
     ]
    }
   ],
   "source": [
    "#NBVAL_IGNORE_OUTPUT\n",
    "summary = op.apply()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Under-the-hood, some code has been generated (`print(op)` to display the generated code), JIT-compiled, and executed. Since no additional arguments have been passed, `op` has used `u` as input. We can verify that the content of `u.data` is as expected"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "((time, x, y), (3, 4, 4))"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "u.dimensions, u.shape"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Data([[[0., 0., 0., 0.],\n",
       "       [0., 0., 0., 0.],\n",
       "       [0., 0., 0., 0.],\n",
       "       [0., 0., 0., 0.]],\n",
       "\n",
       "      [[1., 1., 1., 1.],\n",
       "       [1., 1., 1., 1.],\n",
       "       [1., 1., 1., 1.],\n",
       "       [1., 1., 1., 1.]],\n",
       "\n",
       "      [[2., 2., 2., 2.],\n",
       "       [2., 2., 2., 2.],\n",
       "       [2., 2., 2., 2.],\n",
       "       [2., 2., 2., 2.]]], dtype=float32)"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "u.data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In particular, we observe that:\n",
    "\n",
    "* `u` has size 3 along the time dimension, since it was built with `save=3`. Therefore `op` could only execute 2 timesteps, namely time=0 and time=1; given `Eq(u.forward, u + 1)`, executing time=2 would cause out-of-bounds access errors. Devito figures this out automatically and sets appropriate minimum and maximum iteration points.\n",
    "* All 16 points in each timeslice of the 4x4 `Grid` have been computed.\n",
    "\n",
    "To access all default arguments used by `op` *without* running the `Operator`, one can run"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'u': <cparam 'P' (0x7fb0d01d45a8)>,\n",
       " 'time_m': 0,\n",
       " 'time_size': 3,\n",
       " 'time_M': 1,\n",
       " 'x_m': 0,\n",
       " 'x_size': 4,\n",
       " 'x_M': 3,\n",
       " 'y_m': 0,\n",
       " 'y_size': 4,\n",
       " 'y_M': 3,\n",
       " 'timers': <cparam 'P' (0x7fb0d0550918)>}"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#NBVAL_IGNORE_OUTPUT\n",
    "op.arguments()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`'u'` stores a pointer to the allocated data; `'timers'` stores a pointer to a data structure used for C-level performance profiling.\n",
    "\n",
    "One may want to replace some of these default arguments. For example, we could increase the minimum iteration point along the spatial Dimensions `x` and `y`, and execute only the very first timestep:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Operator `Kernel` run in 0.00 s\n"
     ]
    }
   ],
   "source": [
    "#NBVAL_IGNORE_OUTPUT\n",
    "u.data[:] = 0.  # Explicit reset to initial value\n",
    "summary = op.apply(x_m=2, y_m=2, time_M=0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We look again at the computed data to convince ourselves that everything went as intended to go"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Data([[[0., 0., 0., 0.],\n",
       "       [0., 0., 0., 0.],\n",
       "       [0., 0., 0., 0.],\n",
       "       [0., 0., 0., 0.]],\n",
       "\n",
       "      [[0., 0., 0., 0.],\n",
       "       [0., 0., 0., 0.],\n",
       "       [0., 0., 1., 1.],\n",
       "       [0., 0., 1., 1.]],\n",
       "\n",
       "      [[0., 0., 0., 0.],\n",
       "       [0., 0., 0., 0.],\n",
       "       [0., 0., 0., 0.],\n",
       "       [0., 0., 0., 0.]]], dtype=float32)"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "u.data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Given a generic `Dimension` `d`, the naming convention is such that:\n",
    "\n",
    "* `d_m` is the minimum iteration point\n",
    "* `d_M` is the maximum iteration point\n",
    "\n",
    "Hence, `op.apply(..., d_m=4, d_M=7, ...)` will run `op` in the compact interval `[4, 7]` along `d`. For historical reasons, `d=...` aliases to `d_M=...`; in many Devito examples it happens to see `op.apply(..., time=10, ...)` -- this is just equivalent to `op.apply(..., time_M=10, ...)`.\n",
    "\n",
    "If we try to specify an invalid iteration extreme, Devito will raise an exception."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "OOB detected due to time_M=2\n"
     ]
    }
   ],
   "source": [
    "from devito.exceptions import InvalidArgument\n",
    "try:\n",
    "    op.apply(time_M=2)\n",
    "except InvalidArgument as e:\n",
    "    print(e)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The same `Operator` can be applied to a different `TimeFunction`. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Operator `Kernel` run in 0.00 s\n"
     ]
    }
   ],
   "source": [
    "#NBVAL_IGNORE_OUTPUT\n",
    "u2 = TimeFunction(name='u', grid=grid, save=5)\n",
    "summary = op.apply(u=u2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Data([[[0., 0., 0., 0.],\n",
       "       [0., 0., 0., 0.],\n",
       "       [0., 0., 0., 0.],\n",
       "       [0., 0., 0., 0.]],\n",
       "\n",
       "      [[1., 1., 1., 1.],\n",
       "       [1., 1., 1., 1.],\n",
       "       [1., 1., 1., 1.],\n",
       "       [1., 1., 1., 1.]],\n",
       "\n",
       "      [[2., 2., 2., 2.],\n",
       "       [2., 2., 2., 2.],\n",
       "       [2., 2., 2., 2.],\n",
       "       [2., 2., 2., 2.]],\n",
       "\n",
       "      [[3., 3., 3., 3.],\n",
       "       [3., 3., 3., 3.],\n",
       "       [3., 3., 3., 3.],\n",
       "       [3., 3., 3., 3.]],\n",
       "\n",
       "      [[4., 4., 4., 4.],\n",
       "       [4., 4., 4., 4.],\n",
       "       [4., 4., 4., 4.],\n",
       "       [4., 4., 4., 4.]]], dtype=float32)"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "u2.data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that this was the third call to `op.apply`, but code generation and JIT-compilation only occurred upon the very first call.\n",
    "\n",
    "There is one relevant case in which the maximum iteration point along the time dimension must be specified -- whenever `save` is unset, as in such a case the `Operator` wouldn't know for how many iterations to run."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "No value found for parameter time_M\n"
     ]
    }
   ],
   "source": [
    "v = TimeFunction(name='v', grid=grid)\n",
    "op2 = Operator(Eq(v.forward, v + 1))\n",
    "try:\n",
    "    op2.apply()\n",
    "except ValueError as e:\n",
    "    print(e)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Operator `Kernel` run in 0.00 s\n"
     ]
    }
   ],
   "source": [
    "#NBVAL_IGNORE_OUTPUT\n",
    "summary = op2.apply(time_M=4)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Data([[[4., 4., 4., 4.],\n",
       "       [4., 4., 4., 4.],\n",
       "       [4., 4., 4., 4.],\n",
       "       [4., 4., 4., 4.]],\n",
       "\n",
       "      [[5., 5., 5., 5.],\n",
       "       [5., 5., 5., 5.],\n",
       "       [5., 5., 5., 5.],\n",
       "       [5., 5., 5., 5.]]], dtype=float32)"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v.data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `summary` variable can be inspected to retrieve performance metrics."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "PerformanceSummary([('section0',\n",
       "                     PerfEntry(time=3e-06, gflopss=0.0, gpointss=0.0, oi=0.0, ops=0, itershapes=[]))])"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#NBVAL_IGNORE_OUTPUT\n",
    "summary"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We observe that basically all entries except for the execution time are fixed at 0. This is because by default Devito avoids to compute performance metrics, to minimize the processing time before returning control to the user (in complex `Operators`, the processing time to retrieve, for instance, the operation count or the memory footprint could be significant). To compute all performance metrics, a user could either export the environment variable `DEVITO_PROFILING` to `'advanced'` or change the profiling level programmatically *before* the `Operator` is constructed"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Operator `Kernel` run in 0.00 s\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "PerformanceSummary([('section0',\n",
       "                     PerfEntry(time=3e-06, gflopss=0.021333333333333333, gpointss=0.010666666666666666, oi=0.16666666666666666, ops=2, itershapes=[(2, 4, 4)]))])"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#NBVAL_IGNORE_OUTPUT\n",
    "from devito import configuration\n",
    "configuration['profiling'] = 'advanced'\n",
    "\n",
    "op = Operator(Eq(u.forward, u*u + 1.))\n",
    "op.apply()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A `PerformanceSummary` will contain as many entries as \"sections\" in the generated code. Currently, there is no way to automatically tie a compiler-generated section to the user-provided `Eq`s (in general, there can be more than one `Eq` in a section). The only option is to look at the generated code and search for bodies of code wrapped within C comments such as\n",
    "```\n",
    "/* Begin section0 */\n",
    "<code>\n",
    "/* End section0 \\*/\"\n",
    "```\n",
    "For example"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Uncomment me and search for /* Begin section0 */ ... /* End section0 */\n",
    "# print(op)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the `PerformanceSummary`, associated to `section0` is a `PerfEntry`, whose entries represent:\n",
    "\n",
    "* time: The time, in seconds, to execute the section.\n",
    "* gflopss: Performance of the section in Gigaflops per second.\n",
    "* gpointss: Performance of the section in Gigapoints per second.\n",
    "* oi: Operational intensity.\n",
    "* ops: Floating point operations at each (innermost loop) iteration.\n",
    "* itershape: The shape of the iteration space."
   ]
  }
 ],
 "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.6.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}