Recent changes to ComponentBaseExperiment

ComponentBaseExperiment modified by Tomassino Ferrauto

Tomassino Ferrauto — Fri, 20 Nov 2015 10:21:41 -0000

ComponentBaseExperiment modified by Tomassino Ferrauto

Tomassino Ferrauto — Tue, 17 Nov 2015 13:59:14 -0000

ComponentBaseExperiment modified by Tomassino Ferrauto

Tomassino Ferrauto — Sat, 14 Nov 2015 08:52:30 -0000

ComponentBaseExperiment modified by Tomassino Ferrauto

Tomassino Ferrauto — Fri, 13 Nov 2015 10:31:30 -0000

--- v12
+++ v13
@@ -9,19 +9,35 @@
 The BaseExperiment and Component classes
 ======

-The [Creating a new experiment]([CreatingNewExperiment]) page explain how to quickly setup a new robotic experiment  by using the *EvoRobotExperiment* class. Here we show other ways to create new experiments that are more flexible (e.g. enable you to instantiate only the components that are needed) but that require more programming effort. This can be done by using the BaseExperiment or the Component classes instead of the EvoRobotExperiment.  You might decide to use these methods, for example, if you want to design an experiment that use a neural network but does not require the utilization of any robot, as in the case of the BackPropagationExperiment illustrated below. Please notice that the type of the class you use to create tour new experiment should be specified in the .ini configuration file of the experiment in  the mainComponent parameter. 
+The [Creating a new experiment]([CreatingNewExperiment]) page explain how to quickly setup a new robotic experiment  by using the *EvoRobotExperiment* class. Here we show other ways to create new experiments that are more flexible (e.g. enable you to instantiate only the components that are needed) but that require more programming effort. This can be done by using the *BaseExperiment* or the *Component* classes instead of *EvoRobotExperiment*.  You might decide to use these methods, for example, if you want to design an experiment that use a neural network but does not require the utilization of any robot, as in the case of the *BackPropagationExperiment* illustrated below.
+
+Please notice that when you create a new experiment using the instructions in this page, you should specify the type of your component in the *type* parameter of the *Component* group, as in the example below.
+
+~~~~~~~
+:::INI
+[TOTAL99]
+...
+# The name of the group specifying the main component of the experiment
+mainComponent = Component
+pluginFile = Backpropagation
+...
+
+[Component]
+type = Backpropagation
+....
+~~~~~~~

 Introduction
 -------

-While FARSA was created with evolutionary robotic experiments in mind, and provides a lot of ready-to-use code for that, the component and plugin architecture is general enough to allow any kind of experiment to be run. For example you may want to write a plugin to work with a  neural network learning algorithm (without any robot involved) or to have a physical simulation without a robot controller or even without any robot at all. While you can still use the *EvoRobotExperiment* class, that means being constrained to the flow imposed by that class (i.e. trials and steps). Moreover, at runtime, a lot of objects that you do not use will be created, wasting memory and computational resources. A better approach is to start from the *BaseExperiment* class, that allows to easily define actions that can be executed both in batch or through the GUI, in a separate thread or in the GUI thread, with support for pause and resume or not and to add new windows.
+While FARSA was created with evolutionary robotic experiments in mind, and provides a lot of ready-to-use code for that, the component and plugin architecture is general enough to allow any kind of experiment to be run. For example you may want to write a plugin to work with a  neural network learning algorithm (without any robot involved) or to have a physical simulation without a robot controller or even without any robot at all. While you can still use the *EvoRobotExperiment* class, that means being constrained to the flow imposed by that class (i.e. trials and steps). Moreover, at runtime, a lot of objects that you do not use will be created, wasting memory and computational resources. A better approach is to start from the *BaseExperiment* class, that allows to easily define actions that can be executed both in batch or through the GUI, in a separate thread or in the GUI thread, with support for pause and resume or not, and to add new windows.

 A further possibility is to inherit from the *Component* class (that, despite the name, is simply a particular kind of component, see the section at the end of [this page]([ComponentsConfig])). This approach will be briefly described at the end of this page, but it is highly discouraged because it is too low-level and because it is scheduled to be removed in the next major FARSA release.

 The *BaseExperiment* Class
 -------

-The *BaseExperiment* class enable you to define actions that can be run in batch or via the *Actions* menu of the *total99* graphic interface. For each action you can specify whether it will run in the GUI thread or in a separate thread and, in this case, whether it is possible to pause the action and run it step-by-step or not. Moreover it enable you to define additional windows required by the experiment (see [this page]([ComponentsConfig]). The [API documentation]([APIDoc]) of *BaseExperiment* contains a detailed description of the class methods. Below we simply use the *Backpropagation* expeimental plugin to illustrate how it can be used. 
+The *BaseExperiment* class enables you to define actions that can be run in batch or via the *Actions* menu of the *total99* graphic interface. For each action you can specify whether it will run in the GUI thread or in a separate thread and, in this case, whether it is possible to pause the action and run it step-by-step or not. Moreover it enables you to declare additional windows required by the experiment (see [this page]([ComponentsConfig])). The [API documentation]([APIDoc]) of *BaseExperiment* contains a detailed description of the class methods. In this page we use the *Backpropagation* experimental plugin to illustrate how it can be used.

 Below we include the configuration file of the experiment. As you can see, in this case only the main experimental component and the neural network sub-component are configured and istantiated. 

@@ -46,80 +62,73 @@
 nMotors = 1
 ~~~~~~~

-Below we include the header file. For sake of clarity we only show the portions of the corresponding file that we want to review. In this example the experiment is called BackPropagation and, as you can see, the *Backpropagation* class is declared as a sub-class of BaseExperiment component. The *configure()*, *describe()*, *save()*, and *postConfigurateInitialization()* methods are standard method inherited from the Component class.  
+Below we include the header file and the definition of the class constructor. For the sake of clarity we only show the portions that we want to review. In this example the experiment is called Backpropagation and, as you can see, the *Backpropagation* class is declared as a sub-class of BaseExperiment component. The *configure()*, *describe()*, *save()*, and *postConfigurateInitialization()* methods are standard method of all components.

-The *getViewers()* function is used to create a custom window . The *getViewers()* function is similar to the function with the same name of the *ParameterSettableUI* class described in [the page about components]([ComponentsConfig]). However within the BaseExperiment class the new window is automatically added to the list of available graphic component and to the menu of the Total99 graphic interface. 
+The *getViewers()* function is used to create a custom windows. It is similar to the function with the same name of the *ParameterSettableUI* class described in [the page about components]([ComponentsConfig]). However within the *BaseExperiment* class, there is no need to create a separate class inheriting from *ParameterSettableUI*.

-The public slots indicate the actions of the experiment that can be executed through the total99 graphic interface or through batch commands. There are different type of methods that can be used to declare and implement actions (for a detailed documentation refer to the [API documentation]([APIDoc]):
+The public slots indicate the actions of the experiment that can be executed through the *total99* graphic interface or through batch commands. There are different macros that can be used to declare the characteristics of actions (for a detailed documentation refer to the [API documentation]([APIDoc]):

-* *DECLARE_THREAD_OPERATION* - is an action that run in a dedicated thread (i.e. not in the GUI thread);
-* *DECLARE_STEPPABLE_THREAD_OPERATION* - is also an action that run in a dedicated thread which can also be  paused or ececuted in a step-by-step mode;
-* *DECLARE_IMMEDIATE_OPERATION* - is an action that runs in the GUI thread. Notice that long running operations that operate in the same thread of the GUI might slow down the reactivity of the graphic interface. 
+* *DECLARE_THREAD_OPERATION* - declares an action that run in a dedicated thread (i.e. not in the GUI thread);
+* *DECLARE_STEPPABLE_THREAD_OPERATION* - also declares an action that run in a dedicated thread which can also be paused or executed in a step-by-step mode;
+* *DECLARE_IMMEDIATE_OPERATION* - declares an action that runs in the GUI thread. Notice that long running operations that operate in the same thread of the GUI might slow down the reactivity of the graphic interface.

-The first argument of each macro is the class name, the second one is the name of the function implementing the operation.  The communication between actions running in a dedicated thread and the GUI should be treated with care (for more information see the **Threading issues** note in [this page]([ComponentsConfig])).
+The first argument of each macro is the class name, the second one is the name of the function implementing the operation. The communication between actions running in a dedicated thread and the GUI should be treated with care (for more information see the **Threading issues** note in [this page]([ComponentsConfig])).

 ~~~~~~~
 :::C++
 #include "baseexperiment.h"
 #include "farsaplugin.h"
 #include "evonet.h"
-#include <QString>
-#include <QVector>

 class FARSA_PLUGIN_API Backpropagation : public farsa::BaseExperiment
 {
-   Q_OBJECT
-   FARSA_REGISTER_CLASS(BaseExperiment)
-   [...]
+    Q_OBJECT
+    FARSA_REGISTER_CLASS(BaseExperiment)
+    [...]
 public:
-   Backpropagation();
-   virtual ~Backpropagation();
-   virtual void configure(farsa::ConfigurationParameters& params, QString prefix);
-   virtual void save(farsa::ConfigurationParameters& params, QString prefix);
-   static void describe(QString type);
-   virtual void postConfigureInitialization();
-   virtual QList<farsa::ParameterSettableUIViewer> getViewers(QWidget* parent, Qt::WindowFlags flags);
+    Backpropagation();
+    virtual ~Backpropagation();
+    virtual void configure(farsa::ConfigurationParameters& params, QString prefix);
+    virtual void save(farsa::ConfigurationParameters& params, QString prefix);
+    static void describe(QString type);
+    virtual void postConfigureInitialization();
+    virtual QList<farsa::ParameterSettableUIViewer> getViewers(QWidget* parent, Qt::WindowFlags flags);
 public slots:
-   virtual void trainAllSeeds();
-   virtual void trainCurrentNetwork();
-   virtual void testAllSeeds();
-   virtual void testCurrentNetwork();
-   virtual void resetNetwork();
-   virtual void saveNetwork();
-   virtual void loadNetwork();
+    virtual void trainAllSeeds();
+    virtual void trainCurrentNetwork();
+    virtual void testAllSeeds();
+    virtual void testCurrentNetwork();
+    virtual void resetNetwork();
+    virtual void saveNetwork();
+    virtual void loadNetwork();
 private:
-   [...]
+    [...]
 };
 [...]
-~~~~~~~

-
-
-~~~~~~~
-:::C++
 Backpropagation::Backpropagation()
-   : farsa::BaseExperiment()
-   , [...]
+    : farsa::BaseExperiment()
+    , [...]
 {
-   DECLARE_STEPPABLE_THREAD_OPERATION(Backpropagation, trainAllSeeds)
-   DECLARE_STEPPABLE_THREAD_OPERATION(Backpropagation, trainCurrentNetwork)
-   DECLARE_STEPPABLE_THREAD_OPERATION(Backpropagation, testAllSeeds)
-   DECLARE_STEPPABLE_THREAD_OPERATION(Backpropagation, testCurrentNetwork)
-   DECLARE_THREAD_OPERATION(Backpropagation, resetNetwork)
-   DECLARE_IMMEDIATE_OPERATION(Backpropagation, saveNetwork)
-   DECLARE_IMMEDIATE_OPERATION(Backpropagation, loadNetwork)
+    DECLARE_STEPPABLE_THREAD_OPERATION(Backpropagation, trainAllSeeds)
+    DECLARE_STEPPABLE_THREAD_OPERATION(Backpropagation, trainCurrentNetwork)
+    DECLARE_STEPPABLE_THREAD_OPERATION(Backpropagation, testAllSeeds)
+    DECLARE_STEPPABLE_THREAD_OPERATION(Backpropagation, testCurrentNetwork)
+    DECLARE_THREAD_OPERATION(Backpropagation, resetNetwork)
+    DECLARE_IMMEDIATE_OPERATION(Backpropagation, saveNetwork)
+    DECLARE_IMMEDIATE_OPERATION(Backpropagation, loadNetwork)
 }
 ~~~~~~~

-Below we include the critical portions of the corresponding .cpp file.
+Below we include the critical portions of the .cpp file containing the implementation of the *Backpropagation* class.

-The *resetNetwork()* is the implementation of an action that replace the connection weights of the network with randomly generated values by calling a specific function. Since this operation action is defined as an operation that run in its own thread, it will not slow down or freeze the operation of the tota99 graphic interface. 
+The *resetNetwork()* is the implementation of an action that replaces the connection weights of the network with randomly generated values by calling a specific function. Since this operation action is defined as an operation that run in its own thread, it will not slow down or freeze the operation of the tota99 graphic interface.

-The *testCurrentNetwork()* action operates by setting state of the sensory neurons of the network, by allowing the activation to spread over the network, and by printing the state of the internal and output neurons of the network, for each defined input pattern. Being declared as a *steppable thread operation* it can enable to user to pause/resume/terminate its execution, to operate in a step-by-step mode, and to vary its execution speed. For making this possible, it need to use the: *pauseFlow()* and *stopFlow()* functions which check whether the function flow should be paused and whether a delay should be added, respectively. The way in which the action operate basically depends on the code included between two subsequent calls of the *pauseFlow()*  functions.  The *stopFlow()* function, instead, enables to termine the action. For a more detailed information please refer to the [API documentation]([APIDoc]).
+The *testCurrentNetwork()* action operates by setting state of the input neurons of the network, by allowing the activation to spread over the network, and by printing the state of the internal and output neurons of the network, for each defined input pattern. Being declared as a *steppable thread operation* it enables to user to pause/resume/terminate its execution, to operate in a step-by-step mode, and to vary its execution speed. For making this possible, you need to use the: *pauseFlow()* and *stopFlow()* functions. The former pauses the execution flow or adds a delay depending on the user requestes. The way in which the action operates basically depends on the code included between two subsequent calls of the *pauseFlow()* functions. The *stopFlow()* function, instead, checks whether the action should be terminated as soon as possible and returns true in this case. For a more detailed information please refer to the [API documentation]([APIDoc]).

-The *saveNetwork()* action enable the user to save the current parameters of the network in an user specified file name, Since it require to open a window to enable the user to indicate the file name and the directory in which the file should be save, it need to operate within the same thread of the GUI. As a consequence, as specified above, is declared as an *immediate operation*.
+The *saveNetwork()* action enables the user to save the current parameters of the network in an user specified file name. Since it requires to open a window to allow the user to indicate the file name and the directory in which the file should be save, it needs to operate within the same thread of the GUI. As a consequence, as explained above, it is declared as an *immediate operation*.

-Finally the *getViewers()* class istantiate a subclass of the *ParameterSettableUI* class that is used to display the state of the network during a test. For more information see [this page]([ComponentsConfig]).
+Finally the *getViewers()* function creates a window that is used to disply the backpropagation error. Its implementation is the same that you may find in the function with the same name of a *ParameterSettableUI* subclass. For more information see [this page]([ComponentsConfig]).

 **NOTE** The *BaseExperiment* class does not include support for resources. If you want to use the resource mechanism in your component, remember to inherit from both *BaseExperiment* and *ConcurrentResourcesUser*.

@@ -127,64 +136,57 @@
 :::C++
 void Backpropagation::resetNetwork()
 {
-   internalResetNetwork();
+    internalResetNetwork();

-   farsa::Logger::info("Neural network weights have been randomized");
+    farsa::Logger::info("Neural network weights have been randomized");
 }
-
-

 void Backpropagation::testCurrentNetwork()
 {
-   if (!m_validNetwork) {
-       farsa::Logger::error("The neural network is invalid, please load a valid network, first");
+    if (!m_validNetwork) {
+        farsa::Logger::error("The neural network is invalid, please load a valid network, first");
+        return;
+    }

-       return;
-   }
+    // Initialization
+    [...]

-   // Initialization
-   [...]
+    for (int i = 0; i < m_testingSet.size(); i++) {
+        pauseFlow();
+        if (stopFlow()) {
+            farsa::Logger::info("Testing interrupted");

-   for (int i = 0; i < m_testingSet.size(); i++) {
-       pauseFlow();
-       if (stopFlow()) {
-           farsa::Logger::info("Testing interrupted");
+            return;
+        }

-           return;
-       }
+        // Computing the neural network output and the error
+        [...]
+    }

-       // Computing the neural network output and the error
-       [...]
-   }
+    [...]

-   [...]
-
-   farsa::Logger::info("Testing done");
+    farsa::Logger::info("Testing done");
 }
-
-

 void Backpropagation::saveNetwork()
 {
-   const QString filename = QFileDialog::getSaveFileName(NULL, "Save neural network", QString(), "Phenotypes (*.phe)");
+    const QString filename = QFileDialog::getSaveFileName(NULL, "Save neural network", QString(), "Phenotypes (*.phe)");

-   if (!filename.isEmpty()) {
-       m_net->save_net_blocks(filename.toLatin1().data(), 1);
+    if (!filename.isEmpty()) {
+        m_net->save_net_blocks(filename.toLatin1().data(), 1);

-       farsa::Logger::info("Neural network saved");
-   }
+        farsa::Logger::info("Neural network saved");
+    }
 }
-
-

 QList<farsa::ParameterSettableUIViewer> Backpropagation::getViewers(QWidget* parent, Qt::WindowFlags flags)
 {
-   QList<farsa::ParameterSettableUIViewer> viewers = BaseExperiment::getViewers(parent, flags);
+    QList<farsa::ParameterSettableUIViewer> viewers = BaseExperiment::getViewers(parent, flags);

-   ErrorStatViewer* statViewer = new ErrorStatViewer(parent, flags);
-   viewers.append(farsa::ParameterSettableUIViewer(statViewer, "Learning Error Statistics"));
+    ErrorStatViewer* statViewer = new ErrorStatViewer(parent, flags);
+    viewers.append(farsa::ParameterSettableUIViewer(statViewer, "Learning Error Statistics"));

-   return viewers;
+    return viewers;
 }
 ~~~~~~~

@@ -192,5 +194,4 @@
 The *Component* Class
 -------

-Alternatively you can use the *Component* class, which is the parent class of all FARSA components.  It is basically a standard component, so you can refer to the [Configuring components]([ComponentsConfig]) page for detailed information. The only method that must necessarily be implemented to use this class is the *stopCurrentOperation* that is used by total99 to terminate all running operation when the application is closed. The usage of this class however is discoraged since it lack several of the important features (e.g. thread management, automatic filling of action menu) which are provided by the BaseExperiment class. 
-
+Alternatively you can use the *Component* class, which is the parent of components that are instantiated directly by *total99* (i.e. that can be specified as the type of the *Component* group in the example configuration files above). It is basically a standard component, so you can refer to the [Configuring components]([ComponentsConfig]) page for detailed information. The only method that must necessarily be implemented to use this class is *stopCurrentOperation* that is used by *total99* to terminate all running operation when the application is closed. The usage of this class however is discoraged since it lack several of the important features (e.g. thread management, automatic filling of action menu) which are provided by the BaseExperiment class.

ComponentBaseExperiment modified by Tomassino Ferrauto

Tomassino Ferrauto — Thu, 12 Nov 2015 10:36:25 -0000

ComponentBaseExperiment modified by Tomassino Ferrauto

Tomassino Ferrauto — Thu, 12 Nov 2015 10:21:19 -0000

--- v10
+++ v11
@@ -1,3 +1,11 @@
+[Prev: Creating a new experiment]([CreatingNewExperiment]) | [Up: Creating a new experiment]([CreatingNewExperiment]) | [Next: Customizing the environment]([CustomizeEnvironment])
+ -------|--------|----------
+        |        |
+
+**Table of contents**
+
+[TOC]
+
 The BaseExperiment and Component classes
 ======

@@ -36,7 +44,6 @@
 type = Evonet
 nSensors = 2
 nMotors = 1
-
 ~~~~~~~

 Below we include the header file. For sake of clarity we only show the portions of the corresponding file that we want to review. In this example the experiment is called BackPropagation and, as you can see, the *Backpropagation* class is declared as a sub-class of BaseExperiment component. The *configure()*, *describe()*, *save()*, and *postConfigurateInitialization()* methods are standard method inherited from the Component class.

ComponentBaseExperiment modified by Stefano Nolfi

Stefano Nolfi — Tue, 27 Oct 2015 16:27:40 -0000

--- v9
+++ v10
@@ -36,6 +36,7 @@
 type = Evonet
 nSensors = 2
 nMotors = 1
+
 ~~~~~~~

 Below we include the header file. For sake of clarity we only show the portions of the corresponding file that we want to review. In this example the experiment is called BackPropagation and, as you can see, the *Backpropagation* class is declared as a sub-class of BaseExperiment component. The *configure()*, *describe()*, *save()*, and *postConfigurateInitialization()* methods are standard method inherited from the Component class.

ComponentBaseExperiment modified by Stefano Nolfi

Stefano Nolfi — Tue, 27 Oct 2015 16:26:43 -0000

--- v8
+++ v9
@@ -1,4 +1,4 @@
-The Component and BaseExperiment classes
+The BaseExperiment and Component classes
 ======

 The [Creating a new experiment]([CreatingNewExperiment]) page explain how to quickly setup a new robotic experiment  by using the *EvoRobotExperiment* class. Here we show other ways to create new experiments that are more flexible (e.g. enable you to instantiate only the components that are needed) but that require more programming effort. This can be done by using the BaseExperiment or the Component classes instead of the EvoRobotExperiment.  You might decide to use these methods, for example, if you want to design an experiment that use a neural network but does not require the utilization of any robot, as in the case of the BackPropagationExperiment illustrated below. Please notice that the type of the class you use to create tour new experiment should be specified in the .ini configuration file of the experiment in  the mainComponent parameter. 
@@ -10,7 +10,12 @@

 A further possibility is to inherit from the *Component* class (that, despite the name, is simply a particular kind of component, see the section at the end of [this page]([ComponentsConfig])). This approach will be briefly described at the end of this page, but it is highly discouraged because it is too low-level and because it is scheduled to be removed in the next major FARSA release.

+The *BaseExperiment* Class
+-------

+The *BaseExperiment* class enable you to define actions that can be run in batch or via the *Actions* menu of the *total99* graphic interface. For each action you can specify whether it will run in the GUI thread or in a separate thread and, in this case, whether it is possible to pause the action and run it step-by-step or not. Moreover it enable you to define additional windows required by the experiment (see [this page]([ComponentsConfig]). The [API documentation]([APIDoc]) of *BaseExperiment* contains a detailed description of the class methods. Below we simply use the *Backpropagation* expeimental plugin to illustrate how it can be used. 
+
+Below we include the configuration file of the experiment. As you can see, in this case only the main experimental component and the neural network sub-component are configured and istantiated. 

 ~~~~~~~
 :::INI
@@ -33,22 +38,17 @@
 nMotors = 1
 ~~~~~~~

-The *BaseExperiment* class
--------
+Below we include the header file. For sake of clarity we only show the portions of the corresponding file that we want to review. In this example the experiment is called BackPropagation and, as you can see, the *Backpropagation* class is declared as a sub-class of BaseExperiment component. The *configure()*, *describe()*, *save()*, and *postConfigurateInitialization()* methods are standard method inherited from the Component class.  

-The *BaseExperiment* class enable you to define actions that can be run in batch or via the *Actions* menu of the *total99* graphic interface. For each action you can specify whether it will run in the GUI thread or in a separate thread and, in this case, whether it is possible to pause the action and run it step-by-step or not. Moreover it enable you to define additional windows required by the experiment (see [this page]([ComponentsConfig]). The [API documentation]([APIDoc]) of *BaseExperiment* contains a detailed description of the class methods. Below we simply use the *Backpropagation* plugin to illustrate how it can be used. 
+The *getViewers()* function is used to create a custom window . The *getViewers()* function is similar to the function with the same name of the *ParameterSettableUI* class described in [the page about components]([ComponentsConfig]). However within the BaseExperiment class the new window is automatically added to the list of available graphic component and to the menu of the Total99 graphic interface. 

-Below we include the header file. For sake of clarity we only show a portion of the corresponding file. In this example the experiment is called BackPropagation and, as you can see, the *Backpropagation* class is declared as a sub-class of BaseExperiment component. The *configure()*, *describe()*, *save()*, and *postConfigurateInitialization()* methods are standard method inherited from the Component class.  
+The public slots indicate the actions of the experiment that can be executed through the total99 graphic interface or through batch commands. There are different type of methods that can be used to declare and implement actions (for a detailed documentation refer to the [API documentation]([APIDoc]):

-The *getViewers()* function is used to create a custom window . The *getViewers()* function is similar to the function with the same name of the *ParameterSettableUI* class described in [the page about components]([ComponentsConfig]). However within the BaseExperiment class the new window is automatically added to the Total99 graphic interface. 
-
-The public slots indicate the actions of the experiment that can be executed by the total99 graphic interface or through batch commands. There are different type of methods that can be used to declare and implement actions (for a detailed documentation refer to the [API documentation]([APIDoc]):
-
-* * *DECLARE_THREAD_OPERATION* - is an action that run in a dedicated thread (i.e. not in the GUI thread);
+* *DECLARE_THREAD_OPERATION* - is an action that run in a dedicated thread (i.e. not in the GUI thread);
 * *DECLARE_STEPPABLE_THREAD_OPERATION* - is also an action that run in a dedicated thread which can also be  paused or ececuted in a step-by-step mode;
 * *DECLARE_IMMEDIATE_OPERATION* - is an action that runs in the GUI thread. Notice that long running operations that operate in the same thread of the GUI might slow down the reactivity of the graphic interface. 

-The first argument of each macro is the class name, the second one is the name of the function implementing the operation.  The communication between actions that run in dedicated thread and the GUI should be handled with care (for mre information see the **Threading issues** note in [this page]([ComponentsConfig])).
+The first argument of each macro is the class name, the second one is the name of the function implementing the operation.  The communication between actions running in a dedicated thread and the GUI should be treated with care (for more information see the **Threading issues** note in [this page]([ComponentsConfig])).

 ~~~~~~~
 :::C++
@@ -103,7 +103,17 @@
 }
 ~~~~~~~

-Below we include critical portion of the corresponding .cpp file.
+Below we include the critical portions of the corresponding .cpp file.
+
+The *resetNetwork()* is the implementation of an action that replace the connection weights of the network with randomly generated values by calling a specific function. Since this operation action is defined as an operation that run in its own thread, it will not slow down or freeze the operation of the tota99 graphic interface. 
+
+The *testCurrentNetwork()* action operates by setting state of the sensory neurons of the network, by allowing the activation to spread over the network, and by printing the state of the internal and output neurons of the network, for each defined input pattern. Being declared as a *steppable thread operation* it can enable to user to pause/resume/terminate its execution, to operate in a step-by-step mode, and to vary its execution speed. For making this possible, it need to use the: *pauseFlow()* and *stopFlow()* functions which check whether the function flow should be paused and whether a delay should be added, respectively. The way in which the action operate basically depends on the code included between two subsequent calls of the *pauseFlow()*  functions.  The *stopFlow()* function, instead, enables to termine the action. For a more detailed information please refer to the [API documentation]([APIDoc]).
+
+The *saveNetwork()* action enable the user to save the current parameters of the network in an user specified file name, Since it require to open a window to enable the user to indicate the file name and the directory in which the file should be save, it need to operate within the same thread of the GUI. As a consequence, as specified above, is declared as an *immediate operation*.
+
+Finally the *getViewers()* class istantiate a subclass of the *ParameterSettableUI* class that is used to display the state of the network during a test. For more information see [this page]([ComponentsConfig]).
+
+**NOTE** The *BaseExperiment* class does not include support for resources. If you want to use the resource mechanism in your component, remember to inherit from both *BaseExperiment* and *ConcurrentResourcesUser*.

 ~~~~~~~
 :::C++
@@ -113,12 +123,9 @@

    farsa::Logger::info("Neural network weights have been randomized");
 }
-~~~~~~~

-*resetNetwork* is declared as a *thread operation*. The *BaseExperiment* class takes care of starting the thread and running the function, so the *resetNetwork* function only contains the instructions implementing the operation logic. In this case the function resets the weights of the tested neural network. As this operation may take some time for big neural networks, it is run in a separate thread to avoid freezing the user interface in the meanwhile.

-~~~~~~~
-:::C++
+
 void Backpropagation::testCurrentNetwork()
 {
    if (!m_validNetwork) {
@@ -146,12 +153,9 @@

    farsa::Logger::info("Testing done");
 }
-~~~~~~~

-*testCurrentNetwork* is declared as a *steppable thread operation*. This means that it is possible to pause its execution, add a constant delay at each step, perform a step at a time, resume normal execution and prematurely terminate the function. For this to be possible the function must make use of two functions: *pauseFlow* and *stopFlow*. The former checks whether the function flow should be paused or a delay should be added. Basically, the code between two subsequent calls of the *pauseFlow* function defines what a step is. The *stopFlow* function, on the other hand, checks if the operation should be terminated prematurely and returns true in this case. The code above shows a typical usage. In case steps are performed inside other objects, it is possible to obtain a *flow controller* object to pass to other objects. Refer to the [API documentation]([APIDoc]) for more information.

-~~~~~~~
-:::C++
+
 void Backpropagation::saveNetwork()
 {
    const QString filename = QFileDialog::getSaveFileName(NULL, "Save neural network", QString(), "Phenotypes (*.phe)");
@@ -162,12 +166,9 @@
        farsa::Logger::info("Neural network saved");
    }
 }
-~~~~~~~

-The *saveNetwork* operation is declared as an *immediate operation*. This means that the operation is basically a function call that is executed in the GUI thread. In this case the operation asks the user a filename where to save the neural network, so it must run in the GUI thread. It is also possible to run other kind of operations, provided that they are quick enough not to make the user interface unresponsive.

-~~~~~~~
-:::C++
+
 QList<farsa::ParameterSettableUIViewer> Backpropagation::getViewers(QWidget* parent, Qt::WindowFlags flags)
 {
    QList<farsa::ParameterSettableUIViewer> viewers = BaseExperiment::getViewers(parent, flags);
@@ -179,13 +180,9 @@
 }
 ~~~~~~~

-The last function worth mentioning in the *Backpropagation* class is *getViewers*. Its implementation is the same that you may find in the function with the same name of a *ParameterSettableUI* subclass and the description given in [this page]([ComponentsConfig]) also applies here.

-**NOTE** The *BaseExperiment* class does not include support for resources. If you want to use the resource mechanism in your component, remember to inherit from both *BaseExperiment* and *ConcurrentResourcesUser*.
-
-The *Component* class
+The *Component* Class
 -------

-As already explained above, the *Component* class is the parent of compoenents that are instantiated directly by *total99*. It is basically a standard component, so you can refer to the [Configuring components]([ComponentsConfig]) page for information on how to implement it. The only additional method that must be implemented is *stopCurrentOperation*, which is called by *total99* when the running operation must be immediately stopped (e.g. when the application is closed).
+Alternatively you can use the *Component* class, which is the parent class of all FARSA components.  It is basically a standard component, so you can refer to the [Configuring components]([ComponentsConfig]) page for detailed information. The only method that must necessarily be implemented to use this class is the *stopCurrentOperation* that is used by total99 to terminate all running operation when the application is closed. The usage of this class however is discoraged since it lack several of the important features (e.g. thread management, automatic filling of action menu) which are provided by the BaseExperiment class. 

-In general you should avoid using *Component* directly, because it requires you to manually perform all the operations that *BaseExperiment* automates (e.g. thread management, filling the action menu, implementing a *ParameterSettableUI* subclass...). Moreover the class is scheduled for removal in the next major release of FARSA.

ComponentBaseExperiment modified by Stefano Nolfi

Stefano Nolfi — Tue, 27 Oct 2015 15:28:37 -0000

--- v7
+++ v8
@@ -36,7 +36,19 @@
 The *BaseExperiment* class
 -------

-The way to go if you want to implement a custom experiment is to start from the *BaseExperiment* class. This class allows to easily define actions that can be run in batch or via the *Actions* menu in the *total99* GUI. For each action you can specify whether it will run in the GUI thread or in a separate thread and, in this case, whether it is possible to pause the action and run it step-by-step or not. Moreover using *BaseExperiment* it is also easier to define additional windows needed by the component with respect to the procedure described in [this page]([ComponentsConfig]). The [API documentation]([APIDoc]) of *BaseExperiment* contains a detailed description of the class methods, here we will show an example of its usage. The example is a simplified version of the *Backpropagation* plugin (some parts of the header and source file have been omitted for the sake of clarity). Here is the header file:
+The *BaseExperiment* class enable you to define actions that can be run in batch or via the *Actions* menu of the *total99* graphic interface. For each action you can specify whether it will run in the GUI thread or in a separate thread and, in this case, whether it is possible to pause the action and run it step-by-step or not. Moreover it enable you to define additional windows required by the experiment (see [this page]([ComponentsConfig]). The [API documentation]([APIDoc]) of *BaseExperiment* contains a detailed description of the class methods. Below we simply use the *Backpropagation* plugin to illustrate how it can be used. 
+
+Below we include the header file. For sake of clarity we only show a portion of the corresponding file. In this example the experiment is called BackPropagation and, as you can see, the *Backpropagation* class is declared as a sub-class of BaseExperiment component. The *configure()*, *describe()*, *save()*, and *postConfigurateInitialization()* methods are standard method inherited from the Component class.  
+
+The *getViewers()* function is used to create a custom window . The *getViewers()* function is similar to the function with the same name of the *ParameterSettableUI* class described in [the page about components]([ComponentsConfig]). However within the BaseExperiment class the new window is automatically added to the Total99 graphic interface. 
+
+The public slots indicate the actions of the experiment that can be executed by the total99 graphic interface or through batch commands. There are different type of methods that can be used to declare and implement actions (for a detailed documentation refer to the [API documentation]([APIDoc]):
+
+* * *DECLARE_THREAD_OPERATION* - is an action that run in a dedicated thread (i.e. not in the GUI thread);
+* *DECLARE_STEPPABLE_THREAD_OPERATION* - is also an action that run in a dedicated thread which can also be  paused or ececuted in a step-by-step mode;
+* *DECLARE_IMMEDIATE_OPERATION* - is an action that runs in the GUI thread. Notice that long running operations that operate in the same thread of the GUI might slow down the reactivity of the graphic interface. 
+
+The first argument of each macro is the class name, the second one is the name of the function implementing the operation.  The communication between actions that run in dedicated thread and the GUI should be handled with care (for mre information see the **Threading issues** note in [this page]([ComponentsConfig])).

 ~~~~~~~
 :::C++
@@ -73,9 +85,7 @@
 [...]
 ~~~~~~~

-The *Backpropagation* class is a component that inherits from *BaseExperiment* and so it respects all the requirements of a component. There are two additional things to notice: the first one is that it has a *getViewers* function and the second one is that there is a list of public slots that correspond to the actions that the component can perform. The *getViewers* function is similar to the function with the same name of the *ParameterSettableUI* class described in [the page about components]([ComponentsConfig]). When using *BaseExperiment* one has not to define a subclass of *ParameterSettableUI* and return it via the *getUIManager* function, because the function to return the list of windows (i.e. *getViewers*) and the function to add menus (i.e. *addAdditionalMenus*) are already part of *BaseExperiment*. Moreover the menu with actions is automatically populated, so there should be no need to override the *fillActionsMenu* function (which is also present).

-As far as the functions implementing the actions is concerned, the thing to highlight here is that they must be declared as *slots*, otherwise it will not be possible to run them when *total99* is started in batch mode. The following code snippets show the relevant parts of the *Backpropagation* class implementation:

 ~~~~~~~
 :::C++
@@ -93,15 +103,7 @@
 }
 ~~~~~~~

-In the constructor the operations that the class provides are declared. There are three kinds of operations and one macro for each of them (again, refer to the [API documentation]([APIDoc]) for a complete explanation):
-
-* *DECLARE_THREAD_OPERATION* - the operation is run in a dedicated thread (i.e. not in the GUI thread). This means that care has to be taken when exchanging data with a GUI element;
-* *DECLARE_STEPPABLE_THREAD_OPERATION* - the operation is run in a dedicated thread, like in *DECLARE_THREAD_OPERATION* but, in addition, it is possible to pause the operation and perform step-by-step execution;
-* *DECLARE_IMMEDIATE_OPERATION* - the operation runs in the GUI thread. Notice that long running operations in this modality will render the GUI non-responsive.
-
-The first argument of each macro is the class name, the second one is the name of the function implementing the operation. As note above, when operations run in a dedicated thread care must be taken when communicating with the GUI. See the **Threading issues** note in [this page]([ComponentsConfig]) for more information.
-
-The next three code snippets show the relevant parts of the implementation of each kind of operations:
+Below we include critical portion of the corresponding .cpp file.

 ~~~~~~~
 :::C++

ComponentBaseExperiment modified by Stefano Nolfi

Stefano Nolfi — Tue, 27 Oct 2015 14:31:39 -0000

--- v6
+++ v7
@@ -1,7 +1,7 @@
 The Component and BaseExperiment classes
 ======

-The [Creating a new experiment]([CreatingNewExperiment]) page explain how to quickly setup a new robotic experiment  by using the *EvoRobotExperiment* class. Here we show other ways to create new experiments that are more flexible (e.g. enable you to instantiate only the components that are needed) but that require more programming effort.
+The [Creating a new experiment]([CreatingNewExperiment]) page explain how to quickly setup a new robotic experiment  by using the *EvoRobotExperiment* class. Here we show other ways to create new experiments that are more flexible (e.g. enable you to instantiate only the components that are needed) but that require more programming effort. This can be done by using the BaseExperiment or the Component classes instead of the EvoRobotExperiment.  You might decide to use these methods, for example, if you want to design an experiment that use a neural network but does not require the utilization of any robot, as in the case of the BackPropagationExperiment illustrated below. Please notice that the type of the class you use to create tour new experiment should be specified in the .ini configuration file of the experiment in  the mainComponent parameter. 

 Introduction
 -------
@@ -10,10 +10,7 @@

 A further possibility is to inherit from the *Component* class (that, despite the name, is simply a particular kind of component, see the section at the end of [this page]([ComponentsConfig])). This approach will be briefly described at the end of this page, but it is highly discouraged because it is too low-level and because it is scheduled to be removed in the next major FARSA release.

-Integration with *total99*
--------

-Before showing how to use the *BaseExperiment* and *Component* classes, we need to quickly explain how they are related to *total99*. Here is the configuration file for the *Backpropagation* plugin, which we will also use as example further below.

 ~~~~~~~
 :::INI
@@ -35,8 +32,6 @@
 nSensors = 2
 nMotors = 1
 ~~~~~~~
-
-When *total99* loads a configuration file it expects to find a group called *\[TOTAL99\]*. The group contains general information about the experiment, but what is important to note here is the *mainComponent* parameter. This is the name of the group associated with the first component that *total99* instantiates (the group is called *\[Component\]* by default). The component in this group must be a subclass of the *Component* class (or of *BaseExperiment*, that has *Component* among its parent classes). This class has some special methods that other components lack which are needed to correctly integrate with *total99*.

 The *BaseExperiment* class
 -------