AEC.02 - Elements of Evolutionary Algorithms.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "<div align='left' style=\"width:400px;height:120px;overflow:hidden;\">\n",
    "<a href='http://www.uff.br'>\n",
    "<img align='left' style='display: block;height: 92%' src='https://github.com/lmarti/jupyter_custom/raw/master/imgs/uff.png' alt='UFF logo' title='UFF logo'/>\n",
    "</a>\n",
    "<a href='http://www.ic.uff.br'>\n",
    "<img align='left' style='display: block;height: 100%' src='https://github.com/lmarti/jupyter_custom/raw/master/imgs/logo-ic.png' alt='IC logo' title='IC logo'/>\n",
    "</a>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {},
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "# Elements of Evolutionary Algorithms"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "slide_helper": "subslide_end"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "## Luis Martí, [IC](http://www.ic.uff.br)/[UFF](http://www.uff.br)\n",
    "\n",
    "[http://lmarti.com](http://lmarti.com); [lmarti@ic.uff.br](mailto:lmarti@ic.uff.br) \n",
    "\n",
    "[Advanced Evolutionary Computation: Theory and Practice](http://lmarti.com/aec-2014) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "The notebook is better viewed rendered as slides. You can convert it to slides and view them by:\n",
    "- using [nbconvert](http://ipython.org/ipython-doc/1/interactive/nbconvert.html) with a command like:\n",
    "  ```bash\n",
    "  $ ipython nbconvert --to slides --post serve <this-notebook-name.ipynb>\n",
    "  ```\n",
    "- installing [Reveal.js - Jupyter/IPython Slideshow Extension](https://github.com/damianavila/live_reveal)\n",
    "- using the online [IPython notebook slide viewer](https://slideviewer.herokuapp.com/) (some slides of the notebook might not be properly rendered).\n",
    "\n",
    "This and other related IPython notebooks can be found at the course github repository:\n",
    "* [https://github.com/lmarti/evolutionary-computation-course](https://github.com/lmarti/evolutionary-computation-course)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "slide_helper": "subslide_end",
     "slide_type": "subslide"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## In this demonstration class we will deal with the features and problems shared by most evolutionary algorithms.\n",
    "\n",
    "*Note*: Most of the material used in this notebook comes from [DEAP](https://github.com/DEAP/deap) documentation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "slide_helper": "subslide_end",
     "slide_type": "subslide"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Elements to take into account using evolutionary algorithms\n",
    "\n",
    "* **Individual representation** (binary, Gray, floating-point, etc.);\n",
    "* **evaluation** and **fitness assignment**;\n",
    "* **mating selection**, that establishes a partial order of individuals in the population using their fitness function value as reference and determines the degree at which individuals in the population will take part in the generation of new (offspring) individuals.\n",
    "* **variation**, that applies a range of evolution-inspired operators, like crossover, mutation, etc., to synthesize offspring individuals from the current (parent) population. This process is supposed to prime the fittest individuals so they play a bigger role in the generation of the offspring.\n",
    "* **environmental selection**, that merges the parent and offspring individuals to produce the population that will be used in the next iteration. This process often involves the deletion of some individuals using a given criterion in order to keep the amount of individuals bellow a certain threshold.\n",
    "* **stopping criterion**, that determines when the algorithm shoulod be stopped, either because the optimum was reach or because the optimization process is not progressing."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Hence a 'general' evolutionary algorithm can be described as"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "slide_helper": "subslide_end"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "```python\n",
    "def evolutionary_algorithm():\n",
    "    'Pseudocode of an evolutionary algorithm'    \n",
    "    populations = [] # a list with all the populations\n",
    "    \n",
    "    populations[0] =  initialize_population(pop_size)\n",
    "    t = 0\n",
    "    \n",
    "    while not stop_criterion(populations[t]):\n",
    "        fitnesses = evaluate(populations[t])\n",
    "        offspring = matting_and_variation(populations[t],\n",
    "                                          fitnesses)\n",
    "        populations[t+1] = environmental_selection(           \n",
    "                                          populations[t],\n",
    "                                          offspring)\n",
    "        t = t+1\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "slide_helper": "subslide_end",
     "slide_type": "subslide"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Python libraries for evolutionary computation\n",
    "\n",
    "* PaGMO/PyGMO\n",
    "* Inspyred\n",
    "* **Distributed Evolutionary Algorithms in Python (DEAP)**\n",
    "\n",
    "> There are potentially many more, feel free to give me some feedback on this."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 6,
     "slide_helper": "subslide_end",
     "slide_type": "subslide"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "<table>\n",
    "<tr>\n",
    "<td width='47%'>\n",
    "<img src='https://raw.githubusercontent.com/DEAP/deap/master/doc/_static/deap_long.png' title=\"DEAP logo\" width='92%' align='center'/>\n",
    "</td>\n",
    "<td>\n",
    "<ul>\n",
    "<li> Open source Python library with,\n",
    "<li> genetic algorithm using any representation;\n",
    "<li> evolutionary strategies (including CMA-ES);\n",
    "<li> multi-objective optimization from the start;\n",
    "<li> co-evolution (cooperative and competitive) of multiple populations;\n",
    "<li> parallelization of the evaluations (and more) using SCOOP;\n",
    "<li> statistics keeping, and;\n",
    "<li> benchmarks module containing some common test functions.\n",
    "<li> [https://github.com/DEAP/deap](https://github.com/DEAP/deap)\n",
    "</ul>\n",
    "</td>\n",
    "</tr>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Lets start with an example and analyze it"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 6,
     "slide_helper": "subslide_end"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "## The One Max problem\n",
    "\n",
    "* Maximize the number of ones in a binary string (list, vector, etc.).\n",
    "* More formally, from the set of binary strings of length $n$,\n",
    "$$\\mathcal{S}=\\left\\{s_1,\\ldots,s_n\\right\\}, \\text{ with } s_i=\\left\\{0,1\\right\\}.$$\n",
    "* Find $s^\\ast\\in\\mathcal{S}$ such that\n",
    "$$s^\\ast = \\operatorname*{arg\\,max}_{s\\in\\mathcal{S}} \\sum_{i=1}^{n}{s_i}.$$\n",
    "* Its clear that the optimum is an *all-ones* string."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Coding the problem"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 12
    },
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "import random\n",
    "from deap import algorithms, base, creator, tools"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false,
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "%matplotlib inline\n",
    "%config InlineBackend.figure_format = 'retina'\n",
    "plt.rc('text', usetex=True)\n",
    "plt.rc('font', family='serif')\n",
    "plt.rcParams['text.latex.preamble'] ='\\\\usepackage{libertine}\\n\\\\usepackage[utf8]{inputenc}'\n",
    "\n",
    "import seaborn\n",
    "seaborn.set(style='whitegrid')\n",
    "seaborn.set_context('notebook')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 13
    },
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "creator.create(\"FitnessMax\", base.Fitness, weights=(1.0,))\n",
    "creator.create(\"Individual\", list, fitness=creator.FitnessMax)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 14,
     "slide_helper": "subslide_end"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "def evalOneMax(individual):\n",
    "    return (sum(individual),)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Defining the elements "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false,
    "internals": {},
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "toolbox = base.Toolbox()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 17
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "toolbox.register(\"attr_bool\", random.randint, 0, 1)\n",
    "toolbox.register(\"individual\", tools.initRepeat, creator.Individual,\n",
    "                 toolbox.attr_bool, n=100)\n",
    "toolbox.register(\"population\", tools.initRepeat, list, \n",
    "                 toolbox.individual)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 18,
     "slide_helper": "subslide_end"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "toolbox.register(\"evaluate\", evalOneMax)\n",
    "toolbox.register(\"mate\", tools.cxTwoPoint)\n",
    "toolbox.register(\"mutate\", tools.mutFlipBit, indpb=0.05)\n",
    "toolbox.register(\"select\", tools.selTournament, tournsize=3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 18,
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Running the experiment"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 18
    },
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "pop = toolbox.population(n=300)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 21
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Lets run only 10 generations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 22
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "result = algorithms.eaSimple(pop, toolbox, cxpb=0.5, mutpb=0.2, \n",
    "                             ngen=10, verbose=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 23
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Current best fitness: (83,)\n"
     ]
    }
   ],
   "source": [
    "print('Current best fitness:', evalOneMax(tools.selBest(pop, k=1)[0]))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 24
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "result = algorithms.eaSimple(pop, toolbox, cxpb=0.5, mutpb=0.2, \n",
    "                             ngen=50, verbose=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 25,
     "slide_helper": "subslide_end"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Current best fitness: (100,)\n"
     ]
    }
   ],
   "source": [
    "print('Current best fitness:', evalOneMax(tools.selBest(pop, k=1)[0]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 25,
     "slide_helper": "subslide_end",
     "slide_type": "subslide"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Essential features\n",
    "\n",
    "* `deap.creator`: meta-factory allowing to create classes that will fulfill the needs of your evolutionary algorithms.\n",
    "* `deap.base.Toolbox`: A toolbox for evolution that contains the evolutionary operators. You may populate the toolbox with any other function by using the `register()` method\n",
    "* `deap.base.Fitness([values])`: The fitness is a measure of quality of a solution. If values are provided as a tuple, the fitness is initalized using those values, otherwise it is empty (or invalid). You should inherit from this class to define your custom fitnesses."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 25,
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Defining an individual\n",
    "First import the required modules and register the different functions required to create individuals that are a list of floats with a minimizing two objectives fitness."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 28
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "import random\n",
    "\n",
    "from deap import base\n",
    "from deap import creator\n",
    "from deap import tools"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 29
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "IND_SIZE = 5"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/Users/lm/anaconda/lib/python3.6/site-packages/deap-1.1.0-py3.6-macosx-10.7-x86_64.egg/deap/creator.py:141: RuntimeWarning: A class named 'Individual' has already been created and it will be overwritten. Consider deleting previous creation of that class or rename it.\n",
      "  RuntimeWarning)\n"
     ]
    }
   ],
   "source": [
    "creator.create(\"FitnessMin\", base.Fitness, weights=(-1.0, -1.0))\n",
    "creator.create(\"Individual\", list, fitness=creator.FitnessMin)\n",
    "\n",
    "toolbox1 = base.Toolbox()\n",
    "toolbox1.register(\"attr_float\", random.random)\n",
    "toolbox1.register(\"individual\", tools.initRepeat, creator.Individual,\n",
    "                 toolbox1.attr_float, n=IND_SIZE)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 30,
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "The first individual can now be built"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 32
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "ind1 = toolbox1.individual()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 33
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Printing the individual ind1 and checking if its fitness is valid will give something like this"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 34
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[0.2989651981634037, 0.9689899788264542, 0.3524509946515799, 0.06381306368762452, 0.4555534543646952]\n"
     ]
    }
   ],
   "source": [
    "print(ind1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 35
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "False\n"
     ]
    }
   ],
   "source": [
    "print(ind1.fitness.valid)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 36,
     "slide_helper": "subslide_end"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "The individual is printed as its base class representation (here a list) and the fitness is invalid because it contains no values."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 36,
     "slide_helper": "subslide_end",
     "slide_type": "subslide"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Evaluation\n",
    "The evaluation is the most \"personal\" part of an evolutionary algorithm\n",
    "* it is the only part of the library that you must write yourself. \n",
    "* A typical evaluation function takes one individual as argument and return its fitness as a tuple. \n",
    "* A fitness is a list of floating point values and has a property valid to know if this individual shall be re-evaluated. \n",
    "* The fitness is set by setting the values to the associated tuple."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 36,
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "For example, the following evaluates the previously created individual ind1 and assign its fitness to the corresponding values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 39
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "def evaluate(individual):\n",
    "    # Do some hard computing on the individual\n",
    "    a = sum(individual)\n",
    "    b = len(individual)\n",
    "    return a, 1. / b"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 40
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "ind1.fitness.values = evaluate(ind1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 41
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n"
     ]
    }
   ],
   "source": [
    "print(ind1.fitness.valid)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 42
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(2.139772689693758, 0.2)\n"
     ]
    }
   ],
   "source": [
    "print(ind1.fitness)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Dealing with single objective fitness is not different, the evaluation function must return a tuple because single-objective is treated as a special case of multi-objective."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end",
     "slide_type": "subslide"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Mutation\n",
    "* The next kind of operator that we will present is the mutation operator. \n",
    "* There is a variety of mutation operators in the deap.tools module. \n",
    "* Each mutation has its own characteristics and may be applied to different type of individual. \n",
    "* Be careful to read the documentation of the selected operator in order to avoid undesirable behaviour.\n",
    "\n",
    "The general rule for mutation operators is that they only mutate, this means that an independent copy must be made prior to mutating the individual if the original individual has to be kept or is a reference to an other individual (see the selection operator)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "In order to apply a mutation (here a gaussian mutation) on the individual ind1, simply apply the desired function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43
    },
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "mutant = toolbox1.clone(ind1)\n",
    "ind2, = tools.mutGaussian(mutant, mu=0.0, sigma=0.2, indpb=0.2)\n",
    "del mutant.fitness.values"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43
    },
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "The fitness’ values are deleted because they not related to the individual anymore. As stated above, the mutation does mutate and only mutate an individual it is not responsible of invalidating the fitness nor anything else. The following shows that ind2 and mutant are in fact the same individual."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43
    },
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ind2 is mutant"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mutant is ind2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end",
     "slide_type": "subslide"
    },
    "slide_helper": "subslide_end",
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Crossover\n",
    "\n",
    "* There is a variety of crossover operators in the `deap.tools module`. \n",
    "* Each crossover has its own characteristics and may be applied to different type of individuals. \n",
    "* Be careful to read the documentation of the selected operator in order to avoid undesirable behaviour.\n",
    "\n",
    "The general rule for crossover operators is that they only mate individuals, this means that an independent copies must be made prior to mating the individuals if the original individuals have to be kept or is are references to other individuals (see the selection operator)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Lets apply a crossover operation to produce the two children that are cloned beforehand."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "child1, child2 = [toolbox1.clone(ind) for ind in (ind1, ind2)]\n",
    "tools.cxBlend(child1, child2, 0.5)\n",
    "del child1.fitness.values\n",
    "del child2.fitness.values"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Selection\n",
    "* Selection is made among a population by the selection operators that are available in the deap.operators module. \n",
    "* The selection operator usually takes as first argument an iterable container of individuals and the number of individuals to select. It returns a list containing the references to the selected individuals. \n",
    "\n",
    "The selection is made as follow."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "selected = tools.selBest([child1, child2], 2)\n",
    "child1 in selected"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end",
     "slide_type": "subslide"
    },
    "slide_helper": "subslide_end",
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Using the Toolbox\n",
    "* The toolbox is intended to contain all the evolutionary tools, from the object initializers to the evaluation operator. \n",
    "* It allows easy configuration of each algorithms. \n",
    "* The toolbox has basically two methods, `register()` and `unregister()`, that are used to add or remove tools from the toolbox.\n",
    "* The usual names for the evolutionary tools are mate(), mutate(), evaluate() and select(), however, any name can be registered as long as it is unique. Here is how they are registered in the toolbox."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end",
     "slide_type": "subslide"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "from deap import base\n",
    "from deap import tools\n",
    "\n",
    "toolbox1 = base.Toolbox()\n",
    "\n",
    "def evaluateInd(individual):\n",
    "    # Do some computation\n",
    "    return result,\n",
    "\n",
    "toolbox1.register(\"mate\", tools.cxTwoPoint)\n",
    "toolbox1.register(\"mutate\", tools.mutGaussian, mu=0, sigma=1, indpb=0.2)\n",
    "toolbox1.register(\"select\", tools.selTournament, tournsize=3)\n",
    "toolbox1.register(\"evaluate\", evaluateInd)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end",
     "slide_type": "subslide"
    },
    "slide_helper": "subslide_end",
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Tool Decoration\n",
    "* A powerful feature that helps to control very precise thing during an evolution without changing anything in the algorithm or operators. \n",
    "* A decorator is a wrapper that is called instead of a function.\n",
    "* It is asked to make some initialization and termination work before and after the actual function is called. \n",
    "\n",
    "For example, in the case of a constrained domain, one can apply a decorator to the mutation and crossover in order to keep any individual from being out-of-bound. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "The following defines a decorator that checks if any attribute in the list is out-of-bound and clips it if it is the case. \n",
    "* The decorator is defined using three functions in order to receive the min and max arguments. \n",
    "* Whenever the mutation or crossover is called, bounds will be check on the resulting individuals."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43
    },
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "def checkBounds(min, max):\n",
    "    def decorator(func):\n",
    "        def wrapper(*args, **kargs):\n",
    "            offspring = func(*args, **kargs)\n",
    "            for child in offspring:\n",
    "                for i in xrange(len(child)):\n",
    "                    if child[i] > max:\n",
    "                        child[i] = max\n",
    "                    elif child[i] < min:\n",
    "                        child[i] = min\n",
    "            return offspring\n",
    "        return wrapper\n",
    "    return decorator\n",
    "\n",
    "toolbox.register(\"mate_example\", tools.cxBlend, alpha=0.2)\n",
    "toolbox.register(\"mutate_example\", tools.mutGaussian, mu=0, sigma=2)\n",
    "\n",
    "MIN = 0; MAX = 10\n",
    "\n",
    "toolbox.decorate(\"mate_example\", checkBounds(MIN, MAX))\n",
    "toolbox.decorate(\"mutate_example\", checkBounds(MIN, MAX))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "This will work on crossover and mutation because both return a tuple of individuals. The mutation is often considered to return a single individual but again like for the evaluation, the single individual case is a special case of the multiple individual case."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end",
     "slide_type": "subslide"
    },
    "slide_helper": "subslide_end",
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Variations\n",
    "\n",
    "* Variations allows to build simple algorithms using predefined small building blocks. \n",
    "* In order to use a variation, the toolbox must be set to contain the required operators. \n",
    "\n",
    "> For example, in the lastly presented complete algorithm, the crossover and mutation are regrouped in the `varAnd()` function, this function requires the toolbox to contain the `mate()` and `mutate()` functions. The variations can be used to simplify the writing of an algorithm as follow.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end",
     "slide_type": "subslide"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "from deap import algorithms\n",
    "\n",
    "NGEN = 20 # number of generations\n",
    "CXPB = 0.6\n",
    "MUTPB = 0.05\n",
    "\n",
    "for g in range(NGEN):\n",
    "    # Select and clone the next generation individuals\n",
    "    offspring = map(toolbox.clone, toolbox.select(pop, len(pop)))\n",
    "\n",
    "    # Apply crossover and mutation on the offspring\n",
    "    offspring = algorithms.varAnd(offspring, toolbox, CXPB, MUTPB)\n",
    "\n",
    "    # Evaluate the individuals with an invalid fitness\n",
    "    invalid_ind = [ind for ind in offspring if not ind.fitness.valid]\n",
    "    fitnesses = toolbox.map(toolbox.evaluate, invalid_ind)\n",
    "    for ind, fit in zip(invalid_ind, fitnesses):\n",
    "        ind.fitness.values = fit\n",
    "\n",
    "    # The population is entirely replaced by the offspring\n",
    "    pop[:] = offspring"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Algorithms\n",
    "* There are several algorithms implemented in the algorithms module. \n",
    "* They are very simple and reflect the basic types of evolutionary algorithms present in the literature. \n",
    "* The algorithms use a Toolbox as defined in the last sections. \n",
    "* In order to setup a toolbox for an algorithm, you must register the desired operators under a specified names, refer to the documentation of the selected algorithm for more details. \n",
    "* Once the toolbox is ready, it is time to launch the algorithm."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43
    },
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "The *simple evolutionary algorithm* takes 5 arguments, a population, a toolbox, a probability of mating each individual at each generation (`cxpb`), a probability of mutating each individual at each generation (`mutpb`) and a number of generations to accomplish (`ngen`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "gen\tnevals\n",
      "0  \t0     \n",
      "1  \t176   \n",
      "2  \t171   \n",
      "3  \t177   \n",
      "4  \t188   \n",
      "5  \t197   \n",
      "6  \t170   \n",
      "7  \t175   \n",
      "8  \t178   \n",
      "9  \t178   \n",
      "10 \t190   \n",
      "11 \t183   \n",
      "12 \t169   \n",
      "13 \t189   \n",
      "14 \t187   \n",
      "15 \t161   \n",
      "16 \t175   \n",
      "17 \t155   \n",
      "18 \t179   \n",
      "19 \t171   \n",
      "20 \t182   \n",
      "21 \t187   \n",
      "22 \t175   \n",
      "23 \t170   \n",
      "24 \t207   \n",
      "25 \t173   \n",
      "26 \t176   \n",
      "27 \t196   \n",
      "28 \t216   \n",
      "29 \t167   \n",
      "30 \t173   \n",
      "31 \t182   \n",
      "32 \t167   \n",
      "33 \t188   \n",
      "34 \t179   \n",
      "35 \t203   \n",
      "36 \t162   \n",
      "37 \t174   \n",
      "38 \t191   \n",
      "39 \t179   \n",
      "40 \t183   \n",
      "41 \t190   \n",
      "42 \t187   \n",
      "43 \t204   \n",
      "44 \t193   \n",
      "45 \t177   \n",
      "46 \t191   \n",
      "47 \t170   \n",
      "48 \t161   \n",
      "49 \t158   \n",
      "50 \t194   \n"
     ]
    }
   ],
   "source": [
    "from deap import algorithms\n",
    "\n",
    "result = algorithms.eaSimple(pop, toolbox, cxpb=0.5, mutpb=0.2, ngen=50)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Computing Statistics\n",
    "Often, one wants to compile statistics on what is going on in the optimization. The Statistics are able to compile such data on arbitrary attributes of any designated object. To do that, one need to register the desired statistic functions inside the stats object using the exact same syntax as the toolbox."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43
    },
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "stats = tools.Statistics(key=lambda ind: ind.fitness.values)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43
    },
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "The statistics object is created using a key as first argument. This key must be supplied a function that will later be applied to the data on which the statistics are computed. The previous code sample uses the fitness.values attribute of each element."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end"
    },
    "slide_helper": "subslide_end",
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "import numpy\n",
    "stats.register(\"avg\", numpy.mean)\n",
    "stats.register(\"std\", numpy.std)\n",
    "stats.register(\"min\", numpy.min)\n",
    "stats.register(\"max\", numpy.max)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end",
     "slide_type": "subslide"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "* The statistical functions are now registered. \n",
    "* The register function expects an alias as first argument and a function operating on vectors as second argument. \n",
    "* Any subsequent argument is passed to the function when called. The creation of the statistics object is now complete."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Predefined Algorithms\n",
    "When using a predefined algorithm such as `eaSimple()`, `eaMuPlusLambda()`, `eaMuCommaLambda()`, or `eaGenerateUpdate()`, the statistics object previously created can be given as argument to the algorithm."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43
    },
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "gen\tnevals\tavg \tstd    \tmin\tmax\n",
      "0  \t0     \t98.8\t2.47521\t88 \t100\n"
     ]
    }
   ],
   "source": [
    "pop, logbook = algorithms.eaSimple(pop, toolbox, cxpb=0.5, mutpb=0.2, ngen=0, \n",
    "                                   stats=stats, verbose=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "* Statistics will automatically be computed on the population every generation. \n",
    "* The verbose argument prints the statistics on screen while the optimization takes place.\n",
    "* Once the algorithm returns, the final population and a Logbook are returned. \n",
    "* See the next section or the Logbook documentation for more information."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Writing Your Own Algorithm\n",
    "\n",
    "When writing your own algorithm, including statistics is very simple. One need only to compile the statistics on the desired object. \n",
    "\n",
    "For example, compiling the statistics on a given population is done by calling the compile() method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43
    },
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "record = stats.compile(pop)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43
    },
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "The argument to the compile function must be an iterable of elements on which the key will be called. Here, our population (`pop`) contains individuals.\n",
    "\n",
    "* The statistics object will call the key function on every individual to retrieve their `fitness.values` attribute. \n",
    "* The resulting array of values is finally given the each statistic function and the result is put into the record dictionary under the key associated with the function. \n",
    "* Printing the record reveals its nature.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'avg': 98.799999999999997, 'std': 2.4752104287649295, 'min': 88.0, 'max': 100.0}\n"
     ]
    }
   ],
   "source": [
    "print(record)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Logging Data\n",
    "Once the data is produced by the statistics, one can save it for further use in a Logbook. \n",
    "\n",
    "* The logbook is intended to be a chronological sequence of entries (as dictionaries). \n",
    "* It is directly compliant with the type of data returned by the statistics objects, but not limited to this data. \n",
    "* *In fact, anything can be incorporated in an entry of the logbook.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end"
    },
    "slide_helper": "subslide_end",
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "logbook = tools.Logbook()\n",
    "logbook.record(gen=0, evals=30, **record)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "The `record()` method takes a variable number of argument, each of which is a data to be recorded. In the last example, we saved the generation, the number of evaluations and everything contained in the record produced by a statistics object using the star magic. All record will be kept in the logbook until its destruction.\n",
    "\n",
    "After a number of records, one may want to retrieve the information contained in the logbook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end"
    },
    "slide_helper": "subslide_end",
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "gen, avg = logbook.select(\"gen\", \"avg\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end",
     "slide_type": "subslide"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "The `select()` method provides a way to retrieve all the information associated with a keyword in all records. This method takes a variable number of string arguments, which are the keywords used in the record or statistics object. Here, we retrieved the generation and the average fitness using a single call to select."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Printing to Screen\n",
    "* A logbook can be printed to screen or file. \n",
    "* Its `__str__()` method returns a header of each key inserted in the first record and the complete logbook for each of these keys. \n",
    "* The row are in chronological order of insertion while the columns are in an undefined order. \n",
    "* The easiest way to specify an order is to set the header attribute to a list of strings specifying the order of the columns."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43
    },
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "logbook.header = \"gen\", \"avg\", \"spam\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43
    },
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "The result is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "gen\tavg \tspam\n",
      "0  \t98.8\t    \n"
     ]
    }
   ],
   "source": [
    "print(logbook)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Plotting Features\n",
    "* One of the most common operation when an optimization is finished is to plot the data during the evolution. \n",
    "* The `Logbook` allows to do this very efficiently. \n",
    "* Using the select method, one can retrieve the desired data and plot it using matplotlib."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "pop = toolbox.population(n=300)\n",
    "pop, logbook = algorithms.eaSimple(pop, toolbox, cxpb=0.5, mutpb=0.2, ngen=50, \n",
    "                                   stats=stats, verbose=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43
    },
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "gen = logbook.select(\"gen\")\n",
    "fit_mins = logbook.select(\"min\")\n",
    "size_avgs = logbook.select(\"avg\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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\n4zPPSD/+8dbrH/2ousLFO+9UX7/1VnUCyu9+tzpEo9brr1fnh3jnHelLXzrY+x9hzAHRYT7993/v\nJR8k6cPRUZIPAAAAANAqtckHSfrmN6u9Hq5ebU88R0kF+/Lmm29W3nzzzXaHsaP0P7lSqUhbf/76\nr9sdErrUUf9ZQXfgOsRRwHWI/XrvvfeaV3zrW/W/5x3lP9/61qGci5WVlcqrr77qvZ6amqr09fVV\nyuWyV9bX11fp6+ur229jY6PS19dXWVtb847T19dXWVxcrFQqlUq5XK4MDQ1VpqamvH3m5+crfX19\nldnZ2cr58+crU1NTlZWVFa9uaGiosrGxUbete7zaYwwNDXnxuXHMz883fK77xbMT9/Nu/+N+1kql\nUllcXPQ+i6tcLjeUuWZnZyt9fX2VV199tTI6OlqZn5+vrKysVIaGhipDQ0P7jv3VV1+tfOMb3/Be\nX7161av/6KOPKt/+9rd3rPfbjj9fNXy5b3/pS5XKmTPVf7/zTvXn5LXXGre7eLFa9+GHh/v+RwQ9\nIDrIP/6jNPrLP/Nef/joF6WvfrWNEQEAAAAHl81mNT4+7r2Ox+OSqpNSutw5IWpXfCgUCgoEAt48\nCdPT0woGgxobG5NUncRxZGSk7ji9vb3esXO5nJLJpILBoCQpGAzq+vXrMk3Te0/DMHTjxo26ePP5\nvEZGRrzJIk3TlGmaWllZqdtuL/HsxjRNLSwsKJfLKZfLKZPJeLG5x9sPd/vNzU0tLy8rGo0qGAwq\nHA43zB2xl9jX19f1+OOPe68nJyc1MTHhvf7Zz362a/1D7ZlnpOefb17nzv2w29CKDz6o/t2B8z9I\nTELZUf526V39q8r/9F7/4umoHnvkkTZGBAAAgENz5YrU0yOtrx9o908++USS9Ijfvx8ODFRjfUCW\nZalYLCoSiXgNZHcJydnZWS8ZEY1Glc/ndePGDa9RvLi46CUmbNuWbdsql8sK1aw6UC6XZRiGHMeR\nYRjeezSb5LK2cW/btorFoiTp7t27dds5jqPNzc26su0rUew1nt0YhrHrJJRuMmW/iQj3nLrcz+2e\n973GPjAwoKWlJcViMcXjcQWDwbpYvvKVr+xa/1B7883my2t+8EF9+Zkz1YkmtyuVmq+O0SFIQHSQ\nR+7Vr+l74luvtCkSAAAAHLrPf1763vcOvPuv7t2TJD366KOHFZGvZmZmlEwmGxIC+Xxe09PTKhaL\n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\nAAAAAElFTkSuQmCC\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x10f5a4828>"
      ]
     },
     "metadata": {
      "image/png": {
       "height": 343,
       "width": 528
      }
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "fig, ax1 = plt.subplots()\n",
    "line1 = ax1.plot(gen, fit_mins, \"b-\", label=\"Minimum Fitness\")\n",
    "ax1.set_xlabel(\"Generation\")\n",
    "ax1.set_ylabel(\"Fitness\", color=\"b\")\n",
    "for tl in ax1.get_yticklabels():\n",
    "    tl.set_color(\"b\")\n",
    "\n",
    "ax2 = ax1.twinx()\n",
    "line2 = ax2.plot(gen, size_avgs, \"r-\", label=\"Average Fitness\")\n",
    "ax2.set_ylabel(\"Size\", color=\"r\")\n",
    "for tl in ax2.get_yticklabels():\n",
    "    tl.set_color(\"r\")\n",
    "\n",
    "lns = line1 + line2\n",
    "labs = [l.get_label() for l in lns]\n",
    "ax1.legend(lns, labs, loc=\"lower right\", frameon=True)\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Constraint Handling\n",
    "\n",
    "We have already seen some alternatives.\n",
    "\n",
    "* **Penality functions** are the most basic way of handling constrains for individuals that cannot be evaluated or are forbiden for problem specific reasons, when falling in a given region. \n",
    "* The penality function gives a fitness disavantage to theses individuals based on the amount of constraint violation in the solution."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "-"
    }
   },
   "source": [
    "<img src='http://deap.readthedocs.org/en/master/_images/constraints.png' width='92%'/>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_type": "subslide"
    },
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "In DEAP, a penality function can be added to any evaluation function using the DeltaPenality decorator provided in the tools module."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {
    "collapsed": false,
    "internals": {
     "frag_helper": "fragment_end",
     "frag_number": 43,
     "slide_helper": "subslide_end"
    },
    "slide_helper": "slide_end",
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "from math import sin\n",
    "from deap import base\n",
    "from deap import tools\n",
    "\n",
    "def evalFct(individual):\n",
    "    \"\"\"Evaluation function for the individual.\"\"\"\n",
    "    x = individual[0]\n",
    "    return (x - 5)**2 * sin(x) * (x/3),\n",
    "\n",
    "def feasible(individual):\n",
    "    \"\"\"Feasability function for the individual. Returns True if feasible False\n",
    "    otherwise.\"\"\"\n",
    "    if 3 < individual[0] < 5:\n",
    "        return True\n",
    "    return False\n",
    "\n",
    "def distance(individual):\n",
    "    \"\"\"A distance function to the feasability region.\"\"\"\n",
    "    return (individual[0] - 5.0)**2\n",
    "\n",
    "toolbox = base.Toolbox()\n",
    "toolbox.register(\"evaluate\", evalFct)\n",
    "toolbox.decorate(\"evaluate\", tools.DeltaPenality(feasible, 7.0, distance))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<hr/>\n",
    "<div class=\"container-fluid\">\n",
    "  <div class='well'>\n",
    "      <div class=\"row\">\n",
    "          <div class=\"col-md-3\" align='center'>\n",
    "              <img align='center'alt=\"Creative Commons License\" style=\"border-width:0\" src=\"https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png\"/>\n",
    "          </div>\n",
    "          <div class=\"col-md-9\">\n",
    "              This work is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](http://creativecommons.org/licenses/by-nc-sa/4.0/).\n",
    "          </div>\n",
    "      </div>\n",
    "  </div>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "application/json": {
       "Software versions": [
        {
         "module": "Python",
         "version": "3.6.0 64bit [GCC 4.2.1 Compatible Apple LLVM 6.0 (clang-600.0.57)]"
        },
        {
         "module": "IPython",
         "version": "5.2.2"
        },
        {
         "module": "OS",
         "version": "Darwin 16.4.0 x86_64 i386 64bit"
        },
        {
         "module": "scipy",
         "version": "0.18.1"
        },
        {
         "module": "numpy",
         "version": "1.11.3"
        },
        {
         "module": "matplotlib",
         "version": "2.0.0"
        },
        {
         "module": "seaborn",
         "version": "0.7.1"
        },
        {
         "module": "deap",
         "version": "1.1"
        }
       ]
      },
      "text/html": [
       "<table><tr><th>Software</th><th>Version</th></tr><tr><td>Python</td><td>3.6.0 64bit [GCC 4.2.1 Compatible Apple LLVM 6.0 (clang-600.0.57)]</td></tr><tr><td>IPython</td><td>5.2.2</td></tr><tr><td>OS</td><td>Darwin 16.4.0 x86_64 i386 64bit</td></tr><tr><td>scipy</td><td>0.18.1</td></tr><tr><td>numpy</td><td>1.11.3</td></tr><tr><td>matplotlib</td><td>2.0.0</td></tr><tr><td>seaborn</td><td>0.7.1</td></tr><tr><td>deap</td><td>1.1</td></tr><tr><td colspan='2'>Sat Mar 04 03:52:24 2017 BRT</td></tr></table>"
      ],
      "text/latex": [
       "\\begin{tabular}{|l|l|}\\hline\n",
       "{\\bf Software} & {\\bf Version} \\\\ \\hline\\hline\n",
       "Python & 3.6.0 64bit [GCC 4.2.1 Compatible Apple LLVM 6.0 (clang-600.0.57)] \\\\ \\hline\n",
       "IPython & 5.2.2 \\\\ \\hline\n",
       "OS & Darwin 16.4.0 x86\\_64 i386 64bit \\\\ \\hline\n",
       "scipy & 0.18.1 \\\\ \\hline\n",
       "numpy & 1.11.3 \\\\ \\hline\n",
       "matplotlib & 2.0.0 \\\\ \\hline\n",
       "seaborn & 0.7.1 \\\\ \\hline\n",
       "deap & 1.1 \\\\ \\hline\n",
       "\\hline \\multicolumn{2}{|l|}{Sat Mar 04 03:52:24 2017 BRT} \\\\ \\hline\n",
       "\\end{tabular}\n"
      ],
      "text/plain": [
       "Software versions\n",
       "Python 3.6.0 64bit [GCC 4.2.1 Compatible Apple LLVM 6.0 (clang-600.0.57)]\n",
       "IPython 5.2.2\n",
       "OS Darwin 16.4.0 x86_64 i386 64bit\n",
       "scipy 0.18.1\n",
       "numpy 1.11.3\n",
       "matplotlib 2.0.0\n",
       "seaborn 0.7.1\n",
       "deap 1.1\n",
       "Sat Mar 04 03:52:24 2017 BRT"
      ]
     },
     "execution_count": 45,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# To install run: pip install version_information\n",
    "%load_ext version_information\n",
    "%version_information scipy, numpy, matplotlib, seaborn, deap"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<link href=\"https://fonts.googleapis.com/css?family=Titillium+Web\" rel=\"stylesheet\">\n",
       "<link href='https://fonts.googleapis.com/css?family=Inconsolata:400,700' rel='stylesheet' type='text/css'/>\n",
       "<style>\n",
       ".text_cell_render h1 h2 h3 h4 h5 {\n",
       "font-style:regular;\n",
       "font-family: 'Titillium Web', sans-serif;\n",
       "display: block;\n",
       "}\n",
       "/*font-weight: 200;*/\n",
       "/*text-align: left;\n",
       "line-height: 100%;\n",
       "display: block;\n",
       "}*/\n",
       ".text_cell_render h1 {\n",
       "/*font-size: 24pt;*/\n",
       "font-weight: bold;\n",
       "margin-bottom: 0.1em;\n",
       "margin-top: 0.5em;\n",
       "color:#4a4a4a;\n",
       "}\n",
       "\n",
       ".reveal h1 {\n",
       "font-family: 'Titillium Web', sans-serif;\n",
       "/*font-size: 24pt;*/\n",
       "font-weight: bold;\n",
       "margin-bottom: 0.1em;\n",
       "margin-top: 0.5em;\n",
       "color:#4a4a4a;\n",
       "}\n",
       ".text_cell_render h2 {\n",
       "/*font-size: 21pt;*/\n",
       "margin-bottom: 0.1em;\n",
       "margin-top: 0.3em;\n",
       "color:#595959;\n",
       "}\n",
       ".text_cell_render h3 {\n",
       "/*font-size: 19pt;*/\n",
       "margin-bottom: 0.1em;\n",
       "margin-top: 0.3em;\n",
       "color:#595959;\n",
       "}\n",
       ".text_cell_render h4 {\n",
       "/*font-size: 17pt;*/\n",
       "margin-bottom: 0.1em;\n",
       "margin-top: 0.3em;\n",
       "color:#595959;\n",
       "}\n",
       ".text_cell_render h5 {\n",
       "/*font-size: 15pt;*/\n",
       "margin-bottom: 0.1em;\n",
       "margin-top: 0.3em;\n",
       "color:#595959;\n",
       "}\n",
       "div.text_cell_render{\n",
       "font-family: 'Titillium Web', sans-serif;\n",
       "line-height: 120%;\n",
       "font-size: 100%;\n",
       "font-weight: 400;\n",
       "text-align: justify;\n",
       "margin-left:0em;\n",
       "margin-right:0em;\n",
       "}\n",
       ".reveal div.text_cell_render{\n",
       "font-family: 'Titillium Web', sans-serif;\n",
       "line-height: 120%;\n",
       "font-size: 74%;\n",
       "font-weight: 400;\n",
       "text-align: justify;\n",
       "margin-left:0em;\n",
       "margin-right:0em;\n",
       "}\n",
       ".reveal h1 {\n",
       "font-family: 'Titillium Web', sans-serif;\n",
       "/*font-size: 90%; */\n",
       "/*font-size: 24pt;*/\n",
       "font-weight: bold;\n",
       "margin-bottom: 0.1em;\n",
       "margin-top: 0.5em;\n",
       "color:#4a4a4a;\n",
       "}\n",
       ".reveal h2 {\n",
       "font-family: 'Titillium Web', sans-serif;\n",
       "/*font-size: 24pt;*/\n",
       "font-weight: bold;\n",
       "margin-bottom: 0.1em;\n",
       "margin-top: 0.5em;\n",
       "color:#595959;\n",
       "}\n",
       ".reveal h3 {\n",
       "font-family: 'Titillium Web', sans-serif;\n",
       "/*font-size: 24pt;*/\n",
       "font-weight: bold;\n",
       "margin-bottom: 0.1em;\n",
       "margin-top: 0.5em;\n",
       "color:#595959;\n",
       "}\n",
       ".reveal h4 {\n",
       "font-family: 'Titillium Web', sans-serif;\n",
       "font-weight: bold;\n",
       "margin-bottom: 0.1em;\n",
       "margin-top: 0.5em;\n",
       "color:#595959;\n",
       "}\n",
       ".reveal code {\n",
       "font-family: 'Inconsolata', monospace;\n",
       "}\n",
       ".reveal pre {\n",
       "font-family: 'Inconsolata', monospace;\n",
       "}\n",
       "code {\n",
       "font-family: 'Inconsolata', monospace;\n",
       "}\n",
       "pre {\n",
       "font-family: 'Inconsolata', monospace;\n",
       "}\n",
       ".CodeMirror{\n",
       "font-family: \"Inconsolata\", monospace;\n",
       "}\n",
       "</style>\n",
       "<script>\n",
       "</script>\n"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "execution_count": 46,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# this code is here for cosmetic reasons\n",
    "from IPython.core.display import HTML\n",
    "from urllib.request import urlopen\n",
    "HTML(urlopen('https://raw.githubusercontent.com/lmarti/jupyter_custom/master/custom.include').read().decode('utf-8'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " "
   ]
  }
 ],
 "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.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}