Merge github.com:DEAP/deap into mo-cma-es

Conflicts:
	examples/ga/nsga2.py

.travis.yml

@@ -1,14 +1,17 @@
 language: python
-python:
-  - "2.6"
-  - "2.7"
-  - "3.2"
-  - "3.3"
-  - "3.4"
-  - "pypy"
+matrix:
+  include:
+    - python: "2.7"
+      env: NUMPY=numpy
+    - python: "3.4"
+      env: NUMPY=numpy
+    - python: "pypy"
+      env: NUMPY="git+https://bitbucket.org/pypy/numpy.git"
 # command to install dependencies
 install:
-  - pip install .
-  - pip install numpy
+  - python setup.py install
+  - pip install $NUMPY
 # command to run tests
-script: nosetests 
+script:
+  # run python3 tests from build/lib because the 2to3 from setup.py does not modify files in-place
+  - if [[ ${TRAVIS_PYTHON_VERSION%%.*} == '3' ]]; then nosetests -v --where=build/lib; else nosetests -v; fi

README.md

@@ -26,12 +26,12 @@ Following acceptation of [PEP 438](http://www.python.org/dev/peps/pep-0438/) by
 You can find the most recent releases at: https://pypi.python.org/pypi/deap/.
 
 ## Documentation
-See the [DEAP User's Guide](http://deap.gel.ulaval.ca/doc/default/index.html) for DEAP documentation.
+See the [DEAP User's Guide](http://deap.readthedocs.org/) for DEAP documentation.
 
 In order to get the tip documentation, change directory to the `doc` subfolder and type in `make html`, the documentation will be under `_build/html`. You will need [Sphinx](http://sphinx.pocoo.org) to build the documentation.
 
 ### Notebooks
-Also checkout our new [notebook examples](https://github.com/DEAP/notebook). Using [IPython's](http://ipython.org/) notebook feature you'll be able to navigate and execute each block of code individually and fell what every line is doing. Either, look at the notebooks online using the notebook viewer links at the botom of the page or download the notebooks, navigate to the you download directory and run
+Also checkout our new [notebook examples](https://github.com/DEAP/notebooks). Using [IPython's](http://ipython.org/) notebook feature you'll be able to navigate and execute each block of code individually and fell what every line is doing. Either, look at the notebooks online using the notebook viewer links at the botom of the page or download the notebooks, navigate to the you download directory and run
 
 ```bash
 ipython notebook --pylab inline
@@ -50,6 +50,9 @@ If you wish to build from sources, download or clone the repository and type
 python setup.py install
 ```
 
+## Build Status
+DEAP build status is available on Travis-CI https://travis-ci.org/DEAP/deap.
+
 ## Requirements
 The most basic features of DEAP requires Python2.6. In order to combine the toolbox and the multiprocessing module Python2.7 is needed for its support to pickle partial functions. CMA-ES requires Numpy, and we recommend matplotlib for visualization of results as it is fully compatible with DEAP's API.
 
@@ -113,6 +116,7 @@ Authors of scientific papers including results generated using DEAP are encourag
   * François-Michel De Rainville, Félix-Antoine Fortin, Marc-André Gardner, Marc Parizeau and Christian Gagné, "DEAP: A Python Framework for Evolutionary Algorithms", in !EvoSoft Workshop, Companion proc. of the Genetic and Evolutionary Computation Conference (GECCO 2012), July 07-11 2012. [Paper](http://goo.gl/pXXug)
 
 ## Projects using DEAP
+  * Lara-Cabrera, R., Cotta, C. and Fernández-Leiva, A.J. (2014). Geometrical vs topological measures for the evolution of aesthetic maps in a rts game, Entertainment Computing,
   * Macret, M. and Pasquier, P. (2013). Automatic Tuning of the OP-1 Synthesizer Using a Multi-objective Genetic Algorithm. In Proceedings of the 10th Sound and Music Computing Conference (SMC). (pp 614-621).
   * Fortin, F. A., Grenier, S., & Parizeau, M. (2013, July). Generalizing the improved run-time complexity algorithm for non-dominated sorting. In Proceeding of the fifteenth annual conference on Genetic and evolutionary computation conference (pp. 615-622). ACM.
   * Fortin, F. A., & Parizeau, M. (2013, July). Revisiting the NSGA-II crowding-distance computation. In Proceeding of the fifteenth annual conference on Genetic and evolutionary computation conference (pp. 623-630). ACM.

deap/algorithms.py

@@ -46,7 +46,7 @@ def varAnd(population, toolbox, cxpb, mutpb):
     The variation goes as follow. First, the parental population
     :math:`P_\mathrm{p}` is duplicated using the :meth:`toolbox.clone` method
     and the result is put into the offspring population :math:`P_\mathrm{o}`.
-    A first loop over :math:`P_\mathrm{o}` is executed to mate consecutive
+    A first loop over :math:`P_\mathrm{o}` is executed to mate pairs of consecutive
     individuals. According to the crossover probability *cxpb*, the
     individuals :math:`\mathbf{x}_i` and :math:`\mathbf{x}_{i+1}` are mated
     using the :meth:`toolbox.mate` method. The resulting children
@@ -95,30 +95,44 @@ def eaSimple(population, toolbox, cxpb, mutpb, ngen, stats=None,
     :param halloffame: A :class:`~deap.tools.HallOfFame` object that will
                        contain the best individuals, optional.
     :param verbose: Whether or not to log the statistics.
-    :returns: The final population.
-    
-    It uses :math:`\lambda = \kappa = \mu` and goes as follow.
-    It first initializes the population (:math:`P(0)`) by evaluating
-    every individual presenting an invalid fitness. Then, it enters the
-    evolution loop that begins by the selection of the :math:`P(g+1)`
-    population. Then the crossover operator is applied on a proportion of
-    :math:`P(g+1)` according to the *cxpb* probability, the resulting and the
-    untouched individuals are placed in :math:`P'(g+1)`. Thereafter, a
-    proportion of :math:`P'(g+1)`, determined by *mutpb*, is 
-    mutated and placed in :math:`P''(g+1)`, the untouched individuals are
-    transferred :math:`P''(g+1)`. Finally, those new individuals are evaluated
-    and the evolution loop continues until *ngen* generations are completed.
-    Briefly, the operators are applied in the following order ::
+    :returns: The final population
+    :returns: A class:`~deap.tools.Logbook` with the statistics of the
+              evolution
     
+    The algorithm takes in a population and evolves it in place using the
+    :meth:`varAnd` method. It returns the optimized population and a
+    :class:`~deap.tools.Logbook` with the statistics of the evolution. The
+    logbook will contain the generation number, the number of evalutions for
+    each generation and the statistics if a :class:`~deap.tools.Statistics` is
+    given as argument. The *cxpb* and *mutpb* arguments are passed to the
+    :func:`varAnd` function. The pseudocode goes as follow ::
+
         evaluate(population)
-        for i in range(ngen):
-            offspring = select(population)
-            offspring = mate(offspring)
-            offspring = mutate(offspring)
+        for g in range(ngen):
+            population = select(population, len(population))
+            offspring = varAnd(population, toolbox, cxpb, mutpb)
             evaluate(offspring)
             population = offspring
+
+    As stated in the pseudocode above, the algorithm goes as follow. First, it
+    evaluates the individuals with an invalid fitness. Second, it enters the
+    generational loop where the selection procedure is applied to entirely
+    replace the parental population. The 1:1 replacement ratio of this
+    algorithm **requires** the selection procedure to be stochastic and to
+    select multiple times the same individual, for example,
+    :func:`~deap.tools.selTournament` and :func:`~deap.tools.selRoulette`.
+    Third, it applies the :func:`varAnd` function to produce the next
+    generation population. Fourth, it evaluates the new individuals and
+    compute the statistics on this population. Finally, when *ngen*
+    generations are done, the algorithm returns a tuple with the final
+    population and a :class:`~deap.tools.Logbook` of the evolution.
+
+    .. note::
+
+        Using a non-stochastic selection method will result in no selection as
+        the operator selects *n* individuals from a pool of *n*.
     
-    This function expects :meth:`toolbox.mate`, :meth:`toolbox.mutate`,
+    This function expects the :meth:`toolbox.mate`, :meth:`toolbox.mutate`,
     :meth:`toolbox.select` and :meth:`toolbox.evaluate` aliases to be
     registered in the toolbox.
     
@@ -183,8 +197,9 @@ def varOr(population, toolbox, lambda_, cxpb, mutpb):
     :param lambda\_: The number of children to produce
     :param cxpb: The probability of mating two individuals.
     :param mutpb: The probability of mutating an individual.
-    :returns: A list of varied individuals that are independent of their
-              parents.
+    :returns: The final population
+    :returns: A class:`~deap.tools.Logbook` with the statistics of the
+              evolution
     
     The variation goes as follow. On each of the *lambda_* iteration, it
     selects one of the three operations; crossover, mutation or reproduction.
@@ -243,22 +258,32 @@ def eaMuPlusLambda(population, toolbox, mu, lambda_, cxpb, mutpb, ngen,
     :param halloffame: A :class:`~deap.tools.HallOfFame` object that will
                        contain the best individuals, optional.
     :param verbose: Whether or not to log the statistics.
-    :returns: The final population.
-    
-    First, the individuals having an invalid fitness are evaluated. Then, the
-    evolutionary loop begins by producing *lambda_* offspring from the
-    population, the offspring are generated by a crossover, a mutation or a
-    reproduction proportionally to the probabilities *cxpb*, *mutpb* and 1 -
-    (cxpb + mutpb). The offspring are then evaluated and the next generation
-    population is selected from both the offspring **and** the population.
-    Briefly, the operators are applied as following ::
+    :returns: The final population
+    :returns: A class:`~deap.tools.Logbook` with the statistics of the
+              evolution.
     
+    The algorithm takes in a population and evolves it in place using the
+    :func:`varOr` function. It returns the optimized population and a
+    :class:`~deap.tools.Logbook` with the statistics of the evolution. The
+    logbook will contain the generation number, the number of evalutions for
+    each generation and the statistics if a :class:`~deap.tools.Statistics` is
+    given as argument. The *cxpb* and *mutpb* arguments are passed to the
+    :func:`varOr` function. The pseudocode goes as follow ::
+
         evaluate(population)
-        for i in range(ngen):
+        for g in range(ngen):
             offspring = varOr(population, toolbox, lambda_, cxpb, mutpb)
             evaluate(offspring)
             population = select(population + offspring, mu)
-    
+
+    First, the individuals having an invalid fitness are evaluated. Second,
+    the evolutionary loop begins by producing *lambda_* offspring from the
+    population, the offspring are generated by the :func:`varOr` function. The
+    offspring are then evaluated and the next generation population is
+    selected from both the offspring **and** the population. Finally, when
+    *ngen* generations are done, the algorithm returns a tuple with the final
+    population and a :class:`~deap.tools.Logbook` of the evolution.
+
     This function expects :meth:`toolbox.mate`, :meth:`toolbox.mutate`,
     :meth:`toolbox.select` and :meth:`toolbox.evaluate` aliases to be
     registered in the toolbox. This algorithm uses the :func:`varOr`
@@ -324,21 +349,38 @@ def eaMuCommaLambda(population, toolbox, mu, lambda_, cxpb, mutpb, ngen,
     :param halloffame: A :class:`~deap.tools.HallOfFame` object that will
                        contain the best individuals, optional.
     :param verbose: Whether or not to log the statistics.
-    :returns: The final population.
-    
-    First, the individuals having an invalid fitness are evaluated. Then, the
-    evolutionary loop begins by producing *lambda_* offspring from the
-    population, the offspring are generated by a crossover, a mutation or a
-    reproduction proportionally to the probabilities *cxpb*, *mutpb* and 1 -
-    (cxpb + mutpb). The offspring are then evaluated and the next generation
-    population is selected **only** from the offspring. Briefly, the operators
-    are applied as following ::
+    :returns: The final population
+    :returns: A class:`~deap.tools.Logbook` with the statistics of the
+              evolution
     
+    The algorithm takes in a population and evolves it in place using the
+    :func:`varOr` function. It returns the optimized population and a
+    :class:`~deap.tools.Logbook` with the statistics of the evolution. The
+    logbook will contain the generation number, the number of evalutions for
+    each generation and the statistics if a :class:`~deap.tools.Statistics` is
+    given as argument. The *cxpb* and *mutpb* arguments are passed to the
+    :func:`varOr` function. The pseudocode goes as follow ::
+
         evaluate(population)
-        for i in range(ngen):
+        for g in range(ngen):
             offspring = varOr(population, toolbox, lambda_, cxpb, mutpb)
             evaluate(offspring)
             population = select(offspring, mu)
+
+    First, the individuals having an invalid fitness are evaluated. Second,
+    the evolutionary loop begins by producing *lambda_* offspring from the
+    population, the offspring are generated by the :func:`varOr` function. The
+    offspring are then evaluated and the next generation population is
+    selected from both the offspring **and** the population. Finally, when
+    *ngen* generations are done, the algorithm returns a tuple with the final
+    population and a :class:`~deap.tools.Logbook` of the evolution.
+
+    .. note::
+
+        Care must be taken when the lambda:mu ratio is 1 to 1 as a non-stochastic
+        selection will result in no selection at all as
+        the operator selects *lambda* individuals from a pool of *mu*.
+
     
     This function expects :meth:`toolbox.mate`, :meth:`toolbox.mutate`,
     :meth:`toolbox.select` and :meth:`toolbox.evaluate` aliases to be
@@ -404,11 +446,22 @@ def eaGenerateUpdate(toolbox, ngen, halloffame=None, stats=None,
     :param halloffame: A :class:`~deap.tools.HallOfFame` object that will
                        contain the best individuals, optional.
     :param verbose: Whether or not to log the statistics.
-
-    :returns: The final population.
-    
-    The toolbox should contain a reference to the generate and the update method 
-    of the chosen strategy.
+    :returns: The final population
+    :returns: A class:`~deap.tools.Logbook` with the statistics of the
+              evolution
+
+    The algorithm generates the individuals using the :func:`toolbox.generate`
+    function and updates the generation method with the :func:`toolbox.update`
+    function. It returns the optimized population and a
+    :class:`~deap.tools.Logbook` with the statistics of the evolution. The
+    logbook will contain the generation number, the number of evalutions for
+    each generation and the statistics if a :class:`~deap.tools.Statistics` is
+    given as argument. The pseudocode goes as follow ::
+
+        for g in range(ngen):
+            population = toolbox.generate()
+            evaluate(population)
+            toolbox.update(population)
 
     .. [Colette2010] Collette, Y., N. Hansen, G. Pujol, D. Salazar Aponte and
        R. Le Riche (2010). On Object-Oriented Programming of Optimizers -

deap/benchmarks/__init__.py

@@ -231,7 +231,7 @@ def rastrigin(individual):
        * - Global optima
          - :math:`x_i = 0, \\forall i \in \\lbrace 1 \\ldots N\\rbrace`, :math:`f(\mathbf{x}) = 0`
        * - Function
-         - :math:`f(\\mathbf{x}) = 10N \sum_{i=1}^N x_i^2 - 10 \\cos(2\\pi x_i)`
+         - :math:`f(\\mathbf{x}) = 10N + \sum_{i=1}^N x_i^2 - 10 \\cos(2\\pi x_i)`
 
     .. plot:: code/benchmarks/rastrigin.py
        :width: 67 %
@@ -343,8 +343,6 @@ def shekel(individual, a, c):
     of maxima is given by the length of any of the arguments *a* or *c*, *a*
     is a matrix of size :math:`M\\times N`, where *M* is the number of maxima
     and *N* the number of dimensions and *c* is a :math:`M\\times 1` vector.
-    The matrix :math:`\\mathcal{A}` can be seen as the position of the maxima
-    and the vector :math:`\\mathbf{c}`, the width of the maxima.
     
     :math:`f_\\text{Shekel}(\mathbf{x}) = \\sum_{i = 1}^{M} \\frac{1}{c_{i} + 
     \\sum_{j = 1}^{N} (x_{j} - a_{ij})^2 }`
@@ -360,7 +358,7 @@ def shekel(individual, a, c):
     .. plot:: code/benchmarks/shekel.py
         :width: 67 %
     """
-    return sum((1. / (c[i] + sum((x - a[i][j])**2 for j, x in enumerate(individual)))) for i in range(len(c))),
+    return sum((1. / (c[i] + sum((individual[j] - aij)**2 for j, aij in enumerate(a[i])))) for i in range(len(c))),
 
 # Multiobjectives
 def kursawe(individual):