Difference between revisions of "Talk:Evoptool: Evolutionary Optimization Tool"

From AIRWiki
Jump to: navigation, search
(Add an Objective Function)
(Blanked the page)
Line 1: Line 1:
= ''ToDo List (only for developers)''=
* '''TODO:''' XMLParser incorrect propagation of erroFlag, does not discovers errors
* '''TODO''' DEUM: svd resolutor causes problems durign execution.
* '''TODO''' export data in tgz not in tar
* '''TODO''' BugFix, convertire XMLParser e tutti i decorator ad usare Algorithm->getName() invece che stringhe defini manualmente (inconsistenze).
= Old Page =
=== '''Graphic User Interface'''===
The graphic user interface of evoptool is quite intuitive. The user can easily customize his own experiment, and visualize the results graph. In the next rows there are shortly described the GUI componets and their use.
[[Image:Evo2.png|600px|thumb|center|Evoptool running on Ubuntu 9.04.]]
# ''Control Buttons.'' There are three control buttons which can be used to start or stop the execution of an experitment, and to force the update of the graphs.
# ''Objective Function Settings.'' This part of the toolbar allows the customization of the Objective Problem. It is possible to select an objective function type and fix the individual size as number of bits. 
# ''Average Mode Setting.'' Pushing this toggled button it is possible to enable ''Average Test Mode''. In this mode, evoptool will run a difined number of algortihms for each selected one in the ''Algorithm Panel'', and it will perform the average of the different executions of the same algorithm. This option is usefull to show the average behavior of searchers.
# ''Algorithms Panel.'' This panel allows to select a set of algorithms to compare in a particular execution. It is subdivided in four parts, in order to classify algorithms for belonging kind. Next, is possible to customize the parameters of each selected algorithm.
# ''Result Tabs. ''This tabs show the result graphics of the a test execution in real time mode. At this time, only the average fitness graph is implemented in evoptool, but new graphs can be easily added in future.
# ''Log Monitor. ''This monitor keep the user informed about the execution status and several others information such warnings or errors.
==== '''Video Example of Use'''====
In this short video is briefly presented an example of use of evoptool. It starts by configuring the Optimization Problem to solve, next select a set of algortihms to compare and finally is showed the execution of a test.
=== '''Command Line'''===
Evoptool is also powered by a ''command line'' interface, so when the GUI is not needed and can be an unusefull weight, it is possible to escape it and run the software just typing a command inside a terminal such ''bash or dash''.
==== '''Commands''' ====
* ''--help (-h). ''This command print at video usefull information about evoptool commands and their use.
* ''--version (-v). ''This command print at video information about currently version of the software and others informations such ''Copyright'' or link to the evoptool web page.
* ''--nogui [CONF_FILE] (-n). ''This is the more usefull command, such it allows to run evoptool from command line and to achieve the results as an image graph or, for more complex purposes, as data files. This command need only of one parameter that specify the ''CONFIGURATION FILE'' for the execution. The configuration file parameter need to be specified with a proper ''PATH'' if, and only if, its position differs from the program executable folder. In the next image is possible to view the output generated from an execution of a test from command line.
[[Image:Evo3.png|600px|thumb|center|Evoptool running from command line]]
==== '''Configuration File''' ====
In order to run evoptool from command line, is needed a proper ''configuration file'' that define all the contraints and settings for that particulat test execution. A default configuration file can be found in the folder ''../evoptool/trunk/gui/bin/confi.evoptool'', and the user is free to customize it or to create a different file in a different position and specify the entire ''PATH'' before run evoptool.
The configuration file is quite intuitive, and the default file presents several usuful information about the contents and how to modify it. It is subdivided in three main section, each of them define the behavior of a particular component.
* ''General Settings.'' Allows to specify if the execution of a test have to be a normal one (''Single Run Mode''), or an average execution (''Multi Run Mode''). In the last case, the parameter ''N_ALGO'' define the number of execution of an algorithm on that perform the average.
* ''Objective Function.''Allows to specify which is the Objective Function for this test execution and to define the needed parameters as the individual size or others.
* ''Algorithms.'' Allows to define a set of algorithms to run, and to specify their parameters individually.
Some usefull information on how to customize the configuration file are listed in the next rows:
* Comment or uncomment lines with a simbol '#' for customize the configuration.
* Mandatory sections are signaled with a simbol '*', other sections can be deleted.
* Uneeded parameters must be commented!
* Values must be between square braces.
* Order of parameters inside sections is mandatory!
* There must be the end of file delimiter at last line.
== '''Documentation''' ==
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.
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.]]
==='''Software Modules''' ===
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.
* ''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.
=== '''Hierarchies''' ===
This section have the purpose to show some structures internal to evoptool implementation. In particular there are presented the main hierarchies of this software, so, future developers will be facilitated during the development of new componets.
==== '''Algorithms Hierarchy''' ====
[[Image:Algo.png|700px|thumb|center|Algorithms Hierarchy]]
Every algorithm implemented inside evoptool inherits from the abstract class ''Algorithm''. This defines every common attributes and functions, and it is an hight level of abstraction for an algorithm. Next, the others abstract classes ''GA, EDA, gEDA'' defines and some times implements common attributes and functions for each category of algorithm, in order to generalize more possible their own concepts. Finally every concrete algorithm will be inherits from one of those last abstract class, and will be a complete implementation of a particular kind of searcher.
==== '''Decorators Hierarchy''' ====
[[Image:Dec.png|700px|thumb|center|Algorithm Decorators Hierarchy]]
Decorators are a very useufull and versatile objects. They allow to easily integrate a new algorithm in the graphic user interface. The abstract class ''AlgorithmDecorator'' define some functons that every concrete decorator have to implement. In addiction, it provides the function ''addParameter'' that allows a fast customization of each concrete decorator. Finally, a decorator can be viewed as a ''Wrapper'' for that algorithms that aren't directly implemented inside evoptool such sBOA.
==== '''Objective Functions Hierarchy''' ====
[[Image:Of.png|700px|thumb|center|Objective Functions Hierarchy]]
This hierarchy define the structure of Objective Functions. As we can see, it is a quite simple architecture. Every objective functionions inherits from the abstract class ''ObjectiveFunction'', that defines an abstract function ''f'' that represents the fitness function. Finally every concrete objective function have to implements this function as specified from the Optimization Problem.
== '''How To Add New Features''' ==
Along the next sections will be presented some procedures to follow in order to add new features and components to evoptool. Those instructions are usefull to avoid common errors or to forget some parts of the implementation.
=== '''Add an Algorithm ''' ===
Adding a new algorithm is really an easy task to do. The next lines will show the steps to follow in order to do it. As convenience, we will refere to a generic ''NewAlgorithm'' and it will be an algorithm of the category ''SomeGenetic''.
# ''Create files.'' Create the files ''NewAlgorithm.h'' and ''NewAlgorithm.cpp'' inside the ''../evoptool/trunk/somegenetic/src/'' folder.
# ''Fill files.'' Every algorithm must inherits from the abstract class ''Algorithm'', or from one of its abstract or concrete implementation. Such it have to be a concrete class, it must implments every abstract function inherited from its superclass.
# ''Create Decorator.'' See next section.
# ''Update Configuration Parser.'' See proper section.
=== '''Add a Decorator ''' ===
In the following lines there are showed the steps to follow in order to add a new algorithm decorator to the grafic user interface. Here, we suppose to add a decorator called ''SomeAlgoDecorator'' for convenience, but obviously these instructions are valid for every decorator.
# ''Create files.'' Create the files ''SomeAlgoDecorator.h'' and ''SomeAlgoDecorator.cpp'' inside the ''../evoptool/trunk/gui/src/'' folder.
# ''Fill files.'' Every decorator must inherits from the abstract class ''AlgorithmDecorator'', and must provides a concrete implementation of the abstract function:
#* Solver* newInstance(...)
#* MultiSolver* newInstance(...)
#* string plotProperties(...)
#* void initContent(...)
# ''Configure headers.'' Add the ''SomeAlgoDecorator.h'' to ''AlgorithmDecorators.h'' (note the 's'!) that is placed in the ''../evoptool/trunk/gui/src/'' folder. This will avoid to include a long list of decorator headers to the main GUI class.
# ''Add decorator to GUI.'' In order to concretly add the decorator to the GUI, is needed to modify the ''GUI.cpp'' class, adding proper code lines to the ''initAlgorithmDecorators'' function.
=== '''Update Configuration Parser ''' ===
In order to add a new algorithm in the ''command line mode'', it is need to modify and update the configuration parser, and to perfom other few task. As previous sections, we want to add a generic ''SomeAlgorithm'' to the ''Configuration Parser''.
# ''Configure headers.'' Be sure that the file ''SomeAlgorithm.h'' is added to the header ''Algorithms.h'' (note the 's'!) that is placed in the ''../evoptool/trunk/gui/src/'' folder. This will avoid to include a long list of headers.
# ''Modify Configuration File.'' Add a new algorithm section to the end of the configuration file. Be sure to fix for that algorithm a proper free identification number. The section must contains every parameters needed by the algorithm.
# ''Update Configuration Parser.'' This task need to update the function ''parseAlgorithm'' of the file ''ConfParser.cpp'' placed in the ''../evoptool/trunk/gui/src/'' folder. Look that, such we can run evoptool in different run modes, there are two different implementation of this function that have a different return object. Remember to update both the implementation!
## Add a new case block to the switch/case structure. Be sure to use as case label the same number used before in the configuration file.
## Fill the case block with the code for parse the algorithm parameters. Parse every parameter using the just implemented functions. This will avoid to make errors and to spend a lot of time.
=== '''Add an Objective Function ''' ===
This section will lists all the steps to follow in order to add a new objective function, and so add a new optimization problem, to evoptool. Here, we assume for convenience that the objective function to add is called ''SomeObjFun''.
# ''Create files.'' Create the files ''SomeObjFun.h'' and ''SomeObjFun.cpp'' inside the ''../evoptool/trunk/opt-pbl/src/'' folder.
# ''Fill files.'' Every objective function must inherits from the abstract class ''ObjectiveFunction'', or from one of its concrete implementation. It must implements or overwrites the abstract function ''f'' (fitness) inherited from its superclass.
# ''Configure headers.'' Add the ''SomeObjFun.h'' to ''ObjectiveFunctions.h'' (note the 's'!) that is placed in the ''../evoptool/trunk/opt-pbl/src/'' folder. This will avoid to include a long list of headers within the libraries ''core'' and ''gui''.
# ''Update Enumeration.'' Add a new value for the enum ''Evoptool::Task'' defined in the ''Evoptool.h'' header file. The header ''Evoptool.h'' can be found in the ''../evoptool/trunk/core/src/'' folder.
# ''Update GUI''. In order to link the just created fitness function with the grafic user interface it is needed to modify the ''EvoptoolGUI.cpp'' file.
#* ''getSelectedObjectiveFunction function''. Add the new component to the ''switch/case'' block.
#* ''initObjList function.'' Add the new componet to the ''Gtk::TreeModel'' object, so it will be showed in the proper selection menu.
# ''Update Configuration Parser.''
## Update the XMLParser (''../evoptool/trunk/core/src/XMLParser.cpp''). This is a quite simple task to do, just look to the code.
## Update the example XML configuration file, (''../evoptool/trunk/evoptool-file/configuration-examples/testConf.xml''), adding the necessary description of the new objective function parameters.
== '''Usefull Links''' ==
* [https://svn.ws.dei.polimi.it/evoptool/ Evoptool Repository] (Need authentication!)
* [http://www.gnu.org/software/gsl/ GNU Scientific Library]
* [http://www.gtkmm.org/ GUI Library Gtkmm]
* [http://www.boost.org/ Boost Library]
* [http://www.gnuplot.info/ Gnuplot Utility]
* [http://www.cplusplus.com/reference/ C++ Library reference]

Latest revision as of 17:37, 22 October 2011