session-4/examples/extending-the-cuda-target.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Extending the CUDA Target\n",
    "\n",
    "## What is this?\n",
    "\n",
    "Numba supports extending it to work with types it is not already aware of. This notebook presents the [Interval Example](http://numba.pydata.org/numba-doc/latest/extending/interval-example.html) from the documentation on Extending Numba, but working for CUDA.\n",
    "\n",
    "## Why demo this?\n",
    "\n",
    "It's not been possible to extend the CUDA target until recently.\n",
    "\n",
    "* This demonstrates what works so far: adding new types and using them in CUDA\n",
    "* Still to be completed: boxing and unboxing - passing in and out of CUDA kernels\n",
    "\n",
    "## Use cases\n",
    "\n",
    "* Add support in Numba CUDA for masked arrays\n",
    "* Some class-like things (c.f. `Interval` example here)\n",
    "* Awkward Arrays\n",
    "* Your use case - please share ideas / wishes!\n",
    "\n",
    "## Overview"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<IPython.core.display.Image object>"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from IPython.core.display import Image\n",
    "Image('pipeline.png')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Extensions are involved with the following pipeline stages:\n",
    "\n",
    "- **Type inference:** Teaching Numba how to recognise and work with a new type\n",
    "- **Data model:** Not strictly a stage, but provides a coupling between typing and lowering\n",
    "- **Lowering:** Turning Numba IR into LLVM IR\n",
    "\n",
    "## Some initial setup"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's define an `Interval` class, for interval arithmetic:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Interval(object):\n",
    "    \"\"\" \n",
    "    A half-open interval on the real number line.\n",
    "    \"\"\"\n",
    "    def __init__(self, lo, hi):\n",
    "        self.lo = lo\n",
    "        self.hi = hi\n",
    "\n",
    "    def __repr__(self):\n",
    "        return 'Interval(%f, %f)' % (self.lo, self.hi)\n",
    "\n",
    "    @property\n",
    "    def width(self):\n",
    "        return self.hi - self.lo"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Typing\n",
    "\n",
    "### Creating a new type\n",
    "\n",
    "First we need a representation that Numba understands for the type of `Interval` objects. The base Numba type is `types.Type`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "from numba import types\n",
    "\n",
    "class IntervalType(types.Type):\n",
    "    def __init__(self):\n",
    "        super().__init__(name='Interval')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We just need a single instance of the type object, so let's make it now:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "interval_type = IntervalType()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Associating the type with Python instances\n",
    "\n",
    "To enable Numba to recognise instances of the `Interval` class as the `interval_type`, we register a function that takes an instance of `Interval`, and returns the Numba type :"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "from numba.core.extending import typeof_impl\n",
    "\n",
    "@typeof_impl.register(Interval)\n",
    "def typeof_interval(val, c): \n",
    "    return interval_type"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The typing function takes two parameters. We don't need to use them here, but they are:\n",
    "\n",
    "* `val`: the instance being typed. This can be useful if there are multiple Numba types for a given Python type, or if it is parameterized - e.g. a 1D array needs to be a different type to a 2D array.\n",
    "* `c`: The *typeof context* - This can be ignored in most cases.\n",
    "\n",
    "All `Interval` objects are the same type, so we can safely just return `interval_type` without inspecting `val`.\n",
    "\n",
    "### Typing the constructor\n",
    "\n",
    "When the constructor, `Interval(lo, hi)` is called, Numba needs to know what the return type will be. We register the typing for callables (like constructors) with:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "from numba.core.extending import type_callable\n",
    "\n",
    "@type_callable(Interval)\n",
    "def type_interval(context):\n",
    "    def typer(lo, hi):\n",
    "        if isinstance(lo, types.Float) and isinstance(hi, types.Float):\n",
    "            return interval_type\n",
    "    return typer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The typer can return:\n",
    "\n",
    "* A Numba type, if the typing is successful\n",
    "* `None`, if the typing is unsuccessful.\n",
    "  - If the typing is unsuccessful, that doesn't result in an immediate error - Numba could try other registered typing functions to see if any of those will successfully return a type.\n",
    "\n",
    "We've restricted construction of `Interval` objects in jitted functions to using floats for the bounds of the interval, keeping things simple for now.\n",
    "\n",
    "## The Data Model\n",
    "\n",
    "The *Data model* couples Numba's front end with the LLVM backend, from a typing perspective - each model registered with Numba contains a description of the structure of the type in terms of more primitive types, which can be mapped more directly to LLVM types.\n",
    "\n",
    "There are various models that make a good starting point for defining a model for a custom class - we'll use the `StructModel`, since the representation of an `Interval` instance is a bit like a struct of two floats.\n",
    "\n",
    "To use the `StructModel`, we provide a list of the members of the struct and their types:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "from numba.core.extending import models, register_model\n",
    "\n",
    "@register_model(IntervalType)\n",
    "class IntervalModel(models.StructModel):\n",
    "    def __init__(self, dmm, fe_type):\n",
    "        members = [\n",
    "            ('lo', types.float64),\n",
    "            ('hi', types.float64),\n",
    "            ]\n",
    "        models.StructModel.__init__(self, dmm, fe_type, members)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Lowering\n",
    "\n",
    "### Attribute access\n",
    "\n",
    "Numba provides a quick way to expose the attributes of a struct without us having to write code to generate the LLVM IR to access the data - this is `make_attribute_wrapper`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "from numba.core.extending import make_attribute_wrapper\n",
    "\n",
    "make_attribute_wrapper(IntervalType, 'lo', 'lo')\n",
    "make_attribute_wrapper(IntervalType, 'hi', 'hi')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Implementing the constructor\n",
    "\n",
    "To lower a function, we need to generate the LLVM IR that implements it. We need to register a function with Numba that does this generation. The implementation for lowering the Interval constructor follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "from numba.core.extending import lower_builtin\n",
    "from numba.core import cgutils\n",
    "\n",
    "@lower_builtin(Interval, types.Float, types.Float)\n",
    "def impl_interval(context, builder, sig, args):\n",
    "    typ = sig.return_type\n",
    "    lo, hi = args\n",
    "    interval = cgutils.create_struct_proxy(typ)(context, builder)\n",
    "    interval.lo = lo\n",
    "    interval.hi = hi\n",
    "    return interval._getvalue()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An explanation of each part of the implementation:\n",
    "    \n",
    "* The `@lower_builtin` decorator decorates the function for a typing given as parameters to the decorator. The function called is first, followed by the types of its arguments.\n",
    "* The implementation function is always called with four arguments:\n",
    "  - `context`: The *typing context* - this can be used to generate values and casts appropriate to the target.\n",
    "  - `builder`: An llvmlite IR builder, used for generating IR directly.\n",
    "  - `sig`: The signature of the function, consisting of the return type and argument types (and the type of the receiver, for methods). We only need the return type here.\n",
    "  - `args`: The arguments to the function, as LLVM IR generated previously.\n",
    "* `cgutils` is a library of code generation utilities.\n",
    "  - Rather than fiddling around directly creating a struct and manipulating it directly, we use the `create_struct_proxy` method to create an object that generates the struct, and allows us to generate IR that manipulates it.\n",
    "  - We can treat the struct proxy a bit like a Python object, assigning `lo` to `interval.lo` generates the IR that assigns the IR `lo` value to the IR for the struct proxy.\n",
    "* We don't actually want a struct proxy object to come out of this function - Numba is expecting an IR node - we get this with the `_getvalue()` method.\n",
    "\n",
    "#### IR dump\n",
    "\n",
    "You can dump IR with the environment variable `NUMBA_DUMP_LLVM=1`. Some excerpts of IR generated by `impl_interval` look like:\n",
    "\n",
    "For `interval = cgutils.create_struct_proxy(typ)(context, builder)`:\n",
    "\n",
    "```\n",
    "  %\"x\" = alloca {double, double}\n",
    "  store {double, double} zeroinitializer, {double, double}* %\"x\"\n",
    "```\n",
    "\n",
    "For `interval.lo = lo`:\n",
    "\n",
    "```\n",
    "  %\"$const4.1\" = alloca double\n",
    "  store double 0x3ff0000000000000, double* %\"$const4.1\"\n",
    "  %\".12\" = load double, double* %\"$const4.1\"\n",
    "  %\".17\" = getelementptr inbounds {double, double}, {double, double}* %\".14\", i32 0, i32 0\n",
    "  store double %\".12\", double* %\".17\"\n",
    "```\n",
    "\n",
    "For `interval.hi = hi`:\n",
    "\n",
    "```\n",
    "  %\"$const6.2\" = alloca double\n",
    "  store double 0x4008000000000000, double* %\"$const6.2\"\n",
    "  %\".13\" = load double, double* %\"$const6.2\"\n",
    "  %\".19\" = getelementptr inbounds {double, double}, {double, double}* %\".14\", i32 0, i32 1\n",
    "  store double %\".13\", double* %\".19\"\n",
    "```\n",
    "\n",
    "Generated IR is very verbose and contains a lot of redundancy - a lot of this is optimized to something simpler by LLVM later.\n",
    "\n",
    "### Implementing an attribute\n",
    "\n",
    "The example in the Numba documentation makes this very easy, with:\n",
    "\n",
    "```python\n",
    "@overload_attribute(IntervalType, \"width\")\n",
    "def get_width(interval):\n",
    "    def getter(interval):\n",
    "        return interval.hi - interval.lo\n",
    "    return getter\n",
    "```\n",
    "\n",
    "Which allows the implementation of the attribute to be written in Python that then gets jitted (rather than having to write IR manually) - however, `@overload` doesn't work for the CUDA target yet, so we need to use some more low-level APIs, and directly interact with registries in the CUDA target.\n",
    "\n",
    "#### Typing\n",
    "\n",
    "We register all the attributes of a type in a single class. The type is identified by the `key` property:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "from numba.core.typing.templates import AttributeTemplate\n",
    "from numba.cuda.cudadecl import registry as cuda_registry\n",
    "\n",
    "@cuda_registry.register_attr\n",
    "class Interval_attrs(AttributeTemplate):\n",
    "    key = IntervalType\n",
    "\n",
    "    def resolve_width(self, mod):\n",
    "        return types.float64"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Each attribute is typed by a `resolve_<attr>` function, which returns the type of the attribute. We only have one attribute to resolve here."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Lowering\n",
    "\n",
    "Lowering an attribute is similar to the `@lower_builtin` decorator we used above, but we'll use the `@lower_attr` decorator instead (I usually rename it to `@cuda_lower_attr` to avoid confusion with other `@lower_attr` things in Numba): "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "from numba.cuda.cudaimpl import lower_attr as cuda_lower_attr\n",
    "\n",
    "@cuda_lower_attr(IntervalType, 'width')\n",
    "def cuda_Interval_width(context, builder, sig, arg):\n",
    "    lo = builder.extract_value(arg, 0)\n",
    "    hi = builder.extract_value(arg, 1)\n",
    "    return builder.fsub(hi, lo)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The code above builds the IR to get the 0 (`lo`) and 1 (`hi`) elements out of its argument, and then subtract them with the `fsub` instruction. The generated IR (abridged) may look like):\n",
    "\n",
    "```\n",
    "  %\".49\" = load {double, double}, {double, double}* %\"x\"\n",
    "  %\".50\" = extractvalue {double, double} %\".49\", 0\n",
    "  %\".51\" = extractvalue {double, double} %\".49\", 1\n",
    "  %\".52\" = fsub double %\".51\", %\".50\"\n",
    "  %\".54\" = load double, double* %\"$14load_attr.5\"\n",
    "  store double %\".52\", double* %\"$14load_attr.5\"\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Trying it out"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "from numba import cuda, njit\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First let's define some `@njit` functions that we'll call from a kernel:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "@njit\n",
    "def inside_interval(interval, x):\n",
    "    \"\"\"Tests attribute access\"\"\"\n",
    "    return interval.lo <= x < interval.hi\n",
    "\n",
    "\n",
    "@njit\n",
    "def interval_width(interval):\n",
    "    \"\"\"Tests property access\"\"\"\n",
    "    return interval.width\n",
    "\n",
    "\n",
    "@njit\n",
    "def sum_intervals(i, j):\n",
    "    \"\"\"Tests the Interval constructor\"\"\"\n",
    "    return Interval(i.lo + j.lo, i.hi + j.hi)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we'll create a kernel that uses them:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "@cuda.jit\n",
    "def kernel(arr):\n",
    "    x = Interval(1.0, 3.0)\n",
    "    arr[0] = x.hi + x.lo\n",
    "    arr[1] = x.width\n",
    "    arr[2] = inside_interval(x, 2.5)\n",
    "    arr[3] = inside_interval(x, 3.5)\n",
    "    arr[4] = interval_width(x)\n",
    "\n",
    "    y = Interval(7.5, 9.0)\n",
    "    z = sum_intervals(x, y)\n",
    "    arr[5] = z.lo\n",
    "    arr[6] = z.hi"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And call it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 4. ,  2. ,  1. ,  0. ,  2. ,  8.5, 12. ])"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "out = np.zeros(7)\n",
    "\n",
    "kernel[1, 1](out)\n",
    "\n",
    "# Should print: [ 4.   2.   1.   0.   2.   8.5 12. ]\n",
    "out"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Further info:\n",
    "\n",
    "* Discussion with Jim Pivarski on the Numba Discourse: https://numba.discourse.group/t/making-awkward-arrays-work-in-the-cuda-target/63\n",
    "* The Interval example: http://numba.pydata.org/numba-doc/latest/extending/interval-example.html#type-inference-for-python-values\n",
    "* More examples:\n",
    "  - Lots of typing functions in here: https://github.com/numba/numba/blob/master/numba/cuda/cudadecl.py\n",
    "  - Lots of lowering functions: https://github.com/numba/numba/blob/master/numba/cuda/cudaimpl.py"
   ]
  }
 ],
 "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.8.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}