Skip to content

Commit

Permalink
Remove symbolic link and fix examples documentation.
Browse files Browse the repository at this point in the history 
Each example documentation now includes a link to the googlecode
page. The link is automatically formatted with the proper branch
in the Sphinx config file using the extlink extension. This
allowed us to remove the symbolic link to the example folder in
the documentation folder.

--HG--
branch : dev
  • Loading branch information
@cmd-ntrf
cmd-ntrf authored and felix.antoine.fortin committed Nov 20, 2013
1 parent 1dd343c commit 4233354
Show file tree
Hide file tree
Showing 20 changed files with 100 additions and 96 deletions.
2 changes: 0 additions & 2 deletions doc/Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,6 @@ clean:
html:
PYTHONPATH=${PWD}/../ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
mkdir -p $(BUILDDIR)/html/examples/code
cp -R code/examples/* $(BUILDDIR)/html/examples/code
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

dirhtml:
Expand Down
2 changes: 1 addition & 1 deletion doc/api/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,4 @@ Description of the functions, classes and modules contained within DEAP.
tools
algo
gp
benchmarks
.. benchmarks
1 change: 0 additions & 1 deletion doc/code/examples
View file

This file was deleted.

10 changes: 9 additions & 1 deletion doc/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
'sphinx.ext.pngmath', 'sphinx.ext.intersphinx']
'sphinx.ext.pngmath', 'sphinx.ext.intersphinx', 'sphinx.ext.extlinks']

try:
import matplotlib
Expand Down Expand Up @@ -125,6 +125,14 @@
# Whether to show links to the files in HTML.
plot_html_show_formats = True

# -- Options for extlinks extension ----------------------------------------------

import subprocess
branch = subprocess.check_output(["hg", "branch"])[:-1]
extlinks = {'example': ('https://code.google.com/p/deap/source/browse/examples/%s.py?name='+branch,
'examples/')}


# -- Options for HTML output ---------------------------------------------------

# Add any paths that contain custom themes here, relative to this directory.
Expand Down
8 changes: 4 additions & 4 deletions doc/examples/bipop_cmaes.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ restarts, with different population sizes, of a standard CMA-ES.
As usual, the first thing to do is to create the types and as usual, we'll
need a minimizing fitness and an individual that is a :class:`list`.

.. literalinclude:: /code/examples/es/cma_bipop.py
.. literalinclude:: ../../examples/es/cma_bipop.py
:lines: 34-35

The main function includes the setting of some parameters, namely the number
Expand All @@ -24,19 +24,19 @@ because it will change with the restarts. Next are initialized the
:class:`~deap.tools.HallOfFame` and the list of :class:`~deap.tools.Statistics`
objects, one for each restart.

.. literalinclude:: /code/examples/es/cma_bipop.py
.. literalinclude:: ../../examples/es/cma_bipop.py
:lines: 37-45

Then the first loop controlling the restart is set up. It encapsulates the
generational loop with its many stop criteria. The content of this last loop
is simply the generate-update loop as presented in the
:func:`deap.algorithms.eaGenerateUpdate` function.

.. literalinclude:: /code/examples/es/cma_bipop.py
.. literalinclude:: ../../examples/es/cma_bipop.py
:lines: 54,92-104,108-121,145-184,187-189

Some variables have been omited for clarity, refer to the complete example for
more details [`source code <code/es/cmaes_bipop.py>`_].
more details :example:`es/cma_bipop`.

.. [Hansen2001] Hansen and Ostermeier, 2001. Completely Derandomized
Self-Adaptation in Evolution Strategies. *Evolutionary Computation*
Expand Down
4 changes: 2 additions & 2 deletions doc/examples/cmaes.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ As usual the first thing to do is to create the types and as usual we'll need
a minimizing fitness and an individual that is a :class:`list`. A toolbox is
then created with the desired evaluation function.

.. literalinclude:: /code/examples/es/cma_minfct.py
.. literalinclude:: ../../examples/es/cma_minfct.py
:lines: 28-32

Then, it does not get any harder. Once a :class:`~deap.cma.Strategy` is
Expand All @@ -24,7 +24,7 @@ uses in the :func:`~deap.algorithms.eaGenerateUpdate` algorithm. The
:class:`Individual` class. The random number generator from numpy is seeded
because the :mod:`~deap.cma` module draws all its number from it.

.. literalinclude:: /code/examples/es/cma_minfct.py
.. literalinclude:: ../../examples/es/cma_minfct.py
:lines: 34,36,37,41-50,52,54

.. [Hansen2001] Hansen and Ostermeier, 2001. Completely Derandomized
Expand Down
10 changes: 5 additions & 5 deletions doc/examples/cmaes_plotting.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,30 +26,30 @@ step size, the axis ratio and the major axis of the covariace matrix, the best
value so far, the best coordinates so far and the standard deviation of the
all coordinates at each generation.

.. literalinclude:: /code/examples/es/cma_plotting.py
.. literalinclude:: ../../examples/es/cma_plotting.py
:lines: 59-64

Once the objects are created, the evolution loop, based on a generational
stopping criterion, calls repeatedly the :meth:`generate`, :meth:`evaluate`
and :meth:`update` methods registered in the toolbox.

.. literalinclude:: /code/examples/es/cma_plotting.py
.. literalinclude:: ../../examples/es/cma_plotting.py
:lines: 66-75

Then, the previoulsy created objects start to play their role. The according
data is recorded in each object on each generation.

.. literalinclude:: /code/examples/es/cma_plotting.py
.. literalinclude:: ../../examples/es/cma_plotting.py
:lines: 80,81,88-93

Now that the data is recorded the only thing left to do is to plot it. We'll
use `matplotlib <http://matplotlib.org>`_ to generate the graphics from the
recorded data.

.. literalinclude:: /code/examples/es/cma_plotting.py
.. literalinclude:: ../../examples/es/cma_plotting.py
:lines: 95-124

Which gives the following result.

.. plot:: code/examples/es/cma_plotting.py
.. plot:: ../examples/es/cma_plotting.py
:width: 67%
16 changes: 8 additions & 8 deletions doc/examples/coev_coop.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,15 +20,15 @@ population.
The first step is to create a bunch of species that will evolve in our
population.

.. literalinclude:: /code/examples/coev/coop_evol.py
.. literalinclude:: ../../examples/coev/coop_evol.py
:lines: 70

Cooperative coevolution works by sending the best individual of each species
(called representative) to help in the evaluation of the individuals of the
other species. Since the individuals are not yet evaluated we select randomly
the individuals that will be in the set of representatives.

.. literalinclude:: /code/examples/coev/coop_evol.py
.. literalinclude:: ../../examples/coev/coop_evol.py
:lines: 75

The evaluation function takes a list of individuals to be evaluated including
Expand All @@ -42,7 +42,7 @@ usual, something like this ::

The evolution can now begin.

.. literalinclude:: /code/examples/coev/coop_evol.py
.. literalinclude:: ../../examples/coev/coop_evol.py
:lines: 83-95,101-103,111

The last lines evolve each species once before sharing their representatives.
Expand All @@ -56,11 +56,11 @@ to add a species and remove useless species on stagnation. These steps are not
covered in this example but are present in the complete source code of
the coevolution examples.

- `Coevolution Base <code/coev/coop_base.py>`_
- `Coevolution Niching <code/coev/coop_niche.py>`_
- `Coevolution Generalization <code/coev/coop_gen.py>`_
- `Coevolution Adaptation <code/coev/coop_adapt.py>`_
- `Coevolution Final <code/coev/coop_evol.py>`_
- :example:`Coevolution Base <coev/coop_base>`
- :example:`Coevolution Niching <coev/coop_niche>`
- :example:`Coevolution Generalization <coev/coop_gen>`
- :example:`Coevolution Adaptation <coev/coop_adapt>`
- :example:`Coevolution Final <coev/coop_evol>`

.. [Potter2001] Potter, M. and De Jong, K., 2001, Cooperative
Coevolution: An Architecture for Evolving Co-adapted Subcomponents.
8 changes: 4 additions & 4 deletions doc/examples/eda.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ with a certain distribution and estimate the problem distribution from the
generate-update logic. The strategy contains a random number generator which
is adapted from the population. The following :class:`EDA` class do just that.

.. literalinclude:: /code/examples/eda/fctmin.py
.. literalinclude:: ../../examples/eda/fctmin.py
:pyobject: EDA

A normal random number generator is initialized with a certain mean
Expand All @@ -37,7 +37,7 @@ Two classes are needed, a minimization fitness and a individual that will
combine the fitness and the real values. Moreover, we will use
:class:`numpy.ndarray` as base class for our individuals.

.. literalinclude:: /code/examples/eda/fctmin.py
.. literalinclude:: ../../examples/eda/fctmin.py
:lines: 28-29

Operators
Expand All @@ -49,7 +49,7 @@ We will use the method of an initialized :class:`EDA`. For the generate
method, we set the class that the individuals are transferred in to our
:class:`Individual` class containing a fitness.

.. literalinclude:: /code/examples/eda/fctmin.py
.. literalinclude:: ../../examples/eda/fctmin.py
:pyobject: main

The complete example : [`source code <code/eda/fctmin.py>`_].
The complete :example:`eda/fctmin`.
14 changes: 7 additions & 7 deletions doc/examples/es_fctmin.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ In order to have this kind of evolution we'll need a type of individual that
contains a :attr:`strategy` attribute. We'll also minimize the objective
function, which gives the following classes creation.

.. literalinclude:: /code/examples/es/fctmin.py
.. literalinclude:: ../../examples/es/fctmin.py
:lines: 33-35

The initialization function for an evolution strategy is not defined by DEAP.
Expand All @@ -24,37 +24,37 @@ strategy, *scls*. The next arguments are the minimum and maximum values for
the individual and strategy attributes. The strategy is added in the
:attr:`strategy` member of the returned individual.

.. literalinclude:: /code/examples/es/fctmin.py
.. literalinclude:: ../../examples/es/fctmin.py
:pyobject: generateES

This generation function is registered in the toolbox like any other
initializer.

.. literalinclude:: /code/examples/es/fctmin.py
.. literalinclude:: ../../examples/es/fctmin.py
:lines: 56-57

The strategy controls the standard deviation of the mutation. It is common to
have a lower bound on the values so that the algorithm don't fall in
exploitation only. This lower bound is added to the variation operator by
the following decorator.

.. literalinclude:: /code/examples/es/fctmin.py
.. literalinclude:: ../../examples/es/fctmin.py
:pyobject: checkStrategy

The variation operators are decorated via the
:meth:`~deap.base.Toolbox.decorate` method of the toolbox and the evaluation
function is taken from the :mod:`~deap.benchmarks` module.

.. literalinclude:: /code/examples/es/fctmin.py
.. literalinclude:: ../../examples/es/fctmin.py
:lines: 59,60,63-65

From here, everything left to do is either write the algorithm or use one
provided in :mod:`~deap.algorithms`. Here we will use the
:func:`~deap.algorithms.eaMuCommaLambda` algorithm.

.. literalinclude:: /code/examples/es/fctmin.py
.. literalinclude:: ../../examples/es/fctmin.py
:lines: 67,69-81

The complete [`source code <code/es/fctmin.py>`_].
The complete :example:`es/fctmin`.

.. [Beyer2002] Beyer and Schwefel, 2002, Evolution strategies - A Comprehensive Introduction
18 changes: 9 additions & 9 deletions doc/examples/ga_knapsack.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ efficient algorithm to have a representation close the problem. Here, what can
be closer to a bag than a set? Lets make our individuals inherit from the
:class:`set` class.

.. literalinclude:: /code/examples/ga/knapsack.py
.. literalinclude:: ../../examples/ga/knapsack.py
:lines: 41-42

That's it. You now have individuals that are in fact sets, they have the usual
Expand All @@ -20,19 +20,19 @@ minimization of the first objective (the weight of the bag) and a maximization
of the second objective (the value of the bag). We will now create a
dictionary of 100 random items to map the values and weights.

.. literalinclude:: /code/examples/ga/knapsack.py
.. literalinclude:: ../../examples/ga/knapsack.py
:lines: 34-39

We now need to initialize a population and the individuals therein. For this
we will need a :class:`~deap.base.Toolbox` to register our generators since
sets can also be created with an input iterable.

.. literalinclude:: /code/examples/ga/knapsack.py
.. literalinclude:: ../../examples/ga/knapsack.py
:lines: 44,47,50-53

Voilà! The *last* thing to do is to define our evaluation function.

.. literalinclude:: /code/examples/ga/knapsack.py
.. literalinclude:: ../../examples/ga/knapsack.py
:pyobject: evalKnapsack

Everything is ready for evolution. Ho no wait, since DEAP's developers are
Expand All @@ -41,28 +41,28 @@ directly on sets. Lets define some. For example, a crossover, producing two
children from two parents, could be that the first child is the
intersection of the two sets and the second child their absolute difference.

.. literalinclude:: /code/examples/ga/knapsack.py
.. literalinclude:: ../../examples/ga/knapsack.py
:pyobject: cxSet

A mutation operator could randomly add or remove an element from the set
input individual.

.. literalinclude:: /code/examples/ga/knapsack.py
.. literalinclude:: ../../examples/ga/knapsack.py
:pyobject: mutSet


We then register these operators in the toolbox. Since it is a multi-objective
problem, we have selected the SPEA-II selection scheme :
:func:`~deap.tools.selSPEA2`

.. literalinclude:: /code/examples/ga/knapsack.py
.. literalinclude:: ../../examples/ga/knapsack.py
:lines: 83-86

From here, everything left to do is either write the algorithm or use
provided in :mod:`~deap.algorithms`. Here we will use the
:func:`~deap.algorithms.eaMuPlusLambda` algorithm.

.. literalinclude:: /code/examples/ga/knapsack.py
.. literalinclude:: ../../examples/ga/knapsack.py
:lines: 88,90-107

Finally, a :class:`~deap.tools.ParetoFront` may be used to retrieve the best
Expand All @@ -73,4 +73,4 @@ in the statistics object with the ``axis=0`` argument to compute the
statistics on each objective independently. Otherwise, Numpy would compute
a single mean for both objectives.

The complete example : [`source code <code/ga/knapsack.py>`_].
The complete :example:`ga/knapsack`.
Loading

0 comments on commit 4233354

Please sign in to comment.