From 423335478664421c231c64db73ba5cbc12612a9f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A9lix-Antoine=20Fortin?= Date: Tue, 19 Nov 2013 23:44:29 -0500 Subject: [PATCH] Remove symbolic link and fix examples documentation. 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 --- doc/Makefile | 2 -- doc/api/index.rst | 2 +- doc/code/examples | 1 - doc/conf.py | 10 ++++++++- doc/examples/bipop_cmaes.rst | 8 +++---- doc/examples/cmaes.rst | 4 ++-- doc/examples/cmaes_plotting.rst | 10 ++++----- doc/examples/coev_coop.rst | 16 +++++++------- doc/examples/eda.rst | 8 +++---- doc/examples/es_fctmin.rst | 14 ++++++------- doc/examples/ga_knapsack.rst | 18 ++++++++-------- doc/examples/ga_onemax.rst | 28 ++++++++++++------------- doc/examples/ga_onemax_short.rst | 6 +++--- doc/examples/gp_ant.rst | 8 +++---- doc/examples/gp_multiplexer.rst | 8 +++---- doc/examples/gp_parity.rst | 6 +++--- doc/examples/gp_spambase.rst | 8 +++---- doc/examples/gp_symbreg.rst | 16 +++++++------- doc/examples/pso_basic.rst | 15 +++++++------ doc/tutorials/advanced/benchmarking.rst | 8 +++---- 20 files changed, 100 insertions(+), 96 deletions(-) delete mode 120000 doc/code/examples diff --git a/doc/Makefile b/doc/Makefile index 965ea1edf..98589296f 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -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: diff --git a/doc/api/index.rst b/doc/api/index.rst index e44e0aad9..bcfe05e08 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -12,4 +12,4 @@ Description of the functions, classes and modules contained within DEAP. tools algo gp - benchmarks + .. benchmarks diff --git a/doc/code/examples b/doc/code/examples deleted file mode 120000 index da7b19653..000000000 --- a/doc/code/examples +++ /dev/null @@ -1 +0,0 @@ -../../examples/ \ No newline at end of file diff --git a/doc/conf.py b/doc/conf.py index 2fbb58307..f0c084592 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -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 @@ -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. diff --git a/doc/examples/bipop_cmaes.rst b/doc/examples/bipop_cmaes.rst index cd2e636b1..9ef3ffb79 100644 --- a/doc/examples/bipop_cmaes.rst +++ b/doc/examples/bipop_cmaes.rst @@ -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 @@ -24,7 +24,7 @@ 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 @@ -32,11 +32,11 @@ 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 `_]. +more details :example:`es/cma_bipop`. .. [Hansen2001] Hansen and Ostermeier, 2001. Completely Derandomized Self-Adaptation in Evolution Strategies. *Evolutionary Computation* diff --git a/doc/examples/cmaes.rst b/doc/examples/cmaes.rst index e69428b8a..1cbaf801d 100644 --- a/doc/examples/cmaes.rst +++ b/doc/examples/cmaes.rst @@ -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 @@ -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 diff --git a/doc/examples/cmaes_plotting.rst b/doc/examples/cmaes_plotting.rst index c37532d9f..1834b0004 100644 --- a/doc/examples/cmaes_plotting.rst +++ b/doc/examples/cmaes_plotting.rst @@ -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 `_ 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% \ No newline at end of file diff --git a/doc/examples/coev_coop.rst b/doc/examples/coev_coop.rst index 9d1e283df..ab2b9d4e8 100644 --- a/doc/examples/coev_coop.rst +++ b/doc/examples/coev_coop.rst @@ -20,7 +20,7 @@ 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 @@ -28,7 +28,7 @@ Cooperative coevolution works by sending the best individual of each species 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 @@ -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. @@ -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 `_ -- `Coevolution Niching `_ -- `Coevolution Generalization `_ -- `Coevolution Adaptation `_ -- `Coevolution Final `_ +- :example:`Coevolution Base ` +- :example:`Coevolution Niching ` +- :example:`Coevolution Generalization ` +- :example:`Coevolution Adaptation ` +- :example:`Coevolution Final ` .. [Potter2001] Potter, M. and De Jong, K., 2001, Cooperative Coevolution: An Architecture for Evolving Co-adapted Subcomponents. diff --git a/doc/examples/eda.rst b/doc/examples/eda.rst index 4da278f1c..8c6ef31be 100644 --- a/doc/examples/eda.rst +++ b/doc/examples/eda.rst @@ -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 @@ -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 @@ -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 `_]. +The complete :example:`eda/fctmin`. diff --git a/doc/examples/es_fctmin.rst b/doc/examples/es_fctmin.rst index 395a7a773..39f97477e 100644 --- a/doc/examples/es_fctmin.rst +++ b/doc/examples/es_fctmin.rst @@ -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. @@ -24,13 +24,13 @@ 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 @@ -38,23 +38,23 @@ 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 `_]. +The complete :example:`es/fctmin`. .. [Beyer2002] Beyer and Schwefel, 2002, Evolution strategies - A Comprehensive Introduction diff --git a/doc/examples/ga_knapsack.rst b/doc/examples/ga_knapsack.rst index e58d15af3..bb96ecdd6 100644 --- a/doc/examples/ga_knapsack.rst +++ b/doc/examples/ga_knapsack.rst @@ -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 @@ -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 @@ -41,13 +41,13 @@ 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 @@ -55,14 +55,14 @@ 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 @@ -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 `_]. +The complete :example:`ga/knapsack`. diff --git a/doc/examples/ga_onemax.rst b/doc/examples/ga_onemax.rst index 686576f33..fafab772c 100644 --- a/doc/examples/ga_onemax.rst +++ b/doc/examples/ga_onemax.rst @@ -23,7 +23,7 @@ provides a convenient method for creating types called the creator. First of all, we need to import some modules. -.. literalinclude:: /code/examples/ga/onemax.py +.. literalinclude:: ../../examples/ga/onemax.py :lines: 16-20 ------- @@ -47,7 +47,7 @@ argument *base* is the base classe that the new type created should inherit from. Finally the optional arguments are members to add to the new type, for example a :attr:`fitness` for an individual or :attr:`speed` for a particle. -.. literalinclude:: /code/examples/ga/onemax.py +.. literalinclude:: ../../examples/ga/onemax.py :lines: 22-23 The first line creates a maximizing fitness by replacing, in the base type @@ -74,7 +74,7 @@ to store functions with their arguments. The toolbox contains two methods, :meth:`~deap.base.Toolbox.register` and :meth:`~deap.base.Toolbox.unregister` that are used to do the tricks. -.. literalinclude:: /code/examples/ga/onemax.py +.. literalinclude:: ../../examples/ga/onemax.py :lines: 25-31 In this code block we registered a generation function and two initialization @@ -107,7 +107,7 @@ The Evaluation Function The evaluation function is pretty simple in this case, we need to count the number of ones in the individual. This is done by the following lines of code. -.. literalinclude:: /code/examples/ga/onemax.py +.. literalinclude:: ../../examples/ga/onemax.py :lines: 33-34 The returned value must be an iterable of length equal to the number of @@ -126,7 +126,7 @@ the algorithms, see the :ref:`short-ga-onemax` for an example. Registering the operators and their default arguments in the toolbox is done as follow. -.. literalinclude:: /code/examples/ga/onemax.py +.. literalinclude:: ../../examples/ga/onemax.py :lines: 37-40 The evaluation is given the alias evaluate. Having a single argument being the @@ -154,7 +154,7 @@ Creating the Population Before evolving it, we need to instantiate a population. This step is done effortless using the method we registered in the toolbox. -.. literalinclude:: /code/examples/ga/onemax.py +.. literalinclude:: ../../examples/ga/onemax.py :lines: 42, 45 @@ -162,7 +162,7 @@ effortless using the method we registered in the toolbox. parameter left open earlier in the toolbox. The next thing to do is to evaluate this brand new population. -.. literalinclude:: /code/examples/ga/onemax.py +.. literalinclude:: ../../examples/ga/onemax.py :lines: 50-53 We first :func:`map` the evaluation function to every individual, then assign @@ -177,7 +177,7 @@ The evolution of the population is the last thing to accomplish. Let say that we want to evolve for a fixed number of generation :data:`NGEN`, the evolution will then begin with a simple for statement. -.. literalinclude:: /code/examples/ga/onemax.py +.. literalinclude:: ../../examples/ga/onemax.py :lines: 57-59 Is that simple enough? Lets continue with more complicated things, selecting, @@ -188,7 +188,7 @@ individuals. In a simple GA, the first step is to select the next generation. -.. literalinclude:: /code/examples/ga/onemax.py +.. literalinclude:: ../../examples/ga/onemax.py :lines: 61-64 This step creates an offspring list that is an exact copy of the selected @@ -201,19 +201,19 @@ of code, where a crossover is applied with probability :data:`CXPB` and a mutation with probability :data:`MUTPB`. The ``del`` statement simply invalidate the fitness of the modified individuals. -.. literalinclude:: /code/examples/ga/onemax.py +.. literalinclude:: ../../examples/ga/onemax.py :lines: 66-76 The population now needs to be re-evaluated, we then apply the evaluation as seen earlier, but this time only on the individuals with an invalid fitness. -.. literalinclude:: /code/examples/ga/onemax.py +.. literalinclude:: ../../examples/ga/onemax.py :lines: 78-82 And finally, last but not least, we replace the old population by the offspring. -.. literalinclude:: /code/examples/ga/onemax.py +.. literalinclude:: ../../examples/ga/onemax.py :lines: 87 This is the end of the evolution part, it will continue until the predefined @@ -222,11 +222,11 @@ number of generation are accomplished. Although, some statistics may be gathered on the population, the following lines print the min, max, mean and standard deviation of the population. -.. literalinclude:: /code/examples/ga/onemax.py +.. literalinclude:: ../../examples/ga/onemax.py :lines: 89-100 A :class:`~deap.tools.Statistics` object has been defined to facilitate how statistics are gathered. It is not presented here so that we can focus on the core and not the gravitating helper objects of DEAP. -The complete example : [`source code `_]. +The complete :example:`ga/onemax`. diff --git a/doc/examples/ga_onemax_short.rst b/doc/examples/ga_onemax_short.rst index 5ffbd5c9b..f94912b2b 100644 --- a/doc/examples/ga_onemax_short.rst +++ b/doc/examples/ga_onemax_short.rst @@ -12,13 +12,13 @@ algorithms impemented use specific functions from the toolbox, in this case :func:`evaluate`, :func:`mate`, :func:`mutate` and :func:`~deap.Toolbox.select` must be registered. -.. literalinclude:: /code/examples/ga/onemax_short.py +.. literalinclude:: ../../examples/ga/onemax_short.py :lines: 41-44 The toolbox is then passed to the algorithm and the algorithm uses the registered function. -.. literalinclude:: /code/examples/ga/onemax_short.py +.. literalinclude:: ../../examples/ga/onemax_short.py :lines: 46, 49-58 The short GA One max example makes use of a @@ -32,4 +32,4 @@ these objects. Finally, the *verbose* keyword indicate wheter we want the algorithm to output the results after each generation or not. -The complete example : [`source code `_] +The complete :example:`ga/onemax_short` diff --git a/doc/examples/gp_ant.rst b/doc/examples/gp_ant.rst index e56d64ff1..596ed60d2 100644 --- a/doc/examples/gp_ant.rst +++ b/doc/examples/gp_ant.rst @@ -17,7 +17,7 @@ Primitives set used We use the standard primitives set for the Artificial Ant problem : -.. literalinclude:: /code/examples/gp/ant.py +.. literalinclude:: ../../examples/gp/ant.py :lines: 150-156 - ``if_food_ahead`` is a primitive which executes its first argument if there @@ -38,7 +38,7 @@ We use the standard primitives set for the Artificial Ant problem : Although those functions are obviously not already built-in in Python, it is very easy to define them : -.. literalinclude:: /code/examples/gp/ant.py +.. literalinclude:: ../../examples/gp/ant.py :lines: 62-75, 122-123 Partial functions are a powerful feature of Python which allow to create @@ -56,7 +56,7 @@ number of pieces of food picked up. In this example, we are using a classical trail, the *Santa Fe trail*, in which there is 89 pieces of food. Therefore, a perfect individual would achieve a fitness of 89. -.. literalinclude:: /code/examples/gp/ant.py +.. literalinclude:: ../../examples/gp/ant.py :pyobject: evalArtificialAnt Where `ant` is the instance of the simulator used. The @@ -73,7 +73,7 @@ Note that as the problem is harder, improving the selection pressure by increasing the size of the tournament to 7 allows to achieve better performance. -The complete [`source code `_] +The complete :example:`gp/ant` .. _refPapersAnt: diff --git a/doc/examples/gp_multiplexer.rst b/doc/examples/gp_multiplexer.rst index 0eac4c289..636319be7 100644 --- a/doc/examples/gp_multiplexer.rst +++ b/doc/examples/gp_multiplexer.rst @@ -20,7 +20,7 @@ The primitive set is almost the same as the set used in :ref:`Parity :mod:`operator`, and a specific if-then-else primitive, which return either its second or third argument depending on the value of the first one. -.. literalinclude:: /code/examples/gp/multiplexer.py +.. literalinclude:: ../../examples/gp/multiplexer.py :lines: 56-62 As usual, we also add two terminals, a Boolean true and a Boolean false. @@ -33,7 +33,7 @@ at start up, instead of at each evaluation call. This pre-computation also allows to easily tune the multiplexer size, by changing the value of *MUX_SELECT_LINES*. -.. literalinclude:: /code/examples/gp/multiplexer.py +.. literalinclude:: ../../examples/gp/multiplexer.py :lines: 32-54 @@ -41,10 +41,10 @@ After that, the evaluation function is trivial, as we have both inputs and output values. The fitness is then the number of well predicted outputs over the 2048 cases (for a 3-8 multiplexer). -.. literalinclude:: /code/examples/gp/multiplexer.py +.. literalinclude:: ../../examples/gp/multiplexer.py :pyobject: evalMultiplexer -The complete example: [`source code `_] +The complete :example:`gp/multiplexer`. .. _refPapersMux: diff --git a/doc/examples/gp_parity.rst b/doc/examples/gp_parity.rst index b84aceb0a..de0d5b9c0 100644 --- a/doc/examples/gp_parity.rst +++ b/doc/examples/gp_parity.rst @@ -20,7 +20,7 @@ Primitives set used Parity uses standard Boolean operators as primitives, available in the Python operator module : -.. literalinclude:: /code/examples/gp/parity.py +.. literalinclude:: ../../examples/gp/parity.py :lines: 49-55 In addition to the *n* inputs, we add two constant terminals, one at 0, one @@ -38,7 +38,7 @@ In this implementation, the fitness of a Parity individual is simply the number of successful cases. Thus, the fitness is maximized, and the maximum value is 64 in the case of a 6 inputs problems. -.. literalinclude:: /code/examples/gp/parity.py +.. literalinclude:: ../../examples/gp/parity.py :pyobject: evalParity `inputs` and `outputs` are two pre-generated lists, to speedup the @@ -53,7 +53,7 @@ Conclusion The other parts of the program are mostly the same as the :ref:`Symbolic Regression algorithm `. -The complete example: [`source code `_] +The complete :example:`gp/parity`. .. _refPapersParity: diff --git a/doc/examples/gp_spambase.rst b/doc/examples/gp_spambase.rst index 0dd15e24d..ccbf67c88 100644 --- a/doc/examples/gp_spambase.rst +++ b/doc/examples/gp_spambase.rst @@ -29,7 +29,7 @@ type, and where the return value type is specified before run time. We define a typed primitive set almost the same way than a normal one, but we have to specify the types used. -.. literalinclude:: /code/examples/gp/spambase.py +.. literalinclude:: ../../examples/gp/spambase.py :lines: 37-68 On the first line, we see the declaration of a typed primitive set with @@ -55,7 +55,7 @@ spam database, and then checks if the prediction made by the individual matches the expected Boolean output. The count of well predicted emails is returned as the fitness of the individual (which is so, at most, 400). -.. literalinclude:: /code/examples/gp/spambase.py +.. literalinclude:: ../../examples/gp/spambase.py :pyobject: evalSpambase @@ -66,7 +66,7 @@ The toolbox used is very similar to the one presented in the symbolic regression example, but notice that we now use specific STGP operators for crossovers and mutations : -.. literalinclude:: /code/examples/gp/spambase.py +.. literalinclude:: ../../examples/gp/spambase.py :lines: 88-92 @@ -80,7 +80,7 @@ read it, or use a non-standard library, but with Python, you can use the built-in module :mod:`csv` and, within 2 lines, it is done! The data is now in the matrix *spam* and can easily be used through all the program : -The complete [`source code `_] +The complete :example:`gp/spambase` .. _refPapersSpam: diff --git a/doc/examples/gp_symbreg.rst b/doc/examples/gp_symbreg.rst index a71364d6a..ff11dd2cc 100644 --- a/doc/examples/gp_symbreg.rst +++ b/doc/examples/gp_symbreg.rst @@ -29,7 +29,7 @@ primitives set. They should make good building blocks for the individuals so the evolution can succeed. In this problem, we use a classical set of primitives, which are basic arithmetic functions : -.. literalinclude:: /code/examples/gp/symbreg.py +.. literalinclude:: ../../examples/gp/symbreg.py :lines: 29-43 The redefinition of the division is made to protect it against a zero @@ -50,7 +50,7 @@ only one input, but it could have as many as you want. By default, those inputs are named "ARGx", where "x" is a number, but you can easily rename them : -.. literalinclude:: /code/examples/gp/symbreg.py +.. literalinclude:: ../../examples/gp/symbreg.py :lines: 44 Creator @@ -60,7 +60,7 @@ As any evolutionary program, symbolic regression needs (at least) two object types : an individual containing the genotype and a fitness. We can easily create them with the creator : -.. literalinclude:: /code/examples/gp/symbreg.py +.. literalinclude:: ../../examples/gp/symbreg.py :lines: 46-47 The first line creates the fitness object (this is a minimization problem, so @@ -80,7 +80,7 @@ Toolbox Now, we want to register some parameters specific to the evolution process. In DEAP, this is done through the toolbox : -.. literalinclude:: /code/examples/gp/symbreg.py +.. literalinclude:: ../../examples/gp/symbreg.py :lines: 49-69 First, a toolbox instance is created (in some problem types like coevolution, @@ -102,7 +102,7 @@ the RMSE, which is returned as the fitness of the individual. stores it as an iterable. Knowing that, you can understand why the evaluation function must return a tuple value (even if it is a 1-tuple) : - .. literalinclude:: /code/examples/gp/symbreg.py + .. literalinclude:: ../../examples/gp/symbreg.py :pyobject: evalSymbReg :emphasize-lines: 9 @@ -129,7 +129,7 @@ this case, we want to compute the mean, standard deviation, minimum, and maximum of both the individuals fitness and size. For that we'll use a :class:`~deap.tools.MultiStatistics` object. - .. literalinclude:: /code/examples/gp/symbreg.py + .. literalinclude:: ../../examples/gp/symbreg.py :lines: 77-86 Note that a simple :class:`~deap.tools.Statistics` object can be used, as in @@ -143,14 +143,14 @@ process, but nothing has been initialized. We can start the evolution by creating the population and then calling a complete algorithm. In this case, we'll use :func:`~deap.algorithms.eaSimple`. -.. literalinclude:: /code/examples/gp/symbreg.py +.. literalinclude:: ../../examples/gp/symbreg.py :lines: 71,74,75,88-91 The hall of fame is a specific structure which contains the *n* best individuals (here, the best one only). -The complete [`source code `_]. +The complete :example:`gp/symbreg`. .. _refPapersSymbreg: diff --git a/doc/examples/pso_basic.rst b/doc/examples/pso_basic.rst index 0797aaf95..a47cd050f 100644 --- a/doc/examples/pso_basic.rst +++ b/doc/examples/pso_basic.rst @@ -17,7 +17,7 @@ Modules Before writing functions and algorithms, we need to import some module from the standard library and from DEAP. -.. literalinclude:: /code/examples/pso/basic.py +.. literalinclude:: ../../examples/pso/basic.py :lines: 16-24 Representation @@ -33,7 +33,7 @@ best state in which it has been so far. This translates in DEAP by the following two lines of code : -.. literalinclude:: /code/examples/pso/basic.py +.. literalinclude:: ../../examples/pso/basic.py :lines: 26-28 Here we create two new objects in the :mod:`~deap.creator` space. First, we @@ -59,14 +59,14 @@ random speed for a particle. The next function create a particle and initialize its attributes, except for the attribute :attr:`best`, which will be set only after evaluation : -.. literalinclude:: /code/examples/pso/basic.py +.. literalinclude:: ../../examples/pso/basic.py :pyobject: generate The function :func:`updateParticle` first computes the speed, then limits the speed values between ``smin`` and ``smax``, and finally computes the new particle position. -.. literalinclude:: /code/examples/pso/basic.py +.. literalinclude:: ../../examples/pso/basic.py :pyobject: updateParticle The operators are registered in the toolbox with their parameters. The @@ -78,7 +78,7 @@ The evaluation function :func:`~deap.benchmarks.h1` is from [Knoek2003]_. The function is already defined in the benchmarks module, so we can register it directly. -.. literalinclude:: /code/examples/pso/basic.py +.. literalinclude:: ../../examples/pso/basic.py :lines: 50-54 Algorithm @@ -89,14 +89,13 @@ algorithm by firstly creating a new population, and then apply the original PSO algorithm. The variable `best` contains the best particle ever found (it known as gbest in the original algorithm). -.. literalinclude:: /code/examples/pso/basic.py +.. literalinclude:: ../../examples/pso/basic.py :pyobject: main Conclusion ========== -The full PSO basic example can be found here : [`source code -`_]. +The full PSO basic example can be found here : :example:`pso/basic`. This is a video of the algorithm in action, plotted with matplotlib_. The red dot represents the best solution found so far. diff --git a/doc/tutorials/advanced/benchmarking.rst b/doc/tutorials/advanced/benchmarking.rst index 6b3a8e948..16757ae2a 100644 --- a/doc/tutorials/advanced/benchmarking.rst +++ b/doc/tutorials/advanced/benchmarking.rst @@ -22,7 +22,7 @@ is then to transform them in a single element tuple as required by DEAP philosophy on single objective optimization. We will use a decorator for this. -.. literalinclude:: /code/examples/bbob.py +.. literalinclude:: ../../../examples/bbob.py :pyobject: tupleize The algorithm is encapsulated in a main function that receives four @@ -36,7 +36,7 @@ Then, the target fitness value is encapsulated in a :class:`FitnessMin` object so that we can easily compare the individuals with it. Following is simply the algorithm, which is explained in the :ref:`one-fifth` example. -.. literalinclude:: /code/examples/bbob.py +.. literalinclude:: ../../../examples/bbob.py :pyobject: main Running the Benchmark @@ -54,11 +54,11 @@ there is even no need to save the best individual found by our algorithm (call to the :func:`main` function). The single line that is related to the provided algorithm in the call to the :func:`main` function. -.. literalinclude:: /code/examples/bbob.py +.. literalinclude:: ../../../examples/bbob.py :lines: 26,27,28,90-137 Once these experiments are done, the data contained in the :file:`ouput` directory can be used to build the results document. See the `BBOB `_ web site on how to build the document. -The complete example : [`source code `_]. \ No newline at end of file +The complete :example:`bbob`. \ No newline at end of file