neopz-binding.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# NeoPZ Python binding with pybind11\n",
    "\n",
    "### Gustavo Batistela\n",
    "### 08/10/2019"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# What is pybind11?\n",
    "\n",
    "**pybind11** is a lightweight header-only library that exposes C++ types in Python and vice versa\n",
    "\n",
    "[https://pybind11.readthedocs.io](https://pybind11.readthedocs.io)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# What is pybind11 capable of binding?\n",
    "\n",
    "- Functions accepting and returning **custom data structures** per value, reference, or pointer\n",
    "- Overloaded functions\n",
    "- Instance methods and static methods and attributes\n",
    "- Enumerations\n",
    "- Custom operators\n",
    "- Single and multiple inheritance\n",
    "- STL data structures\n",
    "- And more...\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# A simple example\n",
    "\n",
    "\n",
    "```cpp\n",
    "#include <pybind11/pybind11.h>\n",
    "\n",
    "int add(int i, int j) {\n",
    "    return i + j;\n",
    "}\n",
    "\n",
    "PYBIND11_MODULE(example1, m) {\n",
    "    m.def(\"add\", &add);\n",
    "}\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on built-in function add in module example1:\n",
      "\n",
      "add(...) method of builtins.PyCapsule instance\n",
      "    add(arg0: int, arg1: int) -> int\n",
      "\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import example1\n",
    "help(example1.add)\n",
    "example1.add(1,2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# A *better documented* simple example\n",
    "\n",
    "\n",
    "```cpp\n",
    "#include <pybind11/pybind11.h>\n",
    "\n",
    "int add(int i, int j) {\n",
    "    return i + j;\n",
    "}\n",
    "\n",
    "PYBIND11_MODULE(example2, m) {\n",
    "    m.doc() = \"A documented example module\";\n",
    "    m.def(\"add\", &add, \"A function which adds two numbers\",\n",
    "          py::arg(\"i\"), py::arg(\"j\") = 11);\n",
    "}\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on built-in function add in module example2:\n",
      "\n",
      "add(...) method of builtins.PyCapsule instance\n",
      "    add(i: int, j: int = 11) -> int\n",
      "    \n",
      "    A function which adds two numbers\n",
      "\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import example2\n",
    "help(example2.add)\n",
    "example2.add(1, j =2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# The magic '\\_\\_repr\\_\\_' method\n",
    "\n",
    "```cpp\n",
    "struct Pet {\n",
    "    Pet(const std::string &name) : name(name) { }\n",
    "    void setName(const std::string &name_) { name = name_; }\n",
    "    const std::string &getName() const { return name; }\n",
    "\n",
    "    std::string name;\n",
    "};\n",
    "```\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# The magic '\\_\\_repr\\_\\_' method\n",
    "\n",
    "\n",
    "```cpp\n",
    "PYBIND11_MODULE(example1, m) {\n",
    "    m.def(\"add\", &add);\n",
    "    py::class_<Pet>(m, \"Pet\")\n",
    "            .def(py::init<const std::string &>())\n",
    "            .def(\"setName\", &Pet::setName)\n",
    "            .def(\"getName\", &Pet::getName);\n",
    "}\n",
    "```\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<example1.Pet object at 0x7f7910237298>\n"
     ]
    }
   ],
   "source": [
    "import example1 as ex1\n",
    "a = ex1.Pet(\"Amora\")\n",
    "print(a)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# The magic '\\_\\_repr\\_\\_' method\n",
    "\n",
    "```cpp\n",
    "PYBIND11_MODULE(example1, m) {\n",
    "    py::class_<Pet2>(m, \"Pet2\", \"A Pet class\")\n",
    "        .def(py::init<const std::string &>(), \"Pet constructor\", py::arg(\"name\"))\n",
    "        .def(\"setName\", &Pet2::setName, \"Sets pet name\", py::arg(\"name\"))\n",
    "        .def(\"getName\", &Pet2::getName, \"Reads pet name\")\n",
    "        .def(\"__repr__\", [](const Pet2& pet) {\n",
    "            std::string r = \"Pet2: \";\n",
    "            r += pet.getName();\n",
    "            return r;\n",
    "        }\n",
    "    );\n",
    "}\n",
    "```\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on class Pet2 in module example2:\n",
      "\n",
      "class Pet2(pybind11_builtins.pybind11_object)\n",
      " |  A Pet class\n",
      " |  \n",
      " |  Method resolution order:\n",
      " |      Pet2\n",
      " |      pybind11_builtins.pybind11_object\n",
      " |      builtins.object\n",
      " |  \n",
      " |  Methods defined here:\n",
      " |  \n",
      " |  __init__(...)\n",
      " |      __init__(self: example2.Pet2, name: str) -> None\n",
      " |      \n",
      " |      Pet constructor\n",
      " |  \n",
      " |  __repr__(...)\n",
      " |      __repr__(self: example2.Pet2) -> str\n",
      " |  \n",
      " |  getName(...)\n",
      " |      getName(self: example2.Pet2) -> str\n",
      " |      \n",
      " |      Reads pet name\n",
      " |  \n",
      " |  setName(...)\n",
      " |      setName(self: example2.Pet2, name: str) -> None\n",
      " |      \n",
      " |      Sets pet name\n",
      " |  \n",
      " |  ----------------------------------------------------------------------\n",
      " |  Methods inherited from pybind11_builtins.pybind11_object:\n",
      " |  \n",
      " |  __new__(*args, **kwargs) from pybind11_builtins.pybind11_type\n",
      " |      Create and return a new object.  See help(type) for accurate signature.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "import example2 as ex2\n",
    "a = ex2.Pet2(\"Amora\")\n",
    "help(example2.Pet2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# A NeoPZ case\n",
    "## Constructors\n",
    "\n",
    "### Original code\n",
    "```cpp\n",
    "\t/** @brief Constructor of the transformation with square matrix */\n",
    "\tTPZTransform(int dim);\n",
    "\t/** @brief Default constructor */\n",
    "\tTPZTransform();\n",
    "\t/** @brief Constructor of the transformation with rectangular matrix */\n",
    "\tTPZTransform(int fRow,int fCol);\n",
    "```\n",
    "### Python binding\n",
    "```cpp\n",
    "    py::class_<TPZTransform<double>>(m, \"TPZTransform\")\n",
    "        .def(py::init())\n",
    "        .def(py::init<int>())\n",
    "        .def(py::init<int, int>())\n",
    "        \n",
    "        ...\n",
    "```\n",
    "Constructor bindings are generated by `py::init()`\n",
    "\n",
    "Constructor overloading is done using the different parameters inside `<>`\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# A NeoPZ case\n",
    "## Class methods\n",
    "### Original code\n",
    "```cpp\n",
    "\t/** @brief Sets the transformation matrices */\n",
    "\tvoid SetMatrix(TPZFMatrix<T> &mult,TPZFMatrix<T> &sum);\n",
    "\t\n",
    "\t/** @brief Multiply the transformation object (to the right) with right (Multiplying matrices) */\n",
    "\tTPZTransform<T> Multiply(TPZTransform<T> &right);\n",
    "\t\n",
    "\t/** @brief Transforms the vector */\n",
    "\tvoid Apply(TPZVec<T> &vectorin,TPZVec<T> &vectorout);\n",
    "```\n",
    "### Python binding\n",
    "```cpp\n",
    "        .def(\"SetMatrix\", &TPZTransform<double>::SetMatrix)\n",
    "        .def(\"Multiply\", &TPZTransform<double>::Multiply)\n",
    "        .def(\"Apply\", &TPZTransform<double>::Apply)\n",
    "```\n",
    "\n",
    "In order to bind class methods, a reference to the function needs to be passed"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# A NeoPZ case\n",
    "## Class methods + Lambda expressions\n",
    "Sometimes it is preferred to define a *lambda expression* instead of passing a reference to an existing function:\n",
    "```cpp\n",
    "    // TPZManVector<double> bindings\n",
    "    py::class_<TPZManVector<double>>(m, \"TPZVecDouble\")\n",
    "        \n",
    "        ...\n",
    "        \n",
    "        // Lambda needed for index verification\n",
    "        .def(\"__getitem__\",\n",
    "             [](const TPZManVector<double>& vec, int64_t position) {\n",
    "                 if (position >= vec.size() || position < 0) throw py::index_error();\n",
    "                 return vec[position];\n",
    "             },\n",
    "             py::is_operator()\n",
    "        )\n",
    "        // Lambda needed since print function returning a std::string object does not exist in NeoPZ\n",
    "        .def(\"__repr__\",\n",
    "            [](TPZManVector<double>& vec) {\n",
    "               std::stringstream repr;\n",
    "               vec.Print(repr);\n",
    "               return repr.str();\n",
    "            }\n",
    "        )\n",
    "        \n",
    "        ...\n",
    "```\n",
    "\n",
    "**Note that this way of defining the *\\_\\_repr\\_\\_* method is very convenient.**\n",
    "\n",
    "**It reuses NeoPZ code and will not change across different classes since they all implement a Print(std::ostream) method.**\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# A NeoPZ case\n",
    "## Overloading methods\n",
    "### Original code\n",
    "```cpp\n",
    "\t\t/** @brief Get all sides with lower dimension on side */\t\n",
    "\t\tstatic void LowerDimensionSides(int side,TPZStack<int> &smallsides);\n",
    "\t\t/** @brief Get all sides with lower dimension but equal to DimTarget on side */\n",
    "\t\tstatic void LowerDimensionSides(int side,TPZStack<int> &smallsides, int DimTarget);\n",
    "```\n",
    "### Python binding\n",
    "```cpp\n",
    "    // TPZPrism bindings\n",
    "    py::class_<pztopology::TPZPrism>(m, \"TPZPrism\")\n",
    "        \n",
    "        ...\n",
    "        \n",
    "        .def_static(\"LowerDimensionSides\",\n",
    "            py::overload_cast<int, TPZStack<int> &>(&pztopology::TPZPrism::LowerDimensionSides))\n",
    "        .def_static(\"LowerDimensionSides\", \n",
    "            py::overload_cast<int, TPZStack<int> &, int>(&pztopology::TPZPrism::LowerDimensionSides))\n",
    "        \n",
    "        ...\n",
    "```\n",
    "Class methods are overloaded using `py::overload_cast<>` and declaring the different parameters inside `<>`.\n",
    "\n",
    "Static methods are generated by using `.def_static` instead of `.def` (nearly all Topology methods are bound this way)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# A NeoPZ case\n",
    "## Overloading methods II\n",
    "### Original code\n",
    "```cpp\n",
    "\tconst TPZFMatrix<T>  & Mult() const {return fMult;}\n",
    "\t\n",
    "\tTPZFMatrix<T>  & Mult() {return fMult;}\n",
    "```\n",
    "### Python binding\n",
    "```cpp\n",
    "        .def(\"Mult\", py::overload_cast<>(&TPZTransform<double>::Mult))\n",
    "        .def(\"Mult\", py::overload_cast<>(&TPZTransform<double>::Mult, py::const_))\n",
    "```\n",
    "Methods that are overloaded by *constness* require `py::const_` at the end."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# A NeoPZ case\n",
    "## Class members\n",
    "\n",
    "It's possible to \"*bind*\" class members by passing a reference to the getter and setter function.\n",
    "\n",
    "```cpp\n",
    "        .def_property_readonly(\"fMult\", py::overload_cast<>(&TPZTransform<double>::Mult))\n",
    "        .def_property_readonly(\"fSum\", py::overload_cast<>(&TPZTransform<double>::Sum))\n",
    "```\n",
    "\n",
    "This makes possible to call:\n",
    "```python\n",
    "    a = TPZTransform.fMult\n",
    "```\n",
    "Instead of\n",
    "```python\n",
    "    a = TPZTransform.Mult()\n",
    "```\n",
    "\n",
    "Not much of a difference though."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {
    "scrolled": false,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Testing quadrilateral NumSides and NSideNodes\n",
      "\n",
      "1\n",
      "1\n",
      "1\n",
      "2\n",
      "2\n",
      "2\n",
      "3\n"
     ]
    }
   ],
   "source": [
    "from neopz import *\n",
    "\n",
    "print(\"Testing quadrilateral NumSides and NSideNodes\\n\")\n",
    "for sideId in range(TPZTriangle.NumSides()):\n",
    "    print(TPZTriangle.NSideNodes(sideId))\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {
    "scrolled": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "TPZTransform\n",
      "  Mult '(1 x 2)' = [\n",
      "\t2.000000  0.000000  \n",
      "]\n",
      "  Sum'(1 x 1)' = [\n",
      "\t-1.000000  \n",
      "]\n"
     ]
    }
   ],
   "source": [
    "from neopz import *\n",
    "\n",
    "\n",
    "trans = TPZTriangle.SideToSideTransform(TPZTriangle.NumSides() - 1, 3)\n",
    "print(trans)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "scrolled": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Testing container classes\n",
      "\n",
      "TPZMatrix '(2 x 1)' = [\n",
      "\t1.000000  \n",
      "\t1.000000  \n",
      "]\n",
      "TPZMatrix '(1 x 3)' = [\n",
      "\t0.000000  -1.000000  1.000000  \n",
      "]\n",
      "\n",
      "Number of elements = 3\n"
     ]
    }
   ],
   "source": [
    "from neopz import *\n",
    "\n",
    "print(\"\\nTesting container classes\\n\")\n",
    "\n",
    "matrix = TPZMatrix(2, 1, 1.)\n",
    "print(matrix)\n",
    "\n",
    "matrix = TPZTetrahedron.SideToSideTransform(TPZTetrahedron.NumSides() - 1, 9).Mult()\n",
    "print(matrix)\n",
    "\n",
    "vec = TPZVecDouble(3, 1.)\n",
    "print(vec)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# An important remark\n",
    "\n",
    "You don't need to implement *every* method of a class to make it visible in python.\n",
    "\n",
    "In fact you don't need **any** method to be implemented.\n",
    "\\\n",
    "\\\n",
    "\\\n",
    "If you are only interested in returning an object from a first method and then passing as argument to a second method, the following line will suffice:\n",
    "\n",
    "```cpp\n",
    "py::class_<TPZStack<int>>(m, \"TPZStackInt\");\n",
    "```\n",
    "\n",
    "If somehow the object also needs to be **initialized** in Python, you'll aditionally have to bind one constructor. But nothing more than that...\n",
    "```cpp\n",
    "py::class_<TPZStack<int>>(m, \"TPZStackInt\")\n",
    "    .def(py::init());\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# An important remark\n",
    "\n",
    "Alright, alright, maybe being able to print the object would be nice:\n",
    "```cpp\n",
    "    .def(\"__repr__\",\n",
    "        [](const TPZStack<int>& stack) {\n",
    "            std::string r(\"TPZStackInt [\");\n",
    "            for (int i = 0; i < stack.NElements(); i++) {\n",
    "                r += std::to_string(stack[i]);\n",
    "                if (i != stack.NElements() - 1) {\n",
    "                    r += \", \";\n",
    "                }\n",
    "            }\n",
    "            r += \"]\";\n",
    "            return r;\n",
    "        }\n",
    "    )\n",
    "```\n",
    "\n",
    "In this example I didn't use the Print method available in NeoPZ. As I said before, _very inconvenient_...\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "scrolled": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "TPZStackInt []\n",
      "TPZStackInt [0, 1, 2, 3, 4, 5]\n"
     ]
    }
   ],
   "source": [
    "from neopz import *\n",
    "\n",
    "stack = TPZStackInt()\n",
    "print(stack)\n",
    "TPZTriangle.LowerDimensionSides(6, stack)\n",
    "print(stack)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Obrigado!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.6.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}