doc/optimizer.rst

   1
   2 .. _optimizationplugin:
   3
   4 Definition of an algorithm for the OptimizerLoop
   5 ==========================================================================
   6 The definition of the optimization algorithm is done by way of plugin.
   7 The plugin can be a C++ plugin implemented in a dynamic library (.so file) or a Python plugin implemented in a Python module (.py).
   8 It is possible to implement two kinds of algorithm : synchronous or asynchronous.
   9
  10 Synchronous algorithm
  11 --------------------------------------------------
  12 In synchronous mode, the OptimizerLoop calls the algorithm to know what are the types of the input port (sample sent to the internal node),
  13 and of the output port (data returned by the internal node). Then it calls the algorithm to initialize
  14 it. At each iteration, it calls the algorithm to produce new sample or to stop the iteration. Finally, it calls the algorithm
  15 to finalize the optimization process.
  16
  17 A synchronous algorithm is implemented in a class derived from the base class OptimizerAlgSync with several methods that
  18 must be implemented and some optional methods (in C++ and in Python):
  19
  20 - **getTCForIn**, this method must return the YACS type of the input port of the internal node
  21 - **getTCForOut**, this method must return the YACS type of the output port of the internal node
  22 - **initialize** (optional), this method is called during the algorithm initialization
  23 - **start**, this method is called at the beginning of iterations
  24 - **takeDecision**, this method is called at each iteration
  25 - **finish** (optional), this method is called to finish the algorithm at the end of the iteration process
  26
  27 In Python you need to implement another method:
  28
  29 - **setPool**, this method is used to set the data pool that is used to exchange data
  30
  31 C++ plugin example
  32 ''''''''''''''''''''
  33 Here is a small example of a C++ synchronous algorithm:
  34
  35 .. literalinclude:: ../src/yacsloader/Test/OptimizerAlgSyncExample.cxx
  36     :language: cpp
  37
  38 Here, the entry point in the dynamic library is the name of the factory function : createOptimizerAlgSyncExample
  39 that returns an instance of the OptimizerAlgSyncExample class that implements the algorithm.
  40
  41 Python plugin example
  42 ''''''''''''''''''''''
  43 Here, the same example of a synchronous algorithm in Python:
  44
  45 .. literalinclude:: ../src/yacsloader/Test/algosyncexample.py
  46
  47 Here, the entry point in the Python module is directly the name of the class that implements the algorithm : myalgosync.
  48
  49
  50 Asynchronous algorithm
  51 --------------------------------------------------
  52 In asynchronous mode, all is the same except that after the initialization phase, the OptimizerLoop calls the algorithm only one time
  53 to start it in a separate thread.
  54
  55 An asynchronous algorithm is implemented in a class derived from the base class OptimizerAlgASync with several methods that
  56 must be implemented and some optional methods (in C++ and in Python):
  57
  58 - **getTCForIn**, this method must return the YACS type of the input port of the internal node
  59 - **getTCForOut**, this method must return the YACS type of the output port of the internal node
  60 - **initialize** (optional), this method is called during the algorithm initialization
  61 - **startToTakeDecision**, this method is called to start the iteration process in a separate thread. It is the body of the algorithm.
  62 - **finish** (optional), this method is called to finish the algorithm at the end of the iteration process
  63
  64 In Python you need to implement another method:
  65
  66 - **setPool**, this method is used to set the data pool that is used to exchange data
  67
  68 C++ plugin example
  69 ''''''''''''''''''''
  70 Here is a small example of a C++ asynchronous algorithm:
  71
  72 .. literalinclude:: ../src/yacsloader/Test/OptimizerAlgASyncExample.cxx
  73     :language: cpp
  74
  75
  76 Here, the entry point in the dynamic library is the name of the factory function : createOptimizerAlgASyncExample
  77 that returns an instance of the OptimizerAlgASyncExample class that implements the algorithm.
  78
  79 Python plugin example
  80 ''''''''''''''''''''''''
  81 Here is an example of an asynchronous algorithm implemented in Python:
  82
  83 .. literalinclude:: ../src/yacsloader/Test/algoasyncexample.py
  84
  85 Here, the entry point in the Python module is directly the name of the class that implements the algorithm : myalgoasync.
  86
  87
  88 C++ algorithm calling Python code
  89 --------------------------------------------------
  90
  91 In some cases, it can be necessary to implement the algorithm as a C++ class but
  92 nevertheless to call some Python code from this class. This is also possible with the
  93 OptimizerLoop and even quite simple. To achieve this, your C++ class should inherit from
  94 PyOptimizerAlgSync for a synchronous algorithm or from PyOptimizerAlgASync for an
  95 asynchronous algorithm. The guidelines for developing the algorithm are the same as in
  96 the C++ case, but you can also call any method from the Python C API. You don't need to
  97 take care of the Python global interpreter lock or of thread states because this is
  98 already done in the PyOptimizerAlg classes. An example of this kind of algorithm is the
  99 class OpenTURNSScriptLauncher that can be found in the module OPENTURNS_SRC.