Commit 2c92732c authored by Joseph Pallamidessi's avatar Joseph Pallamidessi

start to write the easea manual

parent 7d5a2412
\documentclass{article}
\usepackage{array}
\usepackage[francais]{babel}
\usepackage[utf8]{inputenc}
\begin{document}
\title{The EASEA manual}
\author{Equipe BFO \\
\small Université de Strasbourg}
\maketitle
\section{This manual} % (fold)
\label{sec:introduction}
\paragraph{} % (fold)
\label{par:}
This document is intended to programimer working on the EASEA platform and to
everyone working with it. It contain the language and idioms description, the
concept behind it and the documentation related to the compiler and its genetic
algorithm library.
% paragraph (end)
% section introduction (end)
\section{Introduction} % (fold)
\label{sec:Introduction}
\paragraph{} % (fold)
\label{par:}
EASEA and EASEA-CLOUD are Free Open Source Software (under GNU Affero v3 General Public License) developed by the SONIC (Stochastic Optimisation and Nature Inspired Computing) group of the BFO team at Université de Strasbourg. Through the Strasbourg Complex Systems Digital Campus, the platforms are shared with the UNESCO CS-DC UniTwin and E-laboratory on Complex Computational Ecosystems (ECCE).
EASEA (EAsy Specification of Evolutionary Algorithms) is an Artificial Evolution
platform that allows scientists with only basic skills in computer science to
implement evolutionary algorithms and to exploit the massive parallelism of
many-core architectures in order to optimize virtually any real-world problems
(continous, discrete, combinatorial, mixed and more (with Genetic Programming)),
typically allowing for speedups up to x500 on a \$3,000 machine, depending on the complexity of the evaluation function of the inverse problem to be solved.
Then, for very large problems, EASEA can also exploit computational ecosystems as it can parallelize (using an embedded island model) over loosely coupled heterogenous machines (Windows, Linux or Macintosh, with or without GPGPU cards, provided that they have internet access) a grid of computers or a Cloud.
% paragraph (end)
% section Introduction (end)
\section{Capabilities and features} % (fold)
\label{sec:Capabilities}
\subsection{The platform} % (fold)
\label{sub:subsection name}
\paragraph{} % (fold)
\label{par:}
Runs can be distributed over cluster of homogeneous AND heterogeneous machines.
Distribution can be done locally on the same machine or over the internet (using a embedded island model).
Parallelization over GPGPU cards leading to massive speedup (x100 to x1000).
C++-like description language.
EASEA use CUDA to parallelize over GPGPU card. There is, as absurd as it sound, no
parallelization over CPU at the time of redaction, but a working openMP prototype
enters its final testing phase.
EASEA offer a high level of parametrization and the possibility to include large
chunk of C/C++ code with little to no change at all.
% paragraph (end)
% subsection subsection name (end)
\subsection{Current genetic algorithm implementation} % (fold)
\label{sub:current genetic algorithm implementation}
\paragraph{} % (fold)
\label{par:}
Darwinian and baldwinian approach
Genetic programming
CMA-ES (Covariance Matrix Adaptation Evolution Strategy)
Memetic approach
EASEA also offer out-of-the-box a wide range of selector: Max/Min deterministic,
Max/Min Random, Max/Min tournament and MaxRoulette.
Three stopping criterion are possible : by generation, by time and by user
defined control.
The main advantage of EASEA
% paragraph (end)
% subsection current genetic algorithm implementation (end)
% section Capabilities (end)
\section{Support} % (fold)
\label{sec:Support}
In order to have a working grapher, java jre 1.6 is required. Without it, an error appears at the start of easea's compiled programs but can be safely ignored.
EASEA had been compiled and tested with those following compilers:
Gcc 4.4 to 4.8.2
Clang 3.0 to 3.3
Mingw-gcc 4.8.2
CUDA SDK > 4.1
% section Support (end)
\section{Workflow} % (fold)
\label{sec:Workflow}
easea compiler [GP,CUDA,CUDA_GP, etc ...]-> geneticAlgo.ez -> make -> geneticAlgo
(executable)
% section Workflow (end)
\section{The language} % (fold)
\label{sec:the language}
\subsection{EASEA defined sections} % (fold)
\label{sub:EASEA defined sections}
Genome specific fields
Genome Initialiser
Description
Uses the Genome EASEA variable to access the individual's genome.
EASEA syntax
\GenomeClass::initialiser :
...
\end
Example
\GenomeClass::initialiser :
for(int i=0; i<SIZE; i++ ) {
Genome.x[i] = (float)random(X_MIN,X_MAX);
Genome.sigma[i]=(float)random(0.,0.5);
}
\end
Genome Crossover
Description
Binary crossover that results in the production of a single child.
The child is initialized by cloning the first parent.
Uses parent1 and parent 2 EASEA variables to access the parents genome.
Uses the child EASEA variable to access the child's genome.
EASEA syntax
\GenomeClass::crossover :
...
\end
Example
\GenomeClass::crossover :
for (int i=0; i<SIZE; i++)
{
float alpha = (float)random(0.,1.); // barycentric crossover
child.x[i] = alpha*parent1.x[i] + (1.-alpha)*parent2.x[i];
}
\end
Genome mutator
Description
Must return the number of mutations.
Uses the Genome variable to access the individual's genome.
EASEA syntax
\GenomeClass::mutator :
...
\end
Example
\GenomeClass::mutator : // Must return the number of mutations
int NbMut=0;
float pond = (float)random(0.,1.);
for (int i=0; i<SIZE; i++) {
if (tossCoin(pMutPerGene)){
NbMut++;
Genome[i] += pond;
}
}
return NbMut;
\end
Genome Evaluator
The evaluation function is expected to be autonomous and independent from the rest of the code, for correct parallelization.
Description
Must return the fitness of the individual.
Uses the Genome defined variable to access the individual's genome.
EASEA syntax
\GenomeClass::evaluator :
...
\end
Example
\GenomeClass::evaluator :
float Score= 0.0;
Score= Weierstrass(Genome.x, SIZE);
return Score;
\end
Genome Display
Description
Uses the Genome variable to access the individual's genome.
EASEA syntax
\GenomeClass::display :
...
\end
Example
\GenomeClass::display :
for( size_t i=0 ; i<SIZE ; i++){
cout << Genome.x[i] << ":" << "|";
}
cout << Genome.fitness <<< "\n";
\end
User definition fields
User Declarations
Description
This is the section where the user can declare some global variables and some global function.
EASEA syntax
\User declarations :
...
\end
Example
\User declarations :
#define SIZE 100 //Problem size
#define Abs(x) ((x) < 0 ? -(x) : (x)) //Definition of the Abs global function
#define MAX(x,y) ((x)>(y)?(x):(y)) //Definition of the MAX global function
#define MIN(x,y) ((x)<(y)?(x):(y)) //Definition of the MIN global function
#define PI 3.141592654 //Definition of the PI global variable
\end
User functions
Description
This is the section where the user can declare the different functions he will need.
EASEA syntax
\User declarations :
...
\end
Example
\User declarations :
float gauss()
/* Generates a normally distributed random value with variance 1 and 0 mean.
Algorithm based on "gasdev" from Numerical recipes' pg. 203. */
{
int iset = 0;
float gset = 0.0;
float v1 = 0.0, v2 = 0.0, r = 0.0;
float factor = 0.0;
if (iset) {
iset = 0;
return gset;
}
else {
do {
v1 = (float)random(0.,1.) * 2.0 - 1.0;
v2 = (float)random(0.,1.) * 2.0 - 1.0;
r = v1 * v1 + v2 * v2;
}
while (r > 1.0);
factor = sqrt (-2.0 * log (r) / r);
gset = v1 * factor;
iset = 1;
return (v2 * factor);
}
}
\end
User Classes
Description
This is the section where the user will be able to declare:
The genome of the individuals trough the GenomeClass class
Different classes that will be needed.
The GenomeClass field has to be present and ideally not empty. All the variables defined in this field (the genome) will be accessible in several other fields using the 'Genome' variable. Other "hidden" variables can be accessed such as:
The fitness (variable: fitness. Ex: Genome.fitness)
EASEA syntax
\User Class :
...
GenomeClass{
...
}
\end
Example
\User classes:
Element {
int Value;
Element *pNext; }
GenomeClass {
Element *pList;
int Size; }
\end
User Makefile
Description
This section allows the user to add some flags to the compiler typically to include some custom libraries.
Two flags of the Makefile are accessible to the user in this section:
CPPFLAGS
LDFLAGS
EASEA syntax
\User Makefile options :
...
\end
Example
\User Makefile options :
CPPLAGS += -llibrary
LDFLAGS += -I/path/to/include
\end
Miscellaneous fields
Before everything else function
Description
This function will be called at the start of the algorithm before the parent initialization.
EASEA syntax
\Before everything else function :
...
\end
After everything else function
Description
This function will be called once the last generation has finished.
The population can be accessed.
EASEA syntax
\After everything else function :
...
\end
At the beginning of each generation function
Description
This function will be called every generation before the reproduction phase.
The population can be accessed.
EASEA syntax
\At the beginning of each generation function :
...
\end
At the end of each generation function
Description
This function will be called at every generation after the printing of generation statistics.
The population can be accessed.
EASEA syntax
\At the end of each generation function :
...
\end
At each generation before reduce function
Description
This function will be called at every generation before performing the different population reductions.
The parent population AND the offspring population can be accessed (merged into a single population).
EASEA syntax
\At every generation before reduce function :
...
\end
Memetic specific field
Genome Optimiser
Description
The optimiser field is a Genome specific field. It is meant to contain the function defining the way an individual will be locally optimized n times. The function will hence be called sequentially as many times as the user desires for each individual.
EASEA gives the user two possibilities when designing their local optimization function :
The user can choose to design the function that will enhance the genome of their individuals only in which case the rest of the local optimizer (i.e. creating the local optimizing loop, checking if an individual has improved or not, storing temporary individuals, calling of the evaluation function, etc ...) will be taken care of by the EASEA memetic algorithm. The function will have to be called as many times as specified by the Number of optimisation iterations parameter.
The user can choose to write the complete local optimizer. This way, he will have the complete freedom to design a more complex and specific optimizer, but he will also have to deal with the creation of the local optimization loop, the management of temporary individuals, the calling of the evaluation function etc... The Number of optimisation iterations parameter will have to be set to 1 as the function desigend by the user will contain it's own optimization loop requiring it's own specific number of optimization iterations.
EASEA syntax
\GenomeClass::optimiser :
...
\end
Examples
The two following examples will expose the two different ways the optimizer field can be used. The first example will show a simple mutation function. The second example will show the design of a complete local optimizer. Both examples are GPU compatible.
Genome optimization only
\GenomeClass::optimiser :
float pas = 0.001;
Genome.x[currentIteration%SIZE]+=pas;
\end
This example shows a simple mutation function that will add a small variation to one of the genes of an individual. The call to this function will be followed by a call to the evaluation function, and a replacement process. If the modification of the genome has improved the individual, it will replace the original one. This is being taken care of by the EASEA memetic algorithm.
Complete local optimizer
\GenomeClass : : optimiser : // Optimises the Genome
float pas=0.001;
float fitnesstmp = Genome.fitness ;
float tmp[SIZE];
int index = 0;
for(int i=0; i<SIZE; i++)
tmp[ i ] = Genome.x[ i ];
for(int i=0; i<100; i++){
tmp[index] += pas;
fitnesstmp = Weierstrass(tmp, SIZE);
if(fitnesstmp < Genome.fitness){
Genome. fitness = fitnesstmp ;
Genome.x[ index ] = tmp[ index ];
}
else {
fitnesstmp = Genome.fitness;
tmp[ index ] = Genome.x[ index ];
if( pas < 0 )
index = ( index + 1)%SIZE;
pas *= -1;
}
}
\ end
This example shows how to design a complete local optimization function. The genome is almost being changed in the same way as in the first example.
% subsection EASEA defined sections (end)
\subsection{EASEA defined functions} % (fold)
\label{sub:EASEA defined functions}
Random Number Generators
TossCoin
Description
Simulates the toss of a coin. There are two different definitions of the tossCoin function:
A simple toss of a coin.
A biased toss of a coin.
EASEA syntax
bool tossCoin() // SImple tosscoin
bool tossCoin(float bias) // Biased tossCoin
Example
if( tossCoin(0.1)){
...
}
Random
Description
Generates a random number. There are several definitions to the random function:
Random function with Min Max Boundary
Random function with Max Boundary only
In the case of a Max boundary only, the Min boundary will be 0.
EASEA syntax
int random( int Min, int Max)
int random( int Max)
float random( float Min, float Max)
double random( double Min, double Max)
% subsection EASEA defined functions (end)
% section the language (end)
\subsection{EASEA defined variable} % (fold)
\label{sub:EASEA defined variable}
Current Generation
Return the current generation number. This variable can be modified.
EASEA syntax
currentGeneration
Number of Generation
Returns the generation limit. This variable can be modified.
EASEA syntax
NB_GEN
Population Size
Returns the size of the population. This variable cannot be modified.
EASEA syntax
POP_SIZE
Mutation Probability
Returns the mutation probability. This variable can be modified.
EASEA syntax
MUT_PROB
Crossover Probability
Returns the crossover probability. This variable can be modified.
EASEA syntax
XOVER_PROB
Minimise
Returns a boolean indicating of the algorithm performs a minimization of not. Returns true if minimizing.
EASEA syntax
MINIMISE
Population
Returns a pointer to the main population. This variable cannot be used everywhere. If misused, it can provoque unexpected behaviours or compile errors.
EASEA syntax
pPopulation ([i] to access individuals)
fitness
pPopulation[i]->fitness
Best individual
Returns a pointer to the best individual found to this point. All the genome field can be accessed as well as the fitness field. All the genome fields can be modified.
EASEA syntax
bBest ("->" operator to access variables)
Genome
Returns the genome of an individual (can only be used in genome specific EASEA sections such as mutation, initialisation, [[EASEA defined sections#Genome Evaluation|evaluation and display). All the fields can be modified.
EASEA syntax
Genome ("." operator to access variables)
Parent 1
Returns the genome of the first selected parent. Can only be used in the crossover genome section.
EASEA syntax
parent1
Parent 2
Returns the genome of the second selected parent. Can only be used in the crossover genome section.
EASEA syntax
parent2
Child
Returns the genome of the newly created individual. Can only be used in the crossover genome section.
EASEA syntax
child
Basic Parameters
Number of generations
Description :
Gives the maximum number of generations during wich the evolutionary algorithm will run.
EASEA syntax :
Number of generations:
Values : Integer strictly over 0.
Command line syntax :
--nbGen=
Values : Integer strictly over 0.
Time limit
Description :
Sets the maximum amount of time in seconds during wich the evolutionary algorithm will be allowed to run. Setting this parameter to 0 deactivates the time limit.
EASEA syntax :
Time limit :
Values : Positive Integer.
Command line syntax :
--timeLimit=
Values : Positive Integer.
Population size
Description :
Sets the size of the population that will be evolved.
EASEA syntax :
Population size :
Values : Integer strictly over 0.
Command line syntax :
--popSize=
Values : Integer strictly over 0.
Offspring size
Description :
Sets the number of individual that will be produced trough evolutionary crossover and/or mutation.
EASEA syntax :
Offspring size :
Values : Integer strictly over 0.
Command line syntax :
--nbOffspring=
Values : Integer strictly over 0.
Mutation probability
Desciption :
This parameter determines the probability that an individual will be mutated during it's creation process.
EASEA syntax :
Mutation probability :
Values : Real number between 0.0 and 1.0 .
Command line syntax :
This parameter is not avaible in command line yet.
Crossover probability
Description :
This parameter determines the probability that an individual will be the result of a crossover during it's creation process.
EASEA syntax :
Crossover probability :
Values : Real number between 0.0 and 1.0 .
Command line syntax :
This parameter is not avaible in command line yet.
Evaluator goal
Description :
This parameter will set the goal of the evolutionary algorithm.
EASEA syntax :
Evaluator goal :
Values : minimis/ze or maximis/ze
Command line syntax :
This parameter is too fundamental to the behaviour of the algorithm to be changed in command line.
Selection operator
Description :
This parameter decides of the way individuals of the parent population will be selected to create the new individuals. Several operator are avaiable in EASEA:
Tournament (need a selection pressure)
Deterministic
Roulette (only when Evaluator goal = maximise)
Random
When the selection pressure is an integer over 0, the best individual from the n will be selected.
When the selection pressure is a real number between 0.0 and 1.0, the best individual of 2 will be selection with the probability p given by the selection pressure.
EASEA syntax :
Selection operator: OPERATOR SELECTION_PRESSURE
Values for operators : Tournament Deterministic Roulette Random
Values for selection pressure : Integer strictly over 0 or Real number between 0.0 and 1.0 .
Compile line syntax :
--selectionOperator=
--selectionPressure=
Values for operators : Tournament Deterministic Roulette Random
Values for selection pressure : Integer strictly over 0 or Real number between 0.0 and 1.0 .
Surviving parents
Description :
This parameter will determine the number of children that will be participating in the run for the next generation (IL VA FALLOIR MODIFIER CETTE DESCRITPION)
EASEA syntax :
Surviving offspring: