search.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "# Solving problems by Searching\n",
    "\n",
    "This notebook serves as supporting material for topics covered in **Chapter 3 - Solving Problems by Searching** and **Chapter 4 - Beyond Classical Search** from the book *Artificial Intelligence: A Modern Approach.* This notebook uses implementations from [search.py](https://github.com/aimacode/aima-python/blob/master/search.py) module. Let's start by importing everything from search module."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true,
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "from search import *\n",
    "from notebook import psource\n",
    "\n",
    "# Needed to hide warnings in the matplotlib sections\n",
    "import warnings\n",
    "warnings.filterwarnings(\"ignore\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## CONTENTS\n",
    "\n",
    "* Overview\n",
    "* Problem\n",
    "* Search Algorithms Visualization\n",
    "* Breadth-First Tree Search\n",
    "* Breadth-First Search\n",
    "* Uniform Cost Search\n",
    "* A\\* Search\n",
    "* Best First Search\n",
    "* Genetic Algorithm"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## OVERVIEW\n",
    "\n",
    "Here, we learn about problem solving. Building goal-based agents that can plan ahead to solve problems, in particular, navigation problem/route finding problem. First, we will start the problem solving by precisely defining **problems** and their **solutions**. We will look at several general-purpose search algorithms. Broadly, search algorithms are classified into two types:\n",
    "\n",
    "* **Uninformed search algorithms**: Search algorithms which explore the search space without having any information about the problem other than its definition.\n",
    "* Examples:\n",
    "    1. Breadth First Search\n",
    "    2. Depth First Search\n",
    "    3. Depth Limited Search\n",
    "    4. Iterative Deepening Search\n",
    "\n",
    "\n",
    "* **Informed search algorithms**: These type of algorithms leverage any information (heuristics, path cost) on the problem to search through the search space to find the solution efficiently.\n",
    "* Examples:\n",
    "    1. Best First Search\n",
    "    2. Uniform Cost Search\n",
    "    3. A\\* Search\n",
    "    4. Recursive Best First Search\n",
    "\n",
    "*Don't miss the visualisations of these algorithms solving the route-finding problem defined on Romania map at the end of this notebook.*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## PROBLEM\n",
    "\n",
    "Let's see how we define a Problem. Run the next cell to see how abstract class `Problem` is defined in the search module."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%psource Problem"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `Problem` class has six methods.\n",
    "\n",
    "* `__init__(self, initial, goal)` : This is what is called a `constructor` and is the first method called when you create an instance of the class. `initial` specifies the initial state of our search problem. It represents the start state from where our agent begins its task of exploration to find the goal state(s) which is given in the `goal` parameter.\n",
    "\n",
    "\n",
    "* `actions(self, state)` : This method returns all the possible actions agent can execute in the given state `state`.\n",
    "\n",
    "\n",
    "* `result(self, state, action)` : This returns the resulting state if action `action` is taken in the state `state`. This `Problem` class only deals with deterministic outcomes. So we know for sure what every action in a state would result to.\n",
    "\n",
    "\n",
    "* `goal_test(self, state)` : Given a graph state, it checks if it is a terminal state. If the state is indeed a goal state, value of `True` is returned. Else, of course, `False` is returned.\n",
    "\n",
    "\n",
    "* `path_cost(self, c, state1, action, state2)` : Return the cost of the path that arrives at `state2` as a result of taking `action` from `state1`, assuming total cost of `c` to get up to `state1`.\n",
    "\n",
    "\n",
    "* `value(self, state)` : This acts as a bit of extra information in problems where we try to optimise a value when we cannot do a goal test."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will use the abstract class `Problem` to define our real **problem** named `GraphProblem`. You can see how we define `GraphProblem` by running the next cell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%psource GraphProblem"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now it's time to define our problem. We will define it by passing `initial`, `goal`, `graph` to `GraphProblem`. So, our problem is to find the goal state starting from the given initial state on the provided graph. Have a look at our romania_map, which is an Undirected Graph containing a dict of nodes as keys and neighbours as values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "romania_map = UndirectedGraph(dict(\n",
    "    Arad=dict(Zerind=75, Sibiu=140, Timisoara=118),\n",
    "    Bucharest=dict(Urziceni=85, Pitesti=101, Giurgiu=90, Fagaras=211),\n",
    "    Craiova=dict(Drobeta=120, Rimnicu=146, Pitesti=138),\n",
    "    Drobeta=dict(Mehadia=75),\n",
    "    Eforie=dict(Hirsova=86),\n",
    "    Fagaras=dict(Sibiu=99),\n",
    "    Hirsova=dict(Urziceni=98),\n",
    "    Iasi=dict(Vaslui=92, Neamt=87),\n",
    "    Lugoj=dict(Timisoara=111, Mehadia=70),\n",
    "    Oradea=dict(Zerind=71, Sibiu=151),\n",
    "    Pitesti=dict(Rimnicu=97),\n",
    "    Rimnicu=dict(Sibiu=80),\n",
    "    Urziceni=dict(Vaslui=142)))\n",
    "\n",
    "romania_map.locations = dict(\n",
    "    Arad=(91, 492), Bucharest=(400, 327), Craiova=(253, 288),\n",
    "    Drobeta=(165, 299), Eforie=(562, 293), Fagaras=(305, 449),\n",
    "    Giurgiu=(375, 270), Hirsova=(534, 350), Iasi=(473, 506),\n",
    "    Lugoj=(165, 379), Mehadia=(168, 339), Neamt=(406, 537),\n",
    "    Oradea=(131, 571), Pitesti=(320, 368), Rimnicu=(233, 410),\n",
    "    Sibiu=(207, 457), Timisoara=(94, 410), Urziceni=(456, 350),\n",
    "    Vaslui=(509, 444), Zerind=(108, 531))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "It is pretty straightforward to understand this `romania_map`. The first node **Arad** has three neighbours named **Zerind**, **Sibiu**, **Timisoara**. Each of these nodes are 75, 140, 118 units apart from **Arad** respectively. And the same goes with other nodes.\n",
    "\n",
    "And `romania_map.locations` contains the positions of each of the nodes. We will use the straight line distance (which is different from the one provided in `romania_map`) between two cities in algorithms like A\\*-search and Recursive Best First Search.\n",
    "\n",
    "**Define a problem:**\n",
    "Hmm... say we want to start exploring from **Arad** and try to find **Bucharest** in our romania_map. So, this is how we do it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "romania_problem = GraphProblem('Arad', 'Bucharest', romania_map)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Romania Map Visualisation\n",
    "\n",
    "Let's have a visualisation of Romania map [Figure 3.2] from the book and see how different searching algorithms perform / how frontier expands in each search algorithm for a simple problem named `romania_problem`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Have a look at `romania_locations`. It is a dictionary defined in search module. We will use these location values to draw the romania graph using **networkx**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'Oradea': (131, 571), 'Eforie': (562, 293), 'Timisoara': (94, 410), 'Hirsova': (534, 350), 'Bucharest': (400, 327), 'Rimnicu': (233, 410), 'Fagaras': (305, 449), 'Lugoj': (165, 379), 'Giurgiu': (375, 270), 'Mehadia': (168, 339), 'Pitesti': (320, 368), 'Drobeta': (165, 299), 'Craiova': (253, 288), 'Sibiu': (207, 457), 'Iasi': (473, 506), 'Urziceni': (456, 350), 'Vaslui': (509, 444), 'Neamt': (406, 537), 'Zerind': (108, 531), 'Arad': (91, 492)}\n"
     ]
    }
   ],
   "source": [
    "romania_locations = romania_map.locations\n",
    "print(romania_locations)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's start the visualisations by importing necessary modules. We use networkx and matplotlib to show the map in the notebook and we use ipywidgets to interact with the map to see how the searching algorithm works."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "import networkx as nx\n",
    "import matplotlib.pyplot as plt\n",
    "from matplotlib import lines\n",
    "\n",
    "from ipywidgets import interact\n",
    "import ipywidgets as widgets\n",
    "from IPython.display import display\n",
    "import time"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's get started by initializing an empty graph. We will add nodes, place the nodes in their location as shown in the book, add edges to the graph."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# initialise a graph\n",
    "G = nx.Graph()\n",
    "\n",
    "# use this while labeling nodes in the map\n",
    "node_labels = dict()\n",
    "# use this to modify colors of nodes while exploring the graph.\n",
    "# This is the only dict we send to `show_map(node_colors)` while drawing the map\n",
    "node_colors = dict()\n",
    "\n",
    "for n, p in romania_locations.items():\n",
    "    # add nodes from romania_locations\n",
    "    G.add_node(n)\n",
    "    # add nodes to node_labels\n",
    "    node_labels[n] = n\n",
    "    # node_colors to color nodes while exploring romania map\n",
    "    node_colors[n] = \"white\"\n",
    "\n",
    "# we'll save the initial node colors to a dict to use later\n",
    "initial_node_colors = dict(node_colors)\n",
    "    \n",
    "# positions for node labels\n",
    "node_label_pos = { k:[v[0],v[1]-10]  for k,v in romania_locations.items() }\n",
    "\n",
    "# use this while labeling edges\n",
    "edge_labels = dict()\n",
    "\n",
    "# add edges between cities in romania map - UndirectedGraph defined in search.py\n",
    "for node in romania_map.nodes():\n",
    "    connections = romania_map.get(node)\n",
    "    for connection in connections.keys():\n",
    "        distance = connections[connection]\n",
    "\n",
    "        # add edges to the graph\n",
    "        G.add_edge(node, connection)\n",
    "        # add distances to edge_labels\n",
    "        edge_labels[(node, connection)] = distance"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# initialise a graph\n",
    "G = nx.Graph()\n",
    "\n",
    "# use this while labeling nodes in the map\n",
    "node_labels = dict()\n",
    "# use this to modify colors of nodes while exploring the graph.\n",
    "# This is the only dict we send to `show_map(node_colors)` while drawing the map\n",
    "node_colors = dict()\n",
    "\n",
    "for n, p in romania_locations.items():\n",
    "    # add nodes from romania_locations\n",
    "    G.add_node(n)\n",
    "    # add nodes to node_labels\n",
    "    node_labels[n] = n\n",
    "    # node_colors to color nodes while exploring romania map\n",
    "    node_colors[n] = \"white\"\n",
    "\n",
    "# we'll save the initial node colors to a dict to use later\n",
    "initial_node_colors = dict(node_colors)\n",
    "    \n",
    "# positions for node labels\n",
    "node_label_pos = { k:[v[0],v[1]-10]  for k,v in romania_locations.items() }\n",
    "\n",
    "# use this while labeling edges\n",
    "edge_labels = dict()\n",
    "\n",
    "# add edges between cities in romania map - UndirectedGraph defined in search.py\n",
    "for node in romania_map.nodes():\n",
    "    connections = romania_map.get(node)\n",
    "    for connection in connections.keys():\n",
    "        distance = connections[connection]\n",
    "\n",
    "        # add edges to the graph\n",
    "        G.add_edge(node, connection)\n",
    "        # add distances to edge_labels\n",
    "        edge_labels[(node, connection)] = distance"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We have completed building our graph based on romania_map and its locations. It's time to display it here in the notebook. This function `show_map(node_colors)` helps us do that. We will be calling this function later on to display the map at each and every interval step while searching, using variety of algorithms from the book."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def show_map(node_colors):\n",
    "    # set the size of the plot\n",
    "    plt.figure(figsize=(18,13))\n",
    "    # draw the graph (both nodes and edges) with locations from romania_locations\n",
    "    nx.draw(G, pos = romania_locations, node_color = [node_colors[node] for node in G.nodes()])\n",
    "\n",
    "    # draw labels for nodes\n",
    "    node_label_handles = nx.draw_networkx_labels(G, pos = node_label_pos, labels = node_labels, font_size = 14)\n",
    "    # add a white bounding box behind the node labels\n",
    "    [label.set_bbox(dict(facecolor='white', edgecolor='none')) for label in node_label_handles.values()]\n",
    "\n",
    "    # add edge lables to the graph\n",
    "    nx.draw_networkx_edge_labels(G, pos = romania_locations, edge_labels=edge_labels, font_size = 14)\n",
    "    \n",
    "    # add a legend\n",
    "    white_circle = lines.Line2D([], [], color=\"white\", marker='o', markersize=15, markerfacecolor=\"white\")\n",
    "    orange_circle = lines.Line2D([], [], color=\"orange\", marker='o', markersize=15, markerfacecolor=\"orange\")\n",
    "    red_circle = lines.Line2D([], [], color=\"red\", marker='o', markersize=15, markerfacecolor=\"red\")\n",
    "    gray_circle = lines.Line2D([], [], color=\"gray\", marker='o', markersize=15, markerfacecolor=\"gray\")\n",
    "    green_circle = lines.Line2D([], [], color=\"green\", marker='o', markersize=15, markerfacecolor=\"green\")\n",
    "    plt.legend((white_circle, orange_circle, red_circle, gray_circle, green_circle),\n",
    "               ('Un-explored', 'Frontier', 'Currently Exploring', 'Explored', 'Final Solution'),\n",
    "               numpoints=1,prop={'size':16}, loc=(.8,.75))\n",
    "    \n",
    "    # show the plot. No need to use in notebooks. nx.draw will show the graph itself.\n",
    "    plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can simply call the function with node_colors dictionary object to display it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "image/png": "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\nTpyoCxcuWDsOAAAAAFtjGJnX6Lx6NXf7Xb2auZ9h5EusmTNnqmTJknrllVdyfL1q1ary9fWVJEVF\nReVYVoaGhqpSpUrm57/++qtMJpP+85//aPTo0SpbtqycnJx08eJFxcbGymQyKT4+Xt27d5e7u7sa\nN25s3vfTTz9Vq1at5ObmJhcXFwUGBurbb7+1OF9AQICaNWumuLg4NWzYUM7Ozqpbt642bNhgkWn5\n8uU6deqUeUn5PzP+U3h4uEqXLq3U1FSL7UlJSXJzc9PYsWNv+RneiWXLlmVb1p6enq4WLVqoatWq\nunz5sqT/fcZHjhxRy5Yt5ezsLG9vb02aNEkZGRm3PIdhGJo7d65q1qwpR0dHeXt7a/DgweZjZzGZ\nTBo/frxmzJihypUry9HRUUeOHMlxGfudfNZZ3nnnHdWqVUtFixZVvXr19MEHHyggIEABAQF3/8HZ\nAMpOFDqXL1/W7NmzFRkZae0ohV6DBg307LPPatKkSdaOAgAAYDUP6rX5gAIvISHzZkR348yZzP3z\nWHp6unbt2qW2bduqaNGieX78qVOn6scff9SSJUu0YcMGi3OEhISocuXKWrdunWbMmCFJ2rp1q1q1\naiVXV1etWrVKq1evVlJSkpo3b64TJ05YHPv48eMaOnSoIiIitH79enl7e6t79+766aefJEkTJ05U\n+/btVapUKSUkJCghISHHgk6SBg4cqLNnz2Z7ffXq1UpOTs5xefqNDMNQWlpatkeWsLAwde/eXX37\n9tWpU6ckSZMnT9bnn3+u1atXq3jx4hbHe/rpp9W6dWtt3LhRwcHBmjx5sl5++eVbZhg/frwiIiLU\npk0bbd68WaNHj1ZsbKw6dOiQrSiNjY3V1q1bNWvWLG3dulVly5a96XFv91lL0o4dOxQSEqJatWpp\n/fr1GjlypIYNG6Yff/zxtp+drWMZOwqd+fPnq23btvLx8bF2FCjzD5vatWurX79+ql+/vrXjAAAA\n3HdpaWnq06ePIiIi1LBhQ2vHAR4Mw4ZJX3996zEnT+Z+VmeWq1el556Type/+ZgGDaSYmFwd9ty5\nc7p27ZoqVqx4d7luo3Tp0tqwYUOOs0G7deuWbTbp0KFD1aJFC23atMm8rWXLlqpSpYpmz56tmH+8\nv3Pnzik+Pl7Vq1eXlHm9SW9vb7333nsaN26cqlatqlKlSsnR0fG2S7Nr166tFi1aaPHixQoKCjJv\nX7x4sdq2bavKlSvf9r1OmzZN06ZNy7b9zz//lKenpyRpyZIlql+/vnr37q3IyEhNmTJFkydPtpjZ\nmqVfv37mGaVt27Y1T5QaNmyY3N3ds42/cOGCZs+erT59+mjhwoWSpMDAQJUqVUq9e/fWli1b1Llz\nZ/N4wzC0fft2FStWzLwtMTExx/d2u89akiIjI1W7dm2LX++6devKz89PNWrUuO3nZ8uY2YlC5eLF\ni5o3bx6zOgsQDw8PRUdHKzw8XEY+LRMBAAAoyOzt7dW0aVN17NhR3bt3v+lffgHkUnr63S9FN4zM\n/R8wTz/9dI5FpyR17drV4vmxY8d0/PhxhYSEWMyMdHZ2VtOmTRUfH28xvnr16ubyTZK8vLzk5eWl\n33///a6yvvjii9q1a5eOHTsmSdq/f7+++uqrO5rVKUkvvPCC9u/fn+3xz2LS3d1dq1evVnx8vAID\nA/XEE09ozJgxOR7vn6WrJPXo0UNXrlzJtqQ/y759+5SSkqJevXpl28/e3l6ffvqpxfannnrKoui8\nldt91unp6Tpw4ICeffZZi1/vRx999I6KYlvHzE4UKjExMerYsaPFbxqwvn79+mnJkiVas2aNevbs\nae04AAAA91WRIkU0aNAgPf/881q4cKFatGihDh06KDIy8qbXuwMKvTuZURkTI40ZI6Wk5P74Tk6Z\ns0eHDs39vrfg4eGhYsWK6bfffsvT42bx9va+49fO/v8S/7CwMIWFhWUbX6FCBYvnJUuWzDbGyclJ\nf//9991EVdeuXVWmTBktXrxYs2bN0uuvv66yZcuqU6dOd7S/t7e3/Pz8bjuuSZMmqlmzpo4ePaoh\nQ4bIzi7neX+lS5fO8XnWEvgbZd174sbP1d7eXh4eHtnuTXGrX5sb3e6zPnfunFJTU+Xl5ZVt3I3v\nozBiZicKjZSUFB06dEgTJ060dhTcoEiRIlqwYIFGjRqlK1euWDsOAACAVTg7O2v06NE6duyYHn74\nYT366KMaPHiwTp8+be1owIPJ319ycLi7fe3tpUaN8jaPMouwgIAA7dixQ9fv4A7xWdfcTLmhsD1/\n/nyO4282qzOn1zw8PCRJ06dPz3GG5ObNm2+b7144ODiob9++io2N1dmzZ7VmzRqFhYXJ3j5v5+VF\nR0fr2LFj8vX11fDhw3Xp0qUcx505cybH5+XKlctxfFYh+ccff1hsT0tL0/nz57MVlrf6tcktT09P\nOTg4mAvrf7rxfRRGlJ0oNOzt7fXee++pSpUq1o6CHDz++ONq2bKlpk6dau0oAAAAVlWiRAm9/PLL\nSkxMlKOjo+rWrauxY8dmmyUE4DaaNpVymPl2R0qXztw/H4wdO1bnz5/X6NGjc3z9l19+0TfffCNJ\n5mt7/nMp9cWLF/X555/fc46aNWuqUqVK+u677+Tn55ftkXVH+NxwcnLStWvX7nj8gAEDdPHiRXXv\n3l3Xr19Xv379cn3OW9mzZ4+mTp2qqVOnavPmzbp48aIGDhyY49j33nvP4vmaNWvk6uqqevXq5Ti+\nSZMmcnR01Jo1ayy2v/vuu0pLS8vXO6IXKVJEfn5+ev/99y0uB3fw4EH98ssv+XbeBwXL2FFo2NnZ\n5cvd7pB3XnnlFdWrV08vvPAClxoAAACFnpeXl+bMmaOIiAhNnjxZNWrU0LBhwzR06FC5ublZOx5Q\n8JlM0ujR0ogRubtRkbNz5n55OBPvn5544gnzd/vo0aMKDQ1VhQoV9Ndff2nnzp1aunSpVq9eLV9f\nX7Vr104lSpRQv379FB0drevXr+uVV16Rq6vrPecwmUx67bXX1KVLF6WkpCgoKEienp46c+aMPv/8\nc1WoUEERERG5Ombt2rV14cIFLVq0SH5+fipatOhNy0Ipc9Zk586dtWHDBnXq1EkPP/zwHZ/r1KlT\n2rdvX7btFStWlLe3t/766y+FhISoVatWGjlypEwmk5YsWaKgoCAFBgaqT58+Fvu98cYbysjIUKNG\njfTxxx9r6dKlioqKUokSJXI8f8mSJTVixAhNnz5dLi4uat++vRITEzVhwgQ1a9ZMHTp0uOP3cjei\no6PVtm1bde3aVf3799e5c+cUFRWlMmXK3HSpfmFRuN89gALF29tbY8aM0bBhw6wdBQAAoMAoX768\nFi9erISEBCUmJqp69eqKiYm56+vkAYVKWJjUsGHmNTjvhJOT9Oij0gsv5GusYcOG6bPPPpO7u7tG\njhypJ598UqGhoUpMTNTixYvN1610d3fXli1bZGdnp6CgIL300ksKDw9Xy5Yt8yRH+/btFR8fr+Tk\nZPXt21eBgYEaPXq0/vjjDzW9i5mtffv2VY8ePTRu3Dj5+/vf0fU3u3fvLkl3fGOiLLGxsWratGm2\nx9tvvy1J6t+/v65du6bly5ebl5B3795dYWFhGjx4sH766SeL423atEk7duxQ586dtWrVKk2YMOG2\n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\npKdgwkRKegrJqcmcunGKN2LeoPni5iSlJOVonoULF2YuvvXXxzfffAPAN998g4WFBXFxcTmWo3v3\n7nh6ev7rfhcvXiQ8PBwvLy8cHBxwcXGhVq1aDBo0iNTU1Ee65smTJ7GwsODzzz9/5LxbtmwhMjIy\nW88pBZOFSX8VRES4e/cudnZ2RscQERERkf9ZunQpbm5uNGzYEOCBHZ0mk4n33nuP0qVL06VLF43q\nKYCOHz+Oj4/PYx2bmp5K4OJA9ibu5W763X/d387Kjjrl6hDbIzbHOjwXLlxIr169WL58Oa6urlle\nq1q1KoULF+b333/n2LFj+Pr6Zlm4Nzt1796d7777jpMnTz5wnxs3buDv74+trS0RERFUqVKFa9eu\nER8fz5IlSzhy5AhOTk4Pfc2TJ09SuXJlPvvsM7p37/5IeceMGcOUKVPu+3Lj7t27xMfH4+npiYuL\nyyOd05w9ye9VXqdh7CJi1jIyMti6dSsHDhygR48elCpVyuhIIiIiIgJ06dIly/MHDV23sLCgdu3a\nvPnmm0ydOpXJkyfTvn17je4RAObFz+PAhQMPVegEuJt+l/0X9jM/fj79a/fP0Ww1atR4YGdl4cKF\nqVevXo5e/2EsW7aMs2fPcvToUXx9fTO3v/jii0yaNClP/J7Z2dnlifdK8g4NYxcRs2ZpacmtW7fY\ntm0bgwYNMjqOiIiIiDyGpk2bEhcXxzvvvENkZCR169Zl8+bNGt5u5kwmE+9++y63Um890nG3Um/x\n7rfvGvrz83fD2Bs1akTTpk2JiYkhICAAR0dH/Pz8WLNmTZZjExIS6N69OxUqVMDBwYFKlSrx2muv\ncePGjUfOce3aNQBKly5932t/LXSmpKQwevRo3N3dsbW1pUKFCowbN+5fh7o3atSIZ5999r7trq6u\nvPzyy8D/7+q8d10LCwusrf/o33vQMPZFixbh7++PnZ0dTz31FD179uTSpUv3XSMsLIwlS5bg7e1N\noUKFePrpp9m1a9c/Zpa8TcVOETFbKSkpAAQFBfHiiy+ybNkyNm/ebHAqEREREXkcFhYWtG3blgMH\nDhAREcHAgQMJDAxU0cKM7T63m8vJlx/r2EvJl9h9bnc2J8oqPT2dtLS0zEd6evq/HpOQkMDQoUOJ\niIhgxYoVlCpVihdffJFTp05l7pOYmIi7uzsffvghmzZt4s0332TTpk08//zzj5yxTp06AHTu3JmY\n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\nmzdn5syZVKhQwei4IiIiIiIiuSI1NZVFixYxYcIEatasyaRJk/D39zc6lohIvqMxwpKrChcuzJUr\nV/Dw8ADAysoK+GOOxAEDBrB48WJ++OEHBg0axK1bt4yMKpKFyWQiPT3d6BgiIiIiUkDZ2Njw8ssv\n89NPP9GsWTNatmxJt27dOHnypNHRRETyFRU7JdcVL178ga916tSJ9957jytXruDo6JiLqUT+WXJy\nMuXLl+f8+fNGRxERERGRAsze3p7Bgwdz8uRJqlatSr169di2bZvmkxcReUgaxi550vXr1ylWrJjR\nMUSyGD16NGfOnOHzzz83OoqIiIiImIlr167h5OSEra2t0VFERPIFFTvFMCaTCQsLC6NjiDy0pKQk\nfHx8WLp0KY0aNTI6joiIiIiIiIj8hYaxi2FOnz5NWlqa0TFEHpqTkxPTpk0jPDxc83eKiIiIiIiI\n5EEqdophunTpwsaNG42OIfJIQkJCKFKkCJ9++qnRUURERERERETkLzSMXQzxww8/0LJlS3755Res\nra2NjiPySA4fPsyzzz7L8ePHKVGihNFxREREREREROR/1Nkphpg/fz49e/ZUoVPyJX9/f0JCQhgz\nZozRUURERERERETkT9TZKbkuJSUFV1dXdu3ahaenp9FxRB7L9evX8fHxYcOGDQQEBBgdR0RERERE\nRERQZ6cYYO3atfj4+KjQKflasWLFmDRpEuHh4eg7IxEREREREZG8QcVOyXXz58+nT58+RscQeWK9\ne/fmzp07LFmyxOgoIiIiIiIiIoKGsUsuS0xMpFq1apw7dw5HR0ej44g8se+++44XX3yREydO4Ozs\nbHQcEREREREREbOmzk7JVQsXLiQ4OFiFTikw6tWrR4sWLZg0aZLRUURERERERETMnjo7JddkZGRQ\nuXJlli5dSp06dYyOI5JtLl68iJ+fH99++y1VqlQxOo6IiIiImLH09HTS0tKws7MzOoqIiCHU2Sm5\nZseOHTg6OvL0008bHUUkW5UuXZrRo0czaNAgLVYkIiIiIoZr06YNO3bsMDqGiIghVOyUXDNv3jz6\n9OmDhYWF0VFEsl14eDhnzpxhzZo1RkcRERERETNmZWVFjx49GDNmjL6IFxGzpGHskitu3LhBhQoV\nOHnyJC4uLkbHEckR33zzDf369eOHH37AwcHB6DgiIiIiYqbS0tLw9fVl1qxZtGjRwug4IiK5Sp2d\n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\ndWw2m2w2m9zd3U1HAYC7UOzM4Gw2m5YuXfpY55g9e7a8vb3tlCjlXL16Vf7+/nrvvfd08eJF03EA\nGFSgQAGNHz/e4ddx9P3y1VdfZeV2wE5atWql0qVLa8iQIaajAECqxUgSAKkRxc506s4nbfd7dOjQ\nQZIUGRmphg0bPta1WrZsqWPHjtkhdcr67LPPtHv3bkVFRalYsWJ69913df78edOxANhZhw4dku59\nLi4uevLJJ/XWW2/pjz/+SNpn27Zt6tGjh8OzpMT90tXVVd27d9fhw4fl7++vgIAAvfvuu7py5YpD\nrwukNzabTZ988omWLFmidevWmY4DAACAB0SxM52KjIxMekybNu2ubR999JEkKXfu3I899MDT01M5\nc+Z87MyPIy4u7pGOy58/v6ZMmaK9e/fq9u3bKlGihPr27atz587ZOSEAk2rWrKnIyEidOHFC06dP\nV3h4eLLipp+fnzJlyuTwHCl5v/T29tbw4cO1f/9+RUdHq1ixYnr//fcZkgs8hOzZs2vatGnq0KGD\n/vzzT9NxAAAA8AAodqZTuXPnTnpkyZLlrm2ZM2eWlHwY+4kTJ2Sz2bRw4UJVrVpVnp6eKlu2rPbs\n2aN9+/apSpUq8vLy0gsvvJBsWOT/Dss8ffq0GjdurGzZsilTpkwqVqyYFi5cmPT63r17VbNmTXl6\neipbtmx3/QGxbds21a5dWzly5JCvr69eeOEF/frrr8nen81m05QpU9S0aVN5eXlpyJAhSkhIUOfO\nnVWwYEF5enqqSJEiev/995WYmPivP687c3Pt379fTk5OKlmypHr27KkzZ848wk8fQGrj7u6u3Llz\nK1++fKpdu7ZatmypH374Ien1/x3GbrPZ9Omnn6px48bKlCmT/P39tW7dOp05c0Z16tSRl5eXypQp\nk2xezDv3wrVr16pkyZLy8vJStWrV/vF+KUkrVqxQxYoV5enpqezZs6thw4aKiYm5Zy5Jevnll9Wz\nZ88Hfu+5c+fWp59+qg0bNmjz5s0qWrSo5syZw8rtwAOqV6+e6tevrz59+piOAgBGsKYxgLSGYifu\nMnz4cA0cOFA7d+5UlixZ9Prrr6tXr14KCwvT1q1bFRMTo969e9/3+B49eig6Olrr1q3T/v379eGH\nHyYVXKOiolSnTh15e3tr69atWr58uTZt2qROnTolHX/jxg21bdtWv/zyi7Zu3aoyZcqofv36dw3B\n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\nxyEqFwEBAfDw8OBUJxGRAuGZnUSkUh4+fIi4uDj069dPdBSiD1JYWIjS0lLo6OiIjkJKJDg4GBER\nETh16hQ0NDREx6myTpw4AQ8PD9StWxehoaGwsbERHUmh+Pr6IjU1Ffv37+dRMqTUys7qvH79OmrW\nrCk6DhER/T9OdhKRSrl37x63ZFKVsGXLFoSEhKCkpER0FFISsbGxWLFiBXbv3s2is4J1794dly9f\nxtChQ9GjRw9MmTIFjx49Eh1LYSxevBg3b97Etm3bREch+iB79uyBh4cHi04iIgXDspOIVErt2rWR\nnZ0tOgbRP9q8eTPS0tJQWlqK4uLiv5WaDRs2xJ49e3Djxg1BCUmZPH78GKNGjcKmTZvQqFEj0XFU\ngrq6OqZMmYJr165BKpXCysoKa9asQVFRkehowmlpaSE8PBw+Pj7IysoSHYfovchkMnh6emL27Nmi\noxAR0V+w7CQilcKyk5SFr68voqKiIJVKoa6uDjU1NQDA06dPkZKSgtu3byM5ORkJCQmCk5Kik8lk\nGD9+PAYNGoQBAwaIjqNyPvroI6xZswYnT57EgQMH0KpVKxw/flx0LOFsbGzg7e0NFxcXlJaWio5D\n9K9JJBJUr15d/vuZiIgUB8/sJCKVIpPJoKWlhby8PGhqaoqOQ/RGAwcORF5eHrp27YqrV68iIyMD\n9+7dQ15eHqRSKQwMDKCjo4OvvvoKn3/+uei4pMDWrFmD7du3IyYmBlpaWqLjqDSZTIaIiAh4enrC\nxsYGK1asgKmpqehYwpSUlKBz584YMmQIPD09RcchIiKiKoKTnUSkUiQSCWrVqsXpTlJ4n376KaKi\nohAREYFnz56hY8eO8PHxwdatW3Ho0CFEREQgIiICnTp1Eh2VFNivv/6KgIAA/PDDDyw6FYBEIsGg\nQYOQkpKC9u3bw87ODr6+vnj69Ok7Pb64uLiCE1YuNTU1bN++HUuXLkVycrLoOERUSZ4+fQoPDw+Y\nmJhAW1sbn376KS5cuCC/PS8vD9OmTUODBg2gra0NCwsLrFq1SmBiIlI26qIDEBFVtrJL2evVqyc6\nCtEbNWrUCLVr18Z3330HfX19aGlpQVtbm5fL0TvLzc2Fo6Mj1qxZo9LTg4qoWrVq8PPzw5gxY+Dn\n5wdLS0ssXboUzs7Ob9xOLpPJcPToURw+fBidOnXCiBEjKjl1xTA1NcWyZcvg5OSEuLg4XnVBpAJc\n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\nZcv0zTff6MMPP7R1OQAAoIog7AQAyGKxKD8CGnabAAAeCUlEQVQ//4qzQbOysmSxWHTixInrdjIs\nKCiQp6en4uLi9NRTT131ujNnzsjT01MpKSkKDw+XJLVv316FhYVatGiRvL29NWzYMJWUlGj16tXs\nCVnJvL299f3331v3u7tRP//8szp06KDk5GTrrCoAsKW8vDxZLBZ5eXnZuhQAAFBFsLENAEAmk0ke\nHh7y8PDQww8/XO786dOn5eDgcNXXX95v8+DBgzKZTNa9On9//vI4krRy5Urdc889CgoKkiRt2bJF\nKSkp2rVrlzVEmzt3rpo3b66DBw+qWbNmlfKc+M3ljuw3E3ZevHhRAwYM0PTp0wk6AVQZ9evXt3UJ\nAACgirn59WsAgGrnesvYzWazJGnv3r1ydXWVm5tbmfO/bz6UmJioyZMn6+WXX1bdunV16dIlrVu3\nTt7e3goJCdGvv/4qSapTp468vLyUnp5+m56q+rocdt6McePGKTg4WM8999xtqgoArq2kpEQsSgMA\nANdD2AkAqDQZGRny9PS0NjuyWCwqLS2VnZ2dCgoKNH78eE2aNEmjR4/WjBkzJEmXLl3S3r171aRJ\nE0n/C07z8vLk4eGhX375xXovVI6bDTuXL1+udevW6d1336WjJQCbefzxx5WcnGzrMgAAQBXHMnYA\nQIVYLBadPXtW7u7u2rdvn3x9fVWnTh1JvwWXNWrUUFpaml588UWdPXtWCxcuVERERJnZnnl5edal\n6pdDzZycHNWoUaNCXeJxZUFBQdq0adMNXXvgwAGNGTNGa9assf67AsCddvDgQaWlpalDhw62LgUA\nAFRxhJ0AgAo5duyYunfvrqKiIh06dEh+fn5655131KlTJ7Vr104JCQmaPXu22rdvr9dff12urq6S\nftu/02KxyNXVVYWFhdbO3jVq1JAkpaWlydHRUX5+ftbrLyspKVGfPn3KdY739fXVPffcc4ffgbtP\nkyZNbmhmZ3FxsQYOHKgJEyZYG0kBgC3ExcVp8ODB122UBwAAQDd2AECFWCwWpaena+fOncrNzdX2\n7du1fft2tWnTRvPnz1erVq105swZRUREKCwsTMHBwQoKClLLli3l4OAgOzs7DR06VIcPH9ayZcvU\nsGFDSVJoaKjatGmj2bNnWwPSy0pKSrR27dpyneOPHTumRo0alQtBAwMD5efnd80mS9VJUVGR6tat\n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\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x7efbc06a4b70>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_map(node_colors)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Voila! You see, the romania map as shown in the Figure[3.2] in the book. Now, see how different searching algorithms perform with our problem statements."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## SEARCHING ALGORITHMS VISUALIZATION\n",
    "\n",
    "In this section, we have visualizations of the following searching algorithms:\n",
    "\n",
    "1. Breadth First Tree Search - Implemented\n",
    "2. Depth First Tree Search - Implemented\n",
    "3. Depth First Graph Search - Implemented\n",
    "4. Breadth First Search - Implemented\n",
    "5. Best First Graph Search - Implemented\n",
    "6. Uniform Cost Search - Implemented\n",
    "7. Depth Limited Search\n",
    "8. Iterative Deepening Search\n",
    "9. A\\*-Search - Implemented\n",
    "10. Recursive Best First Search\n",
    "\n",
    "We add the colors to the nodes to have a nice visualisation when displaying. So, these are the different colors we are using in these visuals:\n",
    "* Un-explored nodes - <font color='black'>white</font>\n",
    "* Frontier nodes - <font color='orange'>orange</font>\n",
    "* Currently exploring node - <font color='red'>red</font>\n",
    "* Already explored nodes - <font color='gray'>gray</font>\n",
    "\n",
    "Now, we will define some helper methods to display interactive buttons and sliders when visualising search algorithms."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def final_path_colors(problem, solution):\n",
    "    \"returns a node_colors dict of the final path provided the problem and solution\"\n",
    "    \n",
    "    # get initial node colors\n",
    "    final_colors = dict(initial_node_colors)\n",
    "    # color all the nodes in solution and starting node to green\n",
    "    final_colors[problem.initial] = \"green\"\n",
    "    for node in solution:\n",
    "        final_colors[node] = \"green\"  \n",
    "    return final_colors\n",
    "\n",
    "\n",
    "def display_visual(user_input, algorithm=None, problem=None):\n",
    "    if user_input == False:\n",
    "        def slider_callback(iteration):\n",
    "            # don't show graph for the first time running the cell calling this function\n",
    "            try:\n",
    "                show_map(all_node_colors[iteration])\n",
    "            except:\n",
    "                pass\n",
    "        def visualize_callback(Visualize):\n",
    "            if Visualize is True:\n",
    "                button.value = False\n",
    "                \n",
    "                global all_node_colors\n",
    "                \n",
    "                iterations, all_node_colors, node = algorithm(problem)\n",
    "                solution = node.solution()\n",
    "                all_node_colors.append(final_path_colors(problem, solution))\n",
    "                \n",
    "                slider.max = len(all_node_colors) - 1\n",
    "                \n",
    "                for i in range(slider.max + 1):\n",
    "                    slider.value = i\n",
    "                     #time.sleep(.5)\n",
    "        \n",
    "        slider = widgets.IntSlider(min=0, max=1, step=1, value=0)\n",
    "        slider_visual = widgets.interactive(slider_callback, iteration = slider)\n",
    "        display(slider_visual)\n",
    "\n",
    "        button = widgets.ToggleButton(value = False)\n",
    "        button_visual = widgets.interactive(visualize_callback, Visualize = button)\n",
    "        display(button_visual)\n",
    "    \n",
    "    if user_input == True:\n",
    "        node_colors = dict(initial_node_colors)\n",
    "        if algorithm == None:\n",
    "            algorithms = {\"Breadth First Tree Search\": breadth_first_tree_search,\n",
    "                          \"Depth First Tree Search\": depth_first_tree_search,\n",
    "                          \"Breadth First Search\": breadth_first_search,\n",
    "                          \"Depth First Graph Search\": depth_first_graph_search,\n",
    "                          \"Uniform Cost Search\": uniform_cost_search,\n",
    "                          \"A-star Search\": astar_search}\n",
    "            algo_dropdown = widgets.Dropdown(description = \"Search algorithm: \",\n",
    "                                             options = sorted(list(algorithms.keys())),\n",
    "                                             value = \"Breadth First Tree Search\")\n",
    "            display(algo_dropdown)\n",
    "        \n",
    "        def slider_callback(iteration):\n",
    "            # don't show graph for the first time running the cell calling this function\n",
    "            try:\n",
    "                show_map(all_node_colors[iteration])\n",
    "            except:\n",
    "                pass\n",
    "            \n",
    "        def visualize_callback(Visualize):\n",
    "            if Visualize is True:\n",
    "                button.value = False\n",
    "                \n",
    "                problem = GraphProblem(start_dropdown.value, end_dropdown.value, romania_map)\n",
    "                global all_node_colors\n",
    "                \n",
    "                if algorithm == None:\n",
    "                    user_algorithm = algorithms[algo_dropdown.value]\n",
    "                \n",
    "#                 print(user_algorithm)\n",
    "#                 print(problem)\n",
    "                \n",
    "                iterations, all_node_colors, node = user_algorithm(problem)\n",
    "                solution = node.solution()\n",
    "                all_node_colors.append(final_path_colors(problem, solution))\n",
    "\n",
    "                slider.max = len(all_node_colors) - 1\n",
    "                \n",
    "                for i in range(slider.max + 1):\n",
    "                    slider.value = i\n",
    "#                     time.sleep(.5)\n",
    "                         \n",
    "        start_dropdown = widgets.Dropdown(description = \"Start city: \",\n",
    "                                          options = sorted(list(node_colors.keys())), value = \"Arad\")\n",
    "        display(start_dropdown)\n",
    "\n",
    "        end_dropdown = widgets.Dropdown(description = \"Goal city: \",\n",
    "                                        options = sorted(list(node_colors.keys())), value = \"Fagaras\")\n",
    "        display(end_dropdown)\n",
    "        \n",
    "        button = widgets.ToggleButton(value = False)\n",
    "        button_visual = widgets.interactive(visualize_callback, Visualize = button)\n",
    "        display(button_visual)\n",
    "        \n",
    "        slider = widgets.IntSlider(min=0, max=1, step=1, value=0)\n",
    "        slider_visual = widgets.interactive(slider_callback, iteration = slider)\n",
    "        display(slider_visual)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## BREADTH-FIRST TREE SEARCH\n",
    "\n",
    "We have a working implementation in search module. But as we want to interact with the graph while it is searching, we need to modify the implementation. Here's the modified breadth first tree search."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def tree_search(problem, frontier):\n",
    "    \"\"\"Search through the successors of a problem to find a goal.\n",
    "    The argument frontier should be an empty queue.\n",
    "    Don't worry about repeated paths to a state. [Figure 3.7]\"\"\"\n",
    "    \n",
    "    # we use these two variables at the time of visualisations\n",
    "    iterations = 0\n",
    "    all_node_colors = []\n",
    "    node_colors = dict(initial_node_colors)\n",
    "    \n",
    "    #Adding first node to the queue\n",
    "    frontier.append(Node(problem.initial))\n",
    "    \n",
    "    node_colors[Node(problem.initial).state] = \"orange\"\n",
    "    iterations += 1\n",
    "    all_node_colors.append(dict(node_colors))\n",
    "    \n",
    "    while frontier:\n",
    "        #Popping first node of queue\n",
    "        node = frontier.pop()\n",
    "        \n",
    "        # modify the currently searching node to red\n",
    "        node_colors[node.state] = \"red\"\n",
    "        iterations += 1\n",
    "        all_node_colors.append(dict(node_colors))\n",
    "        \n",
    "        if problem.goal_test(node.state):\n",
    "            # modify goal node to green after reaching the goal\n",
    "            node_colors[node.state] = \"green\"\n",
    "            iterations += 1\n",
    "            all_node_colors.append(dict(node_colors))\n",
    "            return(iterations, all_node_colors, node)\n",
    "        \n",
    "        frontier.extend(node.expand(problem))\n",
    "           \n",
    "        for n in node.expand(problem):\n",
    "            node_colors[n.state] = \"orange\"\n",
    "            iterations += 1\n",
    "            all_node_colors.append(dict(node_colors))\n",
    "\n",
    "        # modify the color of explored nodes to gray\n",
    "        node_colors[node.state] = \"gray\"\n",
    "        iterations += 1\n",
    "        all_node_colors.append(dict(node_colors))\n",
    "        \n",
    "    return None\n",
    "\n",
    "def breadth_first_tree_search(problem):\n",
    "    \"Search the shallowest nodes in the search tree first.\"\n",
    "    iterations, all_node_colors, node = tree_search(problem, FIFOQueue())\n",
    "    return(iterations, all_node_colors, node)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we use ipywidgets to display a slider, a button and our romania map. By sliding the slider we can have a look at all the intermediate steps of a particular search algorithm. By pressing the button **Visualize**, you can see all the steps without interacting with the slider. These two helper functions are the callback functions which are called when we interact with the slider and the button.\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "d55324f7343a4c71a9a2d4da6d037037"
      }
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "b07a3813dd724c51a9b37f646cf2be25"
      }
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "all_node_colors = []\n",
    "romania_problem = GraphProblem('Arad', 'Fagaras', romania_map)\n",
    "display_visual(user_input = False, algorithm = breadth_first_tree_search, problem = romania_problem)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Depth-First Tree Search:\n",
    "Now let's discuss another searching algorithm, Depth-First Tree Search."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def depth_first_tree_search(problem):\n",
    "    \"Search the deepest nodes in the search tree first.\"\n",
    "    # This algorithm might not work in case of repeated paths\n",
    "    # and may run into an infinite while loop.\n",
    "    iterations, all_node_colors, node = tree_search(problem, Stack())\n",
    "    return(iterations, all_node_colors, node)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "523b10cf84e54798a044ee714b864b52"
      }
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "aecea953f6a448c192ac8e173cf46e35"
      }
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "all_node_colors = []\n",
    "romania_problem = GraphProblem('Arad', 'Oradea', romania_map)\n",
    "display_visual(user_input = False, algorithm = depth_first_tree_search, problem = romania_problem)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "## BREADTH-FIRST SEARCH\n",
    "\n",
    "Let's change all the node_colors to starting position and define a different problem statement."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def breadth_first_search(problem):\n",
    "    \"[Figure 3.11]\"\n",
    "    \n",
    "    # we use these two variables at the time of visualisations\n",
    "    iterations = 0\n",
    "    all_node_colors = []\n",
    "    node_colors = dict(initial_node_colors)\n",
    "    \n",
    "    node = Node(problem.initial)\n",
    "    \n",
    "    node_colors[node.state] = \"red\"\n",
    "    iterations += 1\n",
    "    all_node_colors.append(dict(node_colors))\n",
    "      \n",
    "    if problem.goal_test(node.state):\n",
    "        node_colors[node.state] = \"green\"\n",
    "        iterations += 1\n",
    "        all_node_colors.append(dict(node_colors))\n",
    "        return(iterations, all_node_colors, node)\n",
    "    \n",
    "    frontier = FIFOQueue()\n",
    "    frontier.append(node)\n",
    "    \n",
    "    # modify the color of frontier nodes to blue\n",
    "    node_colors[node.state] = \"orange\"\n",
    "    iterations += 1\n",
    "    all_node_colors.append(dict(node_colors))\n",
    "        \n",
    "    explored = set()\n",
    "    while frontier:\n",
    "        node = frontier.pop()\n",
    "        node_colors[node.state] = \"red\"\n",
    "        iterations += 1\n",
    "        all_node_colors.append(dict(node_colors))\n",
    "        \n",
    "        explored.add(node.state)     \n",
    "        \n",
    "        for child in node.expand(problem):\n",
    "            if child.state not in explored and child not in frontier:\n",
    "                if problem.goal_test(child.state):\n",
    "                    node_colors[child.state] = \"green\"\n",
    "                    iterations += 1\n",
    "                    all_node_colors.append(dict(node_colors))\n",
    "                    return(iterations, all_node_colors, child)\n",
    "                frontier.append(child)\n",
    "\n",
    "                node_colors[child.state] = \"orange\"\n",
    "                iterations += 1\n",
    "                all_node_colors.append(dict(node_colors))\n",
    "                    \n",
    "        node_colors[node.state] = \"gray\"\n",
    "        iterations += 1\n",
    "        all_node_colors.append(dict(node_colors))\n",
    "    return None"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "735a3dea191a42b6bd97fdfd337ea3e7"
      }
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "ef445770d70a4b7c9d1544b98a55ca4d"
      }
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "all_node_colors = []\n",
    "romania_problem = GraphProblem('Arad', 'Bucharest', romania_map)\n",
    "display_visual(user_input = False, algorithm = breadth_first_search, problem = romania_problem)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Depth-First Graph Search:  \n",
    "Although we have a working implementation in search module, we have to make a few changes in the algorithm to make it suitable for visualization."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def graph_search(problem, frontier):\n",
    "    \"\"\"Search through the successors of a problem to find a goal.\n",
    "    The argument frontier should be an empty queue.\n",
    "    If two paths reach a state, only use the first one. [Figure 3.7]\"\"\"\n",
    "    # we use these two variables at the time of visualisations\n",
    "    iterations = 0\n",
    "    all_node_colors = []\n",
    "    node_colors = dict(initial_node_colors)\n",
    "    \n",
    "    frontier.append(Node(problem.initial))\n",
    "    explored = set()\n",
    "    \n",
    "    # modify the color of frontier nodes to orange\n",
    "    node_colors[Node(problem.initial).state] = \"orange\"\n",
    "    iterations += 1\n",
    "    all_node_colors.append(dict(node_colors))\n",
    "      \n",
    "    while frontier:\n",
    "        # Popping first node of queue\n",
    "        node = frontier.pop()\n",
    "        \n",
    "        # modify the currently searching node to red\n",
    "        node_colors[node.state] = \"red\"\n",
    "        iterations += 1\n",
    "        all_node_colors.append(dict(node_colors))\n",
    "        \n",
    "        if problem.goal_test(node.state):\n",
    "            # modify goal node to green after reaching the goal\n",
    "            node_colors[node.state] = \"green\"\n",
    "            iterations += 1\n",
    "            all_node_colors.append(dict(node_colors))\n",
    "            return(iterations, all_node_colors, node)\n",
    "        \n",
    "        explored.add(node.state)\n",
    "        frontier.extend(child for child in node.expand(problem)\n",
    "                        if child.state not in explored and\n",
    "                        child not in frontier)\n",
    "        \n",
    "        for n in frontier:\n",
    "            # modify the color of frontier nodes to orange\n",
    "            node_colors[n.state] = \"orange\"\n",
    "            iterations += 1\n",
    "            all_node_colors.append(dict(node_colors))\n",
    "\n",
    "        # modify the color of explored nodes to gray\n",
    "        node_colors[node.state] = \"gray\"\n",
    "        iterations += 1\n",
    "        all_node_colors.append(dict(node_colors))\n",
    "        \n",
    "    return None\n",
    "\n",
    "\n",
    "def depth_first_graph_search(problem):\n",
    "    \"\"\"Search the deepest nodes in the search tree first.\"\"\"\n",
    "    iterations, all_node_colors, node = graph_search(problem, Stack())\n",
    "    return(iterations, all_node_colors, node)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "61149ffbc02846af97170f8975d4f11d"
      }
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "90b1f8f77fdb4207a3570fbe88a0bdf6"
      }
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "all_node_colors = []\n",
    "romania_problem = GraphProblem('Arad', 'Bucharest', romania_map)\n",
    "display_visual(user_input = False, algorithm = depth_first_graph_search, problem = romania_problem)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## UNIFORM COST SEARCH\n",
    "\n",
    "Let's change all the node_colors to starting position and define a different problem statement."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def best_first_graph_search(problem, f):\n",
    "    \"\"\"Search the nodes with the lowest f scores first.\n",
    "    You specify the function f(node) that you want to minimize; for example,\n",
    "    if f is a heuristic estimate to the goal, then we have greedy best\n",
    "    first search; if f is node.depth then we have breadth-first search.\n",
    "    There is a subtlety: the line \"f = memoize(f, 'f')\" means that the f\n",
    "    values will be cached on the nodes as they are computed. So after doing\n",
    "    a best first search you can examine the f values of the path returned.\"\"\"\n",
    "    \n",
    "    # we use these two variables at the time of visualisations\n",
    "    iterations = 0\n",
    "    all_node_colors = []\n",
    "    node_colors = dict(initial_node_colors)\n",
    "    \n",
    "    f = memoize(f, 'f')\n",
    "    node = Node(problem.initial)\n",
    "    \n",
    "    node_colors[node.state] = \"red\"\n",
    "    iterations += 1\n",
    "    all_node_colors.append(dict(node_colors))\n",
    "    \n",
    "    if problem.goal_test(node.state):\n",
    "        node_colors[node.state] = \"green\"\n",
    "        iterations += 1\n",
    "        all_node_colors.append(dict(node_colors))\n",
    "        return(iterations, all_node_colors, node)\n",
    "    \n",
    "    frontier = PriorityQueue(min, f)\n",
    "    frontier.append(node)\n",
    "    \n",
    "    node_colors[node.state] = \"orange\"\n",
    "    iterations += 1\n",
    "    all_node_colors.append(dict(node_colors))\n",
    "    \n",
    "    explored = set()\n",
    "    while frontier:\n",
    "        node = frontier.pop()\n",
    "        \n",
    "        node_colors[node.state] = \"red\"\n",
    "        iterations += 1\n",
    "        all_node_colors.append(dict(node_colors))\n",
    "        \n",
    "        if problem.goal_test(node.state):\n",
    "            node_colors[node.state] = \"green\"\n",
    "            iterations += 1\n",
    "            all_node_colors.append(dict(node_colors))\n",
    "            return(iterations, all_node_colors, node)\n",
    "        \n",
    "        explored.add(node.state)\n",
    "        for child in node.expand(problem):\n",
    "            if child.state not in explored and child not in frontier:\n",
    "                frontier.append(child)\n",
    "                node_colors[child.state] = \"orange\"\n",
    "                iterations += 1\n",
    "                all_node_colors.append(dict(node_colors))\n",
    "            elif child in frontier:\n",
    "                incumbent = frontier[child]\n",
    "                if f(child) < f(incumbent):\n",
    "                    del frontier[incumbent]\n",
    "                    frontier.append(child)\n",
    "                    node_colors[child.state] = \"orange\"\n",
    "                    iterations += 1\n",
    "                    all_node_colors.append(dict(node_colors))\n",
    "\n",
    "        node_colors[node.state] = \"gray\"\n",
    "        iterations += 1\n",
    "        all_node_colors.append(dict(node_colors))\n",
    "    return None\n",
    "\n",
    "def uniform_cost_search(problem):\n",
    "    \"[Figure 3.14]\"\n",
    "    iterations, all_node_colors, node = best_first_graph_search(problem, lambda node: node.path_cost)\n",
    "    return(iterations, all_node_colors, node)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "a667c668001e4e598478ba4a870c6aec"
      }
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "135c6bd739de4aab8fc7b2fcb6b90954"
      }
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "all_node_colors = []\n",
    "romania_problem = GraphProblem('Arad', 'Bucharest', romania_map)\n",
    "display_visual(user_input = False, algorithm = uniform_cost_search, problem = romania_problem)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## A\\* SEARCH\n",
    "\n",
    "Let's change all the node_colors to starting position and define a different problem statement."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def best_first_graph_search(problem, f):\n",
    "    \"\"\"Search the nodes with the lowest f scores first.\n",
    "    You specify the function f(node) that you want to minimize; for example,\n",
    "    if f is a heuristic estimate to the goal, then we have greedy best\n",
    "    first search; if f is node.depth then we have breadth-first search.\n",
    "    There is a subtlety: the line \"f = memoize(f, 'f')\" means that the f\n",
    "    values will be cached on the nodes as they are computed. So after doing\n",
    "    a best first search you can examine the f values of the path returned.\"\"\"\n",
    "    \n",
    "    # we use these two variables at the time of visualisations\n",
    "    iterations = 0\n",
    "    all_node_colors = []\n",
    "    node_colors = dict(initial_node_colors)\n",
    "    \n",
    "    f = memoize(f, 'f')\n",
    "    node = Node(problem.initial)\n",
    "    \n",
    "    node_colors[node.state] = \"red\"\n",
    "    iterations += 1\n",
    "    all_node_colors.append(dict(node_colors))\n",
    "    \n",
    "    if problem.goal_test(node.state):\n",
    "        node_colors[node.state] = \"green\"\n",
    "        iterations += 1\n",
    "        all_node_colors.append(dict(node_colors))\n",
    "        return(iterations, all_node_colors, node)\n",
    "    \n",
    "    frontier = PriorityQueue(min, f)\n",
    "    frontier.append(node)\n",
    "    \n",
    "    node_colors[node.state] = \"orange\"\n",
    "    iterations += 1\n",
    "    all_node_colors.append(dict(node_colors))\n",
    "    \n",
    "    explored = set()\n",
    "    while frontier:\n",
    "        node = frontier.pop()\n",
    "        \n",
    "        node_colors[node.state] = \"red\"\n",
    "        iterations += 1\n",
    "        all_node_colors.append(dict(node_colors))\n",
    "        \n",
    "        if problem.goal_test(node.state):\n",
    "            node_colors[node.state] = \"green\"\n",
    "            iterations += 1\n",
    "            all_node_colors.append(dict(node_colors))\n",
    "            return(iterations, all_node_colors, node)\n",
    "        \n",
    "        explored.add(node.state)\n",
    "        for child in node.expand(problem):\n",
    "            if child.state not in explored and child not in frontier:\n",
    "                frontier.append(child)\n",
    "                node_colors[child.state] = \"orange\"\n",
    "                iterations += 1\n",
    "                all_node_colors.append(dict(node_colors))\n",
    "            elif child in frontier:\n",
    "                incumbent = frontier[child]\n",
    "                if f(child) < f(incumbent):\n",
    "                    del frontier[incumbent]\n",
    "                    frontier.append(child)\n",
    "                    node_colors[child.state] = \"orange\"\n",
    "                    iterations += 1\n",
    "                    all_node_colors.append(dict(node_colors))\n",
    "\n",
    "        node_colors[node.state] = \"gray\"\n",
    "        iterations += 1\n",
    "        all_node_colors.append(dict(node_colors))\n",
    "    return None\n",
    "\n",
    "def astar_search(problem, h=None):\n",
    "    \"\"\"A* search is best-first graph search with f(n) = g(n)+h(n).\n",
    "    You need to specify the h function when you call astar_search, or\n",
    "    else in your Problem subclass.\"\"\"\n",
    "    h = memoize(h or problem.h, 'h')\n",
    "    iterations, all_node_colors, node = best_first_graph_search(problem, lambda n: n.path_cost + h(n))\n",
    "    return(iterations, all_node_colors, node)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "3e62c492a82044e4813ad5d84e698874"
      }
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "b661fd0c0c8d495db2672aedc25b9a44"
      }
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "all_node_colors = []\n",
    "romania_problem = GraphProblem('Arad', 'Bucharest', romania_map)\n", 
    "display_visual(user_input = False, algorithm = astar_search, problem = romania_problem)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {
    "scrolled": false
   },
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "7f1ffa858c92429bb28f74c23c0c939c"
      }
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "7a98e98ffec14520b93ce542f5169bcc"
      }
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "094beb8cf34c4a5b87f8368539d24091"
      }
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "a8f89c87de964ee69004902763e68a54"
      }
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "2ccdb4aba3ee4371a78306755e5642ad"
      }
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "all_node_colors = []\n",
    "# display_visual(user_input = True, algorithm = breadth_first_tree_search)\n",
    "display_visual(user_input = True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## BEST FIRST SEARCH\n",
    "Let's change all the node_colors to starting position and define a different problem statement."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [],
   "source": [
    "def best_first_graph_search(problem, f):\n",
    "    \"\"\"Search the nodes with the lowest f scores first.\n",
    "    You specify the function f(node) that you want to minimize; for example,\n",
    "    if f is a heuristic estimate to the goal, then we have greedy best\n",
    "    first search; if f is node.depth then we have breadth-first search.\n",
    "    There is a subtlety: the line \"f = memoize(f, 'f')\" means that the f\n",
    "    values will be cached on the nodes as they are computed. So after doing\n",
    "    a best first search you can examine the f values of the path returned.\"\"\"\n",
    "    \n",
    "    # we use these two variables at the time of visualisations\n",
    "    iterations = 0\n",
    "    all_node_colors = []\n",
    "    node_colors = dict(initial_node_colors)\n",
    "    \n",
    "    f = memoize(f, 'f')\n",
    "    node = Node(problem.initial)\n",
    "    \n",
    "    node_colors[node.state] = \"red\"\n",
    "    iterations += 1\n",
    "    all_node_colors.append(dict(node_colors))\n",
    "    \n",
    "    if problem.goal_test(node.state):\n",
    "        node_colors[node.state] = \"green\"\n",
    "        iterations += 1\n",
    "        all_node_colors.append(dict(node_colors))\n",
    "        return(iterations, all_node_colors, node)\n",
    "    \n",
    "    frontier = PriorityQueue(min, f)\n",
    "    frontier.append(node)\n",
    "    \n",
    "    node_colors[node.state] = \"orange\"\n",
    "    iterations += 1\n",
    "    all_node_colors.append(dict(node_colors))\n",
    "    \n",
    "    explored = set()\n",
    "    while frontier:\n",
    "        node = frontier.pop()\n",
    "        \n",
    "        node_colors[node.state] = \"red\"\n",
    "        iterations += 1\n",
    "        all_node_colors.append(dict(node_colors))\n",
    "        \n",
    "        if problem.goal_test(node.state):\n",
    "            node_colors[node.state] = \"green\"\n",
    "            iterations += 1\n",
    "            all_node_colors.append(dict(node_colors))\n",
    "            return(iterations, all_node_colors, node)\n",
    "        \n",
    "        explored.add(node.state)\n",
    "        for child in node.expand(problem):\n",
    "            if child.state not in explored and child not in frontier:\n",
    "                frontier.append(child)\n",
    "                node_colors[child.state] = \"orange\"\n",
    "                iterations += 1\n",
    "                all_node_colors.append(dict(node_colors))\n",
    "            elif child in frontier:\n",
    "                incumbent = frontier[child]\n",
    "                if f(child) < f(incumbent):\n",
    "                    del frontier[incumbent]\n",
    "                    frontier.append(child)\n",
    "                    node_colors[child.state] = \"orange\"\n",
    "                    iterations += 1\n",
    "                    all_node_colors.append(dict(node_colors))\n",
    "\n",
    "        node_colors[node.state] = \"gray\"\n",
    "        iterations += 1\n",
    "        all_node_colors.append(dict(node_colors))\n",
    "    return None\n",
    "\n",
    "def best_first_search(problem, h=None):\n",
    "    \"\"\"Best-first graph search is an informative searching algorithm with f(n) = h(n).\n",
    "    You need to specify the h function when you call best_first_search, or\n",
    "    else in your Problem subclass.\"\"\"\n",
    "    h = memoize(h or problem.h, 'h')\n",
    "    iterations, all_node_colors, node = best_first_graph_search(problem, lambda n: h(n))\n",
    "    return(iterations, all_node_colors, node)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "5ae2d521b74743afa988c462a851c269"
      }
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "559c20b044a4469db7f0ab8c3fae1022"
      }
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "all_node_colors = []\n",
    "romania_problem = GraphProblem('Arad', 'Bucharest', romania_map)\n",
    "display_visual(user_input = False, algorithm = best_first_search, problem = romania_problem)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## A* Heuristics\n",
    "\n",
    "Different heuristics provide different efficiency in solving A* problems which are generally defined by the number of explored nodes as well as the branching factor. With the classic 8 puzzle we can show the efficiency of different heuristics through the number of explored nodes.\n",
    "\n",
    "### 8 Puzzle Problem\n",
    "\n",
    "The *8 Puzzle Problem* consists of a 3x3 tray in which the goal is to get the initial configuration to the goal state by shifting the numbered tiles into the blank space.\n",
    "\n",
    "example:- \n",
    "\n",
    "              Initial State                        Goal State\n",
    "              | 7 | 2 | 4 |                       | 0 | 1 | 2 |\n",
    "              | 5 | 0 | 6 |                       | 3 | 4 | 5 |\n",
    "              | 8 | 3 | 1 |                       | 6 | 7 | 8 |\n",
    "              \n",
    "We have a total of 9 blank tiles giving us a total of 9! initial configuration but not all of these are solvable, the solvability of a configuration can be checked by calculating the Inversion Permutation. If the total Inversion Permutation is even then the initial configuration is solvable else the initial configuration is not solvable which means that only 9!/2 initial states lead to a solution.\n",
    "\n",
    "#### Heuristics :-\n",
    "\n",
    "1.) Manhattan Distance:- For the 8 puzzle problem Manhattan distance is defined as the distance of a tile from its goal state( for the tile numbered '1' in the initial configuration Manhattan distance is 4 \"2 for left and 2 for upward displacement\").\n",
    "\n",
    "2.) No. of Misplaced Tiles:- The heuristic calculates the number of misplaced tiles between the current state and goal state.\n",
    "\n",
    "3.) Sqrt of Manhattan Distance:- It calculates the square root of Manhattan distance.\n",
    "\n",
    "4.) Max Heuristic:- It assign the score as max of Manhattan Distance and No. of misplaced tiles. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# heuristics for 8 Puzzle Problem\n",
    "\n",
    "def linear(state,goal):\n",
    "    return sum([1 if state[i] != goal[i] else 0 for i in range(8)])\n",
    "\n",
    "def manhanttan(state,goal):\n",
    "\tindex_goal = {0:[2,2], 1:[0,0], 2:[0,1], 3:[0,2], 4:[1,0], 5:[1,1], 6:[1,2], 7:[2,0], 8:[2,1]}\n",
    "\tindex_state = {}\n",
    "\tindex = [[0,0], [0,1], [0,2], [1,0], [1,1], [1,2], [2,0], [2,1], [2,2]]\n",
    "\tx=0\n",
    "\ty=0\n",
    "\tfor i in range(len(state)):\n",
    "\t\tindex_state[state[i]] = index[i]\n",
    "\tmhd = 0\n",
    "\tfor i in range(8):\n",
    "\t\tfor j in range(2):\n",
    "\t\t\tmhd = abs(index_goal[i][j] - index_state[i][j]) + mhd\n",
    "\treturn mhd\n",
    "\n",
    "def sqrt_manhanttan(state,goal):\n",
    "\tindex_goal = {0:[2,2], 1:[0,0], 2:[0,1], 3:[0,2], 4:[1,0], 5:[1,1], 6:[1,2], 7:[2,0], 8:[2,1]}\n",
    "\tindex_state = {}\n",
    "\tindex = [[0,0], [0,1], [0,2], [1,0], [1,1], [1,2], [2,0], [2,1], [2,2]]\n",
    "\tx=0\n",
    "\ty=0\n",
    "\tfor i in range(len(state)):\n",
    "\t\tindex_state[state[i]] = index[i]\n",
    "\tmhd = 0\n",
    "\tfor i in range(8):\n",
    "\t\tfor j in range(2):\n",
    "\t\t\tmhd = (index_goal[i][j] - index_state[i][j])**2 + mhd\n",
    "\treturn math.sqrt(mhd)\n",
    "\n",
    "def max_heuristic(state,goal):\n",
    "\tscore1 = manhanttan(state, goal)\n",
    "\tscore2 = linear(state, goal)\n",
    "\treturn max(score1, score2)\t\t\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n",
      "Number of explored nodes by the following heuristic are:  126\n",
      "[2, 4, 3, 1, 5, 6, 7, 8, 0]\n",
      "[2, 4, 3, 1, 5, 0, 7, 8, 6]\n",
      "[2, 4, 3, 1, 0, 5, 7, 8, 6]\n",
      "[2, 0, 3, 1, 4, 5, 7, 8, 6]\n",
      "[0, 2, 3, 1, 4, 5, 7, 8, 6]\n",
      "[1, 2, 3, 0, 4, 5, 7, 8, 6]\n",
      "[1, 2, 3, 4, 0, 5, 7, 8, 6]\n",
      "[1, 2, 3, 4, 5, 0, 7, 8, 6]\n",
      "[1, 2, 3, 4, 5, 6, 7, 8, 0]\n",
      "Number of explored nodes by the following heuristic are:  129\n",
      "[2, 4, 3, 1, 5, 6, 7, 8, 0]\n",
      "[2, 4, 3, 1, 5, 0, 7, 8, 6]\n",
      "[2, 4, 3, 1, 0, 5, 7, 8, 6]\n",
      "[2, 0, 3, 1, 4, 5, 7, 8, 6]\n",
      "[0, 2, 3, 1, 4, 5, 7, 8, 6]\n",
      "[1, 2, 3, 0, 4, 5, 7, 8, 6]\n",
      "[1, 2, 3, 4, 0, 5, 7, 8, 6]\n",
      "[1, 2, 3, 4, 5, 0, 7, 8, 6]\n",
      "[1, 2, 3, 4, 5, 6, 7, 8, 0]\n",
      "Number of explored nodes by the following heuristic are:  126\n",
      "[2, 4, 3, 1, 5, 6, 7, 8, 0]\n",
      "[2, 4, 3, 1, 5, 0, 7, 8, 6]\n",
      "[2, 4, 3, 1, 0, 5, 7, 8, 6]\n",
      "[2, 0, 3, 1, 4, 5, 7, 8, 6]\n",
      "[0, 2, 3, 1, 4, 5, 7, 8, 6]\n",
      "[1, 2, 3, 0, 4, 5, 7, 8, 6]\n",
      "[1, 2, 3, 4, 0, 5, 7, 8, 6]\n",
      "[1, 2, 3, 4, 5, 0, 7, 8, 6]\n",
      "[1, 2, 3, 4, 5, 6, 7, 8, 0]\n",
      "Number of explored nodes by the following heuristic are:  139\n",
      "[2, 4, 3, 1, 5, 6, 7, 8, 0]\n",
      "[2, 4, 3, 1, 5, 0, 7, 8, 6]\n",
      "[2, 4, 3, 1, 0, 5, 7, 8, 6]\n",
      "[2, 0, 3, 1, 4, 5, 7, 8, 6]\n",
      "[0, 2, 3, 1, 4, 5, 7, 8, 6]\n",
      "[1, 2, 3, 0, 4, 5, 7, 8, 6]\n",
      "[1, 2, 3, 4, 0, 5, 7, 8, 6]\n",
      "[1, 2, 3, 4, 5, 0, 7, 8, 6]\n",
      "[1, 2, 3, 4, 5, 6, 7, 8, 0]\n"
     ]
    }
   ],
   "source": [
    "# Solving the puzzle \n",
    "puzzle = EightPuzzle()\n",
    "puzzle.checkSolvability([2,4,3,1,5,6,7,8,0]) # checks whether the initialized configuration is solvable or not\n",
    "puzzle.solve([2,4,3,1,5,6,7,8,0],[1,2,3,4,5,6,7,8,0],max_heuristic) # Max_heuristic\n",
    "puzzle.solve([2,4,3,1,5,6,7,8,0],[1,2,3,4,5,6,7,8,0],linear) # Linear\n",
    "puzzle.solve([2,4,3,1,5,6,7,8,0],[1,2,3,4,5,6,7,8,0],manhanttan) # Manhattan\n",
    "puzzle.solve([2,4,3,1,5,6,7,8,0],[1,2,3,4,5,6,7,8,0],sqrt_manhanttan) # Sqrt_manhattan"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## GENETIC ALGORITHM\n",
    "\n",
    "Genetic algorithms (or GA) are inspired by natural evolution and are particularly useful in optimization and search problems with large state spaces.\n",
    "\n",
    "Given a problem, algorithms in the domain make use of a *population* of solutions (also called *states*), where each solution/state represents a feasible solution. At each iteration (often called *generation*), the population gets updated using methods inspired by biology and evolution, like *crossover*, *mutation* and *natural selection*."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Overview\n",
    "\n",
    "A genetic algorithm works in the following way:\n",
    "\n",
    "1) Initialize random population.\n",
    "\n",
    "2) Calculate population fitness.\n",
    "\n",
    "3) Select individuals for mating.\n",
    "\n",
    "4) Mate selected individuals to produce new population.\n",
    "\n",
    "     * Random chance to mutate individuals.\n",
    "\n",
    "5) Repeat from step 2) until an individual is fit enough or the maximum number of iterations was reached."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Glossary\n",
    "\n",
    "Before we continue, we will lay the basic terminology of the algorithm.\n",
    "\n",
    "* Individual/State: A list of elements (called *genes*) that represent possible solutions.\n",
    "\n",
    "* Population: The list of all the individuals/states.\n",
    "\n",
    "* Gene pool: The alphabet of possible values for an individual's genes.\n",
    "\n",
    "* Generation/Iteration: The number of times the population will be updated.\n",
    "\n",
    "* Fitness: An individual's score, calculated by a function specific to the problem."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Crossover\n",
    "\n",
    "Two individuals/states can \"mate\" and produce one child. This offspring bears characteristics from both of its parents. There are many ways we can implement this crossover. Here we will take a look at the most common ones. Most other methods are variations of those below.\n",
    "\n",
    "* Point Crossover: The crossover occurs around one (or more) point. The parents get \"split\" at the chosen point or points and then get merged. In the example below we see two parents get split and merged at the 3rd digit, producing the following offspring after the crossover.\n",
    "\n",
    "![point crossover](images/point_crossover.png)\n",
    "\n",
    "* Uniform Crossover: This type of crossover chooses randomly the genes to get merged. Here the genes 1, 2 and 5 were chosen from the first parent, so the genes 3, 4 were added by the second parent.\n",
    "\n",
    "![uniform crossover](images/uniform_crossover.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Mutation\n",
    "\n",
    "When an offspring is produced, there is a chance it will mutate, having one (or more, depending on the implementation) of its genes altered.\n",
    "\n",
    "For example, let's say the new individual to undergo mutation is \"abcde\". Randomly we pick to change its third gene to 'z'. The individual now becomes \"abzde\" and is added to the population."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Selection\n",
    "\n",
    "At each iteration, the fittest individuals are picked randomly to mate and produce offsprings. We measure an individual's fitness with a *fitness function*. That function depends on the given problem and it is used to score an individual. Usually the higher the better.\n",
    "\n",
    "The selection process is this:\n",
    "\n",
    "1) Individuals are scored by the fitness function.\n",
    "\n",
    "2) Individuals are picked randomly, according to their score (higher score means higher chance to get picked). Usually the formula to calculate the chance to pick an individual is the following (for population *P* and individual *i*):\n",
    "\n",
    "$$ chance(i) = \\dfrac{fitness(i)}{\\sum_{k \\, in \\, P}{fitness(k)}} $$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Implementation\n",
    "\n",
    "Below we look over the implementation of the algorithm in the `search` module.\n",
    "\n",
    "First the implementation of the main core of the algorithm:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.01//EN\"\n",
       "   \"http://www.w3.org/TR/html4/strict.dtd\">\n",
       "\n",
       "<html>\n",
       "<head>\n",
       "  <title></title>\n",
       "  <meta http-equiv=\"content-type\" content=\"text/html; charset=None\">\n",
       "  <style type=\"text/css\">\n",
       "td.linenos { background-color: #f0f0f0; padding-right: 10px; }\n",
       "span.lineno { background-color: #f0f0f0; padding: 0 5px 0 5px; }\n",
       "pre { line-height: 125%; }\n",
       "body .hll { background-color: #ffffcc }\n",
       "body  { background: #f8f8f8; }\n",
       "body .c { color: #408080; font-style: italic } /* Comment */\n",
       "body .err { border: 1px solid #FF0000 } /* Error */\n",
       "body .k { color: #008000; font-weight: bold } /* Keyword */\n",
       "body .o { color: #666666 } /* Operator */\n",
       "body .ch { color: #408080; font-style: italic } /* Comment.Hashbang */\n",
       "body .cm { color: #408080; font-style: italic } /* Comment.Multiline */\n",
       "body .cp { color: #BC7A00 } /* Comment.Preproc */\n",
       "body .cpf { color: #408080; font-style: italic } /* Comment.PreprocFile */\n",
       "body .c1 { color: #408080; font-style: italic } /* Comment.Single */\n",
       "body .cs { color: #408080; font-style: italic } /* Comment.Special */\n",
       "body .gd { color: #A00000 } /* Generic.Deleted */\n",
       "body .ge { font-style: italic } /* Generic.Emph */\n",
       "body .gr { color: #FF0000 } /* Generic.Error */\n",
       "body .gh { color: #000080; font-weight: bold } /* Generic.Heading */\n",
       "body .gi { color: #00A000 } /* Generic.Inserted */\n",
       "body .go { color: #888888 } /* Generic.Output */\n",
       "body .gp { color: #000080; font-weight: bold } /* Generic.Prompt */\n",
       "body .gs { font-weight: bold } /* Generic.Strong */\n",
       "body .gu { color: #800080; font-weight: bold } /* Generic.Subheading */\n",
       "body .gt { color: #0044DD } /* Generic.Traceback */\n",
       "body .kc { color: #008000; font-weight: bold } /* Keyword.Constant */\n",
       "body .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */\n",
       "body .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */\n",
       "body .kp { color: #008000 } /* Keyword.Pseudo */\n",
       "body .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */\n",
       "body .kt { color: #B00040 } /* Keyword.Type */\n",
       "body .m { color: #666666 } /* Literal.Number */\n",
       "body .s { color: #BA2121 } /* Literal.String */\n",
       "body .na { color: #7D9029 } /* Name.Attribute */\n",
       "body .nb { color: #008000 } /* Name.Builtin */\n",
       "body .nc { color: #0000FF; font-weight: bold } /* Name.Class */\n",
       "body .no { color: #880000 } /* Name.Constant */\n",
       "body .nd { color: #AA22FF } /* Name.Decorator */\n",
       "body .ni { color: #999999; font-weight: bold } /* Name.Entity */\n",
       "body .ne { color: #D2413A; font-weight: bold } /* Name.Exception */\n",
       "body .nf { color: #0000FF } /* Name.Function */\n",
       "body .nl { color: #A0A000 } /* Name.Label */\n",
       "body .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */\n",
       "body .nt { color: #008000; font-weight: bold } /* Name.Tag */\n",
       "body .nv { color: #19177C } /* Name.Variable */\n",
       "body .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */\n",
       "body .w { color: #bbbbbb } /* Text.Whitespace */\n",
       "body .mb { color: #666666 } /* Literal.Number.Bin */\n",
       "body .mf { color: #666666 } /* Literal.Number.Float */\n",
       "body .mh { color: #666666 } /* Literal.Number.Hex */\n",
       "body .mi { color: #666666 } /* Literal.Number.Integer */\n",
       "body .mo { color: #666666 } /* Literal.Number.Oct */\n",
       "body .sa { color: #BA2121 } /* Literal.String.Affix */\n",
       "body .sb { color: #BA2121 } /* Literal.String.Backtick */\n",
       "body .sc { color: #BA2121 } /* Literal.String.Char */\n",
       "body .dl { color: #BA2121 } /* Literal.String.Delimiter */\n",
       "body .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */\n",
       "body .s2 { color: #BA2121 } /* Literal.String.Double */\n",
       "body .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */\n",
       "body .sh { color: #BA2121 } /* Literal.String.Heredoc */\n",
       "body .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */\n",
       "body .sx { color: #008000 } /* Literal.String.Other */\n",
       "body .sr { color: #BB6688 } /* Literal.String.Regex */\n",
       "body .s1 { color: #BA2121 } /* Literal.String.Single */\n",
       "body .ss { color: #19177C } /* Literal.String.Symbol */\n",
       "body .bp { color: #008000 } /* Name.Builtin.Pseudo */\n",
       "body .fm { color: #0000FF } /* Name.Function.Magic */\n",
       "body .vc { color: #19177C } /* Name.Variable.Class */\n",
       "body .vg { color: #19177C } /* Name.Variable.Global */\n",
       "body .vi { color: #19177C } /* Name.Variable.Instance */\n",
       "body .vm { color: #19177C } /* Name.Variable.Magic */\n",
       "body .il { color: #666666 } /* Literal.Number.Integer.Long */\n",
       "\n",
       "  </style>\n",
       "</head>\n",
       "<body>\n",
       "<h2></h2>\n",
       "\n",
       "<div class=\"highlight\"><pre><span></span><span class=\"k\">def</span> <span class=\"nf\">genetic_algorithm</span><span class=\"p\">(</span><span class=\"n\">population</span><span class=\"p\">,</span> <span class=\"n\">fitness_fn</span><span class=\"p\">,</span> <span class=\"n\">gene_pool</span><span class=\"o\">=</span><span class=\"p\">[</span><span class=\"mi\">0</span><span class=\"p\">,</span> <span class=\"mi\">1</span><span class=\"p\">],</span> <span class=\"n\">f_thres</span><span class=\"o\">=</span><span class=\"bp\">None</span><span class=\"p\">,</span> <span class=\"n\">ngen</span><span class=\"o\">=</span><span class=\"mi\">1000</span><span class=\"p\">,</span> <span class=\"n\">pmut</span><span class=\"o\">=</span><span class=\"mf\">0.1</span><span class=\"p\">):</span>\n",
       "    <span class=\"sd\">&quot;&quot;&quot;[Figure 4.8]&quot;&quot;&quot;</span>\n",
       "    <span class=\"k\">for</span> <span class=\"n\">i</span> <span class=\"ow\">in</span> <span class=\"nb\">range</span><span class=\"p\">(</span><span class=\"n\">ngen</span><span class=\"p\">):</span>\n",
       "        <span class=\"n\">population</span> <span class=\"o\">=</span> <span class=\"p\">[</span><span class=\"n\">mutate</span><span class=\"p\">(</span><span class=\"n\">recombine</span><span class=\"p\">(</span><span class=\"o\">*</span><span class=\"n\">select</span><span class=\"p\">(</span><span class=\"mi\">2</span><span class=\"p\">,</span> <span class=\"n\">population</span><span class=\"p\">,</span> <span class=\"n\">fitness_fn</span><span class=\"p\">)),</span> <span class=\"n\">gene_pool</span><span class=\"p\">,</span> <span class=\"n\">pmut</span><span class=\"p\">)</span>\n",
       "                      <span class=\"k\">for</span> <span class=\"n\">i</span> <span class=\"ow\">in</span> <span class=\"nb\">range</span><span class=\"p\">(</span><span class=\"nb\">len</span><span class=\"p\">(</span><span class=\"n\">population</span><span class=\"p\">))]</span>\n",
       "\n",
       "        <span class=\"n\">fittest_individual</span> <span class=\"o\">=</span> <span class=\"n\">fitness_threshold</span><span class=\"p\">(</span><span class=\"n\">fitness_fn</span><span class=\"p\">,</span> <span class=\"n\">f_thres</span><span class=\"p\">,</span> <span class=\"n\">population</span><span class=\"p\">)</span>\n",
       "        <span class=\"k\">if</span> <span class=\"n\">fittest_individual</span><span class=\"p\">:</span>\n",
       "            <span class=\"k\">return</span> <span class=\"n\">fittest_individual</span>\n",
       "\n",
       "\n",
       "    <span class=\"k\">return</span> <span class=\"n\">argmax</span><span class=\"p\">(</span><span class=\"n\">population</span><span class=\"p\">,</span> <span class=\"n\">key</span><span class=\"o\">=</span><span class=\"n\">fitness_fn</span><span class=\"p\">)</span>\n",
       "</pre></div>\n",
       "</body>\n",
       "</html>\n"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "psource(genetic_algorithm)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The algorithm takes the following input:\n",
    "\n",
    "* `population`: The initial population.\n",
    "\n",
    "* `fitness_fn`: The problem's fitness function.\n",
    "\n",
    "* `gene_pool`: The gene pool of the states/individuals. By default 0 and 1.\n",
    "\n",
    "* `f_thres`: The fitness threshold. If an individual reaches that score, iteration stops. By default 'None', which means the algorithm will not halt until the generations are ran.\n",
    "\n",
    "* `ngen`: The number of iterations/generations.\n",
    "\n",
    "* `pmut`: The probability of mutation.\n",
    "\n",
    "The algorithm gives as output the state with the largest score."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For each generation, the algorithm updates the population. First it calculates the fitnesses of the individuals, then it selects the most fit ones and finally crosses them over to produce offsprings. There is a chance that the offspring will be mutated, given by `pmut`. If at the end of the generation an individual meets the fitness threshold, the algorithm halts and returns that individual.\n",
    "\n",
    "The function of mating is accomplished by the method `recombine`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.01//EN\"\n",
       "   \"http://www.w3.org/TR/html4/strict.dtd\">\n",
       "\n",
       "<html>\n",
       "<head>\n",
       "  <title></title>\n",
       "  <meta http-equiv=\"content-type\" content=\"text/html; charset=None\">\n",
       "  <style type=\"text/css\">\n",
       "td.linenos { background-color: #f0f0f0; padding-right: 10px; }\n",
       "span.lineno { background-color: #f0f0f0; padding: 0 5px 0 5px; }\n",
       "pre { line-height: 125%; }\n",
       "body .hll { background-color: #ffffcc }\n",
       "body  { background: #f8f8f8; }\n",
       "body .c { color: #408080; font-style: italic } /* Comment */\n",
       "body .err { border: 1px solid #FF0000 } /* Error */\n",
       "body .k { color: #008000; font-weight: bold } /* Keyword */\n",
       "body .o { color: #666666 } /* Operator */\n",
       "body .ch { color: #408080; font-style: italic } /* Comment.Hashbang */\n",
       "body .cm { color: #408080; font-style: italic } /* Comment.Multiline */\n",
       "body .cp { color: #BC7A00 } /* Comment.Preproc */\n",
       "body .cpf { color: #408080; font-style: italic } /* Comment.PreprocFile */\n",
       "body .c1 { color: #408080; font-style: italic } /* Comment.Single */\n",
       "body .cs { color: #408080; font-style: italic } /* Comment.Special */\n",
       "body .gd { color: #A00000 } /* Generic.Deleted */\n",
       "body .ge { font-style: italic } /* Generic.Emph */\n",
       "body .gr { color: #FF0000 } /* Generic.Error */\n",
       "body .gh { color: #000080; font-weight: bold } /* Generic.Heading */\n",
       "body .gi { color: #00A000 } /* Generic.Inserted */\n",
       "body .go { color: #888888 } /* Generic.Output */\n",
       "body .gp { color: #000080; font-weight: bold } /* Generic.Prompt */\n",
       "body .gs { font-weight: bold } /* Generic.Strong */\n",
       "body .gu { color: #800080; font-weight: bold } /* Generic.Subheading */\n",
       "body .gt { color: #0044DD } /* Generic.Traceback */\n",
       "body .kc { color: #008000; font-weight: bold } /* Keyword.Constant */\n",
       "body .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */\n",
       "body .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */\n",
       "body .kp { color: #008000 } /* Keyword.Pseudo */\n",
       "body .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */\n",
       "body .kt { color: #B00040 } /* Keyword.Type */\n",
       "body .m { color: #666666 } /* Literal.Number */\n",
       "body .s { color: #BA2121 } /* Literal.String */\n",
       "body .na { color: #7D9029 } /* Name.Attribute */\n",
       "body .nb { color: #008000 } /* Name.Builtin */\n",
       "body .nc { color: #0000FF; font-weight: bold } /* Name.Class */\n",
       "body .no { color: #880000 } /* Name.Constant */\n",
       "body .nd { color: #AA22FF } /* Name.Decorator */\n",
       "body .ni { color: #999999; font-weight: bold } /* Name.Entity */\n",
       "body .ne { color: #D2413A; font-weight: bold } /* Name.Exception */\n",
       "body .nf { color: #0000FF } /* Name.Function */\n",
       "body .nl { color: #A0A000 } /* Name.Label */\n",
       "body .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */\n",
       "body .nt { color: #008000; font-weight: bold } /* Name.Tag */\n",
       "body .nv { color: #19177C } /* Name.Variable */\n",
       "body .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */\n",
       "body .w { color: #bbbbbb } /* Text.Whitespace */\n",
       "body .mb { color: #666666 } /* Literal.Number.Bin */\n",
       "body .mf { color: #666666 } /* Literal.Number.Float */\n",
       "body .mh { color: #666666 } /* Literal.Number.Hex */\n",
       "body .mi { color: #666666 } /* Literal.Number.Integer */\n",
       "body .mo { color: #666666 } /* Literal.Number.Oct */\n",
       "body .sa { color: #BA2121 } /* Literal.String.Affix */\n",
       "body .sb { color: #BA2121 } /* Literal.String.Backtick */\n",
       "body .sc { color: #BA2121 } /* Literal.String.Char */\n",
       "body .dl { color: #BA2121 } /* Literal.String.Delimiter */\n",
       "body .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */\n",
       "body .s2 { color: #BA2121 } /* Literal.String.Double */\n",
       "body .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */\n",
       "body .sh { color: #BA2121 } /* Literal.String.Heredoc */\n",
       "body .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */\n",
       "body .sx { color: #008000 } /* Literal.String.Other */\n",
       "body .sr { color: #BB6688 } /* Literal.String.Regex */\n",
       "body .s1 { color: #BA2121 } /* Literal.String.Single */\n",
       "body .ss { color: #19177C } /* Literal.String.Symbol */\n",
       "body .bp { color: #008000 } /* Name.Builtin.Pseudo */\n",
       "body .fm { color: #0000FF } /* Name.Function.Magic */\n",
       "body .vc { color: #19177C } /* Name.Variable.Class */\n",
       "body .vg { color: #19177C } /* Name.Variable.Global */\n",
       "body .vi { color: #19177C } /* Name.Variable.Instance */\n",
       "body .vm { color: #19177C } /* Name.Variable.Magic */\n",
       "body .il { color: #666666 } /* Literal.Number.Integer.Long */\n",
       "\n",
       "  </style>\n",
       "</head>\n",
       "<body>\n",
       "<h2></h2>\n",
       "\n",
       "<div class=\"highlight\"><pre><span></span><span class=\"k\">def</span> <span class=\"nf\">recombine</span><span class=\"p\">(</span><span class=\"n\">x</span><span class=\"p\">,</span> <span class=\"n\">y</span><span class=\"p\">):</span>\n",
       "    <span class=\"n\">n</span> <span class=\"o\">=</span> <span class=\"nb\">len</span><span class=\"p\">(</span><span class=\"n\">x</span><span class=\"p\">)</span>\n",
       "    <span class=\"n\">c</span> <span class=\"o\">=</span> <span class=\"n\">random</span><span class=\"o\">.</span><span class=\"n\">randrange</span><span class=\"p\">(</span><span class=\"mi\">0</span><span class=\"p\">,</span> <span class=\"n\">n</span><span class=\"p\">)</span>\n",
       "    <span class=\"k\">return</span> <span class=\"n\">x</span><span class=\"p\">[:</span><span class=\"n\">c</span><span class=\"p\">]</span> <span class=\"o\">+</span> <span class=\"n\">y</span><span class=\"p\">[</span><span class=\"n\">c</span><span class=\"p\">:]</span>\n",
       "</pre></div>\n",
       "</body>\n",
       "</html>\n"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "psource(recombine)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The method picks at random a point and merges the parents (`x` and `y`) around it.\n",
    "\n",
    "The mutation is done in the method `mutate`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.01//EN\"\n",
       "   \"http://www.w3.org/TR/html4/strict.dtd\">\n",
       "\n",
       "<html>\n",
       "<head>\n",
       "  <title></title>\n",
       "  <meta http-equiv=\"content-type\" content=\"text/html; charset=None\">\n",
       "  <style type=\"text/css\">\n",
       "td.linenos { background-color: #f0f0f0; padding-right: 10px; }\n",
       "span.lineno { background-color: #f0f0f0; padding: 0 5px 0 5px; }\n",
       "pre { line-height: 125%; }\n",
       "body .hll { background-color: #ffffcc }\n",
       "body  { background: #f8f8f8; }\n",
       "body .c { color: #408080; font-style: italic } /* Comment */\n",
       "body .err { border: 1px solid #FF0000 } /* Error */\n",
       "body .k { color: #008000; font-weight: bold } /* Keyword */\n",
       "body .o { color: #666666 } /* Operator */\n",
       "body .ch { color: #408080; font-style: italic } /* Comment.Hashbang */\n",
       "body .cm { color: #408080; font-style: italic } /* Comment.Multiline */\n",
       "body .cp { color: #BC7A00 } /* Comment.Preproc */\n",
       "body .cpf { color: #408080; font-style: italic } /* Comment.PreprocFile */\n",
       "body .c1 { color: #408080; font-style: italic } /* Comment.Single */\n",
       "body .cs { color: #408080; font-style: italic } /* Comment.Special */\n",
       "body .gd { color: #A00000 } /* Generic.Deleted */\n",
       "body .ge { font-style: italic } /* Generic.Emph */\n",
       "body .gr { color: #FF0000 } /* Generic.Error */\n",
       "body .gh { color: #000080; font-weight: bold } /* Generic.Heading */\n",
       "body .gi { color: #00A000 } /* Generic.Inserted */\n",
       "body .go { color: #888888 } /* Generic.Output */\n",
       "body .gp { color: #000080; font-weight: bold } /* Generic.Prompt */\n",
       "body .gs { font-weight: bold } /* Generic.Strong */\n",
       "body .gu { color: #800080; font-weight: bold } /* Generic.Subheading */\n",
       "body .gt { color: #0044DD } /* Generic.Traceback */\n",
       "body .kc { color: #008000; font-weight: bold } /* Keyword.Constant */\n",
       "body .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */\n",
       "body .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */\n",
       "body .kp { color: #008000 } /* Keyword.Pseudo */\n",
       "body .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */\n",
       "body .kt { color: #B00040 } /* Keyword.Type */\n",
       "body .m { color: #666666 } /* Literal.Number */\n",
       "body .s { color: #BA2121 } /* Literal.String */\n",
       "body .na { color: #7D9029 } /* Name.Attribute */\n",
       "body .nb { color: #008000 } /* Name.Builtin */\n",
       "body .nc { color: #0000FF; font-weight: bold } /* Name.Class */\n",
       "body .no { color: #880000 } /* Name.Constant */\n",
       "body .nd { color: #AA22FF } /* Name.Decorator */\n",
       "body .ni { color: #999999; font-weight: bold } /* Name.Entity */\n",
       "body .ne { color: #D2413A; font-weight: bold } /* Name.Exception */\n",
       "body .nf { color: #0000FF } /* Name.Function */\n",
       "body .nl { color: #A0A000 } /* Name.Label */\n",
       "body .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */\n",
       "body .nt { color: #008000; font-weight: bold } /* Name.Tag */\n",
       "body .nv { color: #19177C } /* Name.Variable */\n",
       "body .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */\n",
       "body .w { color: #bbbbbb } /* Text.Whitespace */\n",
       "body .mb { color: #666666 } /* Literal.Number.Bin */\n",
       "body .mf { color: #666666 } /* Literal.Number.Float */\n",
       "body .mh { color: #666666 } /* Literal.Number.Hex */\n",
       "body .mi { color: #666666 } /* Literal.Number.Integer */\n",
       "body .mo { color: #666666 } /* Literal.Number.Oct */\n",
       "body .sa { color: #BA2121 } /* Literal.String.Affix */\n",
       "body .sb { color: #BA2121 } /* Literal.String.Backtick */\n",
       "body .sc { color: #BA2121 } /* Literal.String.Char */\n",
       "body .dl { color: #BA2121 } /* Literal.String.Delimiter */\n",
       "body .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */\n",
       "body .s2 { color: #BA2121 } /* Literal.String.Double */\n",
       "body .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */\n",
       "body .sh { color: #BA2121 } /* Literal.String.Heredoc */\n",
       "body .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */\n",
       "body .sx { color: #008000 } /* Literal.String.Other */\n",
       "body .sr { color: #BB6688 } /* Literal.String.Regex */\n",
       "body .s1 { color: #BA2121 } /* Literal.String.Single */\n",
       "body .ss { color: #19177C } /* Literal.String.Symbol */\n",
       "body .bp { color: #008000 } /* Name.Builtin.Pseudo */\n",
       "body .fm { color: #0000FF } /* Name.Function.Magic */\n",
       "body .vc { color: #19177C } /* Name.Variable.Class */\n",
       "body .vg { color: #19177C } /* Name.Variable.Global */\n",
       "body .vi { color: #19177C } /* Name.Variable.Instance */\n",
       "body .vm { color: #19177C } /* Name.Variable.Magic */\n",
       "body .il { color: #666666 } /* Literal.Number.Integer.Long */\n",
       "\n",
       "  </style>\n",
       "</head>\n",
       "<body>\n",
       "<h2></h2>\n",
       "\n",
       "<div class=\"highlight\"><pre><span></span><span class=\"k\">def</span> <span class=\"nf\">mutate</span><span class=\"p\">(</span><span class=\"n\">x</span><span class=\"p\">,</span> <span class=\"n\">gene_pool</span><span class=\"p\">,</span> <span class=\"n\">pmut</span><span class=\"p\">):</span>\n",
       "    <span class=\"k\">if</span> <span class=\"n\">random</span><span class=\"o\">.</span><span class=\"n\">uniform</span><span class=\"p\">(</span><span class=\"mi\">0</span><span class=\"p\">,</span> <span class=\"mi\">1</span><span class=\"p\">)</span> <span class=\"o\">&gt;=</span> <span class=\"n\">pmut</span><span class=\"p\">:</span>\n",
       "        <span class=\"k\">return</span> <span class=\"n\">x</span>\n",
       "\n",
       "    <span class=\"n\">n</span> <span class=\"o\">=</span> <span class=\"nb\">len</span><span class=\"p\">(</span><span class=\"n\">x</span><span class=\"p\">)</span>\n",
       "    <span class=\"n\">g</span> <span class=\"o\">=</span> <span class=\"nb\">len</span><span class=\"p\">(</span><span class=\"n\">gene_pool</span><span class=\"p\">)</span>\n",
       "    <span class=\"n\">c</span> <span class=\"o\">=</span> <span class=\"n\">random</span><span class=\"o\">.</span><span class=\"n\">randrange</span><span class=\"p\">(</span><span class=\"mi\">0</span><span class=\"p\">,</span> <span class=\"n\">n</span><span class=\"p\">)</span>\n",
       "    <span class=\"n\">r</span> <span class=\"o\">=</span> <span class=\"n\">random</span><span class=\"o\">.</span><span class=\"n\">randrange</span><span class=\"p\">(</span><span class=\"mi\">0</span><span class=\"p\">,</span> <span class=\"n\">g</span><span class=\"p\">)</span>\n",
       "\n",
       "    <span class=\"n\">new_gene</span> <span class=\"o\">=</span> <span class=\"n\">gene_pool</span><span class=\"p\">[</span><span class=\"n\">r</span><span class=\"p\">]</span>\n",
       "    <span class=\"k\">return</span> <span class=\"n\">x</span><span class=\"p\">[:</span><span class=\"n\">c</span><span class=\"p\">]</span> <span class=\"o\">+</span> <span class=\"p\">[</span><span class=\"n\">new_gene</span><span class=\"p\">]</span> <span class=\"o\">+</span> <span class=\"n\">x</span><span class=\"p\">[</span><span class=\"n\">c</span><span class=\"o\">+</span><span class=\"mi\">1</span><span class=\"p\">:]</span>\n",
       "</pre></div>\n",
       "</body>\n",
       "</html>\n"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "psource(mutate)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We pick a gene in `x` to mutate and a gene from the gene pool to replace it with.\n",
    "\n",
    "To help initializing the population we have the helper function `init_population`\":"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.01//EN\"\n",
       "   \"http://www.w3.org/TR/html4/strict.dtd\">\n",
       "\n",
       "<html>\n",
       "<head>\n",
       "  <title></title>\n",
       "  <meta http-equiv=\"content-type\" content=\"text/html; charset=None\">\n",
       "  <style type=\"text/css\">\n",
       "td.linenos { background-color: #f0f0f0; padding-right: 10px; }\n",
       "span.lineno { background-color: #f0f0f0; padding: 0 5px 0 5px; }\n",
       "pre { line-height: 125%; }\n",
       "body .hll { background-color: #ffffcc }\n",
       "body  { background: #f8f8f8; }\n",
       "body .c { color: #408080; font-style: italic } /* Comment */\n",
       "body .err { border: 1px solid #FF0000 } /* Error */\n",
       "body .k { color: #008000; font-weight: bold } /* Keyword */\n",
       "body .o { color: #666666 } /* Operator */\n",
       "body .ch { color: #408080; font-style: italic } /* Comment.Hashbang */\n",
       "body .cm { color: #408080; font-style: italic } /* Comment.Multiline */\n",
       "body .cp { color: #BC7A00 } /* Comment.Preproc */\n",
       "body .cpf { color: #408080; font-style: italic } /* Comment.PreprocFile */\n",
       "body .c1 { color: #408080; font-style: italic } /* Comment.Single */\n",
       "body .cs { color: #408080; font-style: italic } /* Comment.Special */\n",
       "body .gd { color: #A00000 } /* Generic.Deleted */\n",
       "body .ge { font-style: italic } /* Generic.Emph */\n",
       "body .gr { color: #FF0000 } /* Generic.Error */\n",
       "body .gh { color: #000080; font-weight: bold } /* Generic.Heading */\n",
       "body .gi { color: #00A000 } /* Generic.Inserted */\n",
       "body .go { color: #888888 } /* Generic.Output */\n",
       "body .gp { color: #000080; font-weight: bold } /* Generic.Prompt */\n",
       "body .gs { font-weight: bold } /* Generic.Strong */\n",
       "body .gu { color: #800080; font-weight: bold } /* Generic.Subheading */\n",
       "body .gt { color: #0044DD } /* Generic.Traceback */\n",
       "body .kc { color: #008000; font-weight: bold } /* Keyword.Constant */\n",
       "body .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */\n",
       "body .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */\n",
       "body .kp { color: #008000 } /* Keyword.Pseudo */\n",
       "body .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */\n",
       "body .kt { color: #B00040 } /* Keyword.Type */\n",
       "body .m { color: #666666 } /* Literal.Number */\n",
       "body .s { color: #BA2121 } /* Literal.String */\n",
       "body .na { color: #7D9029 } /* Name.Attribute */\n",
       "body .nb { color: #008000 } /* Name.Builtin */\n",
       "body .nc { color: #0000FF; font-weight: bold } /* Name.Class */\n",
       "body .no { color: #880000 } /* Name.Constant */\n",
       "body .nd { color: #AA22FF } /* Name.Decorator */\n",
       "body .ni { color: #999999; font-weight: bold } /* Name.Entity */\n",
       "body .ne { color: #D2413A; font-weight: bold } /* Name.Exception */\n",
       "body .nf { color: #0000FF } /* Name.Function */\n",
       "body .nl { color: #A0A000 } /* Name.Label */\n",
       "body .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */\n",
       "body .nt { color: #008000; font-weight: bold } /* Name.Tag */\n",
       "body .nv { color: #19177C } /* Name.Variable */\n",
       "body .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */\n",
       "body .w { color: #bbbbbb } /* Text.Whitespace */\n",
       "body .mb { color: #666666 } /* Literal.Number.Bin */\n",
       "body .mf { color: #666666 } /* Literal.Number.Float */\n",
       "body .mh { color: #666666 } /* Literal.Number.Hex */\n",
       "body .mi { color: #666666 } /* Literal.Number.Integer */\n",
       "body .mo { color: #666666 } /* Literal.Number.Oct */\n",
       "body .sa { color: #BA2121 } /* Literal.String.Affix */\n",
       "body .sb { color: #BA2121 } /* Literal.String.Backtick */\n",
       "body .sc { color: #BA2121 } /* Literal.String.Char */\n",
       "body .dl { color: #BA2121 } /* Literal.String.Delimiter */\n",
       "body .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */\n",
       "body .s2 { color: #BA2121 } /* Literal.String.Double */\n",
       "body .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */\n",
       "body .sh { color: #BA2121 } /* Literal.String.Heredoc */\n",
       "body .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */\n",
       "body .sx { color: #008000 } /* Literal.String.Other */\n",
       "body .sr { color: #BB6688 } /* Literal.String.Regex */\n",
       "body .s1 { color: #BA2121 } /* Literal.String.Single */\n",
       "body .ss { color: #19177C } /* Literal.String.Symbol */\n",
       "body .bp { color: #008000 } /* Name.Builtin.Pseudo */\n",
       "body .fm { color: #0000FF } /* Name.Function.Magic */\n",
       "body .vc { color: #19177C } /* Name.Variable.Class */\n",
       "body .vg { color: #19177C } /* Name.Variable.Global */\n",
       "body .vi { color: #19177C } /* Name.Variable.Instance */\n",
       "body .vm { color: #19177C } /* Name.Variable.Magic */\n",
       "body .il { color: #666666 } /* Literal.Number.Integer.Long */\n",
       "\n",
       "  </style>\n",
       "</head>\n",
       "<body>\n",
       "<h2></h2>\n",
       "\n",
       "<div class=\"highlight\"><pre><span></span><span class=\"k\">def</span> <span class=\"nf\">init_population</span><span class=\"p\">(</span><span class=\"n\">pop_number</span><span class=\"p\">,</span> <span class=\"n\">gene_pool</span><span class=\"p\">,</span> <span class=\"n\">state_length</span><span class=\"p\">):</span>\n",
       "    <span class=\"sd\">&quot;&quot;&quot;Initializes population for genetic algorithm</span>\n",
       "<span class=\"sd\">    pop_number  :  Number of individuals in population</span>\n",
       "<span class=\"sd\">    gene_pool   :  List of possible values for individuals</span>\n",
       "<span class=\"sd\">    state_length:  The length of each individual&quot;&quot;&quot;</span>\n",
       "    <span class=\"n\">g</span> <span class=\"o\">=</span> <span class=\"nb\">len</span><span class=\"p\">(</span><span class=\"n\">gene_pool</span><span class=\"p\">)</span>\n",
       "    <span class=\"n\">population</span> <span class=\"o\">=</span> <span class=\"p\">[]</span>\n",
       "    <span class=\"k\">for</span> <span class=\"n\">i</span> <span class=\"ow\">in</span> <span class=\"nb\">range</span><span class=\"p\">(</span><span class=\"n\">pop_number</span><span class=\"p\">):</span>\n",
       "        <span class=\"n\">new_individual</span> <span class=\"o\">=</span> <span class=\"p\">[</span><span class=\"n\">gene_pool</span><span class=\"p\">[</span><span class=\"n\">random</span><span class=\"o\">.</span><span class=\"n\">randrange</span><span class=\"p\">(</span><span class=\"mi\">0</span><span class=\"p\">,</span> <span class=\"n\">g</span><span class=\"p\">)]</span> <span class=\"k\">for</span> <span class=\"n\">j</span> <span class=\"ow\">in</span> <span class=\"nb\">range</span><span class=\"p\">(</span><span class=\"n\">state_length</span><span class=\"p\">)]</span>\n",
       "        <span class=\"n\">population</span><span class=\"o\">.</span><span class=\"n\">append</span><span class=\"p\">(</span><span class=\"n\">new_individual</span><span class=\"p\">)</span>\n",
       "\n",
       "    <span class=\"k\">return</span> <span class=\"n\">population</span>\n",
       "</pre></div>\n",
       "</body>\n",
       "</html>\n"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "psource(init_population)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The function takes as input the number of individuals in the population, the gene pool and the length of each individual/state. It creates individuals with random genes and returns the population when done."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Explanation\n",
    "\n",
    "Before we solve problems using the genetic algorithm, we will explain how to intuitively understand the algorithm using a trivial exmaple.\n",
    "\n",
    "#### Generating Phrases\n",
    "\n",
    "In this problem, we use a genetic algorithm to generate a particular target phrase from a population of random strings. This is a classic example that helps build intuition about how to use this algorithm in other problems as well. Before we break the problem down, let us try to brute force the solution. Let us say that we want to generate the phrase \"genetic algorithm\". The phrase is 17 characters long. We can use any character from the 26 lowercase characters and the space character. To generate a random phrase of length 17, each space can be filled in 27 ways. So the total number of possible phrases is\n",
    "\n",
    "$$ 27^{17} = 2153693963075557766310747 $$\n",
    "\n",
    "which is a massive number. If we wanted to generate the phrase \"Genetic Algorithm\", we would also have to include all the 26 uppercase characters into consideration thereby increasing the sample space from 27 characters to 53 characters and the total number of possible phrases then would be\n",
    "\n",
    "$$ 53^{17} = 205442259656281392806087233013 $$\n",
    "\n",
    "If we wanted to include punctuations and numerals into the sample space, we would have further complicated an already impossible problem. Hence, brute forcing is not an option. Now we'll apply the genetic algorithm and see how it significantly reduces the search space. We essentially want to *evolve* our population of random strings so that they better approximate the target phrase as the number of generations increase. Genetic algorithms work on the principle of Darwinian Natural Selection according to which, there are three key concepts that need to be in place for evolution to happen. They are:\n",
    "\n",
    "1. <strong> Heredity </strong>: There must be a process in place by which children receive the properties of their parents. <br> \n",
    "For this particular problem, two strings from the population will be chosen as parents and will be split at a random index and recombined as described in the `recombine` function to create a child. This child string will then be added to the new generation.\n",
    "<pre>\n",
    "</pre>\n",
    "2. <strong> Variation </strong>: There must be a variety of traits present in the population or a means with which to introduce variation. <br>If there is no variation in the sample space, we might never reach the global optimum. To ensure that there is enough variation, we can initialize a large population, but this gets computationally expensive as the population gets larger. Hence, we often use another method called mutation. In this method, we randomly change one or more characters of some strings in the population based on a predefined probability value called the mutation rate or mutation probability as described in the `mutate` function. The mutation rate is usually kept quite low. A mutation rate of zero fails to introduce variation in the population and a high mutation rate (say 50%) is as good as a coin flip and the population fails to benefit from the previous recombinations. An optimum balance has to be maintained between population size and mutation rate so as to reduce the computational cost as well as have sufficient variation in the population.\n",
    "<pre>\n",
    "</pre>\n",
    "3. <strong> Selection </strong>: There must be some mechanism by which some members of the population have the opportunity to be parents and pass down their genetic information and some do not. This is typically referred to as \"survival of the fittest\". <br>\n",
    "There has to be some way of determining which phrases in our population have a better chance of eventually evolving into the target phrase. This is done by introducing a fitness function that calculates how close the generated phrase is to the target phrase. The function will simply return a scalar value corresponding to the number of matching characters between the generated phrase and the target phrase."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before solving the problem, we first need to define our target phrase."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "target = 'Genetic Algorithm'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "We then need to define our gene pool, i.e the elements which an individual from the population might comprise of. Here, the gene pool contains all uppercase and lowercase letters of the English alphabet and the space character."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# The ASCII values of uppercase characters ranges from 65 to 91\n",
    "u_case = [chr(x) for x in range(65, 91)]\n",
    "# The ASCII values of lowercase characters ranges from 97 to 123\n",
    "l_case = [chr(x) for x in range(97, 123)]\n",
    "\n",
    "gene_pool = []\n",
    "gene_pool.extend(u_case) # adds the uppercase list to the gene pool\n",
    "gene_pool.extend(l_case) # adds the lowercase list to the gene pool\n",
    "gene_pool.append(' ')    # adds the space character to the gene pool"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now need to define the maximum size of each population. Larger populations have more variation but are computationally more  expensive to run algorithms on."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "max_population = 100"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As our population is not very large, we can afford to keep a relatively large mutation rate."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "mutation_rate = 0.07 # 7%"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Great! Now, we need to define the most important metric for the genetic algorithm, i.e the fitness function. This will simply return the number of matching characters between the generated sample and the target phrase."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def fitness_fn(sample):\n",
    "    # initialize fitness to 0\n",
    "    fitness = 0\n",
    "    for i in range(len(sample)):\n",
    "        # increment fitness by 1 for every matching character\n",
    "        if sample[i] == target[i]:\n",
    "            fitness += 1\n",
    "    return fitness"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before we run our genetic algorithm, we need to initialize a random population. We will use the `init_population` function to do this. We need to pass in the maximum population size, the gene pool and the length of each individual, which in this case will be the same as the length of the target phrase."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "population = init_population(max_population, gene_pool, len(target))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will now define how the individuals in the population should change as the number of generations increases. First, the `select` function will be run on the population to select *two* individuals with high fitness values. These will be the parents which will then be recombined using the `recombine` function to generate the child."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "parents = select(2, population, fitness_fn) "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# The recombine function takes two parents as arguments, so we need to unpack the previous variable\n",
    "child = recombine(*parents)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we need to apply a mutation according to the mutation rate. We call the `mutate` function on the child with the gene pool and mutation rate as the additional arguments."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "child = mutate(child, gene_pool, mutation_rate)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above lines can be condensed into\n",
    "\n",
    "`child = mutate(recombine(*select(2, population, fitness_fn)), gene_pool, mutation_rate)`\n",
    "\n",
    "And, we need to do this `for` every individual in the current population to generate the new population."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "population = [mutate(recombine(*select(2, population, fitness_fn)), gene_pool, mutation_rate) for i in range(len(population))]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The individual with the highest fitness can then be found using the `max` function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "current_best = max(population, key=fitness_fn)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's print this out"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['j', 'F', 'm', 'F', 'N', 'i', 'c', 'v', 'm', 'j', 'V', 'o', 'd', 'r', 't', 'V', 'H']\n"
     ]
    }
   ],
   "source": [
    "print(current_best)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We see that this is a list of characters. This can be converted to a string using the join function"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "jFmFNicvmjVodrtVH\n"
     ]
    }
   ],
   "source": [
    "current_best_string = ''.join(current_best)\n",
    "print(current_best_string)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now need to define the conditions to terminate the algorithm. This can happen in two ways\n",
    "1. Termination after a predefined number of generations\n",
    "2. Termination when the fitness of the best individual of the current generation reaches a predefined threshold value.\n",
    "\n",
    "We define these variables below"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "ngen = 1200 # maximum number of generations\n",
    "# we set the threshold fitness equal to the length of the target phrase\n",
    "# i.e the algorithm only terminates whne it has got all the characters correct \n",
    "# or it has completed 'ngen' number of generations\n",
    "f_thres = len(target)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "To generate `ngen` number of generations, we run a `for` loop `ngen` number of times. After each generation, we calculate the fitness of the best individual of the generation and compare it to the value of `f_thres` using the `fitness_threshold` function. After every generation, we print out the best individual of the generation and the corresponding fitness value. Lets now write a function to do this."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def genetic_algorithm_stepwise(population, fitness_fn, gene_pool=[0, 1], f_thres=None, ngen=1200, pmut=0.1):\n",
    "    for generation in range(ngen):\n",
    "        population = [mutate(recombine(*select(2, population, fitness_fn)), gene_pool, pmut) for i in range(len(population))]\n",
    "        # stores the individual genome with the highest fitness in the current population\n",
    "        current_best = ''.join(max(population, key=fitness_fn))\n",
    "        print(f'Current best: {current_best}\\t\\tGeneration: {str(generation)}\\t\\tFitness: {fitness_fn(current_best)}\\r', end='')\n",
    "        \n",
    "        # compare the fitness of the current best individual to f_thres\n",
    "        fittest_individual = fitness_threshold(fitness_fn, f_thres, population)\n",
    "        \n",
    "        # if fitness is greater than or equal to f_thres, we terminate the algorithm\n",
    "        if fittest_individual:\n",
    "            return fittest_individual, generation\n",
    "    return max(population, key=fitness_fn) , generation       "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The function defined above is essentially the same as the one defined in `search.py` with the added functionality of printing out the data of each generation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.01//EN\"\n",
       "   \"http://www.w3.org/TR/html4/strict.dtd\">\n",
       "\n",
       "<html>\n",
       "<head>\n",
       "  <title></title>\n",
       "  <meta http-equiv=\"content-type\" content=\"text/html; charset=None\">\n",
       "  <style type=\"text/css\">\n",
       "td.linenos { background-color: #f0f0f0; padding-right: 10px; }\n",
       "span.lineno { background-color: #f0f0f0; padding: 0 5px 0 5px; }\n",
       "pre { line-height: 125%; }\n",
       "body .hll { background-color: #ffffcc }\n",
       "body  { background: #f8f8f8; }\n",
       "body .c { color: #408080; font-style: italic } /* Comment */\n",
       "body .err { border: 1px solid #FF0000 } /* Error */\n",
       "body .k { color: #008000; font-weight: bold } /* Keyword */\n",
       "body .o { color: #666666 } /* Operator */\n",
       "body .ch { color: #408080; font-style: italic } /* Comment.Hashbang */\n",
       "body .cm { color: #408080; font-style: italic } /* Comment.Multiline */\n",
       "body .cp { color: #BC7A00 } /* Comment.Preproc */\n",
       "body .cpf { color: #408080; font-style: italic } /* Comment.PreprocFile */\n",
       "body .c1 { color: #408080; font-style: italic } /* Comment.Single */\n",
       "body .cs { color: #408080; font-style: italic } /* Comment.Special */\n",
       "body .gd { color: #A00000 } /* Generic.Deleted */\n",
       "body .ge { font-style: italic } /* Generic.Emph */\n",
       "body .gr { color: #FF0000 } /* Generic.Error */\n",
       "body .gh { color: #000080; font-weight: bold } /* Generic.Heading */\n",
       "body .gi { color: #00A000 } /* Generic.Inserted */\n",
       "body .go { color: #888888 } /* Generic.Output */\n",
       "body .gp { color: #000080; font-weight: bold } /* Generic.Prompt */\n",
       "body .gs { font-weight: bold } /* Generic.Strong */\n",
       "body .gu { color: #800080; font-weight: bold } /* Generic.Subheading */\n",
       "body .gt { color: #0044DD } /* Generic.Traceback */\n",
       "body .kc { color: #008000; font-weight: bold } /* Keyword.Constant */\n",
       "body .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */\n",
       "body .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */\n",
       "body .kp { color: #008000 } /* Keyword.Pseudo */\n",
       "body .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */\n",
       "body .kt { color: #B00040 } /* Keyword.Type */\n",
       "body .m { color: #666666 } /* Literal.Number */\n",
       "body .s { color: #BA2121 } /* Literal.String */\n",
       "body .na { color: #7D9029 } /* Name.Attribute */\n",
       "body .nb { color: #008000 } /* Name.Builtin */\n",
       "body .nc { color: #0000FF; font-weight: bold } /* Name.Class */\n",
       "body .no { color: #880000 } /* Name.Constant */\n",
       "body .nd { color: #AA22FF } /* Name.Decorator */\n",
       "body .ni { color: #999999; font-weight: bold } /* Name.Entity */\n",
       "body .ne { color: #D2413A; font-weight: bold } /* Name.Exception */\n",
       "body .nf { color: #0000FF } /* Name.Function */\n",
       "body .nl { color: #A0A000 } /* Name.Label */\n",
       "body .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */\n",
       "body .nt { color: #008000; font-weight: bold } /* Name.Tag */\n",
       "body .nv { color: #19177C } /* Name.Variable */\n",
       "body .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */\n",
       "body .w { color: #bbbbbb } /* Text.Whitespace */\n",
       "body .mb { color: #666666 } /* Literal.Number.Bin */\n",
       "body .mf { color: #666666 } /* Literal.Number.Float */\n",
       "body .mh { color: #666666 } /* Literal.Number.Hex */\n",
       "body .mi { color: #666666 } /* Literal.Number.Integer */\n",
       "body .mo { color: #666666 } /* Literal.Number.Oct */\n",
       "body .sa { color: #BA2121 } /* Literal.String.Affix */\n",
       "body .sb { color: #BA2121 } /* Literal.String.Backtick */\n",
       "body .sc { color: #BA2121 } /* Literal.String.Char */\n",
       "body .dl { color: #BA2121 } /* Literal.String.Delimiter */\n",
       "body .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */\n",
       "body .s2 { color: #BA2121 } /* Literal.String.Double */\n",
       "body .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */\n",
       "body .sh { color: #BA2121 } /* Literal.String.Heredoc */\n",
       "body .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */\n",
       "body .sx { color: #008000 } /* Literal.String.Other */\n",
       "body .sr { color: #BB6688 } /* Literal.String.Regex */\n",
       "body .s1 { color: #BA2121 } /* Literal.String.Single */\n",
       "body .ss { color: #19177C } /* Literal.String.Symbol */\n",
       "body .bp { color: #008000 } /* Name.Builtin.Pseudo */\n",
       "body .fm { color: #0000FF } /* Name.Function.Magic */\n",
       "body .vc { color: #19177C } /* Name.Variable.Class */\n",
       "body .vg { color: #19177C } /* Name.Variable.Global */\n",
       "body .vi { color: #19177C } /* Name.Variable.Instance */\n",
       "body .vm { color: #19177C } /* Name.Variable.Magic */\n",
       "body .il { color: #666666 } /* Literal.Number.Integer.Long */\n",
       "\n",
       "  </style>\n",
       "</head>\n",
       "<body>\n",
       "<h2></h2>\n",
       "\n",
       "<div class=\"highlight\"><pre><span></span><span class=\"k\">def</span> <span class=\"nf\">genetic_algorithm</span><span class=\"p\">(</span><span class=\"n\">population</span><span class=\"p\">,</span> <span class=\"n\">fitness_fn</span><span class=\"p\">,</span> <span class=\"n\">gene_pool</span><span class=\"o\">=</span><span class=\"p\">[</span><span class=\"mi\">0</span><span class=\"p\">,</span> <span class=\"mi\">1</span><span class=\"p\">],</span> <span class=\"n\">f_thres</span><span class=\"o\">=</span><span class=\"bp\">None</span><span class=\"p\">,</span> <span class=\"n\">ngen</span><span class=\"o\">=</span><span class=\"mi\">1000</span><span class=\"p\">,</span> <span class=\"n\">pmut</span><span class=\"o\">=</span><span class=\"mf\">0.1</span><span class=\"p\">):</span>\n",
       "    <span class=\"sd\">&quot;&quot;&quot;[Figure 4.8]&quot;&quot;&quot;</span>\n",
       "    <span class=\"k\">for</span> <span class=\"n\">i</span> <span class=\"ow\">in</span> <span class=\"nb\">range</span><span class=\"p\">(</span><span class=\"n\">ngen</span><span class=\"p\">):</span>\n",
       "        <span class=\"n\">population</span> <span class=\"o\">=</span> <span class=\"p\">[</span><span class=\"n\">mutate</span><span class=\"p\">(</span><span class=\"n\">recombine</span><span class=\"p\">(</span><span class=\"o\">*</span><span class=\"n\">select</span><span class=\"p\">(</span><span class=\"mi\">2</span><span class=\"p\">,</span> <span class=\"n\">population</span><span class=\"p\">,</span> <span class=\"n\">fitness_fn</span><span class=\"p\">)),</span> <span class=\"n\">gene_pool</span><span class=\"p\">,</span> <span class=\"n\">pmut</span><span class=\"p\">)</span>\n",
       "                      <span class=\"k\">for</span> <span class=\"n\">i</span> <span class=\"ow\">in</span> <span class=\"nb\">range</span><span class=\"p\">(</span><span class=\"nb\">len</span><span class=\"p\">(</span><span class=\"n\">population</span><span class=\"p\">))]</span>\n",
       "\n",
       "        <span class=\"n\">fittest_individual</span> <span class=\"o\">=</span> <span class=\"n\">fitness_threshold</span><span class=\"p\">(</span><span class=\"n\">fitness_fn</span><span class=\"p\">,</span> <span class=\"n\">f_thres</span><span class=\"p\">,</span> <span class=\"n\">population</span><span class=\"p\">)</span>\n",
       "        <span class=\"k\">if</span> <span class=\"n\">fittest_individual</span><span class=\"p\">:</span>\n",
       "            <span class=\"k\">return</span> <span class=\"n\">fittest_individual</span>\n",
       "\n",
       "\n",
       "    <span class=\"k\">return</span> <span class=\"n\">argmax</span><span class=\"p\">(</span><span class=\"n\">population</span><span class=\"p\">,</span> <span class=\"n\">key</span><span class=\"o\">=</span><span class=\"n\">fitness_fn</span><span class=\"p\">)</span>\n",
       "</pre></div>\n",
       "</body>\n",
       "</html>\n"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "psource(genetic_algorithm)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We have defined all the required functions and variables. Let's now create a new population and test the function we wrote above."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 49,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Current best: Genetic Algorithm\t\tGeneration: 472\t\tFitness: 17\r"
     ]
    }
   ],
   "source": [
    "population = init_population(max_population, gene_pool, len(target))\n",
    "solution, generations = genetic_algorithm_stepwise(population, fitness_fn, gene_pool, f_thres, ngen, mutation_rate)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The genetic algorithm was able to converge!\n",
    "We implore you to rerun the above cell and play around with `target, max_population, f_thres, ngen` etc parameters to get a better intuition of how the algorithm works. To summarize, if we can define the problem states in simple array format and if we can create a fitness function to gauge how good or bad our approximate solutions are, there is a high chance that we can get a satisfactory solution using a genetic algorithm. \n",
    "- There is also a better GUI version of this program `genetic_algorithm_example.py` in the GUI folder for you to play around with."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Usage\n",
    "\n",
    "Below we give two example usages for the genetic algorithm, for a graph coloring problem and the 8 queens problem.\n",
    "\n",
    "#### Graph Coloring\n",
    "\n",
    "First we will take on the simpler problem of coloring a small graph with two colors. Before we do anything, let's imagine how a solution might look. First, we have to represent our colors. Say, 'R' for red and 'G' for green. These make up our gene pool. What of the individual solutions though? For that, we will look at our problem. We stated we have a graph. A graph has nodes and edges, and we want to color the nodes. Naturally, we want to store each node's color. If we have four nodes, we can store their colors in a list of genes, one for each node. A possible solution will then look like this: ['R', 'R', 'G', 'R']. In the general case, we will represent each solution with a list of chars ('R' and 'G'), with length the number of nodes.\n",
    "\n",
    "Next we need to come up with a fitness function that appropriately scores individuals. Again, we will look at the problem definition at hand. We want to color a graph. For a solution to be optimal, no edge should connect two nodes of the same color. How can we use this information to score a solution? A naive (and ineffective) approach would be to count the different colors in the string. So ['R', 'R', 'R', 'R'] has a score of 1 and ['R', 'R', 'G', 'G'] has a score of 2. Why that fitness function is not ideal though? Why, we forgot the information about the edges! The edges are pivotal to the problem and the above function only deals with node colors. We didn't use all the information at hand and ended up with an ineffective answer. How, then, can we use that information to our advantage?\n",
    "\n",
    "We said that the optimal solution will have all the edges connecting nodes of different color. So, to score a solution we can count how many edges are valid (aka connecting nodes of different color). That is a great fitness function!\n",
    "\n",
    "Let's jump into solving this problem using the `genetic_algorithm` function."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First we need to represent the graph. Since we mostly need information about edges, we will just store the edges. We will denote edges with capital letters and nodes with integers:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "edges = {\n",
    "    'A': [0, 1],\n",
    "    'B': [0, 3],\n",
    "    'C': [1, 2],\n",
    "    'D': [2, 3]\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Edge 'A' connects nodes 0 and 1, edge 'B' connects nodes 0 and 3 etc.\n",
    "\n",
    "We already said our gene pool is 'R' and 'G', so we can jump right into initializing our population. Since we have only four nodes, `state_length` should be 4. For the number of individuals, we will try 8. We can increase this number if we need higher accuracy, but be careful! Larger populations need more computating power and take longer. You need to strike that sweet balance between accuracy and cost (the ultimate dilemma of the programmer!)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[['R', 'G', 'G', 'R'], ['R', 'G', 'R', 'R'], ['G', 'R', 'G', 'R'], ['R', 'G', 'R', 'G'], ['G', 'R', 'R', 'G'], ['G', 'R', 'G', 'R'], ['G', 'R', 'R', 'R'], ['R', 'G', 'G', 'G']]\n"
     ]
    }
   ],
   "source": [
    "population = init_population(8, ['R', 'G'], 4)\n",
    "print(population)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We created and printed the population. You can see that the genes in the individuals are random and there are 8 individuals each with 4 genes.\n",
    "\n",
    "Next we need to write our fitness function. We previously said we want the function to count how many edges are valid. So, given a coloring/individual `c`, we will do just that:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def fitness(c):\n",
    "    return sum(c[n1] != c[n2] for (n1, n2) in edges.values())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Great! Now we will run the genetic algorithm and see what solution it gives."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['R', 'G', 'R', 'G']\n"
     ]
    }
   ],
   "source": [
    "solution = genetic_algorithm(population, fitness, gene_pool=['R', 'G'])\n",
    "print(solution)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The algorithm converged to a solution. Let's check its score:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "4\n"
     ]
    }
   ],
   "source": [
    "print(fitness(solution))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The solution has a score of 4. Which means it is optimal, since we have exactly 4 edges in our graph, meaning all are valid!\n",
    "\n",
    "*NOTE: Because the algorithm is non-deterministic, there is a chance a different solution is given. It might even be wrong, if we are very unlucky!*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Eight Queens\n",
    "\n",
    "Let's take a look at a more complicated problem.\n",
    "\n",
    "In the *Eight Queens* problem, we are tasked with placing eight queens on an 8x8 chessboard without any queen threatening the others (aka queens should not be in the same row, column or diagonal). In its general form the problem is defined as placing *N* queens in an NxN chessboard without any conflicts.\n",
    "\n",
    "First we need to think about the representation of each solution. We can go the naive route of representing the whole chessboard with the queens' placements on it. That is definitely one way to go about it, but for the purpose of this tutorial we will do something different. We have eight queens, so we will have a gene for each of them. The gene pool will be numbers from 0 to 7, for the different columns. The *position* of the gene in the state will denote the row the particular queen is placed in.\n",
    "\n",
    "For example, we can have the state \"03304577\". Here the first gene with a value of 0 means \"the queen at row 0 is placed at column 0\", for the second gene \"the queen at row 1 is placed at column 3\" and so forth.\n",
    "\n",
    "We now need to think about the fitness function. On the graph coloring problem we counted the valid edges. The same thought process can be applied here. Instead of edges though, we have positioning between queens. If two queens are not threatening each other, we say they are at a \"non-attacking\" positioning. We can, therefore, count how many such positionings are there.\n",
    "\n",
    "Let's dive right in and initialize our population:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[0, 2, 7, 1, 7, 3, 2, 4], [2, 7, 5, 4, 4, 5, 2, 0], [7, 1, 6, 0, 1, 3, 0, 2], [0, 3, 6, 1, 3, 0, 5, 4], [0, 4, 6, 4, 7, 4, 1, 6]]\n"
     ]
    }
   ],
   "source": [
    "population = init_population(100, range(8), 8)\n",
    "print(population[:5])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We have a population of 100 and each individual has 8 genes. The gene pool is the integers from 0 to 7, in string form. Above you can see the first five individuals.\n",
    "\n",
    "Next we need to write our fitness function. Remember, queens threaten each other if they are at the same row, column or diagonal.\n",
    "\n",
    "Since positionings are mutual, we must take care not to count them twice. Therefore for each queen, we will only check for conflicts for the queens after her.\n",
    "\n",
    "A gene's value in an individual `q` denotes the queen's column, and the position of the gene denotes its row. We can check if the aforementioned values between two genes are the same. We also need to check for diagonals. A queen *a* is in the diagonal of another queen, *b*, if the difference of the rows between them is equal to either their difference in columns (for the diagonal on the right of *a*) or equal to the negative difference of their columns (for the left diagonal of *a*). Below is given the fitness function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def fitness(q):\n",
    "    non_attacking = 0\n",
    "    for row1 in range(len(q)):\n",
    "        for row2 in range(row1+1, len(q)):\n",
    "            col1 = int(q[row1])\n",
    "            col2 = int(q[row2])\n",
    "            row_diff = row1 - row2\n",
    "            col_diff = col1 - col2\n",
    "\n",
    "            if col1 != col2 and row_diff != col_diff and row_diff != -col_diff:\n",
    "                non_attacking += 1\n",
    "\n",
    "    return non_attacking"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the best score achievable is 28. That is because for each queen we only check for the queens after her. For the first queen we check 7 other queens, for the second queen 6 others and so on. In short, the number of checks we make is the sum 7+6+5+...+1. Which is equal to 7\\*(7+1)/2 = 28.\n",
    "\n",
    "Because it is very hard and will take long to find a perfect solution, we will set the fitness threshold at 25. If we find an individual with a score greater or equal to that, we will halt. Let's see how the genetic algorithm will fare."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[5, 0, 6, 3, 7, 4, 1, 3]\n",
      "26\n"
     ]
    }
   ],
   "source": [
    "solution = genetic_algorithm(population, fitness, f_thres=25, gene_pool=range(8))\n",
    "print(solution)\n",
    "print(fitness(solution))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Above you can see the solution and its fitness score, which should be no less than 25."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With that this tutorial on the genetic algorithm comes to an end. Hope you found this guide helpful!"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}