Sferes2 – reference

Object-oriented programming (OOP) has many advantages which are desirable for complex high-level code. However, classic OOP (e.g. in C++) heavily relies on virtual methods to implement abstraction and polymorphism. Such an approach has a significant run-time overhead:

• selecting the good method to call adds an indirection (the software have to check the virtual table)
• abstract/virtual methods cannot be inlined, resulting in a overhead for very simple methods (e.g. setters/getters).

In a few word, we want the main benefits of OOP (abstraction, re-usability) and the efficiency of low-level languages.

One solution in C++ is to use the "curiously recurring template pattern" (http://en.wikipedia.org/wiki/Curiously_Recurring_Template_Pattern). Here is the idea:

template <class Derived> struct Base
{
    void interface()
    {
        static_cast<Derived*>(this)->implementation();
    }
    void f()
    {
       for(int i = 0; i < 3; ++i) interface();
    }
};
 
struct Derived : Base<Derived>
{
    void implementation() { std::cout<<"impl"<<std::endl; }
};

This code mimics a virtual call of an abstract method: in the abstract class (Base), a generic algorithm can use methods which are only defined in the derived classes. Extending this pattern to draw a full hierarchy of classes requires more work; sferes2 relies on the method described in the following paper:

Nicolas Burrus, Alexandre Duret-Lutz, Thierry Géraud, David Lesage and Raphaël Poss. A Static C++ Object-Oriented Programming (SCOOP) Paradigm Mixing Benefits of Traditional OOP and Generic Programming. In Proceedings of the Workshop on Multiple Paradigm with OO Languages (MPOOL'03), 2003. http://www.lrde.epita.fr/dload/papers/mpool03.pdf

This mechanics is hidden in sferes2 behind some macros (see section macros)

Evolutionary algorithms have a lot of parameters (e.g. population size, mutation rate, etc.) and we need a convenient way to set them. A configuration file (e.g. an XML file) is often used; however, such a method has two drawbacks:

• some code to read the files has to be written and kept synchronized with the objects;
• parameters are unknown at compile time so some checks (e.g. if (mutation_type = x) {} else { } …) have to be done many times whereas they are useless.

In sferes2, parameters are defined at compile time using a structure which contains only constants. This structure is passed to all sferes2 classes so they can access to the parameters. This method allows to avoid to write read/write code for parameters. It also allows the compiler to propagate constants and settings in the whole source code, resulting in an executable optimized for the specific parameters.

To simplify the writing of "static virtual functions" and the definition of static parameters, sferes2 provides several macros which are defined in stc.hpp.

• File: sferes/fit/fitness.hpp
• Description: Fitness is the base class of fitness functions in sferes2. It has two main attributes:
  • float _value (setter/getter Fitness::value()) -> the value of the fitness for single-objective optimization
  • std::vector<float> _objs (setter/getter Fitness::objs()) -> the value of each objective, for multiobjective optimization
• This class is abstract

In most sferes2 experiments, you will have to design your own fitness. A fitness should:

• be defined using SFERES_FITNESS(MyFitness, sferes::fit::Fitness)
• define the eval() method, which takes an individual
• attribute a fitness value in this->_value (single objective optimization) or this->_objs (multiobjective optimization)

  A fitness is a "normal" class and consequently you can add other methods or attributes to suit your needs.

Example:

// single objective fitess
SFERES_FITNESS(FitnessSingle, sferes::fit::fitness)
{
  // (optional) constructor
  FitnessSingle()
    {
      this->_value = -1;
    }
  // evaluation
  template<typename Indiv>
    void eval(Indiv& indiv)
  {
    this->_value = -42;
  }
};

// two-objective fitness
SFERES_FITNESS(FitnessMulti, sferes::fit::fitness)
{
  // constructor
  FitnessMulti()
    {
      this->_objs.resize(2);   
    }
  // evaluation
  template<typename Indiv>
    void eval(Indiv& indiv)
  {
    this->_objs[0] = -42;
    this->_objs[1] = 42;
  }
};

When loading a result file, it is often useful to slightly change the fitness function, for instance to display/log data about the behavior of the individual. This can be easily done in sferes2 using the boolean Fitness::mode() than can takes two values:

• fit::mode::view when you are viewing an individual via –load
• fit::mode::eval when you are evaluting individuals (during the evolutionary process)

Example:

// single objective fitess
SFERES_FITNESS(FitnessSingle, sferes::fit::fitness)
{
  // evaluation
  template<typename Indiv>
    void eval(Indiv& indiv)
  {
    if (this->mode() == sferes::fit::mode::view)
      {
      std::ofstream ofs("fit.dat");
      ofs<<"this is a log file !"<<std::endl;
      }
    this->_value = -42;
  }
};

All evolutionary algorithms (EA) use the following parameters:

• static const size_t Params::pop::size = population size
• static const float Params::pop::initial_aleat = during the random generation, Params::pop::initial_aleat × Params::pop::size individuals are generated and only the Params::pop::size best ones are kept
• static const int Params::pop::dump_period: the period between each write of results, examples:
  • 1: statistics are written at each generation (gen_0, gen_1, gen_2, …)
  • -1: statistics are never written (useful for unit tests)
  • 10: statistics are written each 10 generations (gen_0, gen_10, …)

• File: sferes/ea/rank_simple.hpp
• Unit test: tests/ea/rank_simple.cpp
• Typical typename::

typedef sferes::ea::RankSimple<phen_t, eval_t, stat_t, modifier_t, Params> ea_t;

• Description: A rank-based single-objective evolutionary algorithm. Individuals are selected using the following formula:
  • n = k_r × p
  • κ = c^{n + 1} - 1
  • f = n / (κ + 1)
  • i = p - f × log(r × κ + 1)
  • where
    • c = Params::pop::coeff
    • k_r = Params::pop::keep_rate
    • p = Params::pop::size
    • r = a random number in [0,1[
    • i = index of the selected individual
• parameters:
  • static const float Params::pop::coeff = a internal parameter (see the previous formula) ; typical value : 1.1
  • static const float Params::pop::keep_rate = proportion of individuals kept from a generation to the next one ; typical value : 0.2 to 0.6

• File: sferes/ea/nsga2.hpp
• Unit test: tests/ea/nsga2.cpp
• Example: examples/ex_nsga2.cpp
• Typical typename::

typedef sferes::ea::Nsga2<phen_t, eval_t, stat_t, modifier_t, Params> ea_t;

• Description: Implementation of the NSGA-II multiobjective evolutionary algorithm. See:
  • Deb, K. (2001). Multi-Objective Optimization Using Evolutionary Algorithms. Wiley.
  • Deb, K., Pratap, A., Agarwal, S. and Meyarivan, T. (2002). A fast and elitist multiobjective genetic algorithm: NSGA-II. In IEEE transactions on evolutionary computation, 6:2:182-197
• Parameters: pop_size must be divisible by 4
• Note: NSGA-II can be efficient for single-objective optimization as it corresponds to a classic tournament-based evolutionary algorithm. In sferes2, a 1-sized _objs vector in the fitness can be employed (don't use _value).

• File: sferes/ea/eps_moea.hpp
• Unit test: tests/ea/eps_moea.cpp
• Typical typename::

typedef sferes::ea::EpsMOEA<phen_t, eval_t, stat_t, modifier_t, Params> ea_t

• Description: Implementation of the ε-MOEA multiobjective evolutionary algorithm. See:
  • Deb, K., Mohan, M. and Mishra, S. (2005). Evaluating the ε-domination based multi-objective evolutionary algorithm for a quick computation of pareto-optimal solutions. In Evolutionary Computation, 13:4:501-525.
• Parameters
  • SFERES_ARRAY(float, eps, 0.0075f, 0.0075f) = values of ε for each objective. There should be as many values as objectives.
  • SFERES_ARRAY(float, min_fit, 0.0f, 0.0f) = minimum value of fitness for each objective.There should as many values as objectives
  • static const size_t grain = ε-MOEA is a steady-state algorithm which adds individuals one by one. A basic implementation would prevent the parallelization of individuals' evaluation. The parameter grain allows to generate and evaluate grain indidividuals in paralell at each generation. Typical value is size / 4.
• Notes:
  • ε-MOEA employs ε-dominance to sort individuals. This allows users to tune the precision of the pareto front for each objective and often results in better performance than NSGA-II.
  • EpsMOEA should not be used with a modifier (because it uses an archive). You should always use fit::ModifierDummy

To define your own EA, you should use the macro SFERES_EA(Class, Parent). Mandatory methods:

• random_pop(): fill this->_pop with random individuals
• epoch(): main loop of the algorithm

Defined types (these types will be available in your class):

• Phen: phenotype
• Eval: evaluator
• Stat: statistics vector
• FitModifier: modifier
• Params: parameters

SFERES_EA(Test, Ea)
{
 public:
 Test() {}
 void random_pop()
 { /* your code */ }
 void epoch()
 { /* your code */ }
};

Multiobjective EA must also define a pareto_front() method, see ParetoFront.

• File: sferes/stat/best_fit.hpp
• Typical typename:

typedef boost::fusion::vector<sferes::ea::BestFit<phen_t, Params> > stat_t;

• Description:
  • stores the individual with the highest fitness in _best (getter: BestFit::best() ). This assumes that the population is sorted and consequently this statistics stores the first individual of the population.
  • This class is designed for single objective optimization and consequently works using Fitness::_value (and not Fitness::_objs)
  • writes the value of the best fitness in the file <result_directory>/bestfit.dat ; this file should be easily plotted with gnuplot or R.

• File: sferes/stat/mean_fit.hpp
• Typical typename:

typedef boost::fusion::vector<sferes::ea::MeanFit<phen_t, Params> > stat_t;

• Description: computes the mean fitness (single objective, based on Fitness::_value). This class is mainly aimed at providing a simple example of statistics.

• File: sferes/stat/pareto_front.hpp
• Typical typename:

typedef boost::fusion::vector<sferes::ea::ParetoFront<phen_t, Params> > stat_t;

• Description: stores the set of non-dominated individuals by copying the list returned by ea_t::pareto_front(). ParetoFront does not compute the pareto front; this class assumes that the EA computed it. This implies that multiobjective EA classes should define the following method:

SFERES_EA(MyEA, Ea)
{
 public:
  std:vector<Indiv> &pareto_front() const { /* your code */ }
};

• Note: since this statistic can store many individuals, to load a result file you must give the identifier (the rank in the Pareto front) to your executable. For instance, assuming that ParetoFront in the first (0th) statistics in the stat vector, loading the 10th individual should look like:

./my_exp --load gen_100 -s 0 -n 10 -o output

SFERES_STAT(MyStat, Stat)
{
  // examines the population (via the EA) to update the statistics
  template<typename E> void refresh(const E& ea) { /* your code */ }
  // writes the content of the statistics in the stream; k is the number
  // of the individual in the statistics (e.g. in a Pareto front, the
  // statistics contains many individuals)
  void show(std::ostream& os, size_t k) const { /* your code */ }
  // serializes the statistics using boost::serialization
  template<class Archive> void serialize(Archive & ar, const unsigned int version)
  { /* your code */ }
}

• File: sferes/gen/bit_string.hpp
• Unit test: sferes/gen/bit_string.hpp
• Description: vector of bitstrings which can be used to represent a vector of integer parameters or a vector of discrete parameters. Cross-over is a simple one point cross-over (it always happens). The data can be easily converted to int (in the range 0..2^b, where b is the number of bits for each bitstring) via BitString<>::int_data(i) or to float (in the range 0..1) via BitString<>::data(i)
• Template parameter: the number of bitstrings
• Parameters (struct bit_string):
  • static const size_t nb_bits -> number of bits for each bitstring
  • static const float mutation_rate -> the mutation rate for a bitstring (the bitstring i is mutated if a random real is belows mutation_rate)
  • static const float mutation_rate_bit -> the mutation rate for each bit. In pseudo-code, here is the mutation procedure:

foreach(bitstring b in genotype)
  if (rand(0, 1) < Params::bit_string::mutation_rate)
    foreach(bit i in b)
      if (rand(0, 1) < Params::bit_string::mutation_bit)
        flip(i)   

• Typical parameters:

struct Params
{
  struct bit_string
  {
    static const size_t nb_bits = 8;
    static const float mutate_rate = 0.1f;
    static const float mutate_rate_bit = 0.1f;    
  };
};

• Typical typename:

typedef BitString<10, Params> gen_t;

• File: sferes/gen/evo_float.hpp
• Unit test: sferes/tests/gen/evo_float.cpp
• Description: This genotype is a n-sized vector of real (float) numbers. It is designed for real optimization.
• Three mutation types are available:
  • polynomial: polynomial mutation, as defined in Deb(200)1, p 124
  • gaussian: adds a gaussian noise to the current value; the variance is a user-specified parameter
  • uniform: adds a uniform noise to the current value; the range is a user-specified parameter
• Two cross-over types are available (you can disable cross-over by using a cross_rate equals to 0)
  • recombination:
    • a number k is randomly chosen
    • the first child is made of the [0, k[ values of the first parent and of the [k, n-1[ values of the second parent
    • the second child is made of the [0, k[ values of the second parent and of the [k, n-1] values of the first parent
  • SBX (simulated binary cross-over, cf Deb (2001), p 113). Warning: the current implementation is copied from Deb's code and is slightly different from the original paper.
• Parameters:
  • Any variant:
    • (mutation_t and cross_over_t are defined in the namespace sferes::gen::evo_float)
    • static const mutation_t mutation_type: polynomial, gaussian or uniform;
    • static const cross_over_t cross_over_type -> sbx or recombination;
    • static const float mutation_rate -> the rate of mutation of one member of the vector
    • static const float cross_rate -> the rate of cross-over (if no cross-over is applied, parents are copied to children)
  • polynomial mutation:
    • static const float eta_m -> η_m is a parameter which controls the polynomial distribution. See Deb's paper or book.
  • gaussian mutation:
    • static const float sigma -> the standard deviation of the gaussian
  • uniform mutation:
    • static const float max -> maximum change of the current value
  • sbx:
    • static const float eta_c -> see Deb's paper or book.
• Typical typename:

typedef sferes::gen::EvoFloat<10, Params1> gen_t;

• Typical parameters:

using namespace sferes::gen::evo_float;

struct Params1
{
  struct evo_float
  {
    static const float mutation_rate = 0.1f;
    static const float cross_rate = 0.1f;
    static const mutation_t mutation_type = polynomial;
    static const cross_over_t cross_over_type = sbx;
    static const float eta_m = 15.0f;
    static const float eta_c = 15.0f;
  };
};

struct Params2
{
  struct evo_float
  {
    static const float mutation_rate = 0.1f;
    static const float cross_rate = 0.1f;
    static const mutation_t mutation_type = gaussian;
    static const cross_over_t cross_over_type = recombination;
    static const float sigma = 0.3f;
  };
};


struct Params3
{
  struct evo_float
  {
    static const float mutation_rate = 0.1f;
    static const float cross_rate = 0.1f;
    static const mutation_t mutation_type = uniform;
    static const cross_over_t cross_over_type = sbx;
    static const float max = 0.3f;
    static const float eta_c = 15.0f;
  };
};

#include <sferes/stc/stc.hpp>
namespace sferes
{
  namespace gen
  {  
    SFERES_CLASS(MyGenotype)
    {
    public:
      // generates a random genotype
      void random()
      {
      // your code
      }
      // mutates an individual
      void mutate() 
      { 
      // your code to mutate (you have to handle your own mutation_rate)
      }
      // WARNING: the arguments of this method are of the same type
      // than your genotype
      void cross(const MyGenotype& o, MyGenotype& c1, MyGenotype& c2)
      {
      // if you don't know what to do, simply use:
      if (misc::flip_coin())
        {
          c1 = *this;
          c2 = o;
          }
        else
          {
            c2 = *this;
            c1 = o;
          }   
      }
    protected:
      // your data here (your genotype)
    };
  }
}

• File: sferes/phen/indiv.hpp
• Description: The abstract base class for phenotypes.
• Main public methods:

// returns the fitness
Fit& fit();
const Fit& fit() const;
// returns the genotype
Gen& gen()  { return _gen; }
const Gen& gen() const { return _gen; }
// develops the genotype, called by the evalutar before evaluating
// the individual
void develop();
// you can also override the following methods (although in most
// cases, you should override their equivalent in the genotype)
void mutate();
void random();
void cross(const boost::shared_ptr<Exact> i2, 
         boost::shared_ptr<Exact>& o1, 
         boost::shared_ptr<Exact>& o2);
// this method is not implemented in Indiv but it must be in all the
// concrete genotypes. It should describe this particular individual
// in the stream os (see the Parameter source code for an example)
void show(std::ostream& os) const

• Defined types:
  • Fit -> the fitness functor
  • Gen -> genotype

• File: sferes/gen/parameters.hpp
• Unit test: sferes/tests/phen/parameters.cpp
• Description: This phenotype transforms a list of parameters in [0, 1[ (typically a gen::Bitstring or a gen::EvoFloat) to a list of parameter in [min, max[. The genotype class must define a method:

cont std::vector<float>& data() const ();

• Typical typename:

typedef eval::Parameters<gen_t, fit_t, Params> phen_t;

#include <sferes/phen/indiv.hpp>
namespace sferes
{
  namespace phen
  {
    SFERES_INDIV(MyPhenotype, Indiv)
    {
    public:
      // constructor
      MyPhenotype() { /* your code */ }
      // develop the genotype to whatever you want
      void develop(){ /* your code */ }
      // describe this individual
      void show(std::ostream& os) const { /* your code */ }
    protected:
      // your data
    };
  }
}

• File: sferes/eval/eval.hpp
• A basic evaluator (no multiprocessing, no MPI, etc.), i.e. a basic loop.
• Typical typename:

typedef eval::Eval<Params> eval_t;

• File: sferes/eval/parallel.hpp
• Description: A SMP/multicore evaluator based on TBB (http://www.threadingbuildingblocks.org/). Your fitness should be thread-safe!
• Typical typename:

typedef eval::Parallel<Params> eval_t;

• File: sferes/eval/mpi.hpp
• Description: A MPI evaluator based on boost::mpi. It works on clusters (we use it on a JS22 cluster with IBM MPI).
• Typical typename:

typedef eval::Mpi<Params> eval_t;

The only required method is eval. It should call phen_t::develop() then phen_t::fit::eval() for each individual.

namespace sferes
{
  namespace eval
  {
    SFERES_EVAL(Eval)
    {
    public:
      template<typename Phen>
        void eval(std::vector<boost::shared_ptr<Phen> >& pop, size_t begin, size_t end)
      {
        for (size_t i = begin; i < end; ++i)
          {
            pop[i]->develop();
            pop[i]->fit().eval(*pop[i]);
          }
      }
    protected:
    };
  }
}

• File: sferes/modif/dummy.hpp
• Description: basic modifier which does nothing.