lectures/07_mixed_programming_swig.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Mixed language programming with SWIG\n",
    "\n",
    "Simon Funke, Hans Petter Langtangen, Joakim Sundnes, Ola Skavhaug\n",
    "\n",
    "Date: **Oct 5, 2016**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## The nature of Python vs. C\n",
    "\n",
    "A Python variable can hold different objects:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```python\n",
    "d = 3.2    # d holds a float\n",
    "d = 'txt'  # d holds a string\n",
    "d = Button(frame, text='push')  # instance of class Button\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "In C, C++ and Fortran, a variable is declared of a specific type:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```C\n",
    "double d;\n",
    "d = 4.2;\n",
    "d = \"some string\";  /* illegal, compiler error */\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This difference makes it quite complicated to call C, C++ or Fortran from Python"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Learn more about C?\n",
    "\n",
    "[INF3331/INF4331 C tutorial](https://github.com/UiO-INF3331/student-resources-16/blob/master/lectures/07_introduction_to_c.pdf)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Contents\n",
    "\n",
    "* Calling C from Python - the hard way\n",
    "* SWIG\n",
    "    * Python-C\n",
    "    * Python-C++\n",
    "    * Numpy arrays and SWIG"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Calling C from Python - the hard way"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Calling C from Python\n",
    "\n",
    "Suppose we have a C function (from an existing library or our own implementation):\n",
    "\n",
    "```C\n",
    "extern double hw1(double r1, double r2);\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "We want to call this from Python as"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```python\n",
    "from hw import hw1\n",
    "r1 = 1.2\n",
    "r2 = -1.2\n",
    "s = hw1(r1, r2)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "The Python variables `r1` and `r2` hold numbers (`float`). We need to extract these in the C code, convert to `double` variables, then call `hw1`, and finally convert the `double` result to a Python `float`.\n",
    "\n",
    "All this conversion is done in *wrapper* code."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Writing wrapper code\n",
    "\n",
    "Python allows us to write wrapper functions in C that.\n",
    "* Every object in Python is represented by a C struct `PyObject`\n",
    "* Wrapper code converts between `PyObject` variables and plain C variables (from `PyObject` `r1` and `r2` to `double`, and `double` to `PyObject`).\n",
    "* Once compiled it can be loaded as a Python module."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Wrapper code for the `hw` function"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```C\n",
    "#include \"Python.h\"\n",
    "#include \"src/hw.h\"\n",
    "\n",
    "static PyObject *_wrap_hw1(PyObject *self, PyObject *args) {\n",
    "\n",
    "  PyObject *resultobj;\n",
    "  double r1, r2, result;\n",
    "\n",
    "  PyArg_ParseTuple(args, (char *)\"dd:hw1\", &r1, &r2);\n",
    "\n",
    "  hw1(r1, r2, &result);\n",
    "\n",
    "  resultobj = PyFloat_FromDouble(result);\n",
    "  return resultobj;\n",
    "}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Note*: The first function argument (`self`) points to the module object for module-level functions; for a method it points to the object instance.\n",
    "\n",
    "The full example can be found [here](https://github.com/UiO-INF3331/code-snippets-16/tree/master/mixed/c-api)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Using the wrapper\n",
    "\n",
    "* The wrapper function and *hw1* must be compiled and linked to a shared library file.\n",
    "* This file can be loaded in Python as module.\n",
    "\n",
    "$->$ Demo"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "* Direct calls through wrapper code enables efficient data transfer: large arrays can be sent by pointers\n",
    "* Such modules written in other languages are called **extension modules**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Writing wrapper code is tedious\n",
    "\n",
    "A wrapper function is needed for each C function we want to call from Python\n",
    "\n",
    "Let's automated it!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "We shall use SWIG (for C/C++)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Simplified Wrapper and Interface Generation (SWIG)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## More info\n",
    "\n",
    "* [SWIG manual](http://www.swig.org/Doc1.3/Contents.html)\n",
    "* Code snippets, swig example: https://github.com/UiO-INF3331/code-snippets-16/tree/master/mixed/swig"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Scientific Hello World example\n",
    "\n",
    "Consider this Scientific Hello World module (`hw.py`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import math\n",
    "\n",
    "def hw1(r1, r2):                                                                                                                                                                               \n",
    "    s = math.sin(r1 + r2)                                                                                                                                                                      \n",
    "    return s    \n",
    "\n",
    "def hw2(r1, r2):\n",
    "    s = math.sin(r1 + r2)\n",
    "    print('sin({:.2f}+{:.2f})={:.2f}'.format(r1, r2, s))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Usage:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from hw import hw1\n",
    "s = hw1(1.0, 0)\n",
    "hw2(1.0, 0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "We want to implement the module in C and C++, and use it as if it was a pure Python module"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Using SWIG to wrap C and C++\n",
    "\n",
    "* Wrappers to C and C++ codes is automatically generated by SWIG\n",
    "* SWIG is more complicated to use than Cython:\n",
    "    1. First make a SWIG interface file\n",
    "    2. Then run SWIG to generate wrapper code\n",
    "    3. Finally compile and link the C code and the wrapper code"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "# C implementation of `hw1` and `hw2`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Header file:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```C\n",
    "// file: src/hw.h\n",
    "void hw1(double r1, double r2, double *s);\n",
    "void hw2(double r1, double r2);\n",
    "```    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Source file:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "```C\n",
    "// file: src/hw.c\n",
    "#include <stdio.h>\n",
    "#include <math.h>\n",
    "\n",
    "#include \"hw.h\"\n",
    "\n",
    "void hw1(double r1, double r2, double *s)\n",
    "{\n",
    "    *s = sin(r1 + r2);\n",
    "}\n",
    "\n",
    "void hw2(double r1, double r2)\n",
    "{\n",
    "    double s;\n",
    "    s = sin(r1 + r2);\n",
    "    printf(\"sin(%f+%f)=%f\\n\", r1, r2, s);\n",
    "}\n",
    "```    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## SWIG interface file\n",
    "\n",
    "The interface file contains C preprocessor directives and special SWIG directives:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```C\n",
    "/* file: hw.i */\n",
    "%module hw\n",
    "%{\n",
    "/* Everything in this block will be copied in the wrapper file. We include the C header file necessary to compile the interface\n",
    "*/\n",
    "#include \"src/hw.h\"\n",
    "%}\n",
    "\n",
    "/* list functions to be interfaced: */\n",
    "void hw1(double r1, double r2, double *s);\n",
    "void hw2(double r1, double r2);\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Generating the module\n",
    "\n",
    "Run SWIG (preferably in a subdirectory):"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```bash\n",
    "swig -python -Isrc hw.i\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "SWIG generates wrapper code in\n",
    "```bash\n",
    "hw_wrap.c\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Compile and link a shared library module:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```bash\n",
    "gcc -Isrc -fPIC -I/usr/include/python3.5m -I/usr/include/x86_64-linux-gnu/python3.5m -lpython3.5m -c src/hw.c hw_wrap.c\n",
    "gcc -shared -fPIC -o _hw.so hw.o hw_wrap.o\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note:** the underscore prefix in `_hw.so` is required!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## A build script\n",
    "\n",
    "* Make a script to automate the compile+link process\n",
    "* Can use `pkg-config` tool to extract where `Python.h` resides and to use the correct compiler flags."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```bash\n",
    "# file: build.sh\n",
    "swig -python -Isrc hw.i\n",
    "\n",
    "gcc -Isrc -fPIC $(pkg-config --cflags --libs python3) -c src/hw.c hw_wrap.c\n",
    "gcc -shared -fPIC -o _hw.so hw.o hw_wrap.o\n",
    "\n",
    "python -c \"import hw\" # test\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "The compiled module consists of two files: `hw.py` (which loads), `_hw.so`\n",
    "\n",
    "The full example and the build script is found [here](https://github.com/UiO-INF3331/code-snippets-16/tree/master/mixed/swig/c)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Building modules with Distutils (1)\n",
    "\n",
    "* We can use Distutils to compile and link extension modules reliably\n",
    "* First write a script `setup.py`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from distutils.core import setup, Extension\n",
    "\n",
    "name = \"hw\"      # name of the module\n",
    "version = \"1.0\"  # the module's version number\n",
    "\n",
    "setup(name=name, version=version,\n",
    "      ext_modules=[Extension(name='_hw', \n",
    "      # SWIG requires an underscore as a prefix for the module name\n",
    "             sources=[\"hw.i\", \"src/hw.c\"],\n",
    "             include_dirs=['src'])\n",
    "    ])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Building modules with Distutils (2)\n",
    "\n",
    "Now compile and install the module"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```bash\n",
    "# compile module\n",
    "python setup.py build_ext \n",
    "# install in the current directory\n",
    "python setup.py install --install-platlib=. \n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "and test with:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```bash\n",
    "python -c 'import hw'     # test module\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "*Note*:\n",
    "* You can install resulting module files in any directory (make sure that `PYHONPATH` points to it)\n",
    "* Use Distutils for professional distribution!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Testing our implementation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Recall:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```C\n",
    "void hw1(double r1, double r2, double *s)\n",
    "{\n",
    "  *s = sin(r1 + r2);\n",
    "}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Test:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```ipython\n",
    "from hw import hw1\n",
    "r1 = 1;  r2 = -1;  s = 10\n",
    "hw1(r1, r2, s)\n",
    ">>> TypeError: in method 'hw1', argument 3 of type 'double *'\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "**Upps!**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Specifying input/output arguments\n",
    "\n",
    "We need to adjust the SWIG interface file:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```C\n",
    "/* typemaps.i allows input and output pointer arguments to be specified using the names INPUT, OUTPUT, or INOUT */\n",
    "%include \"typemaps.i\"\n",
    "\n",
    "void   hw1(double r1, double r2, double *OUTPUT);\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now the usage from Python is"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```python\n",
    "s = hw1(r1, r2)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Other tools\n",
    "\n",
    "* [Boost](http://www.boost.org/doc/libs/1_62_0/libs/python/doc/html/index.html).Python: tool for wrapping C++ libraries\n",
    "* [PyCXX](http://cxx.sourceforge.net/): C++ facilitates to simplify interfacing C++ with Python\n",
    "* [Instant](https://bitbucket.org/fenics-project/instant): simple tools for inlining C and C++ code in Python scripts\n",
    "* [Cython](http://cython.org/) C-Extensions for Python\n",
    "\n",
    "Note: SWIG can generate interfaces to most scripting languages (Perl, Ruby, Tcl, Java, Guile, Mzscheme, ...)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Which tool should I use??\n",
    "<center>![Mixed Programming Python tools](python_integration_tools.svg \"Python\")</center>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Integrating Python with C++\n",
    "\n",
    "* SWIG supports C++"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "* The only difference is when we run SWIG (`-c++` option):"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "```bash\n",
    "swig -python -c++ -Isrc helloworld.i\n",
    "# generates wrapper code in helloworld_wrap.cxx\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Use a C++ compiler to compile and link:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```bash\n",
    "g++ -Isrc -fPIC -c $(pkg-config --cflags --libs python3) src/HelloWorld.cpp helloworld_wrap.cxx\n",
    "g++ -shared -o _helloworld.so HelloWorld.o helloworld_wrap.o\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Interfacing C++ functions (1)\n",
    "\n",
    "This is like interfacing C functions, except that pointers are usual replaced by references (less powerfull but safer)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```C++\n",
    "// C style\n",
    "void hw3(double r1, double r2, double *s)  \n",
    "{ *s = sin(r1 + r2); }\n",
    "\n",
    "// C++ style\n",
    "void hw4(double r1, double r2, double& s)  \n",
    "{ s = sin(r1 + r2); }\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Interfacing C++ functions (2)\n",
    "\n",
    "Interface file (`HelloWorld.i`):"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```C++\n",
    "%module helloworld\n",
    "%{\n",
    "#include \"src/HelloWorld.h\"\n",
    "%}\n",
    "\n",
    "\n",
    "%include \"typemaps.i\"\n",
    "\n",
    "/* The apply directive is used to change the datatype to OUTPUTs */\n",
    "%apply double *OUTPUT { double* s }\n",
    "%apply double *OUTPUT { double& s }\n",
    "%include \"src/HelloWorld.h\" \n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That's it!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "# Interfacing C++ classes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "* C++ classes add more to the SWIG integration story\n",
    "* Consider a class version of our Hello World module:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```C++\n",
    "/* file: src/HelloWorld.h */\n",
    "class HelloWorld\n",
    "{\n",
    " protected:\n",
    "  double r1, r2, s;\n",
    "  void compute();    // compute s=sin(r1+r2)\n",
    " public:\n",
    "  HelloWorld();\n",
    "  ~HelloWorld();\n",
    "\n",
    "  void set(double r1, double r2);\n",
    "  double get() const { return s; }\n",
    "  void message(std::ostream& out) const;\n",
    "};\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "* Goal: use this class as a Python class"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Function bodies and usage\n",
    "\n",
    "Function bodies:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```C++\n",
    "/* file: src/HelloWorld.cpp */\n",
    "void HelloWorld::set(double r1_, double r2_)\n",
    "{\n",
    "  r1 = r1_;  r2 = r2_;\n",
    "  compute();  // compute s\n",
    "}\n",
    "void HelloWorld::compute()\n",
    "{ s = sin(r1 + r2); }\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "etc."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "**Usage**:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```C++\n",
    "HelloWorld hw;\n",
    "hw.set(r1, r2);\n",
    "hw.message(std::cout);  // write \"Hello, World!\" message\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Adding a subclass\n",
    "\n",
    "To illustrate how to handle class hierarchies, we add a subclass:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```C++\n",
    "/* file: src/HelloWorld2.h */\n",
    "class HelloWorld2 : public HelloWorld\n",
    "{\n",
    " public:\n",
    "  void gets(double& s_) const;\n",
    "};\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```C++\n",
    "/* file: src/HelloWorld2.cpp */\n",
    "void HelloWorld2::gets(double& s_) const { s_ = s; }\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "That is, we have a function with an output argument"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "**Note**: `gets` should return the value when called from Python"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## SWIG interface file"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```C++\n",
    "/* file: helloworld.i */\n",
    "%module helloworld\n",
    "%{\n",
    "/* include C++ header files necessary to compile the interface */\n",
    "#include \"HelloWorld.h\"\n",
    "#include \"HelloWorld2.h\"\n",
    "%}\n",
    "\n",
    "%include \"src/HelloWorld.h\"\n",
    "\n",
    "%include \"typemaps.i\"\n",
    "%apply double* OUTPUT { double& s }\n",
    "%include \"HelloWorld2.h\"\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Adding a class method"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "* SWIG allows us to add class methods"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "* Calling `message` with standard output (`std::cout`) is tricky from Python so we add a `print` method for printing to `std.output`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "* `print` coincides with Python's keyword `print` so we follow the convention of adding an underscore:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "```C++\n",
    "%extend HelloWorld {\n",
    "    void print_() { self->message(std::cout); }\n",
    "}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "This is basically C++ syntax, but `self` is used instead of `this` and `%extend HelloWorld` is a SWIG directive"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Make and compile extension module"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "We can create a `setup.py` file for compiling and installing the module:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from distutils.core import setup, Extension\n",
    "\n",
    "name = \"helloworld\"    # name of the module\n",
    "version = \"1.0\"        # the module's version number\n",
    "\n",
    "setup(name=name, version=version,\n",
    "      # distutils detects .i files and compiles them automatically\n",
    "      ext_modules=[Extension(name='_helloworld', # SWIG requires _ as a prefix for the module name\n",
    "                             sources=[\"helloworld.i\", \n",
    "                                      \"src/HelloWorld.cpp\", \n",
    "                                      \"src/HelloWorld2.cpp\"],\n",
    "                             include_dirs=['src'],\n",
    "                             swig_opts=[\"-c++\"])\n",
    "    ])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Build and compile with:\n",
    "```bash\n",
    "python setup.py build_ext\n",
    "python setup.py install --install-platlib=.\n",
    "```\n",
    "The full example is available [here](https://github.com/UiO-INF3331/code-snippets-16)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Using the module"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from helloworld import HelloWorld, HelloWorld2\n",
    "\n",
    "hw = HelloWorld()     # make class instance\n",
    "hw.set(r1, r2)        # call instance method\n",
    "s = hw.get()\n",
    "hw.print_()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "hw2 = HelloWorld2()   # make subclass instance\n",
    "hw2.set(r1, r2)\n",
    "s = hw2.gets()        # original output arg. is now return value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Remark\n",
    "\n",
    "* It looks like if the C++ class hierarchy is mirrored in Python"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "* Actually, SWIG wraps a `function` interface to any class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import _helloworld   # use _helloworld.so directly\n",
    "hw = _helloworld.new_HelloWorld()\n",
    "_helloworld.HelloWorld_set(hw, r1, r2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "SWIG makes a proxy class in `helloworld.py`, mirroring the original C++ class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import helloworld    # use helloworld.py interface to _helloworld.so\n",
    "hw = helloworld.HelloWorld()\n",
    "hw.set(r1, r2)       # calls _hw.HelloWorld_set(r1, r2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "*Note:* The proxy class introduces some overhead"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "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.5.2"
  },
  "livereveal": {
   "scroll": true,
   "start_slideshow_at": "selected",
   "theme": "serif"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}