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.
In synchronous mode, the OptimizerLoop calls the algorithm to know what are the types of the input port (sample sent to the internal node), and of the output port (data returned by the internal node). Then it calls the algorithm to initialize it. At each iteration, it calls the algorithm to produce new sample or to stop the iteration. Finally, it calls the algorithm to finalize the optimization process.
A synchronous algorithm is implemented in a class derived from the base class OptimizerAlgSync with several methods that must be implemented and some optional methods (in C++ and in Python):
In Python you need to implement another method:
Here is a small example of a C++ synchronous algorithm:
// Copyright (C) 2006-2016 CEA/DEN, EDF R&D
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
//
// See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
//
#include <cmath>
#include <iostream>
#include "OptimizerAlg.hxx"
#include <iostream>
//using namespace YACS::ENGINE;
extern "C"
{
YACS::ENGINE::OptimizerAlgBase * createOptimizerAlgSyncExample(YACS::ENGINE::Pool * pool);
}
class OptimizerAlgSyncExample : public YACS::ENGINE::OptimizerAlgSync
{
private:
int _iter;
YACS::ENGINE::TypeCode *_tcInt;
YACS::ENGINE::TypeCode *_tcDouble;
public:
OptimizerAlgSyncExample(YACS::ENGINE::Pool *pool);
virtual ~OptimizerAlgSyncExample();
//! returns typecode of type expected as Input. OwnerShip of returned pointer is held by this.
virtual YACS::ENGINE::TypeCode *getTCForIn() const;
//! returns typecode of type expected as Output. OwnerShip of returned pointer is held by this.
virtual YACS::ENGINE::TypeCode *getTCForOut() const;
//! returns typecode of type expected for algo initialization. OwnerShip of returned pointer is held by this.
virtual YACS::ENGINE::TypeCode *getTCForAlgoInit() const;
//! returns typecode of type expected as algo result. OwnerShip of returned pointer is held by this.
virtual YACS::ENGINE::TypeCode *getTCForAlgoResult() const;
virtual void initialize(const YACS::ENGINE::Any *input) throw (YACS::Exception);
virtual void start(); //! Update _pool attribute before performing anything.
virtual void takeDecision();//! _pool->getCurrentId gives the \b id at the origin of this call.
//! Perform the job of analysing to know what new jobs to do (_pool->pushInSample)
//! or in case of convergence _pool->destroyAll
virtual void finish();//! Called when optimization has succeed.
virtual YACS::ENGINE::Any * getAlgoResult();
};
OptimizerAlgSyncExample::OptimizerAlgSyncExample(YACS::ENGINE::Pool *pool)
: YACS::ENGINE::OptimizerAlgSync(pool), _tcInt(0), _tcDouble(0), _iter(0)
{
_tcDouble = new YACS::ENGINE::TypeCode(YACS::ENGINE::Double);
_tcInt = new YACS::ENGINE::TypeCode(YACS::ENGINE::Int);
}
OptimizerAlgSyncExample::~OptimizerAlgSyncExample()
{
_tcDouble->decrRef();
_tcInt->decrRef();
}
//! Return the typecode of the expected input of the internal node
YACS::ENGINE::TypeCode * OptimizerAlgSyncExample::getTCForIn() const
{
return _tcDouble;
}
//! Return the typecode of the expected output of the internal node
YACS::ENGINE::TypeCode * OptimizerAlgSyncExample::getTCForOut() const
{
return _tcInt;
}
//! Return the typecode of the expected input of the algorithm (algoInit port)
YACS::ENGINE::TypeCode * OptimizerAlgSyncExample::getTCForAlgoInit() const
{
return _tcInt;
}
//! Return the typecode of the expected output of the algorithm (algoResult port)
YACS::ENGINE::TypeCode * OptimizerAlgSyncExample::getTCForAlgoResult() const
{
return _tcInt;
}
//! Optional method to initialize the algorithm.
/*!
* For now, the parameter input is always NULL. It might be used in the
* future to initialize an algorithm with custom data.
*/
void OptimizerAlgSyncExample::initialize(const YACS::ENGINE::Any *input)
throw (YACS::Exception)
{
std::cout << "Algo initialize, input = " << input->getIntValue() << std::endl;
}
//! Start to fill the pool with samples to evaluate
void OptimizerAlgSyncExample::start()
{
std::cout << "Algo start " << std::endl;
_iter=0;
YACS::ENGINE::Any *val=YACS::ENGINE::AtomAny::New(0.5);
_pool->pushInSample(_iter,val);
}
//! This method is called each time a sample has been evaluated.
/*!
* It can either add new samples to evaluate in the pool, do nothing (wait
* for more samples), or empty the pool to finish the evaluation.
*/
void OptimizerAlgSyncExample::takeDecision()
{
int currentId = _pool->getCurrentId();
double valIn = _pool->getCurrentInSample()->getDoubleValue();
int valOut = _pool->getCurrentOutSample()->getIntValue();
std::cout << "Algo takeDecision currentId=" << currentId;
std::cout << ", valIn=" << valIn;
std::cout << ", valOut=" << valOut << std::endl;
_iter++;
if(_iter < 3)
{
YACS::ENGINE::Any *val=YACS::ENGINE::AtomAny::New(valIn + 1);
_pool->pushInSample(_iter, val);
}
}
/*!
* Optional method called when the algorithm has finished, successfully or
* not, to perform any necessary clean up.
*/
void OptimizerAlgSyncExample::finish()
{
std::cout << "Algo finish" << std::endl;
_pool->destroyAll();
}
/*!
* Return the value of the algoResult port.
*/
YACS::ENGINE::Any * OptimizerAlgSyncExample::getAlgoResult()
{
YACS::ENGINE::Any *val=YACS::ENGINE::AtomAny::New(42);
return val;
}
//! Factory method to create the algorithm.
YACS::ENGINE::OptimizerAlgBase * createOptimizerAlgSyncExample(YACS::ENGINE::Pool *pool)
{
return new OptimizerAlgSyncExample(pool);
}
Here, the entry point in the dynamic library is the name of the factory function : createOptimizerAlgSyncExample that returns an instance of the OptimizerAlgSyncExample class that implements the algorithm.
Here, the same example of a synchronous algorithm in Python:
# Copyright (C) 2006-2016 CEA/DEN, EDF R&D
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
# See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
#
import SALOMERuntime
class myalgosync(SALOMERuntime.OptimizerAlgSync):
def __init__(self):
SALOMERuntime.OptimizerAlgSync.__init__(self, None)
r=SALOMERuntime.getSALOMERuntime()
self.tin=r.getTypeCode("double")
self.tout=r.getTypeCode("int")
self.tAlgoInit=r.getTypeCode("int")
self.tAlgoResult=r.getTypeCode("int")
def setPool(self,pool):
"""Must be implemented to set the pool"""
self.pool=pool
def getTCForIn(self):
"""return typecode of type expected as Input of the internal node """
return self.tin
def getTCForOut(self):
"""return typecode of type expected as Output of the internal node"""
return self.tout
def getTCForAlgoInit(self):
"""return typecode of type expected as input for initialize """
return self.tAlgoInit
def getTCForAlgoResult(self):
"""return typecode of type expected as output of the algorithm """
return self.tAlgoResult
def initialize(self,input):
"""Optional method called on initialization.
The type of "input" is returned by "getTCForAlgoInit"
"""
print "Algo initialize, input = ", input.getIntValue()
def start(self):
"""Start to fill the pool with samples to evaluate."""
print "Algo start "
self.iter=0
# pushInSample(id, value)
self.pool.pushInSample(self.iter, 0.5)
def takeDecision(self):
""" This method is called each time a sample has been evaluated. It can
either add new samples to evaluate in the pool, do nothing (wait for
more samples), or empty the pool to finish the evaluation.
"""
currentId=self.pool.getCurrentId()
valIn = self.pool.getCurrentInSample().getDoubleValue()
valOut = self.pool.getCurrentOutSample().getIntValue()
print "Algo takeDecision currentId=%s, valIn=%s, valOut=%s" % (currentId, valIn, valOut)
self.iter=self.iter+1
if self.iter < 3:
# continue
nextSample = valIn + 1
self.pool.pushInSample(self.iter, nextSample)
def finish(self):
"""Optional method called when the algorithm has finished, successfully
or not, to perform any necessary clean up."""
print "Algo finish"
self.pool.destroyAll()
def getAlgoResult(self):
"""return the result of the algorithm.
The object returned is of type indicated by getTCForAlgoResult.
"""
return 42
Here, the entry point in the Python module is directly the name of the class that implements the algorithm : myalgosync.
In asynchronous mode, all is the same except that after the initialization phase, the OptimizerLoop calls the algorithm only one time to start it in a separate thread.
An asynchronous algorithm is implemented in a class derived from the base class OptimizerAlgASync with several methods that must be implemented and some optional methods (in C++ and in Python):
In Python you need to implement another method:
Here is a small example of a C++ asynchronous algorithm:
// Copyright (C) 2006-2016 CEA/DEN, EDF R&D
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
//
// See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
//
#include "OptimizerAlg.hxx"
#include <iostream>
//using namespace YACS::ENGINE;
extern "C"
{
YACS::ENGINE::OptimizerAlgBase * createOptimizerAlgASyncExample(YACS::ENGINE::Pool * pool);
}
class OptimizerAlgASyncExample : public YACS::ENGINE::OptimizerAlgASync
{
private:
YACS::ENGINE::TypeCode *_tcInt;
YACS::ENGINE::TypeCode *_tcDouble;
public:
OptimizerAlgASyncExample(YACS::ENGINE::Pool *pool);
virtual ~OptimizerAlgASyncExample();
//! returns typecode of type expected as Input. OwnerShip of returned pointer is held by this.
virtual YACS::ENGINE::TypeCode *getTCForIn() const;
//! returns typecode of type expected as Output. OwnerShip of returned pointer is held by this.
virtual YACS::ENGINE::TypeCode *getTCForOut() const;
//! returns typecode of type expected for algo initialization. OwnerShip of returned pointer is held by this.
virtual YACS::ENGINE::TypeCode *getTCForAlgoInit() const;
//! returns typecode of type expected as algo result. OwnerShip of returned pointer is held by this.
virtual YACS::ENGINE::TypeCode *getTCForAlgoResult() const;
virtual void initialize(const YACS::ENGINE::Any *input) throw (YACS::Exception);
virtual void startToTakeDecision();
virtual void finish();//! Called when optimization has succeed.
virtual YACS::ENGINE::Any * getAlgoResult();
};
OptimizerAlgASyncExample::OptimizerAlgASyncExample(YACS::ENGINE::Pool *pool)
: YACS::ENGINE::OptimizerAlgASync(pool), _tcInt(0), _tcDouble(0)
{
_tcDouble = new YACS::ENGINE::TypeCode(YACS::ENGINE::Double);
_tcInt = new YACS::ENGINE::TypeCode(YACS::ENGINE::Int);
}
OptimizerAlgASyncExample::~OptimizerAlgASyncExample()
{
_tcDouble->decrRef();
_tcInt->decrRef();
}
//! Return the typecode of the expected input of the internal node
YACS::ENGINE::TypeCode * OptimizerAlgASyncExample::getTCForIn() const
{
return _tcDouble;
}
//! Return the typecode of the expected output of the internal node
YACS::ENGINE::TypeCode * OptimizerAlgASyncExample::getTCForOut() const
{
return _tcInt;
}
//! Return the typecode of the expected input of the algorithm (algoInit port)
YACS::ENGINE::TypeCode * OptimizerAlgASyncExample::getTCForAlgoInit() const
{
return _tcInt;
}
//! Return the typecode of the expected output of the algorithm (algoResult port)
YACS::ENGINE::TypeCode * OptimizerAlgASyncExample::getTCForAlgoResult() const
{
return _tcInt;
}
//! Optional method to initialize the algorithm.
/*!
* For now, the parameter input is always NULL. It might be used in the
* future to initialize an algorithm with custom data.
*/
void OptimizerAlgASyncExample::initialize(const YACS::ENGINE::Any *input)
throw (YACS::Exception)
{
std::cout << "Algo initialize, input = " << input->getIntValue() << std::endl;
}
//! This method is called only once to launch the algorithm.
/*!
* It must first fill the pool with samples to evaluate and call
* signalMasterAndWait() to block until a sample has been evaluated. When
* returning from this method, it MUST check for an eventual termination
* request (with the method isTerminationRequested()). If the termination
* is requested, the method must perform any necessary cleanup and return
* as soon as possible. Otherwise it can either add new samples to evaluate
* in the pool, do nothing (wait for more samples), or empty the pool and
* return to finish the evaluation.
*/
void OptimizerAlgASyncExample::startToTakeDecision()
{
std::cout << "startToTakeDecision" << std::endl;
int iter = 0;
YACS::ENGINE::Any *val=YACS::ENGINE::AtomAny::New(0.5);
_pool->pushInSample(iter, val);
signalMasterAndWait();
while(!isTerminationRequested())
{
int currentId = _pool->getCurrentId();
double valIn = _pool->getCurrentInSample()->getDoubleValue();
int valOut = _pool->getCurrentOutSample()->getIntValue();
std::cout << "Compute currentId=" << currentId;
std::cout << ", valIn=" << valIn;
std::cout << ", valOut=" << valOut << std::endl;
iter++;
if(iter < 3)
{
YACS::ENGINE::Any *val=YACS::ENGINE::AtomAny::New(valIn + 1);
_pool->pushInSample(iter, val);
}
signalMasterAndWait();
}
}
/*!
* Optional method called when the algorithm has finished, successfully or
* not, to perform any necessary clean up.
*/
void OptimizerAlgASyncExample::finish()
{
std::cout << "Algo finish" << std::endl;
_pool->destroyAll();
}
/*!
* Return the value of the algoResult port.
*/
YACS::ENGINE::Any * OptimizerAlgASyncExample::getAlgoResult()
{
YACS::ENGINE::Any *val=YACS::ENGINE::AtomAny::New(42);
return val;
}
//! Factory method to create the algorithm.
YACS::ENGINE::OptimizerAlgBase * createOptimizerAlgASyncExample(YACS::ENGINE::Pool *pool)
{
return new OptimizerAlgASyncExample(pool);
}
Here, the entry point in the dynamic library is the name of the factory function : createOptimizerAlgASyncExample that returns an instance of the OptimizerAlgASyncExample class that implements the algorithm.
Here is an example of an asynchronous algorithm implemented in Python:
# Copyright (C) 2006-2016 CEA/DEN, EDF R&D
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
# See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
#
import SALOMERuntime
class myalgoasync(SALOMERuntime.OptimizerAlgASync):
def __init__(self):
SALOMERuntime.OptimizerAlgASync.__init__(self, None)
r=SALOMERuntime.getSALOMERuntime()
self.tin=r.getTypeCode("double")
self.tout=r.getTypeCode("int")
self.tAlgoInit=r.getTypeCode("int")
self.tAlgoResult=r.getTypeCode("int")
def setPool(self,pool):
"""Must be implemented to set the pool"""
self.pool=pool
def getTCForIn(self):
"""return typecode of type expected as Input of the internal node """
return self.tin
def getTCForOut(self):
"""return typecode of type expected as Output of the internal node"""
return self.tout
def getTCForAlgoInit(self):
"""return typecode of type expected as input for initialize """
return self.tAlgoInit
def getTCForAlgoResult(self):
"""return typecode of type expected as output of the algorithm """
return self.tAlgoResult
def initialize(self,input):
"""Optional method called on initialization.
The type of "input" is returned by "getTCForAlgoInit"
"""
print "Algo initialize, input = ", input.getIntValue()
def startToTakeDecision(self):
"""This method is called only once to launch the algorithm. It must
first fill the pool with samples to evaluate and call
self.signalMasterAndWait() to block until a sample has been
evaluated. When returning from this method, it MUST check for an
eventual termination request (with the method
self.isTerminationRequested()). If the termination is requested, the
method must perform any necessary cleanup and return as soon as
possible. Otherwise it can either add new samples to evaluate in the
pool, do nothing (wait for more samples), or empty the pool and
return to finish the evaluation.
"""
print "startToTakeDecision"
# fill the pool with samples
iter=0
self.pool.pushInSample(0, 0.5)
#
self.signalMasterAndWait()
while not self.isTerminationRequested():
currentId=self.pool.getCurrentId()
valIn = self.pool.getCurrentInSample().getDoubleValue()
valOut = self.pool.getCurrentOutSample().getIntValue()
print "Compute currentId=%s, valIn=%s, valOut=%s" % (currentId, valIn, valOut)
iter=iter+1
if iter < 3:
nextSample = valIn + 1
self.pool.pushInSample(iter, nextSample)
self.signalMasterAndWait()
def finish(self):
"""Optional method called when the algorithm has finished, successfully
or not, to perform any necessary clean up."""
print "Algo finish"
self.pool.destroyAll()
def getAlgoResult(self):
"""return the result of the algorithm.
The object returned is of type indicated by getTCForAlgoResult.
"""
return 42
Here, the entry point in the Python module is directly the name of the class that implements the algorithm : myalgoasync.
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:
The current sample is the sample used by the latest terminated evaluation.
These are the methods needed to manage the pool of samples:
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:
It is possible to create a pointer to a new object with:
For further information, see include/salome/Any.hxx.
In some cases, it can be necessary to implement the algorithm as a C++ class but nevertheless to call some Python code from this class. This is also possible with the OptimizerLoop and even quite simple. To achieve this, your C++ class should inherit from PyOptimizerAlgSync for a synchronous algorithm or from PyOptimizerAlgASync for an asynchronous algorithm. The guidelines for developing the algorithm are the same as in the C++ case, but you can also call any method from the Python C API. You don’t need to take care of the Python global interpreter lock or of thread states because this is already done in the PyOptimizerAlg classes. An example of this kind of algorithm is the class OpenTURNSScriptLauncher that can be found in the module OPENTURNS_SRC.