From: Ovidiu Mircescu <ovidiu.mircescu@edf.fr>
Date: Tue, 22 Jul 2014 15:52:51 +0000 (+0200)
Subject: More documentation about the OptimizerLoop.
X-Git-Tag: V7_5_0a1~7^2~2
X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=f35803bf043d504589ea6e39402e4657637556ce;p=modules%2Fyacs.git

More documentation about the OptimizerLoop.
---

diff --git a/doc/optimizer.rst b/doc/optimizer.rst
index 5ea0cfd01..9dd3dcf2f 100644
--- a/doc/optimizer.rst
+++ b/doc/optimizer.rst
@@ -7,6 +7,9 @@ The definition of the optimization algorithm is done by way of plugin.
 The plugin can be a C++ plugin implemented in a dynamic library (.so file) or a Python plugin implemented in a Python module (.py).
 It is possible to implement two kinds of algorithm : synchronous or asynchronous.
 
+The algorithm uses a pool of samples to be evaluated.
+When all the samples of the pool are evaluated, the algorithm stops.
+
 Synchronous algorithm
 --------------------------------------------------
 In synchronous mode, the OptimizerLoop calls the algorithm to know what are the types of the input port (sample sent to the internal node), 
@@ -19,10 +22,13 @@ must be implemented and some optional methods (in C++ and in Python):
 
 - **getTCForIn**, this method must return the YACS type of the input port of the internal node
 - **getTCForOut**, this method must return the YACS type of the output port of the internal node
+- **getTCForAlgoInit** (optional), this method returns the type of the "algoInit" port, string if undefined
+- **getTCForAlgoResult** (optional), this method returns the type of the "algoResult" port, string if undefined
 - **initialize** (optional), this method is called during the algorithm initialization
 - **start**, this method is called at the beginning of iterations
 - **takeDecision**, this method is called at each iteration
 - **finish** (optional), this method is called to finish the algorithm at the end of the iteration process
+- **getAlgoResult** (optional), this method returns the value of the "algoResult" port, "NULL" if undefined
 
 In Python you need to implement another method:
 
@@ -57,9 +63,12 @@ must be implemented and some optional methods (in C++ and in Python):
 
 - **getTCForIn**, this method must return the YACS type of the input port of the internal node
 - **getTCForOut**, this method must return the YACS type of the output port of the internal node
+- **getTCForAlgoInit** (optional), this method returns the type of the "algoInit" port, string if undefined
+- **getTCForAlgoResult** (optional), this method returns the type of the "algoResult" port, string if undefined
 - **initialize** (optional), this method is called during the algorithm initialization
 - **startToTakeDecision**, this method is called to start the iteration process in a separate thread. It is the body of the algorithm.
 - **finish** (optional), this method is called to finish the algorithm at the end of the iteration process
+- **getAlgoResult** (optional), this method returns the value of the "algoResult" port, "NULL" if undefined
 
 In Python you need to implement another method:
 
@@ -84,6 +93,53 @@ Here is an example of an asynchronous algorithm implemented in Python:
 
 Here, the entry point in the Python module is directly the name of the class that implements the algorithm : myalgoasync.
 
+Managing the pool of samples
+---------------------------------
+
+Samples can be added to the pool at the initialization of the algorithm or
+every time a sample is evaluated (while "taking decision").
+The algorithm stops to take decisions when every sample is evaluated.
+
+A sample has:
+
+- an identifier - *Id*
+- a priority - it is used to choose the order of evaluation
+- a value - *In*
+- an evaluated or computed value - *Out*
+
+The current sample is the sample used by the latest terminated evaluation.
+
+These are the methods needed to manage the pool of samples:
+
+.. code-block:: cpp
+
+  class Pool
+  {
+      //...
+    public:
+      //For algorithm use
+      int getCurrentId() const ;
+      Any *getCurrentInSample() const ;
+      Any *getCurrentOutSample() const ;
+      Any *getOutSample(int id);
+      void pushInSample(int id, Any *inSample, unsigned char priority = 0);
+      void destroyAll();
+      //...
+  }
+
+In C++, the samples are of type ``YACS::ENGINE::Any``, in order to support any
+type supported by YACS. For conversion to standard types, use:
+
+- ``getIntValue``
+- ``getBoolValue``
+- ``getDoubleValue``
+- ``getStringValue``
+
+It is possible to create a pointer to a new object with:
+
+- ``YACS::ENGINE::AtomAny::New``
+
+For further information, see `include/salome/Any.hxx <file:../../../../../include/salome/Any.hxx>`_.
 
 C++ algorithm calling Python code
 --------------------------------------------------
diff --git a/src/engine/Pool.hxx b/src/engine/Pool.hxx
index 3fd53c97c..efd293777 100644
--- a/src/engine/Pool.hxx
+++ b/src/engine/Pool.hxx
@@ -32,6 +32,12 @@ namespace YACS
     class Any;
     class OptimizerLoop;
 
+    /*! \brief Pool used to manage the samples of the optimizer loop plugin.
+     *  
+     *  Every sample has an identifier (Id), a priority, an initial value (In)
+     *  and an evaluation value (Out).
+     *  The current sample is the sample used by the latest terminated evaluation.
+     */
     class YACSLIBENGINE_EXPORT Pool
     {
       friend class OptimizerLoop;