[wiki.beagle] push by cgagne@gmail.com - Completed migration from User Manual to User Guide. on 2012-08-01 11:25 GMT

[bea...@googlecode.com]

Revision: 8aa7d8ba1b2d
Author: Christian Gagne <christi...@gel.ulaval.ca>
Date: Wed Aug 1 04:25:18 2012
Log: Completed migration from User Manual to User Guide.
http://code.google.com/p/beagle/source/detail?r=8aa7d8ba1b2d&repo=wiki

Modified:
/Architecture.wiki
/GPTutorial.wiki
/UserGuide.wiki

=======================================
--- /Architecture.wiki Wed Aug 1 04:13:32 2012
+++ /Architecture.wiki Wed Aug 1 04:25:18 2012
@@ -313,7 +313,7 @@

During the evolutionary processes, a context gives the current state of
the evolution. A basic, general context is implemented in class `Context`.
It provides some essential contextual informations such as the current
deme, individual, genotype and generation. For a specific EC algorithm, a
specific context could be used. For example, a GP specific context is
defined, `GP::Context`, which contains the call stack with some other GP
specific informations. An Open BEAGLE context is similar to the execution
context of a computer that contains the different registers, counters and
pointers to the actual state of the machine.

-Given that the parameters of Open BEAGLE are distributed in the
appropriate objects, an agent is implemented to take into account these
parameter: the register. All the variables that are considered as
parameters should be registered by giving the reference (object handle) of
the parameter with the associated namespace and tag. The class `Register`
can be seen as a centralized database from which any entity could
dynamically add, delete, access or modify parameters. The register is also
responsible of interpreting the parameters part of the configuration file
(see Section [UserManual#Using_the_Register Using the Register] of the User
Manual for further details).
+Given that the parameters of Open BEAGLE are distributed in the
appropriate objects, an agent is implemented to take into account these
parameter: the register. All the variables that are considered as
parameters should be registered by giving the reference (object handle) of
the parameter with the associated namespace and tag. The class `Register`
can be seen as a centralized database from which any entity could
dynamically add, delete, access or modify parameters. The register is also
responsible of interpreting the parameters part of the configuration file
(see Section [UserGuide#Using_the_Register Using the Register] of the User
Guide for further details).

All the output messages given to the user pass by the logger. It consists
of an interface with the user, that receives all messages, associated with
a type, a class name, and an output level, and output them in a given
device if the used log level allow it. This is very interesting if a user
want, for example, to use Open BEAGLE into a broader system using a
graphical user interface. In such case, the user only need to define his
own specialized logger that will intercept the messages and log them into
the desired device, for example a specific graphical windows. There is
actually one specialized logger, `LoggerXML`, that log messages to a file
and/or the console (the STDOUT device) in a XML format. The other very
interesting aspect of the logger is the possibility to choose the log level
desired. The messages outputted are classified into eight categories, as
depicted in the following.

@@ -470,7 +470,7 @@

*NOTE: This subsection on co-evolution is far to short. It should be
rewritten with more explanations and use examples. Maybe a complete section
in next chapter would be necessary.*

-Co-evolution framework is based on multi-threading programming, where each
thread is associated to a population. The execution sequence of each thread
is the same than what usually done in the main function of standard
evolutions, as described in section
[UserManual#Building_a_System_for_an_Evolution Building a System for an
Evolution] of the User Manual (i.e. build system, evaluation operator,
vivarium, evolver, initialize evolver, and start evolution). The population
in each thread evolves independently, with inter-thread synchronization
only in co-evolutionary fitness evaluation operator. This operator behaves
quite differently than usual mono-population evaluation operator. The
co-evolution evaluation procedure starts by calling
`Coev::EvaluationOp::makeSets`, which makes evaluation sets of the evolving
population and add them into shared storage structure, using method
`Coev::EvaluationOp::addSet`. When the desired number of evaluation sets is
added (the trigger value) the co-evolutionary fitness evaluation method
defined in `Coev::EvaluationOp::evaluateSets` is called. Pure virtual
methods `Coev::EvaluationOp::makeSets` and
`Coev::EvaluationOp::evaluateSets` are problem-specific and must be defined
by the user in its co-evolutionary fitness evaluation operators.
+Co-evolution framework is based on multi-threading programming, where each
thread is associated to a population. The execution sequence of each thread
is the same than what usually done in the main function of standard
evolutions, as described in section
[UserGuide#Building_a_System_for_an_Evolution Building a System for an
Evolution] of the User Guide (i.e. build system, evaluation operator,
vivarium, evolver, initialize evolver, and start evolution). The population
in each thread evolves independently, with inter-thread synchronization
only in co-evolutionary fitness evaluation operator. This operator behaves
quite differently than usual mono-population evaluation operator. The
co-evolution evaluation procedure starts by calling
`Coev::EvaluationOp::makeSets`, which makes evaluation sets of the evolving
population and add them into shared storage structure, using method
`Coev::EvaluationOp::addSet`. When the desired number of evaluation sets is
added (the trigger value) the co-evolutionary fitness evaluation method
defined in `Coev::EvaluationOp::evaluateSets` is called. Pure virtual
methods `Coev::EvaluationOp::makeSets` and
`Coev::EvaluationOp::evaluateSets` are problem-specific and must be defined
by the user in its co-evolutionary fitness evaluation operators.

A trigger value is used to specify the number of evaluation sets needed to
start a co-evolutionary evaluation. This value is usually equal to the
number of threads/populations used, as usually each thread/population add
one evaluation set before doing the co-evolutionary evaluation operation.
But different trigger value can be used depending on the context.

@@ -514,7 +514,7 @@

Open BEAGLE uses a real OO approach to implement the primitives that
compose GP genotypes. The genotypes are composed of nodes that have one
attribute, that is a smart pointer to an abstract primitive. Using this
abstract interface, it is easy to implement primitives that have specific
behavior without loosing any generality.

-To make a concrete primitive that is usable to compose GP trees, the user
needs to declare a concrete class derived from the abstract superclass
`GP::Primitive`. Given that, existing primitives can be reused or
specialized. These are some fundamental principles of OO programming. These
also give us powerful mechanisms to defined atypical primitives without
tweaking the internal structure. Section
[UserManual#Getting_the_Most_of_the_Primitives Getting the Most of the
Primitives] of the User Manual is a detailled discussion on how to define
GP primitives.
+To make a concrete primitive that is usable to compose GP trees, the user
needs to declare a concrete class derived from the abstract superclass
`GP::Primitive`. Given that, existing primitives can be reused or
specialized. These are some fundamental principles of OO programming. These
also give us powerful mechanisms to defined atypical primitives without
tweaking the internal structure. Section
[UserGuide#Getting_the_Most_of_the_Primitives Getting the Most of the
Primitives] of the User Guide is a detailled discussion on how to define GP
primitives.

*NOTE: The following explanations on association between the number of
primitive sets in the super set and the number of trees in the GP
individuals is no more true. This implicit link is broken and it is now
possible to have GP individuals with several trees while having one
primitive set. An index to the associated primitive set has been added to
the GP trees. The following paragraph should be rewritten.*

=======================================
--- /GPTutorial.wiki Wed Aug 1 04:13:11 2012
+++ /GPTutorial.wiki Wed Aug 1 04:25:18 2012
@@ -98,7 +98,7 @@

Step 5 (line 20) builds the vivarium that contains the population. A
vivarium is composed of a set of demes, which are composed of individuals
that are themselves composed of genotypes. A deme, Open BEAGLE class
`Deme`, is simply a set of individuals that evolve together in a closed
circuit. An individual is composed by one or some genotypes and a fitness
value. It can in fact contain more than one genotype. For instance,
Automatically Defined Functions (ADF) (Koza, 1994) are coded using a set of
genotypes (i.e. forest of trees). The genotype is the basic data structure
used for coding individuals. For GP, this data structure is a rooted tree,
defined by class `GP::Tree`. Using the `GP::Vivarium`, the vivarium is
initialized using the default allocators of demes/individuals/genotypes for
GP. However it is possible for the user to override the default setting of
the vivarium and used allocators to desired population elements. More
details about allocators can be found in Section [Architecture#Allocators
Allocators] of the Architecture page.

-At line 22, the evolver is initialized using both command-line arguments
and the Open BEAGLE system. Through the command-line, it is possible to
change the value any of the evolution parameters (how to do this is
explained in Section [GPTutorial#Experimenting_with_the_Example
Experimenting with the Example]). A XML configuration file is also parsed
by the initialize method (see Section [UserManual#Using_the_Register Using
the Register] of the User Manual for more details). Line 23 then makes the
vivarium evolving until the stopping criterion is reached.
+At line 22, the evolver is initialized using both command-line arguments
and the Open BEAGLE system. Through the command-line, it is possible to
change the value any of the evolution parameters (how to do this is
explained in Section [GPTutorial#Experimenting_with_the_Example
Experimenting with the Example]). A XML configuration file is also parsed
by the initialize method (see Section [UserGuide#Using_the_Register Using
the Register] of the User Guide for more details). Line 23 then makes the
vivarium evolving until the stopping criterion is reached.

Notice the fact that all instructions in function `main` are within a
try-catch block. Open BEAGLE defines many standard exceptions for dealing
with abnormal situations. See Section [Architecture#Exceptions Exceptions]
of the Architecture page for more details. The users are encouraged to
proceed this way. Note also that every Open BEAGLE object is dynamically
allocated (by a call to the C++ `new` operator) and its pointer is wrapped
using a `Handle` object. The `Handle` type is a smart pointer that manages
objects allocated on the heap. The use of smart pointers prevents some
common memory leaks and facilitate the work of Open BEAGLE users. These
handlers are fully described in Section [GPTutorial#Fitness_Evaluation
Fitness Evaluation].

@@ -270,7 +270,7 @@
{{{
./symbreg -OBec.conf.file=mysymbreg.conf
}}}
-The configuration file can also describe the form of the evolutionary
algorithm used. For some examples distributed with the Open BEAGLE, there
is two configuration files containing pre-configured evolvers:
_name_`-generational.conf`, and _name_`-steadystate.conf`, where _name_ is
the name of the example. You can change the evolver structure in the
configuration file, which mean changing the operation used in the
evolutionary algorithm. This is explained later in the document, at Section
[UserManual#Building_a_Custom_Evolver Building a Custom Evolver] of the
User Manual.
+The configuration file can also describe the form of the evolutionary
algorithm used. For some examples distributed with the Open BEAGLE, there
is two configuration files containing pre-configured evolvers:
_name_`-generational.conf`, and _name_`-steadystate.conf`, where _name_ is
the name of the example. You can change the evolver structure in the
configuration file, which mean changing the operation used in the
evolutionary algorithm. This is explained later in the document, at Section
[UserGuide#Building_a_Custom_Evolver Building a Custom Evolver] of the User
Guide.

= References =

=======================================
--- /UserGuide.wiki Wed Aug 1 04:12:35 2012
+++ /UserGuide.wiki Wed Aug 1 04:25:18 2012
@@ -1,4 +1,4 @@
-#summary User Manual on Open BEAGLE
+#summary User Guide on Open BEAGLE
#labels RequireUpdate

This page is a extensive presentation of what an application programmer,
which is called the user from now, needs to know to develop EC process with
Open BEAGLE. Some important aspects of C++ programming using Open BEAGLE
are presented here. The discussion starts with what the user should and
should not do (the guidelines). Following this is presented a simple
pattern of what is needed to build a system for an evolution. Thereafter
the different ways to modify the parameters of the system are exposed.
Finally is presented the different approaches to customize the evolutionary
process and a specific manual for the different standard EC algorithms
implemented in Open BEAGLE.
@@ -88,9 +88,9 @@

== The operators and the evolver ==

-As explained in Section [Architecture#Operators_and_Evolver Operators and
Evolver] of the Architecture page, the evolver applies iteratively, at each
generation, the operators on each deme. The operators are packed in the
evolver into the bootstrap and the main-loop sets. For usual application,
the user can instantiate the default evolvers. If the user want to
customize the evolutionary algorithm, he can build his exotic evolver,
using the configuration file. This is the topic of Section
[UserManual#Customizing_the_Evolutionary_Algorithm Customizing the
Evolutionary Algorithm]. In all case, once the operator sets is built, the
whole EC system is initialized with a call to the evolver `initialize`
method. The method takes as arguments an handle to the system and the
command-line arguments. Once the EC system initialized, the evolution can
then be launch with a call to the method `evolve` of the evolver, taking
the vivarium to evolve as argument.
-
-All the EC applications are built following the previously presented
scheme. To get more details on how to develop an application for a specific
EC flavor, take a look in the [GPTutoral GP Tutorial] and
[UserManual#GP_User_Manual GP User Manual] section for GP and Section
[UserManual#GA_User_Manual GA User Manual] for GA. Section
[UserManual#Customizing_the_Evolutionary_Algorithm Customizing the
Evolutionary Algorithm] gives also good insight on configuring a custom
evolution.
+As explained in Section [Architecture#Operators_and_Evolver Operators and
Evolver] of the Architecture page, the evolver applies iteratively, at each
generation, the operators on each deme. The operators are packed in the
evolver into the bootstrap and the main-loop sets. For usual application,
the user can instantiate the default evolvers. If the user want to
customize the evolutionary algorithm, he can build his exotic evolver,
using the configuration file. This is the topic of Section
[UserGuide#Customizing_the_Evolutionary_Algorithm Customizing the
Evolutionary Algorithm]. In all case, once the operator sets is built, the
whole EC system is initialized with a call to the evolver `initialize`
method. The method takes as arguments an handle to the system and the
command-line arguments. Once the EC system initialized, the evolution can
then be launch with a call to the method `evolve` of the evolver, taking
the vivarium to evolve as argument.
+
+All the EC applications are built following the previously presented
scheme. To get more details on how to develop an application for a specific
EC flavor, take a look in the [GPTutoral GP Tutorial] and
[UserGuide#GP_User_Manual GP User Manual] section for GP and Section
[UserGuide#GA_User_Manual GA User Manual] for GA. Section
[UserGuide#Customizing_the_Evolutionary_Algorithm Customizing the
Evolutionary Algorithm] gives also good insight on configuring a custom
evolution.

= Using the Register =

@@ -302,7 +302,7 @@
</Evolver>
</Beagle>
}}}
-The important thing to understand is that the steady-state operator
(`SteadyStateOp`) is a replacement strategy and that the XML tree under it
(between the `<SteadyStateOp>` and `</SteadyStateOp>` tags)) is its
breeding tree. The three sub-trees under it are called randomly following a
uniform probability density function parametrized by their respective
breeding probability. For the first breeding sub-tree to the steady-state
replacement strategy, the breeding probability is given by parameter
`ga.cx1p.indpb`, while for the second sub-tree the breeding probability is
given by parameter `ga.mutflip.indpb`, and the last sub-tree breeding
probability is given by parameter `ec.repro.prob`. The steady-state
replacement strategy generates _n_ individuals with its breeder tree at
each generation, where _n_ is the size of the population. Each newly
generated individual replaces a randomly chosen individual existing in the
actual population in a steady-state fashion. Once the configuration file
set-up correctly, an evolution using the given EA structure can be launched
by given the good configuration file to use on the command-line. See
previous Section [UserManual#Modifying_Parameters_on_the_Command-Line
Modifying Parameters on the Command-Line] for more details.
+The important thing to understand is that the steady-state operator
(`SteadyStateOp`) is a replacement strategy and that the XML tree under it
(between the `<SteadyStateOp>` and `</SteadyStateOp>` tags)) is its
breeding tree. The three sub-trees under it are called randomly following a
uniform probability density function parametrized by their respective
breeding probability. For the first breeding sub-tree to the steady-state
replacement strategy, the breeding probability is given by parameter
`ga.cx1p.indpb`, while for the second sub-tree the breeding probability is
given by parameter `ga.mutflip.indpb`, and the last sub-tree breeding
probability is given by parameter `ec.repro.prob`. The steady-state
replacement strategy generates _n_ individuals with its breeder tree at
each generation, where _n_ is the size of the population. Each newly
generated individual replaces a randomly chosen individual existing in the
actual population in a steady-state fashion. Once the configuration file
set-up correctly, an evolution using the given EA structure can be launched
by given the good configuration file to use on the command-line. See
previous Section [UserGuide#Modifying_Parameters_on_the_Command-Line
Modifying Parameters on the Command-Line] for more details.

== Defining New Operators ==

@@ -333,7 +333,7 @@

The Genetic Algorithm (GA) framework has been re-engineered in version
2.1.0 to extend its support over the basic binary representation to
real-valued GA and simple Evolution Strategy (ES) representations. The
three standard representations of the GA framework share the namespace `GA`
and a similar organization. Each representation has a genotype class that
implement the linear structure which are derived from a `std::vector`.
There is several crossover operators generic (1-point, 2-points, uniform)
for vector-based representation implemented as class template, where the
templated parameter must respect the STL _sequence_ conceptual interface
(the `std::vector` template respects this interface). A
representation-specific type for each generic crossover operator is defined
for each standard GA representation. There is also a
representation-specific mutation operator defined for each standard
representation, along with a per representation evolver.

-To implement an application using a GA representation, we should follow
the steps explained in Section
[UserManual#Building_a_System_for_an_Evolution Building a System for an
Evolution] by taking attention to specify the genotype used and the
appropriate evolver. The following code snippet is extracted for the
`onemax` example and illustrates this for a bit-string GA representation.
+To implement an application using a GA representation, we should follow
the steps explained in Section
[UserGuide#Building_a_System_for_an_Evolution Building a System for an
Evolution] by taking attention to specify the genotype used and the
appropriate evolver. The following code snippet is extracted for the
`onemax` example and illustrates this for a bit-string GA representation.
{{{
// 1. Build the system.
System::Handle lSystem = new System;
@@ -465,7 +465,7 @@
|| `GP::MutationSwapSubtreeOp` || `GP::MutationSwapSubtreeConstrainedOp` ||


-When an user want to take advantage of STGP, he first needs to use an
evolver made of the constrained operators (instead of the simple
unconstrained ones). The example `spambase` included in the distribution
contains configuration files where evolver composed of operators that
support constraints. Section [UserManual#Building_a_Custom_Evolver Building
a Custom Evolver] also explain how to change the set-up of evolvers.
+When an user want to take advantage of STGP, he first needs to use an
evolver made of the constrained operators (instead of the simple
unconstrained ones). The example `spambase` included in the distribution
contains configuration files where evolver composed of operators that
support constraints. Section [UserGuide#Building_a_Custom_Evolver Building
a Custom Evolver] also explain how to change the set-up of evolvers.

The second point needed to do STGP is to set the typing in the primitives
used. The typing is made by associating a char string to a type, generally
the RTTI name of the datum type. To implement the typing of the
individuals, two methods must be over-defined in the concrete primitives
classes, `getArgType` and `getReturnType`. The method `getReturnType` gives
the type of the datum that is returned by the primitives. The method
`getArgType` give the string type of the ith argument of the nodes
associated to the primitive.

@@ -507,7 +507,7 @@

The basic MOEA fitness measure is implemented in class `FitnessMultiObj`,
which maximize all the objectives. A derived fitness measure is also
defined in class `FitnessMultiObjMin` and consists to minimize the
objectives. You should either use one of the two preceding standard MOEA
fitness measure, or use a custom one derived from these as fitness measure.
The class `FitnessMultiObj` is derived from a `std::vector<double>` and
thus the user should use the STL vector interface to set the different
objectives value.

-Once the type of fitness measure used is stated in the evaluation
operator, the population allocators must be set up to use it. This can be
done by following the explanations given in Section
[UserManual#Building_a_System_for_an_Evolution Building a System for an
Evolution], at the item population. This is necessary to clone/copy fitness
value between individuals and to read a milestone from uninitialized
population.
+Once the type of fitness measure used is stated in the evaluation
operator, the population allocators must be set up to use it. This can be
done by following the explanations given in Section
[UserGuide#Building_a_System_for_an_Evolution Building a System for an
Evolution], at the item population. This is necessary to clone/copy fitness
value between individuals and to read a milestone from uninitialized
population.

Finally, the evolutionary algorithm must be set-up for the use of MOEA.
This first imply that a multiobjective selection operation must be used.
There is actually two of these in Open BEAGLE, NSGA-II implemented as
replacement strategy operator `NSGA2Op`, and NPGA 2 implemented as a more
classical selection operator `NPGA2Op`. The following presents how the
NSGA-II configuration file of the multiobjective bit string GA example
`knapsack`.
{{{