embedded-languages-via-overloading.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Embedded Languages via Overloading"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Suppose you are creating a Python library for building logical circuits. You would like programmers to be able to build circuits that correspond to more complex, high-level functions (*e.g.*, from equality of bit vectors to entire hashing functions). How should you approach this task? What are the right abstractions? How can you minimize the amount of extra effort programmers must put into learning your library and its various interfaces?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Python's operator overloading features are not just a way to add syntactic convenience to your data structures. By leveraging this feature in the right way, you can greatly reduce the *conceptual* complexity of a solution by allowing programmers to use the skills they already possess. This article reviews a use case that demonstrates the value of recasting a solution as an *embedded language* within the Python syntax."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Operator Overloading"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Python allows programmers to change the meaning of some of its syntactic constructs when these constructs are applied to objects of programmer-defined classes (the definition of Python's syntax is discussed in more detail in a [previous article](https://python.supply/analyzing-and-transforming-abstract-syntax)). Programmers can do so by defining [special methods](https://docs.python.org/3/reference/datamodel.html) within a class definition. When the Python interpreter sees a certain operator (such as `+`) being applied to objects of a class that has such a special method defined (such as [`__add__`](https://docs.python.org/3/reference/datamodel.html#object.__add__)), the interpreter will invoke that method."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "In the example below, the class `vector` allows users to build objects that represent two-dimensional vectors. The class definition has a method [`__eq__`](https://docs.python.org/3/reference/datamodel.html#object.__eq__)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "class vector():\n",
    "    def __init__(self, *coordinates):\n",
    "        self.coordinates = coordinates\n",
    "\n",
    "    def __eq__(self, other):\n",
    "        return self.coordinates == other.coordinates"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "The method `__eq__` is invoked when two `vector` objects are supplied to the infix `==` operator."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(False, True)"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v = vector(1,2)\n",
    "w = vector(3,4)\n",
    "(v == w, v == v)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Embedded Language for Boolean Circuits"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "An *embedded language* is a specified subset of an existing programming language (which can be called the *host* language) that serves some distinct purpose. An important benefit of embedded languages is that they reuse the existing features of the host language, which can save both implementation effort and the barrier to entry for users of the embedded language."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Returning to the motivating use case of implementing a library for logical circuits, you might consider that a Python programmer using your library *already knows how to use Python to implement a logical circuit*. Therefore, any effort the programmer spends learning to use your library is potentially wasted. How might such a programmer implement a circuit they want to evaluate on inputs?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "For the purposes of this example, assume that the programmer represents bits using the Python integers `0` and `1`. One approach the programmer might use is to define a function that operates on integers and uses Python's built-in logical operators on integer values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "def equal(x, y):\n",
    "    return (x & y) | ((1 - x) & (1 - y))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Below are two approaches a Python programmer might use (the first being an imperative style and the second being a functional style) to implement an equality function `equals` for *bit vectors* using the equality function `equal` for bits that is defined above. You would like your circuit library to accommodate all of these different approaches (because these approaches reflect different trade-offs that might be suitable for different use cases, or simply because programmers might have different preferences or levels of experience with Python)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "def equals(xs, ys):\n",
    "    z = 1\n",
    "    for i in range(len(xs)):\n",
    "        z = z & equal(xs[i], ys[i])\n",
    "    return z\n",
    "\n",
    "def equals(xs, ys):\n",
    "    from functools import reduce\n",
    "    es = [equal(x, y) for (x, y) in zip(xs, ys)]\n",
    "    return reduce((lambda e0, e1: e0 & e1), es)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Under its usual interpretation in Python (*i.e.*, when it is applied to lists of integers), the `equals` function can be used to determine the equality of bit vectors of equal length."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "equals([0,1,1], [0,1,1])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Using overloading, it is possible to provide new definitions for the built-in `&`, `|` and `-` operators that *programmers already used* to define the `equal` and `equals` functions. The `circuit` class definition below includes the [`__or__`](https://docs.python.org/3/reference/datamodel.html#object.__or__), [`__and__`](https://docs.python.org/3/reference/datamodel.html#object.__and__), and [`__rsub__`](https://docs.python.org/3/reference/datamodel.html#object.__rsub__) methods that correspond to the way in which these three infix operators are used."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "class circuit():\n",
    "    def __init__(self, op='bit', args=None):\n",
    "        self.op = op\n",
    "        self.args = [] if args is None else args\n",
    "\n",
    "    def __or__(self, other):\n",
    "        return circuit('or', [self, other])\n",
    "\n",
    "    def __and__(self, other):\n",
    "        return circuit('and', [self, other])\n",
    "\n",
    "    def __rsub__(self, other):\n",
    "        if not isinstance(other, int) or other != 1:\n",
    "            raise ValueError('can only subtract from 1')\n",
    "        return circuit('not', [self])\n",
    "\n",
    "    def __repr__(self):\n",
    "        return 'circuit(\"' + self.op + '\", ' + str(self.args) + ')'\n",
    "\n",
    "    def __str__(self):\n",
    "        return self.__repr__()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "To make it easier to see the circuits after they have been constructed, the definition above also includes a recursive [`__repr__`](https://docs.python.org/3/reference/datamodel.html#object.__repr__) method and an equivalent [`__str__`](https://docs.python.org/3/reference/datamodel.html#object.__str__) method. The first method is invoked when Python attempts to display an object of the class (*e.g.*, in an interactive prompt) and the second is invoked when the built-in Python [`str`](https://docs.python.org/3/library/stdtypes.html#str) function is applied to an object of the class `circuit`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "A programmer can now build a circuit using familiar infix operators. The only difference is that instead of using Python integers to represent the bits that constitute the inputs (*i.e.*, base cases), programmers can use `circuit` objects that represent bit constants."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "c0 = circuit(\"bit\", 0)\n",
    "c1 = circuit(\"bit\", 1)\n",
    "c2 = 1 - (c0 & c1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "More importantly, programmers can now *reuse without modification* the equality functions that have already been defined. However, those same functions now generate entire equality circuits (rather than only computing the result of evaluating those circuits)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "circuit(\"or\", [circuit(\"and\", [circuit(\"bit\", 1), circuit(\"not\", [circuit(\"and\", [circuit(\"bit\", 0), circuit(\"bit\", 1)])])]), circuit(\"and\", [circuit(\"not\", [circuit(\"bit\", 1)]), circuit(\"not\", [circuit(\"not\", [circuit(\"and\", [circuit(\"bit\", 0), circuit(\"bit\", 1)])])])])])"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "equal(c1, c2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Even the more complex `equals` method works seamlessly whether it is given lists of bit vectors or lists of base case circuits."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "circuit(\"and\", [circuit(\"or\", [circuit(\"and\", [circuit(\"bit\", 0), circuit(\"bit\", 0)]), circuit(\"and\", [circuit(\"not\", [circuit(\"bit\", 0)]), circuit(\"not\", [circuit(\"bit\", 0)])])]), circuit(\"or\", [circuit(\"and\", [circuit(\"bit\", 1), circuit(\"bit\", 1)]), circuit(\"and\", [circuit(\"not\", [circuit(\"bit\", 1)]), circuit(\"not\", [circuit(\"bit\", 1)])])])])"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "equals([c0, c1], [c0, c1])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Portable or Specialized Embeddings via Inheritance"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "The advantage of the definition of `circuit` in the section above is that programmers can *build* new circuits using existing built-in Python operators. However, in order to *inspect* or *traverse* the circuit data structure, programmers must become familiar with your class definition. Using [inheritance](https://docs.python.org/3/tutorial/classes.html#inheritance), you can address this second obstacle."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "The variant of the `circuit` class below represents circuits as dictionaries (or, more precisely, as objects of classes that inherit all the features of dictionaries)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "class circuit(dict):\n",
    "    def __or__(self, other):\n",
    "        return circuit({'or': [self, other]})\n",
    "\n",
    "    def __and__(self, other):\n",
    "        return circuit({'and': [self, other]})\n",
    "\n",
    "    def __rsub__(self, other):\n",
    "        if not isinstance(other, int) or other != 1:\n",
    "            raise ValueError('can only subtract from 1')\n",
    "        return circuit({'not': [self]})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Because circuits built by programmers are now also dictionaries, it is easier to use existing built-in libraries to perform common operations. For example, a formatted JSON string representation of a circuit can be emitted using the [json](https://docs.python.org/3/library/json.html) library. In the example below, a JSON representation of the bit vector equality circuit is constructed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\"and\": [{\"or\": [{\"and\": [{\"bit\": 0}, {\"bit\": 0}]}, {\"and\": [{\"not\": [{\"bit\": 0}]}, {\"not\": [{\"bit\": 0}]}]}]}, {\"or\": [{\"and\": [{\"bit\": 1}, {\"bit\": 1}]}, {\"and\": [{\"not\": [{\"bit\": 1}]}, {\"not\": [{\"bit\": 1}]}]}]}]}\n"
     ]
    }
   ],
   "source": [
    "c0 = circuit({\"bit\": 0})\n",
    "c1 = circuit({\"bit\": 1})\n",
    "import json\n",
    "print(json.dumps(equals([c0, c1], [c0, c1])))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "For another example of this approach that is more specialized, consider the `circuit` class below that is derived from the [`Graph`](https://networkx.org/documentation/networkx-1.7/reference/classes.graph.html) class in the [NetworkX](https://networkx.org) library. In this implementation, each `circuit` object is a graph in which nodes correspond to base cases or operations and edges connect operation nodes with their operands. The method corresponding to a binary operator such as `&` performs the following steps:\n",
    "\n",
    "* it accepts two input graphs (each representing an entire circuit, with the output node as the first entry in its node list),\n",
    "* it combines these two graphs into a new graph in which each node's name is extended to reflect the path to that node,\n",
    "* it adds a new node corresponding to the binary operation, and\n",
    "* it adds edges between this new output node and the root nodes of the two input graphs.\n",
    "\n",
    "Note that in order to have mathematical notation within the node labels in the final rendering of the circuit, the [LaTeX](https://en.wikipedia.org/wiki/LaTeX) notation is used for the operator name strings."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "from networkx import Graph, union\n",
    "\n",
    "class circuit(Graph):\n",
    "    def __init__(self, arg=None):\n",
    "        Graph.__init__(self)\n",
    "        if arg is not None:\n",
    "            self.add_nodes_from([str(arg)])\n",
    "\n",
    "    def __or__(self, other):\n",
    "        c = union(\n",
    "            circuit(\"$\\\\vee$\"),\n",
    "            union(self, other, rename=(\"l-\", \"r-\"))\n",
    "        )\n",
    "        c.add_edges_from([\n",
    "            (\"$\\\\vee$\", \"l-\" + list(self.nodes)[0]),\n",
    "            (\"$\\\\vee$\", \"r-\" + list(other.nodes)[0])\n",
    "        ])\n",
    "        return c\n",
    "\n",
    "    def __and__(self, other):\n",
    "        c = union(\n",
    "            circuit(\"$\\\\wedge$\"),\n",
    "            union(self, other, rename=(\"l-\", \"r-\"))\n",
    "        )\n",
    "        c.add_edges_from([\n",
    "            (\"$\\\\wedge$\", \"l-\" + list(self.nodes)[0]),\n",
    "            (\"$\\\\wedge$\", \"r-\" + list(other.nodes)[0])\n",
    "        ])\n",
    "        return c\n",
    "\n",
    "    def __rsub__(self, other):\n",
    "        if not isinstance(other, int) or other != 1:\n",
    "            raise ValueError('can only subtract from 1')\n",
    "        c = union(circuit(\"$\\\\neg$\"), self, rename=(\"\", \"n-\"))\n",
    "        c.add_edges_from([(\"$\\\\neg$\", \"n-\"+list(self.nodes)[0])])\n",
    "        return c"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "This approach makes it possible to render a graph diagram directly from a `circuit` object using the NetworkX library. To demonstrate how a programmer can accomplish this, consider the following circuit `c` built using the original `equals` method (note that it has been unmodified and yet works with objects of the newest variant of `circuit`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "c = equals(\n",
    "    [circuit('$x_0$'), circuit('$x_1$')], \n",
    "    [circuit('$y_0$'), circuit('$y_1$')]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Because `c` inherits all the features of a NetworkX `Graph` object, a programmer can inspect its nodes and edges. In the example below, the last three nodes and the number of edges in the circuit graph are extracted. Notice that each node name is a string that describes the path to that node from the circuit's overall output node (with `'l'` and `'r'` representing left-hand and right-hand subgraphs, respectively)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(['r-r-l-n-$x_1$', 'r-r-r-$\\\\neg$', 'r-r-r-n-$y_1$'], 18)"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(list(c.nodes)[-3:], len(c.edges))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "The following function is convenient for rendering the graph. It takes a node name string, splits it into its constituent parts (representing the path from the output node), and calculates a horizontal and vertical coordinate for that node."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "def position(n):\n",
    "    # Generate coordinates based on the path\n",
    "    # encoded in the node name.\n",
    "    x = sum(\n",
    "        {'l':-1, 'r':1}.get(c, 0)/(2**(i+3)) \n",
    "        for (i, c) in enumerate(n.split('-'))\n",
    "    )\n",
    "    y = n.count('-')/8\n",
    "    return (x, y)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "With the help of the position function, rendering the circuit `c` as a graph is straightforward using the [`draw_networkx`](https://networkx.org/documentation/latest/reference/generated/networkx.drawing.nx_pylab.draw_networkx) function. The positions for the rendered nodes are specified by building a dictionary using `position` and the labels for the rendered nodes are obtained by taking the last component of the node names in `c`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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S7EsO6J51Kkr6a3Ugf1jx5n2799Phw4d6Nu3L6NGjbIouLmmT5/OAw88QEFBAU2aNDnxDQvmJ2lYMDcHDx6kc+fOdO/enaefftqi4OaaPXs2+fn5LFiwgEsuueTEN6R2TqNp2nJd1/Mq/d4Z03SP21eoFror+VBduShUVvnFmTWf+vhh+Ig6ObvZUHXKzCl27NhB+/btGTZsGPfee68N/wHj5s2bR//+/fn0009p0aJF5XcyeX6Sislzs2fPHjp06EB+fj4PP+zsc1ELCgro3bs3s2fPpnXr1pXfSWrnZ9J0KxMsVesu7VumrkpfvlMVgSdVXdEoq5N69s1o86ufhtmyZQsdOnTgueee4/bbb7clfqwWLVpEz549mTFjBu3atfv1DUycn6Rj4txs27aN9u3b8/jjj/OHP/zBlvixKiwspHv37rz77rt07tz51zeQ2onadNF1PeJXbm6uLqpmzZo1+jnnnKPPnj070VFOs3LlSj0zM1OfN29eoqOISmzcuFGvV6+ePn369ERHOc26dev0c889V58xY0aio7gKUKhH6KvSdE309ddf65mZmfrChQsTHeVnGzZs0OvVq6e/9957iY4iovj222/1rKwsRz0xbt26VT///PP1N954I9FRXEearo0WLFigZ2Zm6oWFhYmOov/www96gwYN9FdffTXRUUQVfPXVV3pmZqa+aNGiREfRd+7cqTdu3FifNGlSoqO4UrSmm9ynjCVA586dmTp1Kj169KCoqChhOfbs2cO1117L4MGDHXusUJysXbt2/N///R+9evVi1apVCctx4MABunTpQv/+/Rk8eHDCciQraboWuOmmm3jmmWfo2rUr33//ve3jHzx4kOuuu45bbrnF8e+Ki5N17dqVv/71r3Tr1o3i4mLbxy8rK+P666/nmmuu4bHHHrN9/DNBcq0c4SD9+/fn4MGDXHvttXz55Zece+650TcIlsLeJcfe8S1QS17rQbUgoL++Wi4lvZW6mHSUd3zLy8u58cYbueKKK1xz/qc4We/evX+una+++ors7OzoG5hUO0eOHKFXr140a9aMCRMmoCXxBxQSSZquhQYPHsyBAwfo2rUrCxcupE6dOqffaV8hFE2AkhngTYFQ4PRzG39aD7u/UMulVAQhu6e6xugp5zYePXqU3r17c/755zNp0iT5oXGx/Pz8nxvvF198QWZm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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from networkx import draw_networkx\n",
    "draw_networkx(\n",
    "    c,\n",
    "    pos=dict((n, position(n)) for n in c.nodes),\n",
    "    labels=dict((n, n.split('-')[-1]) for n in c.nodes),\n",
    "    node_size=1000,\n",
    "    node_color=\"orange\"\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Further Reading"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "This article presented a brief overview of [operator overloading in Python](https://docs.python.org/3/reference/datamodel.html#special-method-names), with a motivating example involving a number of [embedded domain-specific languages](https://en.wikipedia.org/wiki/Domain-specific_language#External_and_Embedded_Domain_Specific_Languages) for defining circuits. A Python library that addresses exactly the same circuit construction use case considered in this article is [circuitry](https://pypi.org/project/circuitry/), which defines an embedded language for constructing circuits as defined in the [circuit](https://pypi.org/project/circuit/) library. Other examples of feature-rich and widely used domain-specific languages embedded inside Python include the [Django](https://www.djangoproject.com/) web framework and the [pandas](https://pandas.pydata.org/) data analysis library. However, even small built-in libraries such as [typing](https://docs.python.org/3/library/typing.html) use operator overloading to provide a more streamlined experience for programmers.\n",
    "\n",
    "Many other programming languages support some form of [operator overloading](https://en.wikipedia.org/wiki/Operator_overloading), as well as the introduction of custom infix, prefix, and even postfix operators. [Some languages](https://en.wikipedia.org/wiki/Operator_overloading#Catalog) have both of these features. A more general term for the operator overloading capability is [*ad hoc polymorphism*](https://en.wikipedia.org/wiki/Ad_hoc_polymorphism): the ability to provide multiple definitions for the same syntactic construct (with either the interpreter or compiler determining which definition to use based on the types of the inputs). Other, distinct types of polymorphism exist as well, such as [*parametric polymorphism*](https://en.wikipedia.org/wiki/Parametric_polymorphism): the ability to apply exactly the same function (having the same syntactic definition) to arguments of different types. You might notice that the definitions of `equal` and `equals` in this article are actually examples of parametric polymorphism."
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "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.8.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}