CorsoReti

2012-02-16T14:25:17Z

LuigiMalago:

2011-10-24T22:31:23Z

LuigiMalago:

Evoptool Experiments

2011-10-24T22:30:26Z

LuigiMalago:

{| cellpadding="20" cellspacing="0" border="1"
|function
|instance, run
|size
|algorithm+param
|optimum found
|author
|when
|rev evoptool
|location
|description
|-
|OneMax
|30 runs
|25,64,100
|SNGD, step=4
|100%
|luigi
|2011/06
|~400
|home jobe, SNGD-OneMax
|CEC2011
|-
|
|
|
|
|
|
|
|
|
|}

Evoptool Experiments

2011-10-24T22:29:48Z

LuigiMalago:

{| cellpadding="20" cellspacing="0" border="1"
|function
|size
|instance, run
|algorithm+param
|optimum found
|author
|when
|rev evoptool
|location
|description
|-
|OneMax
|30 runs
|25,64,100
|SNGD, step=4
|100%
|luigi
|2011/06
|~400
|home jobe, SNGD-OneMax
|CEC2011
|-
|
|
|
|
|
|
|
|
|
|}

Evoptool Experiments

2011-10-24T22:29:07Z

LuigiMalago:

{| cellpadding="20" cellspacing="0" border="1"
|function
|size
|instance, run
|algorithm+param
|author
|when
|rev evoptool
|location
|description
|-
|OneMax
|30 runs
|25,64,100
|SNGD, step=4
|luigi
|2011/06
|~400
|home jobe, SNGD-OneMax
|CEC2011
|-
|
|
|
|
|
|
|
|
|}

Evoptool Experiments

2011-10-24T22:28:38Z

LuigiMalago:

{| cellpadding="20" cellspacing="0" border="1"
|Function
|Size
|Instance,run
|Algorithm+param
|Author
|when
|rev evoptool
|location
|description
|-
|OneMax
|30 runs
|25,64,100
|SNGD, step=4
|luigi
|2011/06
|~400
|home jobe, SNGD-OneMax
|CEC2011
|-
|
|
|
|
|
|
|
|
|}

Evoptool Experiments

2011-10-24T22:27:44Z

LuigiMalago:

{| cellpadding="20" cellspacing="0" border="1"
|Function
|Size
|Algorithm+param
|Author
|when
|rev evoptool
|location
|description
|-
|OneMax
|25,64,100
|SNGD, step=4
|luigi
|2011/06
|~400
|home jobe, SNGD-OneMax
|CEC2011
|-
|
|
|
|
|
|
|
|
|}

Evoptool Experiments

2011-10-24T22:27:05Z

LuigiMalago: Created page with "{| cellpadding="20" cellspacing="0" border="1" |Function |Size |Algorithm |Author |when |rev evoptool |location |description |- |OneMax |25,64,100 |SNGD |luigi |2011/06 |~400 |ho..."

{| cellpadding="20" cellspacing="0" border="1"
|Function
|Size
|Algorithm
|Author
|when
|rev evoptool
|location
|description
|-
|OneMax
|25,64,100
|SNGD
|luigi
|2011/06
|~400
|home jobe, SNGD-OneMax
|CEC2011
|-
|
|
|
|
|
|
|
|
|
|}

Evoptool: Evolutionary Optimization Tool

2011-10-24T22:06:00Z

LuigiMalago: /* Installation */

== Description ==

Evolutionary Optimization Tool (Evoptool) is an open source optimization tool writte in C++, distributed under GNU General Public License. Evoptool implements meta-heuristics based on the Evolutionary Computation paradigm and aims to provide a common platform for the development and test of new algorithms, in order to facilitate the performance comparison activity. Evoptool offers a wide set of benchmark problems, from classical toy samples to more complex tasks, and a collection of algorithm implementations from Genetic Algorithms and Estimation of Distribution Algorithms paradigms. Evoptool is flexible, easy to extend, also with algorithms based on other approaches other from EAs.

== The Evoptool Team ==

*[[User:MatteoMatteucci| Matteo Matteucci]] - matteucci [AT] elet.polimi.it

*[http://www.dei.polimi.it/personale/dettaglio.php?id_persona=829&id_sezione=&lettera=M&idlang=ita| Luigi Malagò] - malago [AT] elet.polimi.it

*[[User:GabrieleValentini| Gabriele Valentini]] - gvalentini [AT] iridia.ulb.ac.be

*[[User:DavideCucci| Davide Cucci]] - cucci [AT] elet.polimi.it

'''Formerly involved'''
*Emanuele Corsano

== Mailing List ==
http://groups.google.com/group/evoptool

== Features ==

====Algorithms implemented====
* Genetic Algorithms
** SGA
*Estimation of Distribution Algorithms
**PBIL, UMDA, cGA, COMIT, BOA, FCA
* DEUM framework
**DEUMd, IsingDEUM, DEUM-Chain, DEUM-LDA, DEUM-CE, DEUM-X2, DEUM-JEMP, DEUM-l1, sDEUM
* Stochastic Gradient Descent
**SGD, SNGD
* Other Meta-heuristics
**Simulated Annealing

References to original papers will be added soon.

====Benchmark functions implemented====
* OneMax
* AltBit
* Trap3
* Trap5
* IsingSpinGlass2D
* IsingSpinGlass3D
* Max Cut

== Download ==

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Developers may also access unstable branch. Contact the evoptool team for more details.

== Installation ==
Follow these steps in order to compile evoptool

1. Download source code from svn

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Refer to trunk for the lastest (stable?) version of evoptool

2. First you need to manually compile the <code>l1_logreg-0.8.2</code> package, http://www.stanford.edu/~boyd/l1_logreg/
whose source are already included in the evoptool repository. In order to do that follow the instrunctions in
<code>README.evoptool</code> in the <code>l1_logreg-0.8.2</code> directory

Next, compile <code><id_dist/code> following the instructions in <code>README.evoptool</code> in the <code><id_dist</code> folder

3. Then you need to compile a module at a time. Each module is included in a different folder.
To compile a module, from go to the module source folder and do make lib. For instance, for the module named <code>common</code>

cd common/src
make lib
cd ..

Compile modules in the following orderm due to dependencies

common
functions
ga
stochastic
eda

To clean a module, do

make clean

from the module source directory

4. Go to <code>core</code> module and type

make exe

Binary files will be copied in the <code>bin</code> directory in the root as well as the <code>bin</code> directory of the <code>core</code> module

'''Required packages'''
* Libraries
** ''gtkmm-2.4''
** ''glademm-2.4''
** ''gthread-2.0''
** ''sigc++-2.0''
** ''opencv'' (see for instance http://www.samontab.com/web/2011/06/installing-opencv-2-2-in-ubuntu-11-04/)
** ''gsl''
** ''gslcblas''
** ''libxml++-2.6''
** ''f2c''

* Software
** ''gnuplot''
** ''R (lars package)''

== Running ==

Right now <code>evoptool</code> only runs as a script. GUI is not maintained in the latest version.
The <code>evoptool</code> binary file is supposed to be run in the <code>bin</code> directory in the root, this is because right now the script looks for some configuration files, for the instances of the problems, and temp directories. If you want to run the script from other directories, you just need to copy in that directory the <code>evoptool-file</code> directory that you find in the <code>bin</code> directory. Link such directory instead of copying it is not safe if you run multiple scripts at the same time, since output files will be shared.

To run the algorithm you need to enter as input an xml file. For instance you can run

./evoptool evoptool-file/examples/unitTestOneMax.xml

The <code>evoptool-file/example</code> directory contains a set of xml files for different benchmarks and different algorithms.
Take a loot at the <code>example.xml</code> file for the documentation on hoe to set the parameters for an each execution of <code>evoptool</code>

Each execution of <code>evoptool</code> produces a set of files as output. You can find all files in <code>evoptool-file/temp</code> directory. Plus a tar.gz file containing such files can be produced at the end of the execution of <code>evoptool</code>. See the xml file for details.

evoptool-file/temp/data
contains the raw data of the statistics according to the xml file

evoptool-file/temp/gnuplot
contains the gnuplot files to produce images of the statistics

evoptool-file/temp/image
contains images of the statistics produced according to the xml file

evoptool-file/temp/support
contains logs

== Documentation ==

==== Implement a new benchmark function====

Benchmarks are defined in the <code>function</code> module. A benchmark is the maximization problem of a real valued function defined over a vector of n binary variables. Functions are maximized in <code>evoptool</code>. In order to implement a new benchmark function you have to create a new <code>class</code> that inherits from <code>ObjectiveFunction</code> in the <code>common</code> module. Take a look at the <code>OneMax</code> benchmark function.

Among the arguments of the constructor of the <code>ObjectiveFunction</code> class there must be the size of the benchmark, which may or may not be a parameter of the new benchmark.

OneMax::OneMax(int size) : ObjectiveFunction(size)

In the constructor you have whether the maximum of the function is known or not

_knownSolution = true;

And in case this is known, set the minimum value and maximum value for the function

_minFitness = 0;
_maxFitness = size; //the maximum value of the OneMax function is defined as the sum of the bits of x set to one.

Besides, such values are used in the normalization of the functions in the plots of the statistics.

Each benchmark must implement the <code>f</code> method, which takes the <code>BinaryString</code> x and return f(x). For instance, for <code>OneMax</code> you have

double OneMax::f(BinaryString *bi) {
 if (bi != NULL) {
  if(!(bi->validCache())) {
   /* Fitness cache value not valid */
   int sum = 0;
   for (int j = 0; j < _size; j++) {
    sum = sum + bi->get(j);
   }
   bi->setFitnessCache(sum);
   return sum;
  } else {
   return bi->getFitnessCache();
  }
 } else {
  cerr << "[OneMax::f] binary instance cannot be null" << endl;
  return 0;
 }
}

In order to avoid multiple evaluations of the same <code>BinaryString</code> x, a caching mechanism has been implemented.

Moreover, you are asked to implement the <code>exportInteration</code> function, which return an <code>HyperGraph</code> which represents the interactions present in the function. In order to determine such hypergraph, start from the polinomial representation of the function, and for each monomial introduce a new hyperedge in the hypergraph.

For the <code>OneMax</code> function, such representation corresponds to the independence graph, since such function is linear.

HyperGraph* OneMax::exportInteractions() {
 HyperGraph *interactions = new HyperGraph();
 interactions->createIndependenceGraph(_size);
 return interactions;
}

In <code>Evoptool.h</code> add an entry in the <code>Tasks</code> enum.

/* This enumeration defines an identifier for each task function. */
typedef enum {
 ONE_MAX = 7,
} Tasks;

This value will identify uniquely the benchmark in the xml file. In the <code>XMLParser.cpp</code> file, add an entry for the new function.

bool XMLParser::parseTask(xmlpp::TextReader &reader, Evoptool::TestParameters *params) {
 ..
 switch (task) {
  case Evoptool::ONE_MAX: params->task = new OneMax(size);
  break;
  ..
  default: return false;
 }
 ..
}

Additional parameters can be obtained using the xml TextReader object, as for the <code>ForPeaks</code> function.

case Evoptool::FOUR_PEAKS:
 value = readNodeContent(reader, "peaks", &errorFlag);
 if (errorFlag) return false;
 int peaks = toInt(value);
 params->task = new FourPeaks(size, peaks);
 break;

Finally in the xml file, a function can set with the <code>task</code> tag, together with all parameters.

<task>
 <name>7</name>
 <size>64</size>
</task>

==== To create a new algorithm ====

1. Implement a new algorithm

All algorithms must inherit from the Algorithm class. First override the Algorithm::initAlgorithm as follows:

void DEUM::initAlgorithm(ObjectiveFunction* of) {
Algorithm::initAlgorithm(of);

/* Initialization tasks */
...
}

Then implement a run() method which performs al the required task for '''one''' iteration of your algorithm.

There are some classes which contain useful methods such as samplers and estimators from which your algorithm can inherit. The most useful are:

PopulationBasedAlgorithm
ModelBasedAlgorithm
ExponentialFamilyAlgorithm
BayesianNetworkBasedAlgorithm

2. Append entry in the <tt>Algorithms</tt> enum in Evoptool.h.

typedef enum {
...
DEUM // 5
} Algorithms;

In the xml configuration file, your algorithm will be characterized by the int value associated with the position in this enum declaration.

3. modify the file
core/src/XMLParser.cpp. Search for the method <tt>bool XMLParser::parseAlgorithms</tt> and insert an new entry for your algorithm in the <tt>algorithmParameters</tt> array, for example

AlgorithmParameters algorithmParameters[] = {
...
{ Evoptool::DEUM, 5, (char*) "IDDDI" }, // Pop, percElitism, percSelec, CoolRate, GibbsIterations
...
};

In each entry, the first field is the name of the entry in the <tt>Algorithms</tt> enum just modified in <tt>Evoptool.h</tt>, the second is the number of parameters to be parsed in the xml configuration file and the third is a string specifying their type: <tt>I</tt> for integer and <tt>D</tt> for double.

4. add a case in the switch that follows in <tt>bool XMLParser::parseAlgorithms</tt>, for instance:

case Evoptool::DEUM:
algos[i] = new extendedFCA(intVal[0], doubleVal[0], doubleVal[1], intVal[1], intVal[2], params->rng);
algos[i]->initAlgorithm(params->task);
break;

Note that your algorithm can employ the random number generator provided by the Evoptool core, <tt>params->rng</tt>.

5. Include your headers in core/src/Algorithms.h

6. Document how your algorithm is instantiated in the comments appearing in evoptool-file/exec-scripts/example.xml

Algorithm Id Types Parameters
=====================================================================================================
...
FCA 26 "IDDII" (Pop, PercSelection, LearningRate, MaxCompositionLenght, MaxMonomialOrder)
...

7. Add an instantiation example for your algorithm in evoptool-file/exec-scripts/example.xml

<algo id="26" instanceName="FCA">
<int>1000</int>
<double>0.5</double>
<double>1</double>
<int>64</int>
<int>2</int>
</algo>

==== Run an algorithm in a C++ program ====

The simplest way to do this is to create a new submodule in <code>core</code>, i.e., a new source directory within the source directory of a module
For instance, the steps to create a new submodule named <code>myexample</code> are

1. copy the example submodule <code>exampleRunAlgorithm</code> in a new folder named <code>myexample</code> in

evoptool/core/src

2. modify the <code>Makefile</code> in the <code>myexample</code> directory, see comments in the makefile for more details.

3. edit the <code>main</code> function in the source file, if you need you can create other C++ and .h files in the same folder.

4. from <code>evoptool/core/src/myexample</code> run

make bin

The bin file is create in <code>evoptool/core/bin</code> and copied in <code>evoptool/bin</code>

NOTICE that <code>evoptool/core/bin</code> may be deleted after a <code>make cleanall</code>

5. from <code>evoptool/bin</code> run

./myexample

==== Available statistics ====

In the configuration xml file you can enable the evaluation of three set of statistics:

<statisticsConfiguration>
<evalPopulationStatistics>yes</evalPopulationStatistics>
<evalModelStatistics>yes</evalModelStatistics>
<evalExecutionStatistics>No</evalExecutionStatistics>
...
</statisticsConfiguration>

See the headers file in evoptool/common/src for details.

Evoptool: Evolutionary Optimization Tool

2011-10-24T13:25:04Z

LuigiMalago: /* Algorithms implemented */

== Description ==

Evolutionary Optimization Tool (Evoptool) is an open source optimization tool writte in C++, distributed under GNU General Public License. Evoptool implements meta-heuristics based on the Evolutionary Computation paradigm and aims to provide a common platform for the development and test of new algorithms, in order to facilitate the performance comparison activity. Evoptool offers a wide set of benchmark problems, from classical toy samples to more complex tasks, and a collection of algorithm implementations from Genetic Algorithms and Estimation of Distribution Algorithms paradigms. Evoptool is flexible, easy to extend, also with algorithms based on other approaches other from EAs.

== The Evoptool Team ==

*[[User:MatteoMatteucci| Matteo Matteucci]] - matteucci [AT] elet.polimi.it

*[http://www.dei.polimi.it/personale/dettaglio.php?id_persona=829&id_sezione=&lettera=M&idlang=ita| Luigi Malagò] - malago [AT] elet.polimi.it

*[[User:GabrieleValentini| Gabriele Valentini]] - gvalentini [AT] iridia.ulb.ac.be

*[[User:DavideCucci| Davide Cucci]] - cucci [AT] elet.polimi.it

'''Formerly involved'''
*Emanuele Corsano

== Mailing List ==
http://groups.google.com/group/evoptool

== Features ==

====Algorithms implemented====
* Genetic Algorithms
** SGA
*Estimation of Distribution Algorithms
**PBIL, UMDA, cGA, COMIT, BOA, FCA
* DEUM framework
**DEUMd, IsingDEUM, DEUM-Chain, DEUM-LDA, DEUM-CE, DEUM-X2, DEUM-JEMP, DEUM-l1, sDEUM
* Stochastic Gradient Descent
**SGD, SNGD
* Other Meta-heuristics
**Simulated Annealing

References to original papers will be added soon.

====Benchmark functions implemented====
* OneMax
* AltBit
* Trap3
* Trap5
* IsingSpinGlass2D
* IsingSpinGlass3D
* Max Cut

== Download ==

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Developers may also access unstable branch. Contact the evoptool team for more details.

== Installation ==
Follow these steps in order to compile evoptool

1. Download source code from svn

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Refer to trunk for the lastest (stable?) version of evoptool

2. First you need to manually compile the <code>l1_logreg-0.8.2</code> package, http://www.stanford.edu/~boyd/l1_logreg/
whose source are already included in the evoptool repository. In order to do that follow the instrunctions in
<code>README.evoptool</code> in the <code>l1_logreg-0.8.2</code> directory

Next, compile <code><id_dist/code> following the instructions in <code>README.evoptool</code> in the <code><id_dist</code> folder

3. Then you need to compile a module at a time. Each module is included in a different folder.
To compile a module, from go to the module source folder and do make lib. For instance, for the module named <code>common</code>

cd common/src
make lib
cd ..

Compile modules in the following orderm due to dependencies

common
functions
ga
stochastic
eda

To clean a module, do

make clean

from the module source directory

4. Go to <code>core</code> module and type

make exe

Binary files will be copied in the <code>bin</code> directory in the root as well as the <code>bin</code> directory of the <code>core</code> module

'''Required packages'''
* Libraries
** ''gtkmm-2.4''
** ''glademm-2.4''
** ''gthread-2.0''
** ''sigc++-2.0''
** ''opencv'' (see for instance http://www.samontab.com/web/2011/06/installing-opencv-2-2-in-ubuntu-11-04/)
** ''gsl''
** ''gslcblas''
** ''libxml++-2.6''
** '''f2c''

* Software
** ''gnuplot''

== Running ==

Right now <code>evoptool</code> only runs as a script. GUI is not maintained in the latest version.
The <code>evoptool</code> binary file is supposed to be run in the <code>bin</code> directory in the root, this is because right now the script looks for some configuration files, for the instances of the problems, and temp directories. If you want to run the script from other directories, you just need to copy in that directory the <code>evoptool-file</code> directory that you find in the <code>bin</code> directory. Link such directory instead of copying it is not safe if you run multiple scripts at the same time, since output files will be shared.

To run the algorithm you need to enter as input an xml file. For instance you can run

./evoptool evoptool-file/examples/unitTestOneMax.xml

The <code>evoptool-file/example</code> directory contains a set of xml files for different benchmarks and different algorithms.
Take a loot at the <code>example.xml</code> file for the documentation on hoe to set the parameters for an each execution of <code>evoptool</code>

Each execution of <code>evoptool</code> produces a set of files as output. You can find all files in <code>evoptool-file/temp</code> directory. Plus a tar.gz file containing such files can be produced at the end of the execution of <code>evoptool</code>. See the xml file for details.

evoptool-file/temp/data
contains the raw data of the statistics according to the xml file

evoptool-file/temp/gnuplot
contains the gnuplot files to produce images of the statistics

evoptool-file/temp/image
contains images of the statistics produced according to the xml file

evoptool-file/temp/support
contains logs

== Documentation ==

==== Implement a new benchmark function====

Benchmarks are defined in the <code>function</code> module. A benchmark is the maximization problem of a real valued function defined over a vector of n binary variables. Functions are maximized in <code>evoptool</code>. In order to implement a new benchmark function you have to create a new <code>class</code> that inherits from <code>ObjectiveFunction</code> in the <code>common</code> module. Take a look at the <code>OneMax</code> benchmark function.

Among the arguments of the constructor of the <code>ObjectiveFunction</code> class there must be the size of the benchmark, which may or may not be a parameter of the new benchmark.

OneMax::OneMax(int size) : ObjectiveFunction(size)

In the constructor you have whether the maximum of the function is known or not

_knownSolution = true;

And in case this is known, set the minimum value and maximum value for the function

_minFitness = 0;
_maxFitness = size; //the maximum value of the OneMax function is defined as the sum of the bits of x set to one.

Besides, such values are used in the normalization of the functions in the plots of the statistics.

Each benchmark must implement the <code>f</code> method, which takes the <code>BinaryString</code> x and return f(x). For instance, for <code>OneMax</code> you have

double OneMax::f(BinaryString *bi) {
 if (bi != NULL) {
  if(!(bi->validCache())) {
   /* Fitness cache value not valid */
   int sum = 0;
   for (int j = 0; j < _size; j++) {
    sum = sum + bi->get(j);
   }
   bi->setFitnessCache(sum);
   return sum;
  } else {
   return bi->getFitnessCache();
  }
 } else {
  cerr << "[OneMax::f] binary instance cannot be null" << endl;
  return 0;
 }
}

In order to avoid multiple evaluations of the same <code>BinaryString</code> x, a caching mechanism has been implemented.

Moreover, you are asked to implement the <code>exportInteration</code> function, which return an <code>HyperGraph</code> which represents the interactions present in the function. In order to determine such hypergraph, start from the polinomial representation of the function, and for each monomial introduce a new hyperedge in the hypergraph.

For the <code>OneMax</code> function, such representation corresponds to the independence graph, since such function is linear.

HyperGraph* OneMax::exportInteractions() {
 HyperGraph *interactions = new HyperGraph();
 interactions->createIndependenceGraph(_size);
 return interactions;
}

In <code>Evoptool.h</code> add an entry in the <code>Tasks</code> enum.

/* This enumeration defines an identifier for each task function. */
typedef enum {
 ONE_MAX = 7,
} Tasks;

This value will identify uniquely the benchmark in the xml file. In the <code>XMLParser.cpp</code> file, add an entry for the new function.

bool XMLParser::parseTask(xmlpp::TextReader &reader, Evoptool::TestParameters *params) {
 ..
 switch (task) {
  case Evoptool::ONE_MAX: params->task = new OneMax(size);
  break;
  ..
  default: return false;
 }
 ..
}

Additional parameters can be obtained using the xml TextReader object, as for the <code>ForPeaks</code> function.

case Evoptool::FOUR_PEAKS:
 value = readNodeContent(reader, "peaks", &errorFlag);
 if (errorFlag) return false;
 int peaks = toInt(value);
 params->task = new FourPeaks(size, peaks);
 break;

Finally in the xml file, a function can set with the <code>task</code> tag, together with all parameters.

<task>
 <name>7</name>
 <size>64</size>
</task>

==== To create a new algorithm ====

1. Implement a new algorithm

All algorithms must inherit from the Algorithm class. First override the Algorithm::initAlgorithm as follows:

void DEUM::initAlgorithm(ObjectiveFunction* of) {
Algorithm::initAlgorithm(of);

/* Initialization tasks */
...
}

Then implement a run() method which performs al the required task for '''one''' iteration of your algorithm.

There are some classes which contain useful methods such as samplers and estimators from which your algorithm can inherit. The most useful are:

PopulationBasedAlgorithm
ModelBasedAlgorithm
ExponentialFamilyAlgorithm
BayesianNetworkBasedAlgorithm

2. Append entry in the <tt>Algorithms</tt> enum in Evoptool.h.

typedef enum {
...
DEUM // 5
} Algorithms;

In the xml configuration file, your algorithm will be characterized by the int value associated with the position in this enum declaration.

3. modify the file
core/src/XMLParser.cpp. Search for the method <tt>bool XMLParser::parseAlgorithms</tt> and insert an new entry for your algorithm in the <tt>algorithmParameters</tt> array, for example

AlgorithmParameters algorithmParameters[] = {
...
{ Evoptool::DEUM, 5, (char*) "IDDDI" }, // Pop, percElitism, percSelec, CoolRate, GibbsIterations
...
};

In each entry, the first field is the name of the entry in the <tt>Algorithms</tt> enum just modified in <tt>Evoptool.h</tt>, the second is the number of parameters to be parsed in the xml configuration file and the third is a string specifying their type: <tt>I</tt> for integer and <tt>D</tt> for double.

4. add a case in the switch that follows in <tt>bool XMLParser::parseAlgorithms</tt>, for instance:

case Evoptool::DEUM:
algos[i] = new extendedFCA(intVal[0], doubleVal[0], doubleVal[1], intVal[1], intVal[2], params->rng);
algos[i]->initAlgorithm(params->task);
break;

Note that your algorithm can employ the random number generator provided by the Evoptool core, <tt>params->rng</tt>.

5. Include your headers in core/src/Algorithms.h

6. Document how your algorithm is instantiated in the comments appearing in evoptool-file/exec-scripts/example.xml

Algorithm Id Types Parameters
=====================================================================================================
...
FCA 26 "IDDII" (Pop, PercSelection, LearningRate, MaxCompositionLenght, MaxMonomialOrder)
...

7. Add an instantiation example for your algorithm in evoptool-file/exec-scripts/example.xml

<algo id="26" instanceName="FCA">
<int>1000</int>
<double>0.5</double>
<double>1</double>
<int>64</int>
<int>2</int>
</algo>

==== Run an algorithm in a C++ program ====

The simplest way to do this is to create a new submodule in <code>core</code>, i.e., a new source directory within the source directory of a module
For instance, the steps to create a new submodule named <code>myexample</code> are

1. copy the example submodule <code>exampleRunAlgorithm</code> in a new folder named <code>myexample</code> in

evoptool/core/src

2. modify the <code>Makefile</code> in the <code>myexample</code> directory, see comments in the makefile for more details.

3. edit the <code>main</code> function in the source file, if you need you can create other C++ and .h files in the same folder.

4. from <code>evoptool/core/src/myexample</code> run

make bin

The bin file is create in <code>evoptool/core/bin</code> and copied in <code>evoptool/bin</code>

NOTICE that <code>evoptool/core/bin</code> may be deleted after a <code>make cleanall</code>

5. from <code>evoptool/bin</code> run

./myexample

==== Available Statistics ====

Evoptool: Evolutionary Optimization Tool

2011-10-24T13:24:48Z

LuigiMalago: /* Algorithms implemented */

== Description ==

Evolutionary Optimization Tool (Evoptool) is an open source optimization tool writte in C++, distributed under GNU General Public License. Evoptool implements meta-heuristics based on the Evolutionary Computation paradigm and aims to provide a common platform for the development and test of new algorithms, in order to facilitate the performance comparison activity. Evoptool offers a wide set of benchmark problems, from classical toy samples to more complex tasks, and a collection of algorithm implementations from Genetic Algorithms and Estimation of Distribution Algorithms paradigms. Evoptool is flexible, easy to extend, also with algorithms based on other approaches other from EAs.

== The Evoptool Team ==

*[[User:MatteoMatteucci| Matteo Matteucci]] - matteucci [AT] elet.polimi.it

*[http://www.dei.polimi.it/personale/dettaglio.php?id_persona=829&id_sezione=&lettera=M&idlang=ita| Luigi Malagò] - malago [AT] elet.polimi.it

*[[User:GabrieleValentini| Gabriele Valentini]] - gvalentini [AT] iridia.ulb.ac.be

*[[User:DavideCucci| Davide Cucci]] - cucci [AT] elet.polimi.it

'''Formerly involved'''
*Emanuele Corsano

== Mailing List ==
http://groups.google.com/group/evoptool

== Features ==

====Algorithms implemented====
* Genetic Algorithms
** SGA
*Estimation of Distribution Algorithms
**PBIL, UMDA, cGA, COMIT, BOA, FCA
* DEUM framework
**DEUMd, IsingDEUM, DEUM-Chain, DEUM-LDA, DEUM-CE, DEUM-X2, DEUM-JEMP, DEUM-l1, sDEUM
* Stochastic Gradient Descent
**SNGD, SNGD
* Other Meta-heuristics
**Simulated Annealing

References to original papers will be added soon.

====Benchmark functions implemented====
* OneMax
* AltBit
* Trap3
* Trap5
* IsingSpinGlass2D
* IsingSpinGlass3D
* Max Cut

== Download ==

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Developers may also access unstable branch. Contact the evoptool team for more details.

== Installation ==
Follow these steps in order to compile evoptool

1. Download source code from svn

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Refer to trunk for the lastest (stable?) version of evoptool

2. First you need to manually compile the <code>l1_logreg-0.8.2</code> package, http://www.stanford.edu/~boyd/l1_logreg/
whose source are already included in the evoptool repository. In order to do that follow the instrunctions in
<code>README.evoptool</code> in the <code>l1_logreg-0.8.2</code> directory

Next, compile <code><id_dist/code> following the instructions in <code>README.evoptool</code> in the <code><id_dist</code> folder

3. Then you need to compile a module at a time. Each module is included in a different folder.
To compile a module, from go to the module source folder and do make lib. For instance, for the module named <code>common</code>

cd common/src
make lib
cd ..

Compile modules in the following orderm due to dependencies

common
functions
ga
stochastic
eda

To clean a module, do

make clean

from the module source directory

4. Go to <code>core</code> module and type

make exe

Binary files will be copied in the <code>bin</code> directory in the root as well as the <code>bin</code> directory of the <code>core</code> module

'''Required packages'''
* Libraries
** ''gtkmm-2.4''
** ''glademm-2.4''
** ''gthread-2.0''
** ''sigc++-2.0''
** ''opencv'' (see for instance http://www.samontab.com/web/2011/06/installing-opencv-2-2-in-ubuntu-11-04/)
** ''gsl''
** ''gslcblas''
** ''libxml++-2.6''
** '''f2c''

* Software
** ''gnuplot''

== Running ==

Right now <code>evoptool</code> only runs as a script. GUI is not maintained in the latest version.
The <code>evoptool</code> binary file is supposed to be run in the <code>bin</code> directory in the root, this is because right now the script looks for some configuration files, for the instances of the problems, and temp directories. If you want to run the script from other directories, you just need to copy in that directory the <code>evoptool-file</code> directory that you find in the <code>bin</code> directory. Link such directory instead of copying it is not safe if you run multiple scripts at the same time, since output files will be shared.

To run the algorithm you need to enter as input an xml file. For instance you can run

./evoptool evoptool-file/examples/unitTestOneMax.xml

The <code>evoptool-file/example</code> directory contains a set of xml files for different benchmarks and different algorithms.
Take a loot at the <code>example.xml</code> file for the documentation on hoe to set the parameters for an each execution of <code>evoptool</code>

Each execution of <code>evoptool</code> produces a set of files as output. You can find all files in <code>evoptool-file/temp</code> directory. Plus a tar.gz file containing such files can be produced at the end of the execution of <code>evoptool</code>. See the xml file for details.

evoptool-file/temp/data
contains the raw data of the statistics according to the xml file

evoptool-file/temp/gnuplot
contains the gnuplot files to produce images of the statistics

evoptool-file/temp/image
contains images of the statistics produced according to the xml file

evoptool-file/temp/support
contains logs

== Documentation ==

==== Implement a new benchmark function====

Benchmarks are defined in the <code>function</code> module. A benchmark is the maximization problem of a real valued function defined over a vector of n binary variables. Functions are maximized in <code>evoptool</code>. In order to implement a new benchmark function you have to create a new <code>class</code> that inherits from <code>ObjectiveFunction</code> in the <code>common</code> module. Take a look at the <code>OneMax</code> benchmark function.

Among the arguments of the constructor of the <code>ObjectiveFunction</code> class there must be the size of the benchmark, which may or may not be a parameter of the new benchmark.

OneMax::OneMax(int size) : ObjectiveFunction(size)

In the constructor you have whether the maximum of the function is known or not

_knownSolution = true;

And in case this is known, set the minimum value and maximum value for the function

_minFitness = 0;
_maxFitness = size; //the maximum value of the OneMax function is defined as the sum of the bits of x set to one.

Besides, such values are used in the normalization of the functions in the plots of the statistics.

Each benchmark must implement the <code>f</code> method, which takes the <code>BinaryString</code> x and return f(x). For instance, for <code>OneMax</code> you have

double OneMax::f(BinaryString *bi) {
 if (bi != NULL) {
  if(!(bi->validCache())) {
   /* Fitness cache value not valid */
   int sum = 0;
   for (int j = 0; j < _size; j++) {
    sum = sum + bi->get(j);
   }
   bi->setFitnessCache(sum);
   return sum;
  } else {
   return bi->getFitnessCache();
  }
 } else {
  cerr << "[OneMax::f] binary instance cannot be null" << endl;
  return 0;
 }
}

In order to avoid multiple evaluations of the same <code>BinaryString</code> x, a caching mechanism has been implemented.

Moreover, you are asked to implement the <code>exportInteration</code> function, which return an <code>HyperGraph</code> which represents the interactions present in the function. In order to determine such hypergraph, start from the polinomial representation of the function, and for each monomial introduce a new hyperedge in the hypergraph.

For the <code>OneMax</code> function, such representation corresponds to the independence graph, since such function is linear.

HyperGraph* OneMax::exportInteractions() {
 HyperGraph *interactions = new HyperGraph();
 interactions->createIndependenceGraph(_size);
 return interactions;
}

In <code>Evoptool.h</code> add an entry in the <code>Tasks</code> enum.

/* This enumeration defines an identifier for each task function. */
typedef enum {
 ONE_MAX = 7,
} Tasks;

This value will identify uniquely the benchmark in the xml file. In the <code>XMLParser.cpp</code> file, add an entry for the new function.

bool XMLParser::parseTask(xmlpp::TextReader &reader, Evoptool::TestParameters *params) {
 ..
 switch (task) {
  case Evoptool::ONE_MAX: params->task = new OneMax(size);
  break;
  ..
  default: return false;
 }
 ..
}

Additional parameters can be obtained using the xml TextReader object, as for the <code>ForPeaks</code> function.

case Evoptool::FOUR_PEAKS:
 value = readNodeContent(reader, "peaks", &errorFlag);
 if (errorFlag) return false;
 int peaks = toInt(value);
 params->task = new FourPeaks(size, peaks);
 break;

Finally in the xml file, a function can set with the <code>task</code> tag, together with all parameters.

<task>
 <name>7</name>
 <size>64</size>
</task>

==== To create a new algorithm ====

1. Implement a new algorithm

All algorithms must inherit from the Algorithm class. First override the Algorithm::initAlgorithm as follows:

void DEUM::initAlgorithm(ObjectiveFunction* of) {
Algorithm::initAlgorithm(of);

/* Initialization tasks */
...
}

Then implement a run() method which performs al the required task for '''one''' iteration of your algorithm.

There are some classes which contain useful methods such as samplers and estimators from which your algorithm can inherit. The most useful are:

PopulationBasedAlgorithm
ModelBasedAlgorithm
ExponentialFamilyAlgorithm
BayesianNetworkBasedAlgorithm

2. Append entry in the <tt>Algorithms</tt> enum in Evoptool.h.

typedef enum {
...
DEUM // 5
} Algorithms;

In the xml configuration file, your algorithm will be characterized by the int value associated with the position in this enum declaration.

3. modify the file
core/src/XMLParser.cpp. Search for the method <tt>bool XMLParser::parseAlgorithms</tt> and insert an new entry for your algorithm in the <tt>algorithmParameters</tt> array, for example

AlgorithmParameters algorithmParameters[] = {
...
{ Evoptool::DEUM, 5, (char*) "IDDDI" }, // Pop, percElitism, percSelec, CoolRate, GibbsIterations
...
};

In each entry, the first field is the name of the entry in the <tt>Algorithms</tt> enum just modified in <tt>Evoptool.h</tt>, the second is the number of parameters to be parsed in the xml configuration file and the third is a string specifying their type: <tt>I</tt> for integer and <tt>D</tt> for double.

4. add a case in the switch that follows in <tt>bool XMLParser::parseAlgorithms</tt>, for instance:

case Evoptool::DEUM:
algos[i] = new extendedFCA(intVal[0], doubleVal[0], doubleVal[1], intVal[1], intVal[2], params->rng);
algos[i]->initAlgorithm(params->task);
break;

Note that your algorithm can employ the random number generator provided by the Evoptool core, <tt>params->rng</tt>.

5. Include your headers in core/src/Algorithms.h

6. Document how your algorithm is instantiated in the comments appearing in evoptool-file/exec-scripts/example.xml

Algorithm Id Types Parameters
=====================================================================================================
...
FCA 26 "IDDII" (Pop, PercSelection, LearningRate, MaxCompositionLenght, MaxMonomialOrder)
...

7. Add an instantiation example for your algorithm in evoptool-file/exec-scripts/example.xml

<algo id="26" instanceName="FCA">
<int>1000</int>
<double>0.5</double>
<double>1</double>
<int>64</int>
<int>2</int>
</algo>

==== Run an algorithm in a C++ program ====

The simplest way to do this is to create a new submodule in <code>core</code>, i.e., a new source directory within the source directory of a module
For instance, the steps to create a new submodule named <code>myexample</code> are

1. copy the example submodule <code>exampleRunAlgorithm</code> in a new folder named <code>myexample</code> in

evoptool/core/src

2. modify the <code>Makefile</code> in the <code>myexample</code> directory, see comments in the makefile for more details.

3. edit the <code>main</code> function in the source file, if you need you can create other C++ and .h files in the same folder.

4. from <code>evoptool/core/src/myexample</code> run

make bin

The bin file is create in <code>evoptool/core/bin</code> and copied in <code>evoptool/bin</code>

NOTICE that <code>evoptool/core/bin</code> may be deleted after a <code>make cleanall</code>

5. from <code>evoptool/bin</code> run

./myexample

==== Available Statistics ====

Evoptool: Evolutionary Optimization Tool

2011-10-24T13:23:38Z

LuigiMalago: /* Algorithms implemented */

== Description ==

Evolutionary Optimization Tool (Evoptool) is an open source optimization tool writte in C++, distributed under GNU General Public License. Evoptool implements meta-heuristics based on the Evolutionary Computation paradigm and aims to provide a common platform for the development and test of new algorithms, in order to facilitate the performance comparison activity. Evoptool offers a wide set of benchmark problems, from classical toy samples to more complex tasks, and a collection of algorithm implementations from Genetic Algorithms and Estimation of Distribution Algorithms paradigms. Evoptool is flexible, easy to extend, also with algorithms based on other approaches other from EAs.

== The Evoptool Team ==

*[[User:MatteoMatteucci| Matteo Matteucci]] - matteucci [AT] elet.polimi.it

*[http://www.dei.polimi.it/personale/dettaglio.php?id_persona=829&id_sezione=&lettera=M&idlang=ita| Luigi Malagò] - malago [AT] elet.polimi.it

*[[User:GabrieleValentini| Gabriele Valentini]] - gvalentini [AT] iridia.ulb.ac.be

*[[User:DavideCucci| Davide Cucci]] - cucci [AT] elet.polimi.it

'''Formerly involved'''
*Emanuele Corsano

== Mailing List ==
http://groups.google.com/group/evoptool

== Features ==

====Algorithms implemented====
* Genetic Algorithms
** SGA
*Estimation of Distribution Algorithms
**PBIL, UMDA, cGA, COMIT, BOA, FCA
* DEUM framework
**DEUMd, IsingDEUM, DEUM-Chain
* Stochastic Gradient Descent
**SNGD, SNGD
* Other Meta-heuristics
**Simulated Annealing

References to original papers will be added soon.

====Benchmark functions implemented====
* OneMax
* AltBit
* Trap3
* Trap5
* IsingSpinGlass2D
* IsingSpinGlass3D
* Max Cut

== Download ==

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Developers may also access unstable branch. Contact the evoptool team for more details.

== Installation ==
Follow these steps in order to compile evoptool

1. Download source code from svn

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Refer to trunk for the lastest (stable?) version of evoptool

2. First you need to manually compile the <code>l1_logreg-0.8.2</code> package, http://www.stanford.edu/~boyd/l1_logreg/
whose source are already included in the evoptool repository. In order to do that follow the instrunctions in
<code>README.evoptool</code> in the <code>l1_logreg-0.8.2</code> directory

Next, compile <code><id_dist/code> following the instructions in <code>README.evoptool</code> in the <code><id_dist</code> folder

3. Then you need to compile a module at a time. Each module is included in a different folder.
To compile a module, from go to the module source folder and do make lib. For instance, for the module named <code>common</code>

cd common/src
make lib
cd ..

Compile modules in the following orderm due to dependencies

common
functions
ga
stochastic
eda

To clean a module, do

make clean

from the module source directory

4. Go to <code>core</code> module and type

make exe

Binary files will be copied in the <code>bin</code> directory in the root as well as the <code>bin</code> directory of the <code>core</code> module

'''Required packages'''
* Libraries
** ''gtkmm-2.4''
** ''glademm-2.4''
** ''gthread-2.0''
** ''sigc++-2.0''
** ''opencv'' (see for instance http://www.samontab.com/web/2011/06/installing-opencv-2-2-in-ubuntu-11-04/)
** ''gsl''
** ''gslcblas''
** ''libxml++-2.6''
** '''f2c''

* Software
** ''gnuplot''

== Running ==

Right now <code>evoptool</code> only runs as a script. GUI is not maintained in the latest version.
The <code>evoptool</code> binary file is supposed to be run in the <code>bin</code> directory in the root, this is because right now the script looks for some configuration files, for the instances of the problems, and temp directories. If you want to run the script from other directories, you just need to copy in that directory the <code>evoptool-file</code> directory that you find in the <code>bin</code> directory. Link such directory instead of copying it is not safe if you run multiple scripts at the same time, since output files will be shared.

To run the algorithm you need to enter as input an xml file. For instance you can run

./evoptool evoptool-file/examples/unitTestOneMax.xml

The <code>evoptool-file/example</code> directory contains a set of xml files for different benchmarks and different algorithms.
Take a loot at the <code>example.xml</code> file for the documentation on hoe to set the parameters for an each execution of <code>evoptool</code>

Each execution of <code>evoptool</code> produces a set of files as output. You can find all files in <code>evoptool-file/temp</code> directory. Plus a tar.gz file containing such files can be produced at the end of the execution of <code>evoptool</code>. See the xml file for details.

evoptool-file/temp/data
contains the raw data of the statistics according to the xml file

evoptool-file/temp/gnuplot
contains the gnuplot files to produce images of the statistics

evoptool-file/temp/image
contains images of the statistics produced according to the xml file

evoptool-file/temp/support
contains logs

== Documentation ==

==== Implement a new benchmark function====

Benchmarks are defined in the <code>function</code> module. A benchmark is the maximization problem of a real valued function defined over a vector of n binary variables. Functions are maximized in <code>evoptool</code>. In order to implement a new benchmark function you have to create a new <code>class</code> that inherits from <code>ObjectiveFunction</code> in the <code>common</code> module. Take a look at the <code>OneMax</code> benchmark function.

Among the arguments of the constructor of the <code>ObjectiveFunction</code> class there must be the size of the benchmark, which may or may not be a parameter of the new benchmark.

OneMax::OneMax(int size) : ObjectiveFunction(size)

In the constructor you have whether the maximum of the function is known or not

_knownSolution = true;

And in case this is known, set the minimum value and maximum value for the function

_minFitness = 0;
_maxFitness = size; //the maximum value of the OneMax function is defined as the sum of the bits of x set to one.

Besides, such values are used in the normalization of the functions in the plots of the statistics.

Each benchmark must implement the <code>f</code> method, which takes the <code>BinaryString</code> x and return f(x). For instance, for <code>OneMax</code> you have

double OneMax::f(BinaryString *bi) {
 if (bi != NULL) {
  if(!(bi->validCache())) {
   /* Fitness cache value not valid */
   int sum = 0;
   for (int j = 0; j < _size; j++) {
    sum = sum + bi->get(j);
   }
   bi->setFitnessCache(sum);
   return sum;
  } else {
   return bi->getFitnessCache();
  }
 } else {
  cerr << "[OneMax::f] binary instance cannot be null" << endl;
  return 0;
 }
}

In order to avoid multiple evaluations of the same <code>BinaryString</code> x, a caching mechanism has been implemented.

Moreover, you are asked to implement the <code>exportInteration</code> function, which return an <code>HyperGraph</code> which represents the interactions present in the function. In order to determine such hypergraph, start from the polinomial representation of the function, and for each monomial introduce a new hyperedge in the hypergraph.

For the <code>OneMax</code> function, such representation corresponds to the independence graph, since such function is linear.

HyperGraph* OneMax::exportInteractions() {
 HyperGraph *interactions = new HyperGraph();
 interactions->createIndependenceGraph(_size);
 return interactions;
}

In <code>Evoptool.h</code> add an entry in the <code>Tasks</code> enum.

/* This enumeration defines an identifier for each task function. */
typedef enum {
 ONE_MAX = 7,
} Tasks;

This value will identify uniquely the benchmark in the xml file. In the <code>XMLParser.cpp</code> file, add an entry for the new function.

bool XMLParser::parseTask(xmlpp::TextReader &reader, Evoptool::TestParameters *params) {
 ..
 switch (task) {
  case Evoptool::ONE_MAX: params->task = new OneMax(size);
  break;
  ..
  default: return false;
 }
 ..
}

Additional parameters can be obtained using the xml TextReader object, as for the <code>ForPeaks</code> function.

case Evoptool::FOUR_PEAKS:
 value = readNodeContent(reader, "peaks", &errorFlag);
 if (errorFlag) return false;
 int peaks = toInt(value);
 params->task = new FourPeaks(size, peaks);
 break;

Finally in the xml file, a function can set with the <code>task</code> tag, together with all parameters.

<task>
 <name>7</name>
 <size>64</size>
</task>

==== To create a new algorithm ====

1. Implement a new algorithm

All algorithms must inherit from the Algorithm class. First override the Algorithm::initAlgorithm as follows:

void DEUM::initAlgorithm(ObjectiveFunction* of) {
Algorithm::initAlgorithm(of);

/* Initialization tasks */
...
}

Then implement a run() method which performs al the required task for '''one''' iteration of your algorithm.

There are some classes which contain useful methods such as samplers and estimators from which your algorithm can inherit. The most useful are:

PopulationBasedAlgorithm
ModelBasedAlgorithm
ExponentialFamilyAlgorithm
BayesianNetworkBasedAlgorithm

2. Append entry in the <tt>Algorithms</tt> enum in Evoptool.h.

typedef enum {
...
DEUM // 5
} Algorithms;

In the xml configuration file, your algorithm will be characterized by the int value associated with the position in this enum declaration.

3. modify the file
core/src/XMLParser.cpp. Search for the method <tt>bool XMLParser::parseAlgorithms</tt> and insert an new entry for your algorithm in the <tt>algorithmParameters</tt> array, for example

AlgorithmParameters algorithmParameters[] = {
...
{ Evoptool::DEUM, 5, (char*) "IDDDI" }, // Pop, percElitism, percSelec, CoolRate, GibbsIterations
...
};

In each entry, the first field is the name of the entry in the <tt>Algorithms</tt> enum just modified in <tt>Evoptool.h</tt>, the second is the number of parameters to be parsed in the xml configuration file and the third is a string specifying their type: <tt>I</tt> for integer and <tt>D</tt> for double.

4. add a case in the switch that follows in <tt>bool XMLParser::parseAlgorithms</tt>, for instance:

case Evoptool::DEUM:
algos[i] = new extendedFCA(intVal[0], doubleVal[0], doubleVal[1], intVal[1], intVal[2], params->rng);
algos[i]->initAlgorithm(params->task);
break;

Note that your algorithm can employ the random number generator provided by the Evoptool core, <tt>params->rng</tt>.

5. Include your headers in core/src/Algorithms.h

6. Document how your algorithm is instantiated in the comments appearing in evoptool-file/exec-scripts/example.xml

Algorithm Id Types Parameters
=====================================================================================================
...
FCA 26 "IDDII" (Pop, PercSelection, LearningRate, MaxCompositionLenght, MaxMonomialOrder)
...

7. Add an instantiation example for your algorithm in evoptool-file/exec-scripts/example.xml

<algo id="26" instanceName="FCA">
<int>1000</int>
<double>0.5</double>
<double>1</double>
<int>64</int>
<int>2</int>
</algo>

==== Run an algorithm in a C++ program ====

The simplest way to do this is to create a new submodule in <code>core</code>, i.e., a new source directory within the source directory of a module
For instance, the steps to create a new submodule named <code>myexample</code> are

1. copy the example submodule <code>exampleRunAlgorithm</code> in a new folder named <code>myexample</code> in

evoptool/core/src

2. modify the <code>Makefile</code> in the <code>myexample</code> directory, see comments in the makefile for more details.

3. edit the <code>main</code> function in the source file, if you need you can create other C++ and .h files in the same folder.

4. from <code>evoptool/core/src/myexample</code> run

make bin

The bin file is create in <code>evoptool/core/bin</code> and copied in <code>evoptool/bin</code>

NOTICE that <code>evoptool/core/bin</code> may be deleted after a <code>make cleanall</code>

5. from <code>evoptool/bin</code> run

./myexample

==== Available Statistics ====

Evoptool: Evolutionary Optimization Tool

2011-10-24T13:18:22Z

LuigiMalago: /* Algorithms implemented */

== Description ==

Evolutionary Optimization Tool (Evoptool) is an open source optimization tool writte in C++, distributed under GNU General Public License. Evoptool implements meta-heuristics based on the Evolutionary Computation paradigm and aims to provide a common platform for the development and test of new algorithms, in order to facilitate the performance comparison activity. Evoptool offers a wide set of benchmark problems, from classical toy samples to more complex tasks, and a collection of algorithm implementations from Genetic Algorithms and Estimation of Distribution Algorithms paradigms. Evoptool is flexible, easy to extend, also with algorithms based on other approaches other from EAs.

== The Evoptool Team ==

*[[User:MatteoMatteucci| Matteo Matteucci]] - matteucci [AT] elet.polimi.it

*[http://www.dei.polimi.it/personale/dettaglio.php?id_persona=829&id_sezione=&lettera=M&idlang=ita| Luigi Malagò] - malago [AT] elet.polimi.it

*[[User:GabrieleValentini| Gabriele Valentini]] - gvalentini [AT] iridia.ulb.ac.be

*[[User:DavideCucci| Davide Cucci]] - cucci [AT] elet.polimi.it

'''Formerly involved'''
*Emanuele Corsano

== Mailing List ==
http://groups.google.com/group/evoptool

== Features ==

====Algorithms implemented====
* DEUM

== Download ==

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Developers may also access unstable branch. Contact the evoptool team for more details.

== Installation ==
Follow these steps in order to compile evoptool

1. Download source code from svn

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Refer to trunk for the lastest (stable?) version of evoptool

2. First you need to manually compile the <code>l1_logreg-0.8.2</code> package, http://www.stanford.edu/~boyd/l1_logreg/
whose source are already included in the evoptool repository. In order to do that follow the instrunctions in
<code>README.evoptool</code> in the <code>l1_logreg-0.8.2</code> directory

Next, compile <code><id_dist/code> following the instructions in <code>README.evoptool</code> in the <code><id_dist</code> folder

3. Then you need to compile a module at a time. Each module is included in a different folder.
To compile a module, from go to the module source folder and do make lib. For instance, for the module named <code>common</code>

cd common/src
make lib
cd ..

Compile modules in the following orderm due to dependencies

common
functions
ga
stochastic
eda

To clean a module, do

make clean

from the module source directory

4. Go to <code>core</code> module and type

make exe

Binary files will be copied in the <code>bin</code> directory in the root as well as the <code>bin</code> directory of the <code>core</code> module

'''Required packages'''
* Libraries
** ''gtkmm-2.4''
** ''glademm-2.4''
** ''gthread-2.0''
** ''sigc++-2.0''
** ''opencv'' (see for instance http://www.samontab.com/web/2011/06/installing-opencv-2-2-in-ubuntu-11-04/)
** ''gsl''
** ''gslcblas''
** ''libxml++-2.6''
** '''f2c''

* Software
** ''gnuplot''

== Running ==

Right now <code>evoptool</code> only runs as a script. GUI is not maintained in the latest version.
The <code>evoptool</code> binary file is supposed to be run in the <code>bin</code> directory in the root, this is because right now the script looks for some configuration files, for the instances of the problems, and temp directories. If you want to run the script from other directories, you just need to copy in that directory the <code>evoptool-file</code> directory that you find in the <code>bin</code> directory. Link such directory instead of copying it is not safe if you run multiple scripts at the same time, since output files will be shared.

To run the algorithm you need to enter as input an xml file. For instance you can run

./evoptool evoptool-file/examples/unitTestOneMax.xml

The <code>evoptool-file/example</code> directory contains a set of xml files for different benchmarks and different algorithms.
Take a loot at the <code>example.xml</code> file for the documentation on hoe to set the parameters for an each execution of <code>evoptool</code>

Each execution of <code>evoptool</code> produces a set of files as output. You can find all files in <code>evoptool-file/temp</code> directory. Plus a tar.gz file containing such files can be produced at the end of the execution of <code>evoptool</code>. See the xml file for details.

evoptool-file/temp/data
contains the raw data of the statistics according to the xml file

evoptool-file/temp/gnuplot
contains the gnuplot files to produce images of the statistics

evoptool-file/temp/image
contains images of the statistics produced according to the xml file

evoptool-file/temp/support
contains logs

== Documentation ==

==== Implement a new benchmark function====

Benchmarks are defined in the <code>function</code> module. A benchmark is the maximization problem of a real valued function defined over a vector of n binary variables. Functions are maximized in <code>evoptool</code>. In order to implement a new benchmark function you have to create a new <code>class</code> that inherits from <code>ObjectiveFunction</code> in the <code>common</code> module. Take a look at the <code>OneMax</code> benchmark function.

Among the arguments of the constructor of the <code>ObjectiveFunction</code> class there must be the size of the benchmark, which may or may not be a parameter of the new benchmark.

OneMax::OneMax(int size) : ObjectiveFunction(size)

In the constructor you have whether the maximum of the function is known or not

_knownSolution = true;

And in case this is known, set the minimum value and maximum value for the function

_minFitness = 0;
_maxFitness = size; //the maximum value of the OneMax function is defined as the sum of the bits of x set to one.

Besides, such values are used in the normalization of the functions in the plots of the statistics.

Each benchmark must implement the <code>f</code> method, which takes the <code>BinaryString</code> x and return f(x). For instance, for <code>OneMax</code> you have

double OneMax::f(BinaryString *bi) {
 if (bi != NULL) {
  if(!(bi->validCache())) {
   /* Fitness cache value not valid */
   int sum = 0;
   for (int j = 0; j < _size; j++) {
    sum = sum + bi->get(j);
   }
   bi->setFitnessCache(sum);
   return sum;
  } else {
   return bi->getFitnessCache();
  }
 } else {
  cerr << "[OneMax::f] binary instance cannot be null" << endl;
  return 0;
 }
}

In order to avoid multiple evaluations of the same <code>BinaryString</code> x, a caching mechanism has been implemented.

Moreover, you are asked to implement the <code>exportInteration</code> function, which return an <code>HyperGraph</code> which represents the interactions present in the function. In order to determine such hypergraph, start from the polinomial representation of the function, and for each monomial introduce a new hyperedge in the hypergraph.

For the <code>OneMax</code> function, such representation corresponds to the independence graph, since such function is linear.

HyperGraph* OneMax::exportInteractions() {
 HyperGraph *interactions = new HyperGraph();
 interactions->createIndependenceGraph(_size);
 return interactions;
}

In <code>Evoptool.h</code> add an entry in the <code>Tasks</code> enum.

/* This enumeration defines an identifier for each task function. */
typedef enum {
 ONE_MAX = 7,
} Tasks;

This value will identify uniquely the benchmark in the xml file. In the <code>XMLParser.cpp</code> file, add an entry for the new function.

bool XMLParser::parseTask(xmlpp::TextReader &reader, Evoptool::TestParameters *params) {
 ..
 switch (task) {
  case Evoptool::ONE_MAX: params->task = new OneMax(size);
  break;
  ..
  default: return false;
 }
 ..
}

Additional parameters can be obtained using the xml TextReader object, as for the <code>ForPeaks</code> function.

case Evoptool::FOUR_PEAKS:
 value = readNodeContent(reader, "peaks", &errorFlag);
 if (errorFlag) return false;
 int peaks = toInt(value);
 params->task = new FourPeaks(size, peaks);
 break;

Finally in the xml file, a function can set with the <code>task</code> tag, together with all parameters.

<task>
 <name>7</name>
 <size>64</size>
</task>

==== To create a new algorithm ====

1. Implement a new algorithm

All algorithms must inherit from the Algorithm class. First override the Algorithm::initAlgorithm as follows:

void DEUM::initAlgorithm(ObjectiveFunction* of) {
Algorithm::initAlgorithm(of);

/* Initialization tasks */
...
}

Then implement a run() method which performs al the required task for '''one''' iteration of your algorithm.

There are some classes which contain useful methods such as samplers and estimators from which your algorithm can inherit. The most useful are:

PopulationBasedAlgorithm
ModelBasedAlgorithm
ExponentialFamilyAlgorithm
BayesianNetworkBasedAlgorithm

2. Append entry in the <tt>Algorithms</tt> enum in Evoptool.h.

typedef enum {
...
DEUM // 5
} Algorithms;

In the xml configuration file, your algorithm will be characterized by the int value associated with the position in this enum declaration.

3. modify the file
core/src/XMLParser.cpp. Search for the method <tt>bool XMLParser::parseAlgorithms</tt> and insert an new entry for your algorithm in the <tt>algorithmParameters</tt> array, for example

AlgorithmParameters algorithmParameters[] = {
...
{ Evoptool::DEUM, 5, (char*) "IDDDI" }, // Pop, percElitism, percSelec, CoolRate, GibbsIterations
...
};

In each entry, the first field is the name of the entry in the <tt>Algorithms</tt> enum just modified in <tt>Evoptool.h</tt>, the second is the number of parameters to be parsed in the xml configuration file and the third is a string specifying their type: <tt>I</tt> for integer and <tt>D</tt> for double.

4. add a case in the switch that follows in <tt>bool XMLParser::parseAlgorithms</tt>, for instance:

case Evoptool::DEUM:
algos[i] = new extendedFCA(intVal[0], doubleVal[0], doubleVal[1], intVal[1], intVal[2], params->rng);
algos[i]->initAlgorithm(params->task);
break;

Note that your algorithm can employ the random number generator provided by the Evoptool core, <tt>params->rng</tt>.

5. Include your headers in core/src/Algorithms.h

6. Document how your algorithm is instantiated in the comments appearing in evoptool-file/exec-scripts/example.xml

Algorithm Id Types Parameters
=====================================================================================================
...
FCA 26 "IDDII" (Pop, PercSelection, LearningRate, MaxCompositionLenght, MaxMonomialOrder)
...

7. Add an instantiation example for your algorithm in evoptool-file/exec-scripts/example.xml

<algo id="26" instanceName="FCA">
<int>1000</int>
<double>0.5</double>
<double>1</double>
<int>64</int>
<int>2</int>
</algo>

==== Run an algorithm in a C++ program ====

The simplest way to do this is to create a new submodule in <code>core</code>, i.e., a new source directory within the source directory of a module
For instance, the steps to create a new submodule named <code>myexample</code> are

1. copy the example submodule <code>exampleRunAlgorithm</code> in a new folder named <code>myexample</code> in

evoptool/core/src

2. modify the <code>Makefile</code> in the <code>myexample</code> directory, see comments in the makefile for more details.

3. edit the <code>main</code> function in the source file, if you need you can create other C++ and .h files in the same folder.

4. from <code>evoptool/core/src/myexample</code> run

make bin

The bin file is create in <code>evoptool/core/bin</code> and copied in <code>evoptool/bin</code>

NOTICE that <code>evoptool/core/bin</code> may be deleted after a <code>make cleanall</code>

5. from <code>evoptool/bin</code> run

./myexample

==== Available Statistics ====

Evoptool: Evolutionary Optimization Tool

2011-10-24T13:17:40Z

LuigiMalago: /* Installation */

== Description ==

Evolutionary Optimization Tool (Evoptool) is an open source optimization tool writte in C++, distributed under GNU General Public License. Evoptool implements meta-heuristics based on the Evolutionary Computation paradigm and aims to provide a common platform for the development and test of new algorithms, in order to facilitate the performance comparison activity. Evoptool offers a wide set of benchmark problems, from classical toy samples to more complex tasks, and a collection of algorithm implementations from Genetic Algorithms and Estimation of Distribution Algorithms paradigms. Evoptool is flexible, easy to extend, also with algorithms based on other approaches other from EAs.

== The Evoptool Team ==

*[[User:MatteoMatteucci| Matteo Matteucci]] - matteucci [AT] elet.polimi.it

*[http://www.dei.polimi.it/personale/dettaglio.php?id_persona=829&id_sezione=&lettera=M&idlang=ita| Luigi Malagò] - malago [AT] elet.polimi.it

*[[User:GabrieleValentini| Gabriele Valentini]] - gvalentini [AT] iridia.ulb.ac.be

*[[User:DavideCucci| Davide Cucci]] - cucci [AT] elet.polimi.it

'''Formerly involved'''
*Emanuele Corsano

== Mailing List ==
http://groups.google.com/group/evoptool

== Features ==

====Algorithms implemented====
''DEUM''

== Download ==

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Developers may also access unstable branch. Contact the evoptool team for more details.

== Installation ==
Follow these steps in order to compile evoptool

1. Download source code from svn

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Refer to trunk for the lastest (stable?) version of evoptool

2. First you need to manually compile the <code>l1_logreg-0.8.2</code> package, http://www.stanford.edu/~boyd/l1_logreg/
whose source are already included in the evoptool repository. In order to do that follow the instrunctions in
<code>README.evoptool</code> in the <code>l1_logreg-0.8.2</code> directory

Next, compile <code><id_dist/code> following the instructions in <code>README.evoptool</code> in the <code><id_dist</code> folder

3. Then you need to compile a module at a time. Each module is included in a different folder.
To compile a module, from go to the module source folder and do make lib. For instance, for the module named <code>common</code>

cd common/src
make lib
cd ..

Compile modules in the following orderm due to dependencies

common
functions
ga
stochastic
eda

To clean a module, do

make clean

from the module source directory

4. Go to <code>core</code> module and type

make exe

Binary files will be copied in the <code>bin</code> directory in the root as well as the <code>bin</code> directory of the <code>core</code> module

'''Required packages'''
* Libraries
** ''gtkmm-2.4''
** ''glademm-2.4''
** ''gthread-2.0''
** ''sigc++-2.0''
** ''opencv'' (see for instance http://www.samontab.com/web/2011/06/installing-opencv-2-2-in-ubuntu-11-04/)
** ''gsl''
** ''gslcblas''
** ''libxml++-2.6''
** '''f2c''

* Software
** ''gnuplot''

== Running ==

Right now <code>evoptool</code> only runs as a script. GUI is not maintained in the latest version.
The <code>evoptool</code> binary file is supposed to be run in the <code>bin</code> directory in the root, this is because right now the script looks for some configuration files, for the instances of the problems, and temp directories. If you want to run the script from other directories, you just need to copy in that directory the <code>evoptool-file</code> directory that you find in the <code>bin</code> directory. Link such directory instead of copying it is not safe if you run multiple scripts at the same time, since output files will be shared.

To run the algorithm you need to enter as input an xml file. For instance you can run

./evoptool evoptool-file/examples/unitTestOneMax.xml

The <code>evoptool-file/example</code> directory contains a set of xml files for different benchmarks and different algorithms.
Take a loot at the <code>example.xml</code> file for the documentation on hoe to set the parameters for an each execution of <code>evoptool</code>

Each execution of <code>evoptool</code> produces a set of files as output. You can find all files in <code>evoptool-file/temp</code> directory. Plus a tar.gz file containing such files can be produced at the end of the execution of <code>evoptool</code>. See the xml file for details.

evoptool-file/temp/data
contains the raw data of the statistics according to the xml file

evoptool-file/temp/gnuplot
contains the gnuplot files to produce images of the statistics

evoptool-file/temp/image
contains images of the statistics produced according to the xml file

evoptool-file/temp/support
contains logs

== Documentation ==

==== Implement a new benchmark function====

Benchmarks are defined in the <code>function</code> module. A benchmark is the maximization problem of a real valued function defined over a vector of n binary variables. Functions are maximized in <code>evoptool</code>. In order to implement a new benchmark function you have to create a new <code>class</code> that inherits from <code>ObjectiveFunction</code> in the <code>common</code> module. Take a look at the <code>OneMax</code> benchmark function.

Among the arguments of the constructor of the <code>ObjectiveFunction</code> class there must be the size of the benchmark, which may or may not be a parameter of the new benchmark.

OneMax::OneMax(int size) : ObjectiveFunction(size)

In the constructor you have whether the maximum of the function is known or not

_knownSolution = true;

And in case this is known, set the minimum value and maximum value for the function

_minFitness = 0;
_maxFitness = size; //the maximum value of the OneMax function is defined as the sum of the bits of x set to one.

Besides, such values are used in the normalization of the functions in the plots of the statistics.

Each benchmark must implement the <code>f</code> method, which takes the <code>BinaryString</code> x and return f(x). For instance, for <code>OneMax</code> you have

double OneMax::f(BinaryString *bi) {
 if (bi != NULL) {
  if(!(bi->validCache())) {
   /* Fitness cache value not valid */
   int sum = 0;
   for (int j = 0; j < _size; j++) {
    sum = sum + bi->get(j);
   }
   bi->setFitnessCache(sum);
   return sum;
  } else {
   return bi->getFitnessCache();
  }
 } else {
  cerr << "[OneMax::f] binary instance cannot be null" << endl;
  return 0;
 }
}

In order to avoid multiple evaluations of the same <code>BinaryString</code> x, a caching mechanism has been implemented.

Moreover, you are asked to implement the <code>exportInteration</code> function, which return an <code>HyperGraph</code> which represents the interactions present in the function. In order to determine such hypergraph, start from the polinomial representation of the function, and for each monomial introduce a new hyperedge in the hypergraph.

For the <code>OneMax</code> function, such representation corresponds to the independence graph, since such function is linear.

HyperGraph* OneMax::exportInteractions() {
 HyperGraph *interactions = new HyperGraph();
 interactions->createIndependenceGraph(_size);
 return interactions;
}

In <code>Evoptool.h</code> add an entry in the <code>Tasks</code> enum.

/* This enumeration defines an identifier for each task function. */
typedef enum {
 ONE_MAX = 7,
} Tasks;

This value will identify uniquely the benchmark in the xml file. In the <code>XMLParser.cpp</code> file, add an entry for the new function.

bool XMLParser::parseTask(xmlpp::TextReader &reader, Evoptool::TestParameters *params) {
 ..
 switch (task) {
  case Evoptool::ONE_MAX: params->task = new OneMax(size);
  break;
  ..
  default: return false;
 }
 ..
}

Additional parameters can be obtained using the xml TextReader object, as for the <code>ForPeaks</code> function.

case Evoptool::FOUR_PEAKS:
 value = readNodeContent(reader, "peaks", &errorFlag);
 if (errorFlag) return false;
 int peaks = toInt(value);
 params->task = new FourPeaks(size, peaks);
 break;

Finally in the xml file, a function can set with the <code>task</code> tag, together with all parameters.

<task>
 <name>7</name>
 <size>64</size>
</task>

==== To create a new algorithm ====

1. Implement a new algorithm

All algorithms must inherit from the Algorithm class. First override the Algorithm::initAlgorithm as follows:

void DEUM::initAlgorithm(ObjectiveFunction* of) {
Algorithm::initAlgorithm(of);

/* Initialization tasks */
...
}

Then implement a run() method which performs al the required task for '''one''' iteration of your algorithm.

There are some classes which contain useful methods such as samplers and estimators from which your algorithm can inherit. The most useful are:

PopulationBasedAlgorithm
ModelBasedAlgorithm
ExponentialFamilyAlgorithm
BayesianNetworkBasedAlgorithm

2. Append entry in the <tt>Algorithms</tt> enum in Evoptool.h.

typedef enum {
...
DEUM // 5
} Algorithms;

In the xml configuration file, your algorithm will be characterized by the int value associated with the position in this enum declaration.

3. modify the file
core/src/XMLParser.cpp. Search for the method <tt>bool XMLParser::parseAlgorithms</tt> and insert an new entry for your algorithm in the <tt>algorithmParameters</tt> array, for example

AlgorithmParameters algorithmParameters[] = {
...
{ Evoptool::DEUM, 5, (char*) "IDDDI" }, // Pop, percElitism, percSelec, CoolRate, GibbsIterations
...
};

In each entry, the first field is the name of the entry in the <tt>Algorithms</tt> enum just modified in <tt>Evoptool.h</tt>, the second is the number of parameters to be parsed in the xml configuration file and the third is a string specifying their type: <tt>I</tt> for integer and <tt>D</tt> for double.

4. add a case in the switch that follows in <tt>bool XMLParser::parseAlgorithms</tt>, for instance:

case Evoptool::DEUM:
algos[i] = new extendedFCA(intVal[0], doubleVal[0], doubleVal[1], intVal[1], intVal[2], params->rng);
algos[i]->initAlgorithm(params->task);
break;

Note that your algorithm can employ the random number generator provided by the Evoptool core, <tt>params->rng</tt>.

5. Include your headers in core/src/Algorithms.h

6. Document how your algorithm is instantiated in the comments appearing in evoptool-file/exec-scripts/example.xml

Algorithm Id Types Parameters
=====================================================================================================
...
FCA 26 "IDDII" (Pop, PercSelection, LearningRate, MaxCompositionLenght, MaxMonomialOrder)
...

7. Add an instantiation example for your algorithm in evoptool-file/exec-scripts/example.xml

<algo id="26" instanceName="FCA">
<int>1000</int>
<double>0.5</double>
<double>1</double>
<int>64</int>
<int>2</int>
</algo>

==== Run an algorithm in a C++ program ====

The simplest way to do this is to create a new submodule in <code>core</code>, i.e., a new source directory within the source directory of a module
For instance, the steps to create a new submodule named <code>myexample</code> are

1. copy the example submodule <code>exampleRunAlgorithm</code> in a new folder named <code>myexample</code> in

evoptool/core/src

2. modify the <code>Makefile</code> in the <code>myexample</code> directory, see comments in the makefile for more details.

3. edit the <code>main</code> function in the source file, if you need you can create other C++ and .h files in the same folder.

4. from <code>evoptool/core/src/myexample</code> run

make bin

The bin file is create in <code>evoptool/core/bin</code> and copied in <code>evoptool/bin</code>

NOTICE that <code>evoptool/core/bin</code> may be deleted after a <code>make cleanall</code>

5. from <code>evoptool/bin</code> run

./myexample

==== Available Statistics ====

Evoptool: Evolutionary Optimization Tool

2011-10-24T13:16:43Z

LuigiMalago: /* Mailing List */

== Description ==

Evolutionary Optimization Tool (Evoptool) is an open source optimization tool writte in C++, distributed under GNU General Public License. Evoptool implements meta-heuristics based on the Evolutionary Computation paradigm and aims to provide a common platform for the development and test of new algorithms, in order to facilitate the performance comparison activity. Evoptool offers a wide set of benchmark problems, from classical toy samples to more complex tasks, and a collection of algorithm implementations from Genetic Algorithms and Estimation of Distribution Algorithms paradigms. Evoptool is flexible, easy to extend, also with algorithms based on other approaches other from EAs.

== The Evoptool Team ==

*[[User:MatteoMatteucci| Matteo Matteucci]] - matteucci [AT] elet.polimi.it

*[http://www.dei.polimi.it/personale/dettaglio.php?id_persona=829&id_sezione=&lettera=M&idlang=ita| Luigi Malagò] - malago [AT] elet.polimi.it

*[[User:GabrieleValentini| Gabriele Valentini]] - gvalentini [AT] iridia.ulb.ac.be

*[[User:DavideCucci| Davide Cucci]] - cucci [AT] elet.polimi.it

'''Formerly involved'''
*Emanuele Corsano

== Mailing List ==
http://groups.google.com/group/evoptool

== Features ==

====Algorithms implemented====
''DEUM''

== Download ==

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Developers may also access unstable branch. Contact the evoptool team for more details.

== Installation ==
Follow these steps in order to compile evoptool

1. Download source code from svn

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Refer to trunk for the lastest (stable?) version of evoptool

2. First you need to manually compile the <code>l1_logreg-0.8.2</code> package, http://www.stanford.edu/~boyd/l1_logreg/
whose source are already included in the evoptool repository. In order to do that follow the instrunctions in
<code>README.evoptool</code> in the <code>l1_logreg-0.8.2</code> directory

Next, compile <code><id_dist/code> following the instructions in <code>README.evoptool<code> in the <code><id_dist</code> folder

3. Then you need to compile a module at a time. Each module is included in a different folder.
To compile a module, from go to the module source folder and do make lib. For instance, for the module named <code>common</code>

cd common/src
make lib
cd ..

Compile modules in the following orderm due to dependencies

common
functions
ga
stochastic
eda

To clean a module, do

make clean

from the module source directory

4. Go to <code>core</code> module and type

make exe

Binary files will be copied in the <code>bin</code> directory in the root as well as the <code>bin</code> directory of the <code>core</code> module

'''Required packages'''
* Libraries

** ''gtkmm-2.4''
** ''glademm-2.4''
** ''gthread-2.0''
** ''sigc++-2.0''
** ''opencv'' (see for instance http://www.samontab.com/web/2011/06/installing-opencv-2-2-in-ubuntu-11-04/)
** ''gsl''
** ''gslcblas''
** ''libxml++-2.6''
** '''f2c''

* Software
** ''gnuplot''

== Running ==

Right now <code>evoptool</code> only runs as a script. GUI is not maintained in the latest version.
The <code>evoptool</code> binary file is supposed to be run in the <code>bin</code> directory in the root, this is because right now the script looks for some configuration files, for the instances of the problems, and temp directories. If you want to run the script from other directories, you just need to copy in that directory the <code>evoptool-file</code> directory that you find in the <code>bin</code> directory. Link such directory instead of copying it is not safe if you run multiple scripts at the same time, since output files will be shared.

To run the algorithm you need to enter as input an xml file. For instance you can run

./evoptool evoptool-file/examples/unitTestOneMax.xml

The <code>evoptool-file/example</code> directory contains a set of xml files for different benchmarks and different algorithms.
Take a loot at the <code>example.xml</code> file for the documentation on hoe to set the parameters for an each execution of <code>evoptool</code>

Each execution of <code>evoptool</code> produces a set of files as output. You can find all files in <code>evoptool-file/temp</code> directory. Plus a tar.gz file containing such files can be produced at the end of the execution of <code>evoptool</code>. See the xml file for details.

evoptool-file/temp/data
contains the raw data of the statistics according to the xml file

evoptool-file/temp/gnuplot
contains the gnuplot files to produce images of the statistics

evoptool-file/temp/image
contains images of the statistics produced according to the xml file

evoptool-file/temp/support
contains logs

== Documentation ==

==== Implement a new benchmark function====

Benchmarks are defined in the <code>function</code> module. A benchmark is the maximization problem of a real valued function defined over a vector of n binary variables. Functions are maximized in <code>evoptool</code>. In order to implement a new benchmark function you have to create a new <code>class</code> that inherits from <code>ObjectiveFunction</code> in the <code>common</code> module. Take a look at the <code>OneMax</code> benchmark function.

Among the arguments of the constructor of the <code>ObjectiveFunction</code> class there must be the size of the benchmark, which may or may not be a parameter of the new benchmark.

OneMax::OneMax(int size) : ObjectiveFunction(size)

In the constructor you have whether the maximum of the function is known or not

_knownSolution = true;

And in case this is known, set the minimum value and maximum value for the function

_minFitness = 0;
_maxFitness = size; //the maximum value of the OneMax function is defined as the sum of the bits of x set to one.

Besides, such values are used in the normalization of the functions in the plots of the statistics.

Each benchmark must implement the <code>f</code> method, which takes the <code>BinaryString</code> x and return f(x). For instance, for <code>OneMax</code> you have

double OneMax::f(BinaryString *bi) {
 if (bi != NULL) {
  if(!(bi->validCache())) {
   /* Fitness cache value not valid */
   int sum = 0;
   for (int j = 0; j < _size; j++) {
    sum = sum + bi->get(j);
   }
   bi->setFitnessCache(sum);
   return sum;
  } else {
   return bi->getFitnessCache();
  }
 } else {
  cerr << "[OneMax::f] binary instance cannot be null" << endl;
  return 0;
 }
}

In order to avoid multiple evaluations of the same <code>BinaryString</code> x, a caching mechanism has been implemented.

Moreover, you are asked to implement the <code>exportInteration</code> function, which return an <code>HyperGraph</code> which represents the interactions present in the function. In order to determine such hypergraph, start from the polinomial representation of the function, and for each monomial introduce a new hyperedge in the hypergraph.

For the <code>OneMax</code> function, such representation corresponds to the independence graph, since such function is linear.

HyperGraph* OneMax::exportInteractions() {
 HyperGraph *interactions = new HyperGraph();
 interactions->createIndependenceGraph(_size);
 return interactions;
}

In <code>Evoptool.h</code> add an entry in the <code>Tasks</code> enum.

/* This enumeration defines an identifier for each task function. */
typedef enum {
 ONE_MAX = 7,
} Tasks;

This value will identify uniquely the benchmark in the xml file. In the <code>XMLParser.cpp</code> file, add an entry for the new function.

bool XMLParser::parseTask(xmlpp::TextReader &reader, Evoptool::TestParameters *params) {
 ..
 switch (task) {
  case Evoptool::ONE_MAX: params->task = new OneMax(size);
  break;
  ..
  default: return false;
 }
 ..
}

Additional parameters can be obtained using the xml TextReader object, as for the <code>ForPeaks</code> function.

case Evoptool::FOUR_PEAKS:
 value = readNodeContent(reader, "peaks", &errorFlag);
 if (errorFlag) return false;
 int peaks = toInt(value);
 params->task = new FourPeaks(size, peaks);
 break;

Finally in the xml file, a function can set with the <code>task</code> tag, together with all parameters.

<task>
 <name>7</name>
 <size>64</size>
</task>

==== To create a new algorithm ====

1. Implement a new algorithm

All algorithms must inherit from the Algorithm class. First override the Algorithm::initAlgorithm as follows:

void DEUM::initAlgorithm(ObjectiveFunction* of) {
Algorithm::initAlgorithm(of);

/* Initialization tasks */
...
}

Then implement a run() method which performs al the required task for '''one''' iteration of your algorithm.

There are some classes which contain useful methods such as samplers and estimators from which your algorithm can inherit. The most useful are:

PopulationBasedAlgorithm
ModelBasedAlgorithm
ExponentialFamilyAlgorithm
BayesianNetworkBasedAlgorithm

2. Append entry in the <tt>Algorithms</tt> enum in Evoptool.h.

typedef enum {
...
DEUM // 5
} Algorithms;

In the xml configuration file, your algorithm will be characterized by the int value associated with the position in this enum declaration.

3. modify the file
core/src/XMLParser.cpp. Search for the method <tt>bool XMLParser::parseAlgorithms</tt> and insert an new entry for your algorithm in the <tt>algorithmParameters</tt> array, for example

AlgorithmParameters algorithmParameters[] = {
...
{ Evoptool::DEUM, 5, (char*) "IDDDI" }, // Pop, percElitism, percSelec, CoolRate, GibbsIterations
...
};

In each entry, the first field is the name of the entry in the <tt>Algorithms</tt> enum just modified in <tt>Evoptool.h</tt>, the second is the number of parameters to be parsed in the xml configuration file and the third is a string specifying their type: <tt>I</tt> for integer and <tt>D</tt> for double.

4. add a case in the switch that follows in <tt>bool XMLParser::parseAlgorithms</tt>, for instance:

case Evoptool::DEUM:
algos[i] = new extendedFCA(intVal[0], doubleVal[0], doubleVal[1], intVal[1], intVal[2], params->rng);
algos[i]->initAlgorithm(params->task);
break;

Note that your algorithm can employ the random number generator provided by the Evoptool core, <tt>params->rng</tt>.

5. Include your headers in core/src/Algorithms.h

6. Document how your algorithm is instantiated in the comments appearing in evoptool-file/exec-scripts/example.xml

Algorithm Id Types Parameters
=====================================================================================================
...
FCA 26 "IDDII" (Pop, PercSelection, LearningRate, MaxCompositionLenght, MaxMonomialOrder)
...

7. Add an instantiation example for your algorithm in evoptool-file/exec-scripts/example.xml

<algo id="26" instanceName="FCA">
<int>1000</int>
<double>0.5</double>
<double>1</double>
<int>64</int>
<int>2</int>
</algo>

==== Run an algorithm in a C++ program ====

The simplest way to do this is to create a new submodule in <code>core</code>, i.e., a new source directory within the source directory of a module
For instance, the steps to create a new submodule named <code>myexample</code> are

1. copy the example submodule <code>exampleRunAlgorithm</code> in a new folder named <code>myexample</code> in

evoptool/core/src

2. modify the <code>Makefile</code> in the <code>myexample</code> directory, see comments in the makefile for more details.

3. edit the <code>main</code> function in the source file, if you need you can create other C++ and .h files in the same folder.

4. from <code>evoptool/core/src/myexample</code> run

make bin

The bin file is create in <code>evoptool/core/bin</code> and copied in <code>evoptool/bin</code>

NOTICE that <code>evoptool/core/bin</code> may be deleted after a <code>make cleanall</code>

5. from <code>evoptool/bin</code> run

./myexample

==== Available Statistics ====

Evoptool: Evolutionary Optimization Tool

2011-10-24T13:14:07Z

LuigiMalago: /* To create a new algorithm */

== Description ==

Evolutionary Optimization Tool (Evoptool) is an open source optimization tool writte in C++, distributed under GNU General Public License. Evoptool implements meta-heuristics based on the Evolutionary Computation paradigm and aims to provide a common platform for the development and test of new algorithms, in order to facilitate the performance comparison activity. Evoptool offers a wide set of benchmark problems, from classical toy samples to more complex tasks, and a collection of algorithm implementations from Genetic Algorithms and Estimation of Distribution Algorithms paradigms. Evoptool is flexible, easy to extend, also with algorithms based on other approaches other from EAs.

== The Evoptool Team ==

*[[User:MatteoMatteucci| Matteo Matteucci]] - matteucci [AT] elet.polimi.it

*[http://www.dei.polimi.it/personale/dettaglio.php?id_persona=829&id_sezione=&lettera=M&idlang=ita| Luigi Malagò] - malago [AT] elet.polimi.it

*[[User:GabrieleValentini| Gabriele Valentini]] - gvalentini [AT] iridia.ulb.ac.be

*[[User:DavideCucci| Davide Cucci]] - cucci [AT] elet.polimi.it

'''Formerly involved'''
*Emanuele Corsano

== Mailing List ==
http://groups.google.com/group/evoptool

== Download ==

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Developers may also access unstable branch. Contact the evoptool team for more details.

== Installation ==
Follow these steps in order to compile evoptool

1. Download source code from svn

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Refer to trunk for the lastest (stable?) version of evoptool

2. First you need to manually compile the <code>l1_logreg-0.8.2</code> package, http://www.stanford.edu/~boyd/l1_logreg/
whose source are already included in the evoptool repository. In order to do that follow the instrunctions in
<code>README.evoptool</code> in the <code>l1_logreg-0.8.2</code> directory

Next, compile <code><id_dist/code> following the instructions in <code>README.evoptool<code> in the <code><id_dist</code> folder

3. Then you need to compile a module at a time. Each module is included in a different folder.
To compile a module, from go to the module source folder and do make lib. For instance, for the module named <code>common</code>

cd common/src
make lib
cd ..

Compile modules in the following orderm due to dependencies

common
functions
ga
stochastic
eda

To clean a module, do

make clean

from the module source directory

4. Go to <code>core</code> module and type

make exe

Binary files will be copied in the <code>bin</code> directory in the root as well as the <code>bin</code> directory of the <code>core</code> module

'''Required packages'''
* Libraries

** ''gtkmm-2.4''
** ''glademm-2.4''
** ''gthread-2.0''
** ''sigc++-2.0''
** ''opencv'' (see for instance http://www.samontab.com/web/2011/06/installing-opencv-2-2-in-ubuntu-11-04/)
** ''gsl''
** ''gslcblas''
** ''libxml++-2.6''
** '''f2c''

* Software
** ''gnuplot''

== Running ==

Right now <code>evoptool</code> only runs as a script. GUI is not maintained in the latest version.
The <code>evoptool</code> binary file is supposed to be run in the <code>bin</code> directory in the root, this is because right now the script looks for some configuration files, for the instances of the problems, and temp directories. If you want to run the script from other directories, you just need to copy in that directory the <code>evoptool-file</code> directory that you find in the <code>bin</code> directory. Link such directory instead of copying it is not safe if you run multiple scripts at the same time, since output files will be shared.

To run the algorithm you need to enter as input an xml file. For instance you can run

./evoptool evoptool-file/examples/unitTestOneMax.xml

The <code>evoptool-file/example</code> directory contains a set of xml files for different benchmarks and different algorithms.
Take a loot at the <code>example.xml</code> file for the documentation on hoe to set the parameters for an each execution of <code>evoptool</code>

Each execution of <code>evoptool</code> produces a set of files as output. You can find all files in <code>evoptool-file/temp</code> directory. Plus a tar.gz file containing such files can be produced at the end of the execution of <code>evoptool</code>. See the xml file for details.

evoptool-file/temp/data
contains the raw data of the statistics according to the xml file

evoptool-file/temp/gnuplot
contains the gnuplot files to produce images of the statistics

evoptool-file/temp/image
contains images of the statistics produced according to the xml file

evoptool-file/temp/support
contains logs

== Documentation ==

==== Implement a new benchmark function====

Benchmarks are defined in the <code>function</code> module. A benchmark is the maximization problem of a real valued function defined over a vector of n binary variables. Functions are maximized in <code>evoptool</code>. In order to implement a new benchmark function you have to create a new <code>class</code> that inherits from <code>ObjectiveFunction</code> in the <code>common</code> module. Take a look at the <code>OneMax</code> benchmark function.

Among the arguments of the constructor of the <code>ObjectiveFunction</code> class there must be the size of the benchmark, which may or may not be a parameter of the new benchmark.

OneMax::OneMax(int size) : ObjectiveFunction(size)

In the constructor you have whether the maximum of the function is known or not

_knownSolution = true;

And in case this is known, set the minimum value and maximum value for the function

_minFitness = 0;
_maxFitness = size; //the maximum value of the OneMax function is defined as the sum of the bits of x set to one.

Besides, such values are used in the normalization of the functions in the plots of the statistics.

Each benchmark must implement the <code>f</code> method, which takes the <code>BinaryString</code> x and return f(x). For instance, for <code>OneMax</code> you have

double OneMax::f(BinaryString *bi) {
 if (bi != NULL) {
  if(!(bi->validCache())) {
   /* Fitness cache value not valid */
   int sum = 0;
   for (int j = 0; j < _size; j++) {
    sum = sum + bi->get(j);
   }
   bi->setFitnessCache(sum);
   return sum;
  } else {
   return bi->getFitnessCache();
  }
 } else {
  cerr << "[OneMax::f] binary instance cannot be null" << endl;
  return 0;
 }
}

In order to avoid multiple evaluations of the same <code>BinaryString</code> x, a caching mechanism has been implemented.

Moreover, you are asked to implement the <code>exportInteration</code> function, which return an <code>HyperGraph</code> which represents the interactions present in the function. In order to determine such hypergraph, start from the polinomial representation of the function, and for each monomial introduce a new hyperedge in the hypergraph.

For the <code>OneMax</code> function, such representation corresponds to the independence graph, since such function is linear.

HyperGraph* OneMax::exportInteractions() {
 HyperGraph *interactions = new HyperGraph();
 interactions->createIndependenceGraph(_size);
 return interactions;
}

In <code>Evoptool.h</code> add an entry in the <code>Tasks</code> enum.

/* This enumeration defines an identifier for each task function. */
typedef enum {
 ONE_MAX = 7,
} Tasks;

This value will identify uniquely the benchmark in the xml file. In the <code>XMLParser.cpp</code> file, add an entry for the new function.

bool XMLParser::parseTask(xmlpp::TextReader &reader, Evoptool::TestParameters *params) {
 ..
 switch (task) {
  case Evoptool::ONE_MAX: params->task = new OneMax(size);
  break;
  ..
  default: return false;
 }
 ..
}

Additional parameters can be obtained using the xml TextReader object, as for the <code>ForPeaks</code> function.

case Evoptool::FOUR_PEAKS:
 value = readNodeContent(reader, "peaks", &errorFlag);
 if (errorFlag) return false;
 int peaks = toInt(value);
 params->task = new FourPeaks(size, peaks);
 break;

Finally in the xml file, a function can set with the <code>task</code> tag, together with all parameters.

<task>
 <name>7</name>
 <size>64</size>
</task>

==== To create a new algorithm ====

1. Implement a new algorithm

All algorithms must inherit from the Algorithm class. First override the Algorithm::initAlgorithm as follows:

void DEUM::initAlgorithm(ObjectiveFunction* of) {
Algorithm::initAlgorithm(of);

/* Initialization tasks */
...
}

Then implement a run() method which performs al the required task for '''one''' iteration of your algorithm.

There are some classes which contain useful methods such as samplers and estimators from which your algorithm can inherit. The most useful are:

PopulationBasedAlgorithm
ModelBasedAlgorithm
ExponentialFamilyAlgorithm
BayesianNetworkBasedAlgorithm

2. Append entry in the <tt>Algorithms</tt> enum in Evoptool.h.

typedef enum {
...
DEUM // 5
} Algorithms;

In the xml configuration file, your algorithm will be characterized by the int value associated with the position in this enum declaration.

3. modify the file
core/src/XMLParser.cpp. Search for the method <tt>bool XMLParser::parseAlgorithms</tt> and insert an new entry for your algorithm in the <tt>algorithmParameters</tt> array, for example

AlgorithmParameters algorithmParameters[] = {
...
{ Evoptool::DEUM, 5, (char*) "IDDDI" }, // Pop, percElitism, percSelec, CoolRate, GibbsIterations
...
};

In each entry, the first field is the name of the entry in the <tt>Algorithms</tt> enum just modified in <tt>Evoptool.h</tt>, the second is the number of parameters to be parsed in the xml configuration file and the third is a string specifying their type: <tt>I</tt> for integer and <tt>D</tt> for double.

4. add a case in the switch that follows in <tt>bool XMLParser::parseAlgorithms</tt>, for instance:

case Evoptool::DEUM:
algos[i] = new extendedFCA(intVal[0], doubleVal[0], doubleVal[1], intVal[1], intVal[2], params->rng);
algos[i]->initAlgorithm(params->task);
break;

Note that your algorithm can employ the random number generator provided by the Evoptool core, <tt>params->rng</tt>.

5. Include your headers in core/src/Algorithms.h

6. Document how your algorithm is instantiated in the comments appearing in evoptool-file/exec-scripts/example.xml

Algorithm Id Types Parameters
=====================================================================================================
...
FCA 26 "IDDII" (Pop, PercSelection, LearningRate, MaxCompositionLenght, MaxMonomialOrder)
...

7. Add an instantiation example for your algorithm in evoptool-file/exec-scripts/example.xml

<algo id="26" instanceName="FCA">
<int>1000</int>
<double>0.5</double>
<double>1</double>
<int>64</int>
<int>2</int>
</algo>

==== Run an algorithm in a C++ program ====

The simplest way to do this is to create a new submodule in <code>core</code>, i.e., a new source directory within the source directory of a module
For instance, the steps to create a new submodule named <code>myexample</code> are

1. copy the example submodule <code>exampleRunAlgorithm</code> in a new folder named <code>myexample</code> in

evoptool/core/src

2. modify the <code>Makefile</code> in the <code>myexample</code> directory, see comments in the makefile for more details.

3. edit the <code>main</code> function in the source file, if you need you can create other C++ and .h files in the same folder.

4. from <code>evoptool/core/src/myexample</code> run

make bin

The bin file is create in <code>evoptool/core/bin</code> and copied in <code>evoptool/bin</code>

NOTICE that <code>evoptool/core/bin</code> may be deleted after a <code>make cleanall</code>

5. from <code>evoptool/bin</code> run

./myexample

Evoptool: Evolutionary Optimization Tool

2011-10-22T20:53:34Z

LuigiMalago: /* The Evoptool Team */

== Description ==

Evolutionary Optimization Tool (Evoptool) is an open source optimization tool writte in C++, distributed under GNU General Public License. Evoptool implements meta-heuristics based on the Evolutionary Computation paradigm and aims to provide a common platform for the development and test of new algorithms, in order to facilitate the performance comparison activity. Evoptool offers a wide set of benchmark problems, from classical toy samples to more complex tasks, and a collection of algorithm implementations from Genetic Algorithms and Estimation of Distribution Algorithms paradigms. Evoptool is flexible, easy to extend, also with algorithms based on other approaches other from EAs.

== The Evoptool Team ==

*[[User:MatteoMatteucci| Matteo Matteucci]] - matteucci [AT] elet.polimi.it

*[http://www.dei.polimi.it/personale/dettaglio.php?id_persona=829&id_sezione=&lettera=M&idlang=ita| Luigi Malagò] - malago [AT] elet.polimi.it

*[[User:GabrieleValentini| Gabriele Valentini]] - gvalentini [AT] iridia.ulb.ac.be

*Cucci Davide - cucci [AT] elet.polimi.it

'''Formerly involved'''
*Emanuele Corsano

== Mailing List ==
http://groups.google.com/group/evoptool

== Download ==

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Developers may also access unstable branch. Contact the evoptool team for more details.

== Installation ==
Follow these steps in order to compile evoptool

1. Download source code from svn

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Refer to trunk for the lastest (stable?) version of evoptool

2. First you need to manually compile the <code>l1_logreg-0.8.2</code> package, http://www.stanford.edu/~boyd/l1_logreg/
whose source are already included in the evoptool repository. In order to do that follow the instrunctions in
<code>README.evoptool</code> in the <code>l1_logreg-0.8.2</code> directory

Next, compile <code><id_dist/code> following the instructions in <code>README.evoptool<code> in the <code><id_dist</code> folder

3. Then you need to compile a module at a time. Each module is included in a different folder.
To compile a module, from go to the module source folder and do make lib. For instance, for the module named <code>common</code>

cd common/src
make lib
cd ..

Compile modules in the following orderm due to dependencies

common
functions
ga
stochastic
eda

To clean a module, do

make clean

from the module source directory

4. Go to <code>core</code> module and type

make exe

Binary files will be copied in the <code>bin</code> directory in the root as well as the <code>bin</code> directory of the <code>core</code> module

'''Required packages'''
* Libraries

** ''gtkmm-2.4''
** ''glademm-2.4''
** ''gthread-2.0''
** ''sigc++-2.0''
** ''opencv'' (see for instance http://www.samontab.com/web/2011/06/installing-opencv-2-2-in-ubuntu-11-04/)
** ''gsl''
** ''gslcblas''
** ''libxml++-2.6''
** '''f2c''

* Software
** ''gnuplot''

== Running ==

Right now <code>evoptool</code> only runs as a script. GUI is not maintained in the latest version.
The <code>evoptool</code> binary file is supposed to be run in the <code>bin</code> directory in the root, this is because right now the script looks for some configuration files, for the instances of the problems, and temp directories. If you want to run the script from other directories, you just need to copy in that directory the <code>evoptool-file</code> directory that you find in the <code>bin</code> directory. Link such directory instead of copying it is not safe if you run multiple scripts at the same time, since output files will be shared.

To run the algorithm you need to enter as input an xml file. For instance you can run

./evoptool evoptool-file/examples/unitTestOneMax.xml

The <code>evoptool-file/example</code> directory contains a set of xml files for different benchmarks and different algorithms.
Take a loot at the <code>example.xml</code> file for the documentation on hoe to set the parameters for an each execution of <code>evoptool</code>

Each execution of <code>evoptool</code> produces a set of files as output. You can find all files in <code>evoptool-file/temp</code> directory. Plus a tar.gz file containing such files can be produced at the end of the execution of <code>evoptool</code>. See the xml file for details.

evoptool-file/temp/data
contains the raw data of the statistics according to the xml file

evoptool-file/temp/gnuplot
contains the gnuplot files to produce images of the statistics

evoptool-file/temp/image
contains images of the statistics produced according to the xml file

evoptool-file/temp/support
contains logs

== Documentation ==

==== Implement a new benchmark function====

Benchmarks are defined in the <code>function</code> module. A benchmark is the maximization problem of a real valued function defined over a vector of n binary variables. Functions are maximized in <code>evoptool</code>. In order to implement a new benchmark function you have to create a new <code>class</code> that inherits from <code>ObjectiveFunction</code> in the <code>common</code> module. Take a look at the <code>OneMax</code> benchmark function.

Among the arguments of the constructor of the <code>ObjectiveFunction</code> class there must be the size of the benchmark, which may or may not be a parameter of the new benchmark.

OneMax::OneMax(int size) : ObjectiveFunction(size)

In the constructor you have whether the maximum of the function is known or not

_knownSolution = true;

And in case this is known, set the minimum value and maximum value for the function

_minFitness = 0;
_maxFitness = size; //the maximum value of the OneMax function is defined as the sum of the bits of x set to one.

Besides, such values are used in the normalization of the functions in the plots of the statistics.

Each benchmark must implement the <code>f</code> method, which takes the <code>BinaryString</code> x and return f(x). For instance, for <code>OneMax</code> you have

double OneMax::f(BinaryString *bi) {
 if (bi != NULL) {
  if(!(bi->validCache())) {
   /* Fitness cache value not valid */
   int sum = 0;
   for (int j = 0; j < _size; j++) {
    sum = sum + bi->get(j);
   }
   bi->setFitnessCache(sum);
   return sum;
  } else {
   return bi->getFitnessCache();
  }
 } else {
  cerr << "[OneMax::f] binary instance cannot be null" << endl;
  return 0;
 }
}

In order to avoid multiple evaluations of the same <code>BinaryString</code> x, a caching mechanism has been implemented.

Moreover, you are asked to implement the <code>exportInteration</code> function, which return an <code>HyperGraph</code> which represents the interactions present in the function. In order to determine such hypergraph, start from the polinomial representation of the function, and for each monomial introduce a new hyperedge in the hypergraph.

For the <code>OneMax</code> function, such representation corresponds to the independence graph, since such function is linear.

HyperGraph* OneMax::exportInteractions() {
 HyperGraph *interactions = new HyperGraph();
 interactions->createIndependenceGraph(_size);
 return interactions;
}

In <code>Evoptool.h</code> add an entry in the <code>Tasks</code> enum.

/* This enumeration defines an identifier for each task function. */
typedef enum {
 ONE_MAX = 7,
} Tasks;

This value will identify uniquely the benchmark in the xml file. In the <code>XMLParser.cpp</code> file, add an entry for the new function.

bool XMLParser::parseTask(xmlpp::TextReader &reader, Evoptool::TestParameters *params) {
 ..
 switch (task) {
  case Evoptool::ONE_MAX: params->task = new OneMax(size);
  break;
  ..
  default: return false;
 }
 ..
}

Additional parameters can be obtained using the xml TextReader object, as for the <code>ForPeaks</code> function.

case Evoptool::FOUR_PEAKS:
 value = readNodeContent(reader, "peaks", &errorFlag);
 if (errorFlag) return false;
 int peaks = toInt(value);
 params->task = new FourPeaks(size, peaks);
 break;

Finally in the xml file, a function can set with the <code>task</code> tag, together with all parameters.

<task>
 <name>7</name>
 <size>64</size>
</task>

==== To create a new algorithm (draft) ====

1. Implement a new algorithm

All algorithm must implement intiAlgorithm, and call Algorithm::initAlgorithm
same thing for
Algorithm::run();

2. Add an entry in Evoptool.h

typedef enum {
DEUM
} Algorithms;

3. modify the file
core/src/XMLParser.cpp
and insert an new entry for your algorithm in
bool XMLParser::parseAlgorithms
for instance

{ Evoptool::DEUM, 5, (char*) "IDDDI" } // Pop, percElitism, percSelec, CoolRate, GibbsIterations
where the first argument is the class of the algorithm
the second the number of paramers parsed in the xml file
the third the types of each parameter

4. add a case in the switch that follows in
bool XMLParser::parseAlgorithms

for instance
case Evoptool::EXTENDEDFCA:
algos[i] = new extendedFCA(intVal[0], doubleVal[0], doubleVal[1], intVal[1], intVal[2], params->rng);
algos[i]->initAlgorithm(params->task);
break;

where the algorithm is instantiated

5. Add an entry for your algorithm in
core/src/Algorithms.h

6. Add a line in
evoptool-file/exec-scripts/example.xml
as a documenation for the parameters of your algorithm.
Choose a new Id for your algorithm
Types indicates then type of the parameters (the order is important) that will must be specified
in the xml file (see <algo>) and are passed to the constructor of the algorithm when the object is instantiated
I = integer
D = double
B = bool

==== Run an algorithm in a C++ program ====

The simplest way to do this is to create a new submodule in <code>core</code>, i.e., a new source directory within the source directory of a module
For instance, the steps to create a new submodule named <code>myexample</code> are

1. copy the example submodule <code>exampleRunAlgorithm</code> in a new folder named <code>myexample</code> in

evoptool/core/src

2. modify the <code>Makefile</code> in the <code>myexample</code> directory, see comments in the makefile for more details.

3. edit the <code>main</code> function in the source file, if you need you can create other C++ and .h files in the same folder.

4. from <code>evoptool/core/src/myexample</code> run

make bin

The bin file is create in <code>evoptool/core/bin</code> and copied in <code>evoptool/bin</code>

NOTICE that <code>evoptool/core/bin</code> may be deleted after a <code>make cleanall</code>

5. from <code>evoptool/bin</code> run

./myexample

Evoptool: Evolutionary Optimization Tool

2011-10-22T17:48:41Z

LuigiMalago: /* Installation */

== Description ==

Evolutionary Optimization Tool (Evoptool) is an open source optimization tool writte in C++, distributed under GNU General Public License. Evoptool implements meta-heuristics based on the Evolutionary Computation paradigm and aims to provide a common platform for the development and test of new algorithms, in order to facilitate the performance comparison activity. Evoptool offers a wide set of benchmark problems, from classical toy samples to more complex tasks, and a collection of algorithm implementations from Genetic Algorithms and Estimation of Distribution Algorithms paradigms. Evoptool is flexible, easy to extend, also with algorithms based on other approaches other from EAs.

== The Evoptool Team ==

*[[User:MatteoMatteucci| Matteo Matteucci]] - matteucci [AT] elet.polimi.it

*[[http://www.dei.polimi.it/personale/dettaglio.php?id_persona=829&id_sezione=&lettera=M&idlang=ita| Luigi Malagò]] - malago [AT] elet.polimi.it

*[[User:GabrieleValentini| Gabriele Valentini]] - gvalentini [AT] iridia.ulb.ac.be

*Cucci Davide - cucci [AT] elet.polimi.it

'''Formerly involved'''
*Emanuele Corsano

== Mailing List ==
http://groups.google.com/group/evoptool

== Download ==

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Developers may also access unstable branch. Contact the evoptool team for more details.

== Installation ==
Follow these steps in order to compile evoptool

1. Download source code from svn

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Refer to trunk for the lastest (stable?) version of evoptool

2. First you need to manually compile the <code>l1_logreg-0.8.2</code> package, http://www.stanford.edu/~boyd/l1_logreg/
whose source are already included in the evoptool repository. In order to do that follow the instrunctions in
<code>README.evoptool</code> in the <code>l1_logreg-0.8.2</code> directory

Next, compile <code><id_dist/code> following the instructions in <code>README.evoptool<code> in the <code><id_dist</code> folder

3. Then you need to compile a module at a time. Each module is included in a different folder.
To compile a module, from go to the module source folder and do make lib. For instance, for the module named <code>common</code>

cd common/src
make lib
cd ..

Compile modules in the following orderm due to dependencies

common
functions
ga
stochastic
eda

To clean a module, do

make clean

from the module source directory

4. Go to <code>core</code> module and type

make exe

Binary files will be copied in the <code>bin</code> directory in the root as well as the <code>bin</code> directory of the <code>core</code> module

'''Required packages'''
* Libraries

** ''gtkmm-2.4''
** ''glademm-2.4''
** ''gthread-2.0''
** ''sigc++-2.0''
** ''opencv'' (see for instance http://www.samontab.com/web/2011/06/installing-opencv-2-2-in-ubuntu-11-04/)
** ''gsl''
** ''gslcblas''
** ''libxml++-2.6''
** '''f2c''

* Software
** ''gnuplot''

== Running ==

Right now <code>evoptool</code> only runs as a script. GUI is not maintained in the latest version.
The <code>evoptool</code> binary file is supposed to be run in the <code>bin</code> directory in the root, this is because right now the script looks for some configuration files, for the instances of the problems, and temp directories. If you want to run the script from other directories, you just need to copy in that directory the <code>evoptool-file</code> directory that you find in the <code>bin</code> directory. Link such directory instead of copying it is not safe if you run multiple scripts at the same time, since output files will be shared.

To run the algorithm you need to enter as input an xml file. For instance you can run

./evoptool evoptool-file/examples/unitTestOneMax.xml

The <code>evoptool-file/example</code> directory contains a set of xml files for different benchmarks and different algorithms.
Take a loot at the <code>example.xml</code> file for the documentation on hoe to set the parameters for an each execution of <code>evoptool</code>

Each execution of <code>evoptool</code> produces a set of files as output. You can find all files in <code>evoptool-file/temp</code> directory. Plus a tar.gz file containing such files can be produced at the end of the execution of <code>evoptool</code>. See the xml file for details.

evoptool-file/temp/data
contains the raw data of the statistics according to the xml file

evoptool-file/temp/gnuplot
contains the gnuplot files to produce images of the statistics

evoptool-file/temp/image
contains images of the statistics produced according to the xml file

evoptool-file/temp/support
contains logs

== Documentation ==

==== Implement a new benchmark function====

Benchmarks are defined in the <code>function</code> module. A benchmark is the maximization problem of a real valued function defined over a vector of n binary variables. Functions are maximized in <code>evoptool</code>. In order to implement a new benchmark function you have to create a new <code>class</code> that inherits from <code>ObjectiveFunction</code> in the <code>common</code> module. Take a look at the <code>OneMax</code> benchmark function.

Among the arguments of the constructor of the <code>ObjectiveFunction</code> class there must be the size of the benchmark, which may or may not be a parameter of the new benchmark.

OneMax::OneMax(int size) : ObjectiveFunction(size)

In the constructor you have whether the maximum of the function is known or not

_knownSolution = true;

And in case this is known, set the minimum value and maximum value for the function

_minFitness = 0;
_maxFitness = size; //the maximum value of the OneMax function is defined as the sum of the bits of x set to one.

Besides, such values are used in the normalization of the functions in the plots of the statistics.

Each benchmark must implement the <code>f</code> method, which takes the <code>BinaryString</code> x and return f(x). For instance, for <code>OneMax</code> you have

double OneMax::f(BinaryString *bi) {
 if (bi != NULL) {
  if(!(bi->validCache())) {
   /* Fitness cache value not valid */
   int sum = 0;
   for (int j = 0; j < _size; j++) {
    sum = sum + bi->get(j);
   }
   bi->setFitnessCache(sum);
   return sum;
  } else {
   return bi->getFitnessCache();
  }
 } else {
  cerr << "[OneMax::f] binary instance cannot be null" << endl;
  return 0;
 }
}

In order to avoid multiple evaluations of the same <code>BinaryString</code> x, a caching mechanism has been implemented.

Moreover, you are asked to implement the <code>exportInteration</code> function, which return an <code>HyperGraph</code> which represents the interactions present in the function. In order to determine such hypergraph, start from the polinomial representation of the function, and for each monomial introduce a new hyperedge in the hypergraph.

For the <code>OneMax</code> function, such representation corresponds to the independence graph, since such function is linear.

HyperGraph* OneMax::exportInteractions() {
 HyperGraph *interactions = new HyperGraph();
 interactions->createIndependenceGraph(_size);
 return interactions;
}

In <code>Evoptool.h</code> add an entry in the <code>Tasks</code> enum.

/* This enumeration defines an identifier for each task function. */
typedef enum {
 ONE_MAX = 7,
} Tasks;

This value will identify uniquely the benchmark in the xml file. In the <code>XMLParser.cpp</code> file, add an entry for the new function.

bool XMLParser::parseTask(xmlpp::TextReader &reader, Evoptool::TestParameters *params) {
 ..
 switch (task) {
  case Evoptool::ONE_MAX: params->task = new OneMax(size);
  break;
  ..
  default: return false;
 }
 ..
}

Additional parameters can be obtained using the xml TextReader object, as for the <code>ForPeaks</code> function.

case Evoptool::FOUR_PEAKS:
 value = readNodeContent(reader, "peaks", &errorFlag);
 if (errorFlag) return false;
 int peaks = toInt(value);
 params->task = new FourPeaks(size, peaks);
 break;

Finally in the xml file, a function can set with the <code>task</code> tag, together with all parameters.

<task>
 <name>7</name>
 <size>64</size>
</task>

==== To create a new algorithm (draft) ====

1. Implement a new algorithm

All algorithm must implement intiAlgorithm, and call Algorithm::initAlgorithm
same thing for
Algorithm::run();

2. Add an entry in Evoptool.h

typedef enum {
DEUM
} Algorithms;

3. modify the file
core/src/XMLParser.cpp
and insert an new entry for your algorithm in
bool XMLParser::parseAlgorithms
for instance

{ Evoptool::DEUM, 5, (char*) "IDDDI" } // Pop, percElitism, percSelec, CoolRate, GibbsIterations
where the first argument is the class of the algorithm
the second the number of paramers parsed in the xml file
the third the types of each parameter

4. add a case in the switch that follows in
bool XMLParser::parseAlgorithms

for instance
case Evoptool::EXTENDEDFCA:
algos[i] = new extendedFCA(intVal[0], doubleVal[0], doubleVal[1], intVal[1], intVal[2], params->rng);
algos[i]->initAlgorithm(params->task);
break;

where the algorithm is instantiated

5. Add an entry for your algorithm in
core/src/Algorithms.h

6. Add a line in
evoptool-file/exec-scripts/example.xml
as a documenation for the parameters of your algorithm.
Choose a new Id for your algorithm
Types indicates then type of the parameters (the order is important) that will must be specified
in the xml file (see <algo>) and are passed to the constructor of the algorithm when the object is instantiated
I = integer
D = double
B = bool

==== Run an algorithm in a C++ program ====

The simplest way to do this is to create a new submodule in <code>core</code>, i.e., a new source directory within the source directory of a module
For instance, the steps to create a new submodule named <code>myexample</code> are

1. copy the example submodule <code>exampleRunAlgorithm</code> in a new folder named <code>myexample</code> in

evoptool/core/src

2. modify the <code>Makefile</code> in the <code>myexample</code> directory, see comments in the makefile for more details.

3. edit the <code>main</code> function in the source file, if you need you can create other C++ and .h files in the same folder.

4. from <code>evoptool/core/src/myexample</code> run

make bin

The bin file is create in <code>evoptool/core/bin</code> and copied in <code>evoptool/bin</code>

NOTICE that <code>evoptool/core/bin</code> may be deleted after a <code>make cleanall</code>

5. from <code>evoptool/bin</code> run

./myexample

Evoptool: Evolutionary Optimization Tool

2011-10-22T17:48:18Z

LuigiMalago: /* Installation */

== Description ==

Evolutionary Optimization Tool (Evoptool) is an open source optimization tool writte in C++, distributed under GNU General Public License. Evoptool implements meta-heuristics based on the Evolutionary Computation paradigm and aims to provide a common platform for the development and test of new algorithms, in order to facilitate the performance comparison activity. Evoptool offers a wide set of benchmark problems, from classical toy samples to more complex tasks, and a collection of algorithm implementations from Genetic Algorithms and Estimation of Distribution Algorithms paradigms. Evoptool is flexible, easy to extend, also with algorithms based on other approaches other from EAs.

== The Evoptool Team ==

*[[User:MatteoMatteucci| Matteo Matteucci]] - matteucci [AT] elet.polimi.it

*[[http://www.dei.polimi.it/personale/dettaglio.php?id_persona=829&id_sezione=&lettera=M&idlang=ita| Luigi Malagò]] - malago [AT] elet.polimi.it

*[[User:GabrieleValentini| Gabriele Valentini]] - gvalentini [AT] iridia.ulb.ac.be

*Cucci Davide - cucci [AT] elet.polimi.it

'''Formerly involved'''
*Emanuele Corsano

== Mailing List ==
http://groups.google.com/group/evoptool

== Download ==

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Developers may also access unstable branch. Contact the evoptool team for more details.

== Installation ==
Follow these steps in order to compile evoptool

1. Download source code from svn

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Refer to trunk for the lastest (stable?) version of evoptool

2. First you need to manually compile the <code>l1_logreg-0.8.2</code> package, http://www.stanford.edu/~boyd/l1_logreg/
whose source are already included in the evoptool repository. In order to do that follow the instrunctions in
<code>README.evoptool</code> in the <code>l1_logreg-0.8.2</code> directory

Next, compile <code><id_dist/code> following the instructions in <code>README.evoptool<code> in the <code><id_dist/code> folder

3. Then you need to compile a module at a time. Each module is included in a different folder.
To compile a module, from go to the module source folder and do make lib. For instance, for the module named <code>common</code>

cd common/src
make lib
cd ..

Compile modules in the following orderm due to dependencies

common
functions
ga
stochastic
eda

To clean a module, do

make clean

from the module source directory

4. Go to <code>core</code> module and type

make exe

Binary files will be copied in the <code>bin</code> directory in the root as well as the <code>bin</code> directory of the <code>core</code> module

'''Required packages'''
* Libraries

** ''gtkmm-2.4''
** ''glademm-2.4''
** ''gthread-2.0''
** ''sigc++-2.0''
** ''opencv'' (see for instance http://www.samontab.com/web/2011/06/installing-opencv-2-2-in-ubuntu-11-04/)
** ''gsl''
** ''gslcblas''
** ''libxml++-2.6''
** '''f2c'

* Software
** ''gnuplot''

== Running ==

Right now <code>evoptool</code> only runs as a script. GUI is not maintained in the latest version.
The <code>evoptool</code> binary file is supposed to be run in the <code>bin</code> directory in the root, this is because right now the script looks for some configuration files, for the instances of the problems, and temp directories. If you want to run the script from other directories, you just need to copy in that directory the <code>evoptool-file</code> directory that you find in the <code>bin</code> directory. Link such directory instead of copying it is not safe if you run multiple scripts at the same time, since output files will be shared.

To run the algorithm you need to enter as input an xml file. For instance you can run

./evoptool evoptool-file/examples/unitTestOneMax.xml

The <code>evoptool-file/example</code> directory contains a set of xml files for different benchmarks and different algorithms.
Take a loot at the <code>example.xml</code> file for the documentation on hoe to set the parameters for an each execution of <code>evoptool</code>

Each execution of <code>evoptool</code> produces a set of files as output. You can find all files in <code>evoptool-file/temp</code> directory. Plus a tar.gz file containing such files can be produced at the end of the execution of <code>evoptool</code>. See the xml file for details.

evoptool-file/temp/data
contains the raw data of the statistics according to the xml file

evoptool-file/temp/gnuplot
contains the gnuplot files to produce images of the statistics

evoptool-file/temp/image
contains images of the statistics produced according to the xml file

evoptool-file/temp/support
contains logs

== Documentation ==

==== Implement a new benchmark function====

Benchmarks are defined in the <code>function</code> module. A benchmark is the maximization problem of a real valued function defined over a vector of n binary variables. Functions are maximized in <code>evoptool</code>. In order to implement a new benchmark function you have to create a new <code>class</code> that inherits from <code>ObjectiveFunction</code> in the <code>common</code> module. Take a look at the <code>OneMax</code> benchmark function.

Among the arguments of the constructor of the <code>ObjectiveFunction</code> class there must be the size of the benchmark, which may or may not be a parameter of the new benchmark.

OneMax::OneMax(int size) : ObjectiveFunction(size)

In the constructor you have whether the maximum of the function is known or not

_knownSolution = true;

And in case this is known, set the minimum value and maximum value for the function

_minFitness = 0;
_maxFitness = size; //the maximum value of the OneMax function is defined as the sum of the bits of x set to one.

Besides, such values are used in the normalization of the functions in the plots of the statistics.

Each benchmark must implement the <code>f</code> method, which takes the <code>BinaryString</code> x and return f(x). For instance, for <code>OneMax</code> you have

double OneMax::f(BinaryString *bi) {
 if (bi != NULL) {
  if(!(bi->validCache())) {
   /* Fitness cache value not valid */
   int sum = 0;
   for (int j = 0; j < _size; j++) {
    sum = sum + bi->get(j);
   }
   bi->setFitnessCache(sum);
   return sum;
  } else {
   return bi->getFitnessCache();
  }
 } else {
  cerr << "[OneMax::f] binary instance cannot be null" << endl;
  return 0;
 }
}

In order to avoid multiple evaluations of the same <code>BinaryString</code> x, a caching mechanism has been implemented.

Moreover, you are asked to implement the <code>exportInteration</code> function, which return an <code>HyperGraph</code> which represents the interactions present in the function. In order to determine such hypergraph, start from the polinomial representation of the function, and for each monomial introduce a new hyperedge in the hypergraph.

For the <code>OneMax</code> function, such representation corresponds to the independence graph, since such function is linear.

HyperGraph* OneMax::exportInteractions() {
 HyperGraph *interactions = new HyperGraph();
 interactions->createIndependenceGraph(_size);
 return interactions;
}

In <code>Evoptool.h</code> add an entry in the <code>Tasks</code> enum.

/* This enumeration defines an identifier for each task function. */
typedef enum {
 ONE_MAX = 7,
} Tasks;

This value will identify uniquely the benchmark in the xml file. In the <code>XMLParser.cpp</code> file, add an entry for the new function.

bool XMLParser::parseTask(xmlpp::TextReader &reader, Evoptool::TestParameters *params) {
 ..
 switch (task) {
  case Evoptool::ONE_MAX: params->task = new OneMax(size);
  break;
  ..
  default: return false;
 }
 ..
}

Additional parameters can be obtained using the xml TextReader object, as for the <code>ForPeaks</code> function.

case Evoptool::FOUR_PEAKS:
 value = readNodeContent(reader, "peaks", &errorFlag);
 if (errorFlag) return false;
 int peaks = toInt(value);
 params->task = new FourPeaks(size, peaks);
 break;

Finally in the xml file, a function can set with the <code>task</code> tag, together with all parameters.

<task>
 <name>7</name>
 <size>64</size>
</task>

==== To create a new algorithm (draft) ====

1. Implement a new algorithm

All algorithm must implement intiAlgorithm, and call Algorithm::initAlgorithm
same thing for
Algorithm::run();

2. Add an entry in Evoptool.h

typedef enum {
DEUM
} Algorithms;

3. modify the file
core/src/XMLParser.cpp
and insert an new entry for your algorithm in
bool XMLParser::parseAlgorithms
for instance

{ Evoptool::DEUM, 5, (char*) "IDDDI" } // Pop, percElitism, percSelec, CoolRate, GibbsIterations
where the first argument is the class of the algorithm
the second the number of paramers parsed in the xml file
the third the types of each parameter

4. add a case in the switch that follows in
bool XMLParser::parseAlgorithms

for instance
case Evoptool::EXTENDEDFCA:
algos[i] = new extendedFCA(intVal[0], doubleVal[0], doubleVal[1], intVal[1], intVal[2], params->rng);
algos[i]->initAlgorithm(params->task);
break;

where the algorithm is instantiated

5. Add an entry for your algorithm in
core/src/Algorithms.h

6. Add a line in
evoptool-file/exec-scripts/example.xml
as a documenation for the parameters of your algorithm.
Choose a new Id for your algorithm
Types indicates then type of the parameters (the order is important) that will must be specified
in the xml file (see <algo>) and are passed to the constructor of the algorithm when the object is instantiated
I = integer
D = double
B = bool

==== Run an algorithm in a C++ program ====

The simplest way to do this is to create a new submodule in <code>core</code>, i.e., a new source directory within the source directory of a module
For instance, the steps to create a new submodule named <code>myexample</code> are

1. copy the example submodule <code>exampleRunAlgorithm</code> in a new folder named <code>myexample</code> in

evoptool/core/src

2. modify the <code>Makefile</code> in the <code>myexample</code> directory, see comments in the makefile for more details.

3. edit the <code>main</code> function in the source file, if you need you can create other C++ and .h files in the same folder.

4. from <code>evoptool/core/src/myexample</code> run

make bin

The bin file is create in <code>evoptool/core/bin</code> and copied in <code>evoptool/bin</code>

NOTICE that <code>evoptool/core/bin</code> may be deleted after a <code>make cleanall</code>

5. from <code>evoptool/bin</code> run

./myexample

Evoptool: Evolutionary Optimization Tool

2011-10-22T16:50:22Z

LuigiMalago: /* Installation */

== Description ==

Evolutionary Optimization Tool (Evoptool) is an open source optimization tool writte in C++, distributed under GNU General Public License. Evoptool implements meta-heuristics based on the Evolutionary Computation paradigm and aims to provide a common platform for the development and test of new algorithms, in order to facilitate the performance comparison activity. Evoptool offers a wide set of benchmark problems, from classical toy samples to more complex tasks, and a collection of algorithm implementations from Genetic Algorithms and Estimation of Distribution Algorithms paradigms. Evoptool is flexible, easy to extend, also with algorithms based on other approaches other from EAs.

== The Evoptool Team ==

*[[User:MatteoMatteucci| Matteo Matteucci]] - matteucci [AT] elet.polimi.it

*[[http://www.dei.polimi.it/personale/dettaglio.php?id_persona=829&id_sezione=&lettera=M&idlang=ita| Luigi Malagò]] - malago [AT] elet.polimi.it

*[[User:GabrieleValentini| Gabriele Valentini]] - gvalentini [AT] iridia.ulb.ac.be

*Cucci Davide - cucci [AT] elet.polimi.it

'''Formerly involved'''
*Emanuele Corsano

== Mailing List ==
http://groups.google.com/group/evoptool

== Download ==

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Developers may also access unstable branch. Contact the evoptool team for more details.

== Installation ==
Follow these steps in order to compile evoptool

1. Download source code from svn

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Refer to trunk for the lastest (stable?) version of evoptool

2. First you need to manually compile the <code>l1_logreg-0.8.2</code> package, http://www.stanford.edu/~boyd/l1_logreg/
whose source are already included in the evoptool repository. In order to do that follow the instrunctions in
<code>README.evoptool</code> in the <code>l1_logreg-0.8.2</code> directory

Next, compile <code><id_dist/code> following the instructions in <code>README.evoptool<code> in the <code><id_dist/code> folder

3. Then you need to compile a module at a time. Each module is included in a different folder.
To compile a module, from go to the module source folder and do make lib. For instance, for the module named <code>common</code>

cd common/src
make lib
cd ..

Compile modules in the following orderm due to dependencies

common
functions
ga
stochastic
eda

To clean a module, do

make clean

from the module source directory

4. Go to <code>core</code> module and type

make exe

Binary files will be copied in the <code>bin</code> directory in the root as well as the <code>bin</code> directory of the <code>core</code> module

'''Required packages'''
* Libraries

** ''gtkmm-2.4''
** ''glademm-2.4''
** ''gthread-2.0''
** ''sigc++-2.0''
** ''opencv'' (see for instance http://www.samontab.com/web/2011/06/installing-opencv-2-2-in-ubuntu-11-04/)
** ''gsl''
** ''gslcblas''
** ''libxml++-2.6''

* Software
** ''gnuplot''

== Running ==

Right now <code>evoptool</code> only runs as a script. GUI is not maintained in the latest version.
The <code>evoptool</code> binary file is supposed to be run in the <code>bin</code> directory in the root, this is because right now the script looks for some configuration files, for the instances of the problems, and temp directories. If you want to run the script from other directories, you just need to copy in that directory the <code>evoptool-file</code> directory that you find in the <code>bin</code> directory. Link such directory instead of copying it is not safe if you run multiple scripts at the same time, since output files will be shared.

To run the algorithm you need to enter as input an xml file. For instance you can run

./evoptool evoptool-file/examples/unitTestOneMax.xml

The <code>evoptool-file/example</code> directory contains a set of xml files for different benchmarks and different algorithms.
Take a loot at the <code>example.xml</code> file for the documentation on hoe to set the parameters for an each execution of <code>evoptool</code>

Each execution of <code>evoptool</code> produces a set of files as output. You can find all files in <code>evoptool-file/temp</code> directory. Plus a tar.gz file containing such files can be produced at the end of the execution of <code>evoptool</code>. See the xml file for details.

evoptool-file/temp/data
contains the raw data of the statistics according to the xml file

evoptool-file/temp/gnuplot
contains the gnuplot files to produce images of the statistics

evoptool-file/temp/image
contains images of the statistics produced according to the xml file

evoptool-file/temp/support
contains logs

== Documentation ==

==== Implement a new benchmark function====

Benchmarks are defined in the <code>function</code> module. A benchmark is the maximization problem of a real valued function defined over a vector of n binary variables. Functions are maximized in <code>evoptool</code>. In order to implement a new benchmark function you have to create a new <code>class</code> that inherits from <code>ObjectiveFunction</code> in the <code>common</code> module. Take a look at the <code>OneMax</code> benchmark function.

Among the arguments of the constructor of the <code>ObjectiveFunction</code> class there must be the size of the benchmark, which may or may not be a parameter of the new benchmark.

OneMax::OneMax(int size) : ObjectiveFunction(size)

In the constructor you have whether the maximum of the function is known or not

_knownSolution = true;

And in case this is known, set the minimum value and maximum value for the function

_minFitness = 0;
_maxFitness = size; //the maximum value of the OneMax function is defined as the sum of the bits of x set to one.

Besides, such values are used in the normalization of the functions in the plots of the statistics.

Each benchmark must implement the <code>f</code> method, which takes the <code>BinaryString</code> x and return f(x). For instance, for <code>OneMax</code> you have

double OneMax::f(BinaryString *bi) {
 if (bi != NULL) {
  if(!(bi->validCache())) {
   /* Fitness cache value not valid */
   int sum = 0;
   for (int j = 0; j < _size; j++) {
    sum = sum + bi->get(j);
   }
   bi->setFitnessCache(sum);
   return sum;
  } else {
   return bi->getFitnessCache();
  }
 } else {
  cerr << "[OneMax::f] binary instance cannot be null" << endl;
  return 0;
 }
}

In order to avoid multiple evaluations of the same <code>BinaryString</code> x, a caching mechanism has been implemented.

Moreover, you are asked to implement the <code>exportInteration</code> function, which return an <code>HyperGraph</code> which represents the interactions present in the function. In order to determine such hypergraph, start from the polinomial representation of the function, and for each monomial introduce a new hyperedge in the hypergraph.

For the <code>OneMax</code> function, such representation corresponds to the independence graph, since such function is linear.

HyperGraph* OneMax::exportInteractions() {
 HyperGraph *interactions = new HyperGraph();
 interactions->createIndependenceGraph(_size);
 return interactions;
}

In <code>Evoptool.h</code> add an entry in the <code>Tasks</code> enum.

/* This enumeration defines an identifier for each task function. */
typedef enum {
 ONE_MAX = 7,
} Tasks;

This value will identify uniquely the benchmark in the xml file. In the <code>XMLParser.cpp</code> file, add an entry for the new function.

bool XMLParser::parseTask(xmlpp::TextReader &reader, Evoptool::TestParameters *params) {
 ..
 switch (task) {
  case Evoptool::ONE_MAX: params->task = new OneMax(size);
  break;
  ..
  default: return false;
 }
 ..
}

Additional parameters can be obtained using the xml TextReader object, as for the <code>ForPeaks</code> function.

case Evoptool::FOUR_PEAKS:
 value = readNodeContent(reader, "peaks", &errorFlag);
 if (errorFlag) return false;
 int peaks = toInt(value);
 params->task = new FourPeaks(size, peaks);
 break;

Finally in the xml file, a function can set with the <code>task</code> tag, together with all parameters.

<task>
 <name>7</name>
 <size>64</size>
</task>

==== To create a new algorithm (draft) ====

1. Implement a new algorithm

All algorithm must implement intiAlgorithm, and call Algorithm::initAlgorithm
same thing for
Algorithm::run();

2. Add an entry in Evoptool.h

typedef enum {
DEUM
} Algorithms;

3. modify the file
core/src/XMLParser.cpp
and insert an new entry for your algorithm in
bool XMLParser::parseAlgorithms
for instance

{ Evoptool::DEUM, 5, (char*) "IDDDI" } // Pop, percElitism, percSelec, CoolRate, GibbsIterations
where the first argument is the class of the algorithm
the second the number of paramers parsed in the xml file
the third the types of each parameter

4. add a case in the switch that follows in
bool XMLParser::parseAlgorithms

for instance
case Evoptool::EXTENDEDFCA:
algos[i] = new extendedFCA(intVal[0], doubleVal[0], doubleVal[1], intVal[1], intVal[2], params->rng);
algos[i]->initAlgorithm(params->task);
break;

where the algorithm is instantiated

5. Add an entry for your algorithm in
core/src/Algorithms.h

6. Add a line in
evoptool-file/exec-scripts/example.xml
as a documenation for the parameters of your algorithm.
Choose a new Id for your algorithm
Types indicates then type of the parameters (the order is important) that will must be specified
in the xml file (see <algo>) and are passed to the constructor of the algorithm when the object is instantiated
I = integer
D = double
B = bool

==== Run an algorithm in a C++ program ====

The simplest way to do this is to create a new submodule in <code>core</code>, i.e., a new source directory within the source directory of a module
For instance, the steps to create a new submodule named <code>myexample</code> are

1. copy the example submodule <code>exampleRunAlgorithm</code> in a new folder named <code>myexample</code> in

evoptool/core/src

2. modify the <code>Makefile</code> in the <code>myexample</code> directory, see comments in the makefile for more details.

3. edit the <code>main</code> function in the source file, if you need you can create other C++ and .h files in the same folder.

4. from <code>evoptool/core/src/myexample</code> run

make bin

The bin file is create in <code>evoptool/core/bin</code> and copied in <code>evoptool/bin</code>

NOTICE that <code>evoptool/core/bin</code> may be deleted after a <code>make cleanall</code>

5. from <code>evoptool/bin</code> run

./myexample

Evoptool: Evolutionary Optimization Tool

2011-10-22T15:41:05Z

LuigiMalago: /* Installation */

== Description ==

Evolutionary Optimization Tool (Evoptool) is an open source optimization tool writte in C++, distributed under GNU General Public License. Evoptool implements meta-heuristics based on the Evolutionary Computation paradigm and aims to provide a common platform for the development and test of new algorithms, in order to facilitate the performance comparison activity. Evoptool offers a wide set of benchmark problems, from classical toy samples to more complex tasks, and a collection of algorithm implementations from Genetic Algorithms and Estimation of Distribution Algorithms paradigms. Evoptool is flexible, easy to extend, also with algorithms based on other approaches other from EAs.

== The Evoptool Team ==

*[[User:MatteoMatteucci| Matteo Matteucci]] - matteucci [AT] elet.polimi.it

*[[http://www.dei.polimi.it/personale/dettaglio.php?id_persona=829&id_sezione=&lettera=M&idlang=ita| Luigi Malagò]] - malago [AT] elet.polimi.it

*[[User:GabrieleValentini| Gabriele Valentini]] - gvalentini [AT] iridia.ulb.ac.be

*Cucci Davide - cucci [AT] elet.polimi.it

'''Formerly involved'''
*Emanuele Corsano

== Mailing List ==
http://groups.google.com/group/evoptool

== Download ==

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Developers may also access unstable branch. Contact the evoptool team for more details.

== Installation ==
Follow these steps in order to compile evoptool

1. Download source code from svn

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Refer to trunk for the lastest (stable?) version of evoptool

2. First you need to manually compile the <code>l1_logreg-0.8.2</code> package, http://www.stanford.edu/~boyd/l1_logreg/
whose source are already included in the evoptool repository. In order to do that follow the instrunctions in
<code>README.evoptool</code> in the <code>l1_logreg-0.8.2</code> directory

Next, compile <code><id_dist/code> following the instructions in <code>README.evoptool<code> in the <code><id_dist/code> folder

3. Then you need to compile a module at a time. Each module is included in a different folder.
To compile a module, from go to the module source folder and do make lib. For instance, for the module named <code>common</code>

cd common/src
make lib
cd ..

Compile modules in the following order

common
functions
ga
eda
stochastic

To clean a module, do

make clean

from the module source directory

4. Go to <code>core</code> module and type

make exe

Binary files will be copied in the <code>bin</code> directory in the root as well as the <code>bin</code> directory of the <code>core</code> module

'''Required packages'''
* Libraries

** ''gtkmm-2.4''
** ''glademm-2.4''
** ''gthread-2.0''
** ''sigc++-2.0''
** ''opencv'' (see for instance http://www.samontab.com/web/2011/06/installing-opencv-2-2-in-ubuntu-11-04/)
** ''gsl''
** ''gslcblas''
** ''libxml++-2.6''

* Software
** ''gnuplot''

== Running ==

Right now <code>evoptool</code> only runs as a script. GUI is not maintained in the latest version.
The <code>evoptool</code> binary file is supposed to be run in the <code>bin</code> directory in the root, this is because right now the script looks for some configuration files, for the instances of the problems, and temp directories. If you want to run the script from other directories, you just need to copy in that directory the <code>evoptool-file</code> directory that you find in the <code>bin</code> directory. Link such directory instead of copying it is not safe if you run multiple scripts at the same time, since output files will be shared.

To run the algorithm you need to enter as input an xml file. For instance you can run

./evoptool evoptool-file/examples/unitTestOneMax.xml

The <code>evoptool-file/example</code> directory contains a set of xml files for different benchmarks and different algorithms.
Take a loot at the <code>example.xml</code> file for the documentation on hoe to set the parameters for an each execution of <code>evoptool</code>

Each execution of <code>evoptool</code> produces a set of files as output. You can find all files in <code>evoptool-file/temp</code> directory. Plus a tar.gz file containing such files can be produced at the end of the execution of <code>evoptool</code>. See the xml file for details.

evoptool-file/temp/data
contains the raw data of the statistics according to the xml file

evoptool-file/temp/gnuplot
contains the gnuplot files to produce images of the statistics

evoptool-file/temp/image
contains images of the statistics produced according to the xml file

evoptool-file/temp/support
contains logs

== Documentation ==

==== Implement a new benchmark function====

Benchmarks are defined in the <code>function</code> module. A benchmark is the maximization problem of a real valued function defined over a vector of n binary variables. Functions are maximized in <code>evoptool</code>. In order to implement a new benchmark function you have to create a new <code>class</code> that inherits from <code>ObjectiveFunction</code> in the <code>common</code> module. Take a look at the <code>OneMax</code> benchmark function.

Among the arguments of the constructor of the <code>ObjectiveFunction</code> class there must be the size of the benchmark, which may or may not be a parameter of the new benchmark.

OneMax::OneMax(int size) : ObjectiveFunction(size)

In the constructor you have whether the maximum of the function is known or not

_knownSolution = true;

And in case this is known, set the minimum value and maximum value for the function

_minFitness = 0;
_maxFitness = size; //the maximum value of the OneMax function is defined as the sum of the bits of x set to one.

Besides, such values are used in the normalization of the functions in the plots of the statistics.

Each benchmark must implement the <code>f</code> method, which takes the <code>BinaryString</code> x and return f(x). For instance, for <code>OneMax</code> you have

double OneMax::f(BinaryString *bi) {
 if (bi != NULL) {
  if(!(bi->validCache())) {
   /* Fitness cache value not valid */
   int sum = 0;
   for (int j = 0; j < _size; j++) {
    sum = sum + bi->get(j);
   }
   bi->setFitnessCache(sum);
   return sum;
  } else {
   return bi->getFitnessCache();
  }
 } else {
  cerr << "[OneMax::f] binary instance cannot be null" << endl;
  return 0;
 }
}

In order to avoid multiple evaluations of the same <code>BinaryString</code> x, a caching mechanism has been implemented.

Moreover, you are asked to implement the <code>exportInteration</code> function, which return an <code>HyperGraph</code> which represents the interactions present in the function. In order to determine such hypergraph, start from the polinomial representation of the function, and for each monomial introduce a new hyperedge in the hypergraph.

For the <code>OneMax</code> function, such representation corresponds to the independence graph, since such function is linear.

HyperGraph* OneMax::exportInteractions() {
 HyperGraph *interactions = new HyperGraph();
 interactions->createIndependenceGraph(_size);
 return interactions;
}

In <code>Evoptool.h</code> add an entry in the <code>Tasks</code> enum.

/* This enumeration defines an identifier for each task function. */
typedef enum {
 ONE_MAX = 7,
} Tasks;

This value will identify uniquely the benchmark in the xml file. In the <code>XMLParser.cpp</code> file, add an entry for the new function.

bool XMLParser::parseTask(xmlpp::TextReader &reader, Evoptool::TestParameters *params) {
 ..
 switch (task) {
  case Evoptool::ONE_MAX: params->task = new OneMax(size);
  break;
  ..
  default: return false;
 }
 ..
}

Additional parameters can be obtained using the xml TextReader object, as for the <code>ForPeaks</code> function.

case Evoptool::FOUR_PEAKS:
 value = readNodeContent(reader, "peaks", &errorFlag);
 if (errorFlag) return false;
 int peaks = toInt(value);
 params->task = new FourPeaks(size, peaks);
 break;

Finally in the xml file, a function can set with the <code>task</code> tag, together with all parameters.

<task>
 <name>7</name>
 <size>64</size>
</task>

==== To create a new algorithm (draft) ====

1. Implement a new algorithm

All algorithm must implement intiAlgorithm, and call Algorithm::initAlgorithm
same thing for
Algorithm::run();

2. Add an entry in Evoptool.h

typedef enum {
DEUM
} Algorithms;

3. modify the file
core/src/XMLParser.cpp
and insert an new entry for your algorithm in
bool XMLParser::parseAlgorithms
for instance

{ Evoptool::DEUM, 5, (char*) "IDDDI" } // Pop, percElitism, percSelec, CoolRate, GibbsIterations
where the first argument is the class of the algorithm
the second the number of paramers parsed in the xml file
the third the types of each parameter

4. add a case in the switch that follows in
bool XMLParser::parseAlgorithms

for instance
case Evoptool::EXTENDEDFCA:
algos[i] = new extendedFCA(intVal[0], doubleVal[0], doubleVal[1], intVal[1], intVal[2], params->rng);
algos[i]->initAlgorithm(params->task);
break;

where the algorithm is instantiated

5. Add an entry for your algorithm in
core/src/Algorithms.h

6. Add a line in
evoptool-file/exec-scripts/example.xml
as a documenation for the parameters of your algorithm.
Choose a new Id for your algorithm
Types indicates then type of the parameters (the order is important) that will must be specified
in the xml file (see <algo>) and are passed to the constructor of the algorithm when the object is instantiated
I = integer
D = double
B = bool

==== Run an algorithm in a C++ program ====

The simplest way to do this is to create a new submodule in <code>core</code>, i.e., a new source directory within the source directory of a module
For instance, the steps to create a new submodule named <code>myexample</code> are

1. copy the example submodule <code>exampleRunAlgorithm</code> in a new folder named <code>myexample</code> in

evoptool/core/src

2. modify the <code>Makefile</code> in the <code>myexample</code> directory, see comments in the makefile for more details.

3. edit the <code>main</code> function in the source file, if you need you can create other C++ and .h files in the same folder.

4. from <code>evoptool/core/src/myexample</code> run

make bin

The bin file is create in <code>evoptool/core/bin</code> and copied in <code>evoptool/bin</code>

NOTICE that <code>evoptool/core/bin</code> may be deleted after a <code>make cleanall</code>

5. from <code>evoptool/bin</code> run

./myexample

Evoptool: Evolutionary Optimization Tool

2011-10-22T15:40:45Z

LuigiMalago: /* Installation */

== Description ==

Evolutionary Optimization Tool (Evoptool) is an open source optimization tool writte in C++, distributed under GNU General Public License. Evoptool implements meta-heuristics based on the Evolutionary Computation paradigm and aims to provide a common platform for the development and test of new algorithms, in order to facilitate the performance comparison activity. Evoptool offers a wide set of benchmark problems, from classical toy samples to more complex tasks, and a collection of algorithm implementations from Genetic Algorithms and Estimation of Distribution Algorithms paradigms. Evoptool is flexible, easy to extend, also with algorithms based on other approaches other from EAs.

== The Evoptool Team ==

*[[User:MatteoMatteucci| Matteo Matteucci]] - matteucci [AT] elet.polimi.it

*[[http://www.dei.polimi.it/personale/dettaglio.php?id_persona=829&id_sezione=&lettera=M&idlang=ita| Luigi Malagò]] - malago [AT] elet.polimi.it

*[[User:GabrieleValentini| Gabriele Valentini]] - gvalentini [AT] iridia.ulb.ac.be

*Cucci Davide - cucci [AT] elet.polimi.it

'''Formerly involved'''
*Emanuele Corsano

== Mailing List ==
http://groups.google.com/group/evoptool

== Download ==

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Developers may also access unstable branch. Contact the evoptool team for more details.

== Installation ==
Follow these steps in order to compile evoptool

1. Download source code from svn

Refer to trunk for the lastest (stable?) version of evoptool

2. First you need to manually compile the <code>l1_logreg-0.8.2</code> package, http://www.stanford.edu/~boyd/l1_logreg/
whose source are already included in the evoptool repository. In order to do that follow the instrunctions in
<code>README.evoptool</code> in the <code>l1_logreg-0.8.2</code> directory

Next, compile <code><id_dist/code> following the instructions in <code>README.evoptool<code> in the <code><id_dist/code> folder

3. Then you need to compile a module at a time. Each module is included in a different folder.
To compile a module, from go to the module source folder and do make lib. For instance, for the module named <code>common</code>

cd common/src
make lib
cd ..

Compile modules in the following order

common
functions
ga
eda
stochastic

To clean a module, do

make clean

from the module source directory

4. Go to <code>core</code> module and type

make exe

Binary files will be copied in the <code>bin</code> directory in the root as well as the <code>bin</code> directory of the <code>core</code> module

'''Required packages'''
* Libraries

** ''gtkmm-2.4''
** ''glademm-2.4''
** ''gthread-2.0''
** ''sigc++-2.0''
** ''opencv'' (see for instance http://www.samontab.com/web/2011/06/installing-opencv-2-2-in-ubuntu-11-04/)
** ''gsl''
** ''gslcblas''
** ''libxml++-2.6''

* Software
** ''gnuplot''

== Running ==

Right now <code>evoptool</code> only runs as a script. GUI is not maintained in the latest version.
The <code>evoptool</code> binary file is supposed to be run in the <code>bin</code> directory in the root, this is because right now the script looks for some configuration files, for the instances of the problems, and temp directories. If you want to run the script from other directories, you just need to copy in that directory the <code>evoptool-file</code> directory that you find in the <code>bin</code> directory. Link such directory instead of copying it is not safe if you run multiple scripts at the same time, since output files will be shared.

To run the algorithm you need to enter as input an xml file. For instance you can run

./evoptool evoptool-file/examples/unitTestOneMax.xml

The <code>evoptool-file/example</code> directory contains a set of xml files for different benchmarks and different algorithms.
Take a loot at the <code>example.xml</code> file for the documentation on hoe to set the parameters for an each execution of <code>evoptool</code>

Each execution of <code>evoptool</code> produces a set of files as output. You can find all files in <code>evoptool-file/temp</code> directory. Plus a tar.gz file containing such files can be produced at the end of the execution of <code>evoptool</code>. See the xml file for details.

evoptool-file/temp/data
contains the raw data of the statistics according to the xml file

evoptool-file/temp/gnuplot
contains the gnuplot files to produce images of the statistics

evoptool-file/temp/image
contains images of the statistics produced according to the xml file

evoptool-file/temp/support
contains logs

== Documentation ==

==== Implement a new benchmark function====

Benchmarks are defined in the <code>function</code> module. A benchmark is the maximization problem of a real valued function defined over a vector of n binary variables. Functions are maximized in <code>evoptool</code>. In order to implement a new benchmark function you have to create a new <code>class</code> that inherits from <code>ObjectiveFunction</code> in the <code>common</code> module. Take a look at the <code>OneMax</code> benchmark function.

Among the arguments of the constructor of the <code>ObjectiveFunction</code> class there must be the size of the benchmark, which may or may not be a parameter of the new benchmark.

OneMax::OneMax(int size) : ObjectiveFunction(size)

In the constructor you have whether the maximum of the function is known or not

_knownSolution = true;

And in case this is known, set the minimum value and maximum value for the function

_minFitness = 0;
_maxFitness = size; //the maximum value of the OneMax function is defined as the sum of the bits of x set to one.

Besides, such values are used in the normalization of the functions in the plots of the statistics.

Each benchmark must implement the <code>f</code> method, which takes the <code>BinaryString</code> x and return f(x). For instance, for <code>OneMax</code> you have

double OneMax::f(BinaryString *bi) {
 if (bi != NULL) {
  if(!(bi->validCache())) {
   /* Fitness cache value not valid */
   int sum = 0;
   for (int j = 0; j < _size; j++) {
    sum = sum + bi->get(j);
   }
   bi->setFitnessCache(sum);
   return sum;
  } else {
   return bi->getFitnessCache();
  }
 } else {
  cerr << "[OneMax::f] binary instance cannot be null" << endl;
  return 0;
 }
}

In order to avoid multiple evaluations of the same <code>BinaryString</code> x, a caching mechanism has been implemented.

Moreover, you are asked to implement the <code>exportInteration</code> function, which return an <code>HyperGraph</code> which represents the interactions present in the function. In order to determine such hypergraph, start from the polinomial representation of the function, and for each monomial introduce a new hyperedge in the hypergraph.

For the <code>OneMax</code> function, such representation corresponds to the independence graph, since such function is linear.

HyperGraph* OneMax::exportInteractions() {
 HyperGraph *interactions = new HyperGraph();
 interactions->createIndependenceGraph(_size);
 return interactions;
}

In <code>Evoptool.h</code> add an entry in the <code>Tasks</code> enum.

/* This enumeration defines an identifier for each task function. */
typedef enum {
 ONE_MAX = 7,
} Tasks;

This value will identify uniquely the benchmark in the xml file. In the <code>XMLParser.cpp</code> file, add an entry for the new function.

bool XMLParser::parseTask(xmlpp::TextReader &reader, Evoptool::TestParameters *params) {
 ..
 switch (task) {
  case Evoptool::ONE_MAX: params->task = new OneMax(size);
  break;
  ..
  default: return false;
 }
 ..
}

Additional parameters can be obtained using the xml TextReader object, as for the <code>ForPeaks</code> function.

case Evoptool::FOUR_PEAKS:
 value = readNodeContent(reader, "peaks", &errorFlag);
 if (errorFlag) return false;
 int peaks = toInt(value);
 params->task = new FourPeaks(size, peaks);
 break;

Finally in the xml file, a function can set with the <code>task</code> tag, together with all parameters.

<task>
 <name>7</name>
 <size>64</size>
</task>

==== To create a new algorithm (draft) ====

1. Implement a new algorithm

All algorithm must implement intiAlgorithm, and call Algorithm::initAlgorithm
same thing for
Algorithm::run();

2. Add an entry in Evoptool.h

typedef enum {
DEUM
} Algorithms;

3. modify the file
core/src/XMLParser.cpp
and insert an new entry for your algorithm in
bool XMLParser::parseAlgorithms
for instance

{ Evoptool::DEUM, 5, (char*) "IDDDI" } // Pop, percElitism, percSelec, CoolRate, GibbsIterations
where the first argument is the class of the algorithm
the second the number of paramers parsed in the xml file
the third the types of each parameter

4. add a case in the switch that follows in
bool XMLParser::parseAlgorithms

for instance
case Evoptool::EXTENDEDFCA:
algos[i] = new extendedFCA(intVal[0], doubleVal[0], doubleVal[1], intVal[1], intVal[2], params->rng);
algos[i]->initAlgorithm(params->task);
break;

where the algorithm is instantiated

5. Add an entry for your algorithm in
core/src/Algorithms.h

6. Add a line in
evoptool-file/exec-scripts/example.xml
as a documenation for the parameters of your algorithm.
Choose a new Id for your algorithm
Types indicates then type of the parameters (the order is important) that will must be specified
in the xml file (see <algo>) and are passed to the constructor of the algorithm when the object is instantiated
I = integer
D = double
B = bool

==== Run an algorithm in a C++ program ====

The simplest way to do this is to create a new submodule in <code>core</code>, i.e., a new source directory within the source directory of a module
For instance, the steps to create a new submodule named <code>myexample</code> are

1. copy the example submodule <code>exampleRunAlgorithm</code> in a new folder named <code>myexample</code> in

evoptool/core/src

2. modify the <code>Makefile</code> in the <code>myexample</code> directory, see comments in the makefile for more details.

3. edit the <code>main</code> function in the source file, if you need you can create other C++ and .h files in the same folder.

4. from <code>evoptool/core/src/myexample</code> run

make bin

The bin file is create in <code>evoptool/core/bin</code> and copied in <code>evoptool/bin</code>

NOTICE that <code>evoptool/core/bin</code> may be deleted after a <code>make cleanall</code>

5. from <code>evoptool/bin</code> run

./myexample

Evoptool: Evolutionary Optimization Tool

2011-10-22T15:40:26Z

LuigiMalago: /* Installation */

== Description ==

Evolutionary Optimization Tool (Evoptool) is an open source optimization tool writte in C++, distributed under GNU General Public License. Evoptool implements meta-heuristics based on the Evolutionary Computation paradigm and aims to provide a common platform for the development and test of new algorithms, in order to facilitate the performance comparison activity. Evoptool offers a wide set of benchmark problems, from classical toy samples to more complex tasks, and a collection of algorithm implementations from Genetic Algorithms and Estimation of Distribution Algorithms paradigms. Evoptool is flexible, easy to extend, also with algorithms based on other approaches other from EAs.

== The Evoptool Team ==

*[[User:MatteoMatteucci| Matteo Matteucci]] - matteucci [AT] elet.polimi.it

*[[http://www.dei.polimi.it/personale/dettaglio.php?id_persona=829&id_sezione=&lettera=M&idlang=ita| Luigi Malagò]] - malago [AT] elet.polimi.it

*[[User:GabrieleValentini| Gabriele Valentini]] - gvalentini [AT] iridia.ulb.ac.be

*Cucci Davide - cucci [AT] elet.polimi.it

'''Formerly involved'''
*Emanuele Corsano

== Mailing List ==
http://groups.google.com/group/evoptool

== Download ==

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Developers may also access unstable branch. Contact the evoptool team for more details.

== Installation ==
Follow these steps in order to compile evoptool

1. Download source code from svn https://svn.ws.dei.polimi.it/evoptool/

User
Password

Refer to trunk for the lastest (stable?) version of evoptool

2. First you need to manually compile the <code>l1_logreg-0.8.2</code> package, http://www.stanford.edu/~boyd/l1_logreg/
whose source are already included in the evoptool repository. In order to do that follow the instrunctions in
<code>README.evoptool</code> in the <code>l1_logreg-0.8.2</code> directory

Next, compile <code><id_dist/code> following the instructions in <code>README.evoptool<code> in the <code><id_dist/code> folder

3. Then you need to compile a module at a time. Each module is included in a different folder.
To compile a module, from go to the module source folder and do make lib. For instance, for the module named <code>common</code>

cd common/src
make lib
cd ..

Compile modules in the following order

common
functions
ga
eda
stochastic

To clean a module, do

make clean

from the module source directory

4. Go to <code>core</code> module and type

make exe

Binary files will be copied in the <code>bin</code> directory in the root as well as the <code>bin</code> directory of the <code>core</code> module

'''Required packages'''
* Libraries

** ''gtkmm-2.4''
** ''glademm-2.4''
** ''gthread-2.0''
** ''sigc++-2.0''
** ''opencv'' (see for instance http://www.samontab.com/web/2011/06/installing-opencv-2-2-in-ubuntu-11-04/)
** ''gsl''
** ''gslcblas''
** ''libxml++-2.6''

* Software
** ''gnuplot''

== Running ==

Right now <code>evoptool</code> only runs as a script. GUI is not maintained in the latest version.
The <code>evoptool</code> binary file is supposed to be run in the <code>bin</code> directory in the root, this is because right now the script looks for some configuration files, for the instances of the problems, and temp directories. If you want to run the script from other directories, you just need to copy in that directory the <code>evoptool-file</code> directory that you find in the <code>bin</code> directory. Link such directory instead of copying it is not safe if you run multiple scripts at the same time, since output files will be shared.

To run the algorithm you need to enter as input an xml file. For instance you can run

./evoptool evoptool-file/examples/unitTestOneMax.xml

The <code>evoptool-file/example</code> directory contains a set of xml files for different benchmarks and different algorithms.
Take a loot at the <code>example.xml</code> file for the documentation on hoe to set the parameters for an each execution of <code>evoptool</code>

Each execution of <code>evoptool</code> produces a set of files as output. You can find all files in <code>evoptool-file/temp</code> directory. Plus a tar.gz file containing such files can be produced at the end of the execution of <code>evoptool</code>. See the xml file for details.

evoptool-file/temp/data
contains the raw data of the statistics according to the xml file

evoptool-file/temp/gnuplot
contains the gnuplot files to produce images of the statistics

evoptool-file/temp/image
contains images of the statistics produced according to the xml file

evoptool-file/temp/support
contains logs

== Documentation ==

==== Implement a new benchmark function====

Benchmarks are defined in the <code>function</code> module. A benchmark is the maximization problem of a real valued function defined over a vector of n binary variables. Functions are maximized in <code>evoptool</code>. In order to implement a new benchmark function you have to create a new <code>class</code> that inherits from <code>ObjectiveFunction</code> in the <code>common</code> module. Take a look at the <code>OneMax</code> benchmark function.

Among the arguments of the constructor of the <code>ObjectiveFunction</code> class there must be the size of the benchmark, which may or may not be a parameter of the new benchmark.

OneMax::OneMax(int size) : ObjectiveFunction(size)

In the constructor you have whether the maximum of the function is known or not

_knownSolution = true;

And in case this is known, set the minimum value and maximum value for the function

_minFitness = 0;
_maxFitness = size; //the maximum value of the OneMax function is defined as the sum of the bits of x set to one.

Besides, such values are used in the normalization of the functions in the plots of the statistics.

Each benchmark must implement the <code>f</code> method, which takes the <code>BinaryString</code> x and return f(x). For instance, for <code>OneMax</code> you have

double OneMax::f(BinaryString *bi) {
 if (bi != NULL) {
  if(!(bi->validCache())) {
   /* Fitness cache value not valid */
   int sum = 0;
   for (int j = 0; j < _size; j++) {
    sum = sum + bi->get(j);
   }
   bi->setFitnessCache(sum);
   return sum;
  } else {
   return bi->getFitnessCache();
  }
 } else {
  cerr << "[OneMax::f] binary instance cannot be null" << endl;
  return 0;
 }
}

In order to avoid multiple evaluations of the same <code>BinaryString</code> x, a caching mechanism has been implemented.

Moreover, you are asked to implement the <code>exportInteration</code> function, which return an <code>HyperGraph</code> which represents the interactions present in the function. In order to determine such hypergraph, start from the polinomial representation of the function, and for each monomial introduce a new hyperedge in the hypergraph.

For the <code>OneMax</code> function, such representation corresponds to the independence graph, since such function is linear.

HyperGraph* OneMax::exportInteractions() {
 HyperGraph *interactions = new HyperGraph();
 interactions->createIndependenceGraph(_size);
 return interactions;
}

In <code>Evoptool.h</code> add an entry in the <code>Tasks</code> enum.

/* This enumeration defines an identifier for each task function. */
typedef enum {
 ONE_MAX = 7,
} Tasks;

This value will identify uniquely the benchmark in the xml file. In the <code>XMLParser.cpp</code> file, add an entry for the new function.

bool XMLParser::parseTask(xmlpp::TextReader &reader, Evoptool::TestParameters *params) {
 ..
 switch (task) {
  case Evoptool::ONE_MAX: params->task = new OneMax(size);
  break;
  ..
  default: return false;
 }
 ..
}

Additional parameters can be obtained using the xml TextReader object, as for the <code>ForPeaks</code> function.

case Evoptool::FOUR_PEAKS:
 value = readNodeContent(reader, "peaks", &errorFlag);
 if (errorFlag) return false;
 int peaks = toInt(value);
 params->task = new FourPeaks(size, peaks);
 break;

Finally in the xml file, a function can set with the <code>task</code> tag, together with all parameters.

<task>
 <name>7</name>
 <size>64</size>
</task>

==== To create a new algorithm (draft) ====

1. Implement a new algorithm

All algorithm must implement intiAlgorithm, and call Algorithm::initAlgorithm
same thing for
Algorithm::run();

2. Add an entry in Evoptool.h

typedef enum {
DEUM
} Algorithms;

3. modify the file
core/src/XMLParser.cpp
and insert an new entry for your algorithm in
bool XMLParser::parseAlgorithms
for instance

{ Evoptool::DEUM, 5, (char*) "IDDDI" } // Pop, percElitism, percSelec, CoolRate, GibbsIterations
where the first argument is the class of the algorithm
the second the number of paramers parsed in the xml file
the third the types of each parameter

4. add a case in the switch that follows in
bool XMLParser::parseAlgorithms

for instance
case Evoptool::EXTENDEDFCA:
algos[i] = new extendedFCA(intVal[0], doubleVal[0], doubleVal[1], intVal[1], intVal[2], params->rng);
algos[i]->initAlgorithm(params->task);
break;

where the algorithm is instantiated

5. Add an entry for your algorithm in
core/src/Algorithms.h

6. Add a line in
evoptool-file/exec-scripts/example.xml
as a documenation for the parameters of your algorithm.
Choose a new Id for your algorithm
Types indicates then type of the parameters (the order is important) that will must be specified
in the xml file (see <algo>) and are passed to the constructor of the algorithm when the object is instantiated
I = integer
D = double
B = bool

==== Run an algorithm in a C++ program ====

The simplest way to do this is to create a new submodule in <code>core</code>, i.e., a new source directory within the source directory of a module
For instance, the steps to create a new submodule named <code>myexample</code> are

1. copy the example submodule <code>exampleRunAlgorithm</code> in a new folder named <code>myexample</code> in

evoptool/core/src

2. modify the <code>Makefile</code> in the <code>myexample</code> directory, see comments in the makefile for more details.

3. edit the <code>main</code> function in the source file, if you need you can create other C++ and .h files in the same folder.

4. from <code>evoptool/core/src/myexample</code> run

make bin

The bin file is create in <code>evoptool/core/bin</code> and copied in <code>evoptool/bin</code>

NOTICE that <code>evoptool/core/bin</code> may be deleted after a <code>make cleanall</code>

5. from <code>evoptool/bin</code> run

./myexample

Evoptool: Evolutionary Optimization Tool

2011-10-22T15:39:28Z

LuigiMalago: /* Download */

== Description ==

Evolutionary Optimization Tool (Evoptool) is an open source optimization tool writte in C++, distributed under GNU General Public License. Evoptool implements meta-heuristics based on the Evolutionary Computation paradigm and aims to provide a common platform for the development and test of new algorithms, in order to facilitate the performance comparison activity. Evoptool offers a wide set of benchmark problems, from classical toy samples to more complex tasks, and a collection of algorithm implementations from Genetic Algorithms and Estimation of Distribution Algorithms paradigms. Evoptool is flexible, easy to extend, also with algorithms based on other approaches other from EAs.

== The Evoptool Team ==

*[[User:MatteoMatteucci| Matteo Matteucci]] - matteucci [AT] elet.polimi.it

*[[http://www.dei.polimi.it/personale/dettaglio.php?id_persona=829&id_sezione=&lettera=M&idlang=ita| Luigi Malagò]] - malago [AT] elet.polimi.it

*[[User:GabrieleValentini| Gabriele Valentini]] - gvalentini [AT] iridia.ulb.ac.be

*Cucci Davide - cucci [AT] elet.polimi.it

'''Formerly involved'''
*Emanuele Corsano

== Mailing List ==
http://groups.google.com/group/evoptool

== Download ==

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Developers may also access unstable branch. Contact the evoptool team for more details.

== Installation ==
Follow these steps in order to compile evoptool

1. Download source code from svn https://svn.ws.dei.polimi.it/evoptool/

User
Password

Refer to trunk for the lastest (instable) version of evoptool

2. First you need to manually compile the <code>l1_logreg-0.8.2</code> package, http://www.stanford.edu/~boyd/l1_logreg/
whose source are already included in the evoptool repository. In order to do that follow the instrunctions in
<code>README.evoptool</code> in the <code>l1_logreg-0.8.2</code> directory

Next, compile <code><id_dist/code> following the instructions in <code>README.evoptool<code> in the <code><id_dist/code> folder

3. Then you need to compile a module at a time. Each module is included in a different folder.
To compile a module, from go to the module source folder and do make lib. For instance, for the module named <code>common</code>

cd common/src
make lib
cd ..

Compile modules in the following order

common
functions
ga
eda
stochastic

To clean a module, do

make clean

from the module source directory

4. Go to <code>core</code> module and type

make exe

Binary files will be copied in the <code>bin</code> directory in the root as well as the <code>bin</code> directory of the <code>core</code> module

'''Required packages'''
* Libraries

** ''gtkmm-2.4''
** ''glademm-2.4''
** ''gthread-2.0''
** ''sigc++-2.0''
** ''opencv'' (see for instance http://www.samontab.com/web/2011/06/installing-opencv-2-2-in-ubuntu-11-04/)
** ''gsl''
** ''gslcblas''
** ''libxml++-2.6''

* Software
** ''gnuplot''

== Running ==

Right now <code>evoptool</code> only runs as a script. GUI is not maintained in the latest version.
The <code>evoptool</code> binary file is supposed to be run in the <code>bin</code> directory in the root, this is because right now the script looks for some configuration files, for the instances of the problems, and temp directories. If you want to run the script from other directories, you just need to copy in that directory the <code>evoptool-file</code> directory that you find in the <code>bin</code> directory. Link such directory instead of copying it is not safe if you run multiple scripts at the same time, since output files will be shared.

To run the algorithm you need to enter as input an xml file. For instance you can run

./evoptool evoptool-file/examples/unitTestOneMax.xml

The <code>evoptool-file/example</code> directory contains a set of xml files for different benchmarks and different algorithms.
Take a loot at the <code>example.xml</code> file for the documentation on hoe to set the parameters for an each execution of <code>evoptool</code>

Each execution of <code>evoptool</code> produces a set of files as output. You can find all files in <code>evoptool-file/temp</code> directory. Plus a tar.gz file containing such files can be produced at the end of the execution of <code>evoptool</code>. See the xml file for details.

evoptool-file/temp/data
contains the raw data of the statistics according to the xml file

evoptool-file/temp/gnuplot
contains the gnuplot files to produce images of the statistics

evoptool-file/temp/image
contains images of the statistics produced according to the xml file

evoptool-file/temp/support
contains logs

== Documentation ==

==== Implement a new benchmark function====

Benchmarks are defined in the <code>function</code> module. A benchmark is the maximization problem of a real valued function defined over a vector of n binary variables. Functions are maximized in <code>evoptool</code>. In order to implement a new benchmark function you have to create a new <code>class</code> that inherits from <code>ObjectiveFunction</code> in the <code>common</code> module. Take a look at the <code>OneMax</code> benchmark function.

Among the arguments of the constructor of the <code>ObjectiveFunction</code> class there must be the size of the benchmark, which may or may not be a parameter of the new benchmark.

OneMax::OneMax(int size) : ObjectiveFunction(size)

In the constructor you have whether the maximum of the function is known or not

_knownSolution = true;

And in case this is known, set the minimum value and maximum value for the function

_minFitness = 0;
_maxFitness = size; //the maximum value of the OneMax function is defined as the sum of the bits of x set to one.

Besides, such values are used in the normalization of the functions in the plots of the statistics.

Each benchmark must implement the <code>f</code> method, which takes the <code>BinaryString</code> x and return f(x). For instance, for <code>OneMax</code> you have

double OneMax::f(BinaryString *bi) {
 if (bi != NULL) {
  if(!(bi->validCache())) {
   /* Fitness cache value not valid */
   int sum = 0;
   for (int j = 0; j < _size; j++) {
    sum = sum + bi->get(j);
   }
   bi->setFitnessCache(sum);
   return sum;
  } else {
   return bi->getFitnessCache();
  }
 } else {
  cerr << "[OneMax::f] binary instance cannot be null" << endl;
  return 0;
 }
}

In order to avoid multiple evaluations of the same <code>BinaryString</code> x, a caching mechanism has been implemented.

Moreover, you are asked to implement the <code>exportInteration</code> function, which return an <code>HyperGraph</code> which represents the interactions present in the function. In order to determine such hypergraph, start from the polinomial representation of the function, and for each monomial introduce a new hyperedge in the hypergraph.

For the <code>OneMax</code> function, such representation corresponds to the independence graph, since such function is linear.

HyperGraph* OneMax::exportInteractions() {
 HyperGraph *interactions = new HyperGraph();
 interactions->createIndependenceGraph(_size);
 return interactions;
}

In <code>Evoptool.h</code> add an entry in the <code>Tasks</code> enum.

/* This enumeration defines an identifier for each task function. */
typedef enum {
 ONE_MAX = 7,
} Tasks;

This value will identify uniquely the benchmark in the xml file. In the <code>XMLParser.cpp</code> file, add an entry for the new function.

bool XMLParser::parseTask(xmlpp::TextReader &reader, Evoptool::TestParameters *params) {
 ..
 switch (task) {
  case Evoptool::ONE_MAX: params->task = new OneMax(size);
  break;
  ..
  default: return false;
 }
 ..
}

Additional parameters can be obtained using the xml TextReader object, as for the <code>ForPeaks</code> function.

case Evoptool::FOUR_PEAKS:
 value = readNodeContent(reader, "peaks", &errorFlag);
 if (errorFlag) return false;
 int peaks = toInt(value);
 params->task = new FourPeaks(size, peaks);
 break;

Finally in the xml file, a function can set with the <code>task</code> tag, together with all parameters.

<task>
 <name>7</name>
 <size>64</size>
</task>

==== To create a new algorithm (draft) ====

1. Implement a new algorithm

All algorithm must implement intiAlgorithm, and call Algorithm::initAlgorithm
same thing for
Algorithm::run();

2. Add an entry in Evoptool.h

typedef enum {
DEUM
} Algorithms;

3. modify the file
core/src/XMLParser.cpp
and insert an new entry for your algorithm in
bool XMLParser::parseAlgorithms
for instance

{ Evoptool::DEUM, 5, (char*) "IDDDI" } // Pop, percElitism, percSelec, CoolRate, GibbsIterations
where the first argument is the class of the algorithm
the second the number of paramers parsed in the xml file
the third the types of each parameter

4. add a case in the switch that follows in
bool XMLParser::parseAlgorithms

for instance
case Evoptool::EXTENDEDFCA:
algos[i] = new extendedFCA(intVal[0], doubleVal[0], doubleVal[1], intVal[1], intVal[2], params->rng);
algos[i]->initAlgorithm(params->task);
break;

where the algorithm is instantiated

5. Add an entry for your algorithm in
core/src/Algorithms.h

6. Add a line in
evoptool-file/exec-scripts/example.xml
as a documenation for the parameters of your algorithm.
Choose a new Id for your algorithm
Types indicates then type of the parameters (the order is important) that will must be specified
in the xml file (see <algo>) and are passed to the constructor of the algorithm when the object is instantiated
I = integer
D = double
B = bool

==== Run an algorithm in a C++ program ====

The simplest way to do this is to create a new submodule in <code>core</code>, i.e., a new source directory within the source directory of a module
For instance, the steps to create a new submodule named <code>myexample</code> are

1. copy the example submodule <code>exampleRunAlgorithm</code> in a new folder named <code>myexample</code> in

evoptool/core/src

2. modify the <code>Makefile</code> in the <code>myexample</code> directory, see comments in the makefile for more details.

3. edit the <code>main</code> function in the source file, if you need you can create other C++ and .h files in the same folder.

4. from <code>evoptool/core/src/myexample</code> run

make bin

The bin file is create in <code>evoptool/core/bin</code> and copied in <code>evoptool/bin</code>

NOTICE that <code>evoptool/core/bin</code> may be deleted after a <code>make cleanall</code>

5. from <code>evoptool/bin</code> run

./myexample

Evoptool: Evolutionary Optimization Tool

2011-10-22T15:39:15Z

LuigiMalago: /* Download */

== Description ==

Evolutionary Optimization Tool (Evoptool) is an open source optimization tool writte in C++, distributed under GNU General Public License. Evoptool implements meta-heuristics based on the Evolutionary Computation paradigm and aims to provide a common platform for the development and test of new algorithms, in order to facilitate the performance comparison activity. Evoptool offers a wide set of benchmark problems, from classical toy samples to more complex tasks, and a collection of algorithm implementations from Genetic Algorithms and Estimation of Distribution Algorithms paradigms. Evoptool is flexible, easy to extend, also with algorithms based on other approaches other from EAs.

== The Evoptool Team ==

*[[User:MatteoMatteucci| Matteo Matteucci]] - matteucci [AT] elet.polimi.it

*[[http://www.dei.polimi.it/personale/dettaglio.php?id_persona=829&id_sezione=&lettera=M&idlang=ita| Luigi Malagò]] - malago [AT] elet.polimi.it

*[[User:GabrieleValentini| Gabriele Valentini]] - gvalentini [AT] iridia.ulb.ac.be

*Cucci Davide - cucci [AT] elet.polimi.it

'''Formerly involved'''
*Emanuele Corsano

== Mailing List ==
http://groups.google.com/group/evoptool

== Download ==

svn checkout https://svn.ws.dei.polimi.it/evoptool/trunk --username usrevoptool --password evoptoolpsw

Developers may also access unstable branch. Contact the evoptool team for more details.

== Installation ==
Follow these steps in order to compile evoptool

1. Download source code from svn https://svn.ws.dei.polimi.it/evoptool/

User
Password

Refer to trunk for the lastest (instable) version of evoptool

2. First you need to manually compile the <code>l1_logreg-0.8.2</code> package, http://www.stanford.edu/~boyd/l1_logreg/
whose source are already included in the evoptool repository. In order to do that follow the instrunctions in
<code>README.evoptool</code> in the <code>l1_logreg-0.8.2</code> directory

Next, compile <code><id_dist/code> following the instructions in <code>README.evoptool<code> in the <code><id_dist/code> folder

3. Then you need to compile a module at a time. Each module is included in a different folder.
To compile a module, from go to the module source folder and do make lib. For instance, for the module named <code>common</code>

cd common/src
make lib
cd ..

Compile modules in the following order

common
functions
ga
eda
stochastic

To clean a module, do

make clean

from the module source directory

4. Go to <code>core</code> module and type

make exe

Binary files will be copied in the <code>bin</code> directory in the root as well as the <code>bin</code> directory of the <code>core</code> module

'''Required packages'''
* Libraries

** ''gtkmm-2.4''
** ''glademm-2.4''
** ''gthread-2.0''
** ''sigc++-2.0''
** ''opencv'' (see for instance http://www.samontab.com/web/2011/06/installing-opencv-2-2-in-ubuntu-11-04/)
** ''gsl''
** ''gslcblas''
** ''libxml++-2.6''

* Software
** ''gnuplot''

== Running ==

Right now <code>evoptool</code> only runs as a script. GUI is not maintained in the latest version.
The <code>evoptool</code> binary file is supposed to be run in the <code>bin</code> directory in the root, this is because right now the script looks for some configuration files, for the instances of the problems, and temp directories. If you want to run the script from other directories, you just need to copy in that directory the <code>evoptool-file</code> directory that you find in the <code>bin</code> directory. Link such directory instead of copying it is not safe if you run multiple scripts at the same time, since output files will be shared.

To run the algorithm you need to enter as input an xml file. For instance you can run

./evoptool evoptool-file/examples/unitTestOneMax.xml

The <code>evoptool-file/example</code> directory contains a set of xml files for different benchmarks and different algorithms.
Take a loot at the <code>example.xml</code> file for the documentation on hoe to set the parameters for an each execution of <code>evoptool</code>

Each execution of <code>evoptool</code> produces a set of files as output. You can find all files in <code>evoptool-file/temp</code> directory. Plus a tar.gz file containing such files can be produced at the end of the execution of <code>evoptool</code>. See the xml file for details.

evoptool-file/temp/data
contains the raw data of the statistics according to the xml file

evoptool-file/temp/gnuplot
contains the gnuplot files to produce images of the statistics

evoptool-file/temp/image
contains images of the statistics produced according to the xml file

evoptool-file/temp/support
contains logs

== Documentation ==

==== Implement a new benchmark function====

Benchmarks are defined in the <code>function</code> module. A benchmark is the maximization problem of a real valued function defined over a vector of n binary variables. Functions are maximized in <code>evoptool</code>. In order to implement a new benchmark function you have to create a new <code>class</code> that inherits from <code>ObjectiveFunction</code> in the <code>common</code> module. Take a look at the <code>OneMax</code> benchmark function.

Among the arguments of the constructor of the <code>ObjectiveFunction</code> class there must be the size of the benchmark, which may or may not be a parameter of the new benchmark.

OneMax::OneMax(int size) : ObjectiveFunction(size)

In the constructor you have whether the maximum of the function is known or not

_knownSolution = true;

And in case this is known, set the minimum value and maximum value for the function

_minFitness = 0;
_maxFitness = size; //the maximum value of the OneMax function is defined as the sum of the bits of x set to one.

Besides, such values are used in the normalization of the functions in the plots of the statistics.

Each benchmark must implement the <code>f</code> method, which takes the <code>BinaryString</code> x and return f(x). For instance, for <code>OneMax</code> you have

double OneMax::f(BinaryString *bi) {
 if (bi != NULL) {
  if(!(bi->validCache())) {
   /* Fitness cache value not valid */
   int sum = 0;
   for (int j = 0; j < _size; j++) {
    sum = sum + bi->get(j);
   }
   bi->setFitnessCache(sum);
   return sum;
  } else {
   return bi->getFitnessCache();
  }
 } else {
  cerr << "[OneMax::f] binary instance cannot be null" << endl;
  return 0;
 }
}

In order to avoid multiple evaluations of the same <code>BinaryString</code> x, a caching mechanism has been implemented.

Moreover, you are asked to implement the <code>exportInteration</code> function, which return an <code>HyperGraph</code> which represents the interactions present in the function. In order to determine such hypergraph, start from the polinomial representation of the function, and for each monomial introduce a new hyperedge in the hypergraph.

For the <code>OneMax</code> function, such representation corresponds to the independence graph, since such function is linear.

HyperGraph* OneMax::exportInteractions() {
 HyperGraph *interactions = new HyperGraph();
 interactions->createIndependenceGraph(_size);
 return interactions;
}

In <code>Evoptool.h</code> add an entry in the <code>Tasks</code> enum.

/* This enumeration defines an identifier for each task function. */
typedef enum {
 ONE_MAX = 7,
} Tasks;

This value will identify uniquely the benchmark in the xml file. In the <code>XMLParser.cpp</code> file, add an entry for the new function.

bool XMLParser::parseTask(xmlpp::TextReader &reader, Evoptool::TestParameters *params) {
 ..
 switch (task) {
  case Evoptool::ONE_MAX: params->task = new OneMax(size);
  break;
  ..
  default: return false;
 }
 ..
}

Additional parameters can be obtained using the xml TextReader object, as for the <code>ForPeaks</code> function.

case Evoptool::FOUR_PEAKS:
 value = readNodeContent(reader, "peaks", &errorFlag);
 if (errorFlag) return false;
 int peaks = toInt(value);
 params->task = new FourPeaks(size, peaks);
 break;

Finally in the xml file, a function can set with the <code>task</code> tag, together with all parameters.

<task>
 <name>7</name>
 <size>64</size>
</task>

==== To create a new algorithm (draft) ====

1. Implement a new algorithm

All algorithm must implement intiAlgorithm, and call Algorithm::initAlgorithm
same thing for
Algorithm::run();

2. Add an entry in Evoptool.h

typedef enum {
DEUM
} Algorithms;

3. modify the file
core/src/XMLParser.cpp
and insert an new entry for your algorithm in
bool XMLParser::parseAlgorithms
for instance

{ Evoptool::DEUM, 5, (char*) "IDDDI" } // Pop, percElitism, percSelec, CoolRate, GibbsIterations
where the first argument is the class of the algorithm
the second the number of paramers parsed in the xml file
the third the types of each parameter

4. add a case in the switch that follows in
bool XMLParser::parseAlgorithms

for instance
case Evoptool::EXTENDEDFCA:
algos[i] = new extendedFCA(intVal[0], doubleVal[0], doubleVal[1], intVal[1], intVal[2], params->rng);
algos[i]->initAlgorithm(params->task);
break;

where the algorithm is instantiated

5. Add an entry for your algorithm in
core/src/Algorithms.h

6. Add a line in
evoptool-file/exec-scripts/example.xml
as a documenation for the parameters of your algorithm.
Choose a new Id for your algorithm
Types indicates then type of the parameters (the order is important) that will must be specified
in the xml file (see <algo>) and are passed to the constructor of the algorithm when the object is instantiated
I = integer
D = double
B = bool

==== Run an algorithm in a C++ program ====

The simplest way to do this is to create a new submodule in <code>core</code>, i.e., a new source directory within the source directory of a module
For instance, the steps to create a new submodule named <code>myexample</code> are

1. copy the example submodule <code>exampleRunAlgorithm</code> in a new folder named <code>myexample</code> in

evoptool/core/src

2. modify the <code>Makefile</code> in the <code>myexample</code> directory, see comments in the makefile for more details.

3. edit the <code>main</code> function in the source file, if you need you can create other C++ and .h files in the same folder.

4. from <code>evoptool/core/src/myexample</code> run

make bin

The bin file is create in <code>evoptool/core/bin</code> and copied in <code>evoptool/bin</code>

NOTICE that <code>evoptool/core/bin</code> may be deleted after a <code>make cleanall</code>

5. from <code>evoptool/bin</code> run

./myexample

Talk:Evoptool: Evolutionary Optimization Tool

2011-10-22T15:37:13Z

LuigiMalago: Blanked the page