Difference between revisions of "Evoptool: Evolutionary Optimization Tool"

From AIRWiki
Jump to: navigation, search
(→‎Project Documentation)
(→‎PPSN 2012)
 
(300 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
== '''Project profile''' ==
+
== Description ==
  
−
=== Project name ===
+
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.
−
evoptool: Evolutive Optimization Tool
+
  
−
Combining Estimation of Distribution Algorithms and other Evolutionary techniques for combinatorial optimization
+
== The Evoptool Team ==
  
−
=== Project short description ===
+
*[[User:MatteoMatteucci| Matteo Matteucci]] - matteucci [AT] elet.polimi.it
−
The project will focus on the study, implementation, comparison and analysis of different algorithms for combinatorial optimization using techniques and algorithms proposed in Evolutionary Computation. In particular we are interested in the study of Estimation of Distribution Algorithms, a recent meta-heuristic, often presented as an evolution of Genetic Algorithms, where classical crossover and mutation operators, used in genetic algorithms, are replaced with operators that come from statistics, such as sampling and estimation.
+
−
The focus will be on the implementation of new hybrid algorithms able to combine estimation of distribution algorithms with different approaches available in the evolutionary computation literature, such as genetic algorithms and evolutionary strategies, together with other local search techniques.
+
  
−
=== Dates ===
+
*[http://www.dei.polimi.it/personale/dettaglio.php?id_persona=829&id_sezione=&lettera=M&idlang=ita| Luigi Malagò] - malago [AT] elet.polimi.it
−
Start date: 2009/04/01
+
  
−
End date: till end
+
*[http://iridia.ulb.ac.be/~gvalentini/ Gabriele Valentini] - gvalentini [AT] iridia.ulb.ac.be
  
−
=== People involved ===
+
*[[User:DavideCucci| Davide Cucci]] - cucci [AT] elet.polimi.it
−
===== Project head(s) =====
+
−
M. Matteucci - [[User:MatteoMatteucci]]
+
  
−
L. Malagò - [[User:LuigiMalago]]
+
'''Formerly involved'''
 +
*Emanuele Corsano
  
−
===== Students currently working on the project =====
+
== PPSN 2012 ==
−
G. Valentini - [[User:GabrieleValentini]]
+
  
−
== '''Project Documentation''' ==
+
In this section we report the details of the experiments presented in the paper "Variable Transformations in Estimation of Distribution Algorithms", submitted to PPSN 2012.
  
−
Evoptool is a software with the purpose to compare the performance of several different algorithms from the Evolutive family and, for obvious reasons, with some algorithms from the classical Operation Research family.
+
The experiments were run using the unstable version of evoptool, which is available trought SVN at
−
Evoptool is written in C++ for the GNU/Linux platform and it exploit the Gtk libraries (in this case gtkmm libraries) and GNUplot utility. Inside this tool there are several implemented algorithms and some wrapped ones from already existing applications.
+
  
−
[[Image:Schermata.png|600px|thumb|center|Evoptool running on Ubuntu 9.04.]]
+
https://svn.ws.dei.polimi.it/evoptool/branches/unstable
  
−
==='''Software Modules''' ===
+
For each problem, Alternated Bits, Trap3, Trap3 Overlapping and Trep5, a python script is used to generate the Evoptool configuration files. For a given problm size ''n'', we chose a population size, run 24 instances of the test algorithm and check the success ratio. If it below 95%, we increase the population, otherwise we compute from these runs the average number of fitness function evaluations performed before the global optimum appears in the population. We increase the population exponentially with ''n'', so that ''N=n^k'' and each time the success ratio is below the chosen we set k=k+0.1.
−
Evoptool is made up of several different modules (or libraries). This architecture make easy to organize files and better understanding how the application work.  
+
  
−
* ''common - '' It contains commons classes and ancestors for the algorithm modules and for the optimization function module.
+
Each time an experiment is performed using Evoptool, a .tar file is produced which contain statistics and plots for each instance of the algorithms run and also aggregated averages. The python scripts we used name this tar files with the following convention:
−
* ''ga - '' It contains the implementation of several Genetic Algorithms.
+
−
* ''eda - '' It contains the implementation of several Estimation Distribution Algorithms.
+
−
* ''geda - '' It contains the implementation of several gEDAs.
+
−
* ''or - '' It contains the implementation of some algorithms from the classical Operation Research.
+
−
* ''opt-pbl - '' It contains the implementation of several objective functions (fitness), that represents different problem instances.
+
−
* ''gui - '' This module is the main one, it contains all the classes for manage GUI (algorithm decorators). From the other side it implements the multithread mechanism under the GUI, and last but not list it contains the wrapped applications and take care about wrapping. 
+
−
* ''misc - '' It contains general utility classes such rondom seed geerator.
+
−
* ''shared - ''
+
  
−
=== '''Hierarchies''' ===
+
algorithm-n-N-selection_rate-maps_number.tar
  
−
==== '''Algorithms Hierarchy''' ====
+
All the .tar files used to compute the result presented in the paper, along with the python scripts and everything else needed to reproduce the experiments are available trought SVN at
−
==== '''Decorators Hierarchy''' ====
+
−
==== '''Objective Functions Hierarchy''' ====
+
  
−
=== '''HowToDo''' ===
+
https://svn.ws.dei.polimi.it/evoptool/branches/papers/PPSN-2012-FCA/experiments/
−
==== '''How to Add an Algorithm ''' ====
+
 
−
==== '''How to Add an Objective Function ''' ====
+
== 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
 +
 
 +
(*) instances generated and solved with Spin Glass Server. This service is provided by COPhy and M. Jünger's group.
 +
http://www.informatik.uni-koeln.de/spinglass/
 +
 
 +
== 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) {
 +
  &nbsp;if (bi != NULL) {
 +
  &nbsp;&nbsp;if(!(bi->validCache())) {
 +
  &nbsp;&nbsp;&nbsp;/* Fitness cache value not valid */
 +
  &nbsp;&nbsp;&nbsp;int sum = 0;
 +
  &nbsp;&nbsp;&nbsp;for (int j = 0; j < _size; j++) {
 +
  &nbsp;&nbsp;&nbsp;&nbsp;sum = sum + bi->get(j);
 +
  &nbsp;&nbsp;&nbsp;}
 +
  &nbsp;&nbsp;&nbsp;bi->setFitnessCache(sum);
 +
  &nbsp;&nbsp;&nbsp;return sum;
 +
  &nbsp;&nbsp;} else {
 +
  &nbsp;&nbsp;&nbsp;return bi->getFitnessCache();
 +
  &nbsp;&nbsp;}
 +
  &nbsp;} else {
 +
  &nbsp;&nbsp;cerr << "[OneMax::f] binary instance cannot be null" << endl;
 +
  &nbsp;&nbsp;return 0;
 +
  &nbsp;}
 +
}
 +
 
 +
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() {
 +
  &nbsp;HyperGraph *interactions = new HyperGraph();
 +
  &nbsp;interactions->createIndependenceGraph(_size);
 +
  &nbsp;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 {
 +
  &nbsp;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) {
 +
  &nbsp;..
 +
  &nbsp;switch (task) {
 +
  &nbsp;&nbsp;case Evoptool::ONE_MAX: params->task = new OneMax(size);
 +
  &nbsp;&nbsp;break;
 +
  &nbsp;&nbsp;..
 +
  &nbsp;&nbsp;default: return false;
 +
  &nbsp;}
 +
  &nbsp;..
 +
  }
 +
 
 +
Additional parameters can be obtained using the xml TextReader object, as for the <code>ForPeaks</code> function.
 +
 
 +
  case Evoptool::FOUR_PEAKS:
 +
  &nbsp;value = readNodeContent(reader, "peaks", &errorFlag);
 +
  &nbsp;if (errorFlag) return false;
 +
  &nbsp;int peaks = toInt(value);
 +
  &nbsp;params->task = new FourPeaks(size, peaks);
 +
  &nbsp;break;
 +
 
 +
Finally in the xml file, a function can set with the <code>task</code> tag, together with all parameters.
 +
 
 +
  <task>
 +
  &nbsp;<name>7</name>
 +
  &nbsp;<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.

Latest revision as of 18:02, 14 April 2012

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

Formerly involved

  • Emanuele Corsano

PPSN 2012

In this section we report the details of the experiments presented in the paper "Variable Transformations in Estimation of Distribution Algorithms", submitted to PPSN 2012.

The experiments were run using the unstable version of evoptool, which is available trought SVN at

https://svn.ws.dei.polimi.it/evoptool/branches/unstable

For each problem, Alternated Bits, Trap3, Trap3 Overlapping and Trep5, a python script is used to generate the Evoptool configuration files. For a given problm size n, we chose a population size, run 24 instances of the test algorithm and check the success ratio. If it below 95%, we increase the population, otherwise we compute from these runs the average number of fitness function evaluations performed before the global optimum appears in the population. We increase the population exponentially with n, so that N=n^k and each time the success ratio is below the chosen we set k=k+0.1.

Each time an experiment is performed using Evoptool, a .tar file is produced which contain statistics and plots for each instance of the algorithms run and also aggregated averages. The python scripts we used name this tar files with the following convention:

algorithm-n-N-selection_rate-maps_number.tar

All the .tar files used to compute the result presented in the paper, along with the python scripts and everything else needed to reproduce the experiments are available trought SVN at

https://svn.ws.dei.polimi.it/evoptool/branches/papers/PPSN-2012-FCA/experiments/

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

(*) instances generated and solved with Spin Glass Server. This service is provided by COPhy and M. Jünger's group. http://www.informatik.uni-koeln.de/spinglass/

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 l1_logreg-0.8.2 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 README.evoptool in the l1_logreg-0.8.2 directory

Next, compile <id_dist/code> following the instructions in <code>README.evoptool in the <id_dist 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 common 

 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 core module and type 

 make exe

Binary files will be copied in the bin directory in the root as well as the bin directory of the core module

Required packages

  • Software
    • gnuplot
    • R (lars package)

Running

Right now evoptool only runs as a script. GUI is not maintained in the latest version. The evoptool binary file is supposed to be run in the bin 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 evoptool-file directory that you find in the bin 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 evoptool-file/example directory contains a set of xml files for different benchmarks and different algorithms. Take a loot at the example.xml file for the documentation on hoe to set the parameters for an each execution of evoptool

Each execution of evoptool produces a set of files as output. You can find all files in evoptool-file/temp directory. Plus a tar.gz file containing such files can be produced at the end of the execution of evoptool. 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 function module. A benchmark is the maximization problem of a real valued function defined over a vector of n binary variables. Functions are maximized in evoptool. In order to implement a new benchmark function you have to create a new class that inherits from ObjectiveFunction in the common module. Take a look at the OneMax benchmark function.

Among the arguments of the constructor of the ObjectiveFunction 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 f method, which takes the BinaryString x and return f(x). For instance, for OneMax 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 BinaryString x, a caching mechanism has been implemented.

Moreover, you are asked to implement the exportInteration function, which return an HyperGraph 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 OneMax 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 Evoptool.h add an entry in the Tasks 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 XMLParser.cpp 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 ForPeaks 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 task 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 Algorithms 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 bool XMLParser::parseAlgorithms and insert an new entry for your algorithm in the algorithmParameters 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 Algorithms enum just modified in Evoptool.h, the second is the number of parameters to be parsed in the xml configuration file and the third is a string specifying their type: I for integer and D for double.

4. add a case in the switch that follows in bool XMLParser::parseAlgorithms, 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, params->rng.

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 core, i.e., a new source directory within the source directory of a module For instance, the steps to create a new submodule named myexample are

1. copy the example submodule exampleRunAlgorithm in a new folder named myexample in 

 evoptool/core/src

2. modify the Makefile in the myexample directory, see comments in the makefile for more details.

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

4. from evoptool/core/src/myexample run 

 make bin

The bin file is create in evoptool/core/bin and copied in evoptool/bin

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

5. from evoptool/bin 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.

Retrieved from "https://airwiki.deib.polimi.it/index.php?title=Evoptool:_Evolutionary_Optimization_Tool&oldid=14894"