/*
 *  Open BEAGLE
 *  Copyright (C) 2001-2005 by Christian Gagne and Marc Parizeau
 *
 *  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
 *
 *  Contact:
 *  Laboratoire de Vision et Systemes Numeriques
 *  Departement de genie electrique et de genie informatique
 *  Universite Laval, Quebec, Canada, G1K 7P4
 *  http://vision.gel.ulaval.ca
 *
 */

/*!
 *  \file   beagle/HierarchicalFairCompetitionOp.hpp
 *  \brief  Definition of the class HierarchicalFairCompetitionOp.
 *  \author Christian Gagne
 *  \author Marc Parizeau
 *  $Revision: 1.6 $
 *  $Date: 2005/09/30 15:04:54 $
 */


#ifndef Beagle_HierarchicalFairCompetitionOp_hpp
#define Beagle_HierarchicalFairCompetitionOp_hpp

#include "beagle/config.hpp"
#include "beagle/macros.hpp"
#include "beagle/Object.hpp"
#include "beagle/Pointer.hpp"
#include "beagle/PointerT.hpp"
#include "beagle/Allocator.hpp"
#include "beagle/AllocatorT.hpp"
#include "beagle/AbstractAllocT.hpp"
#include "beagle/ContainerAllocator.hpp"
#include "beagle/Container.hpp"
#include "beagle/ContainerT.hpp"
#include "beagle/Operator.hpp"
#include "beagle/ReplacementStrategyOp.hpp"
#include "beagle/Float.hpp"
#include "beagle/UInt.hpp"

namespace Beagle {

/*!
 *  \class HierarchicalFairCompetitionOp beagle/HierarchicalFairCompetitionOp.hpp "beagle/HierarchicalFairCompetitionOp.hpp"
 *  \brief Hierarchical fair competition replacement strategy operator class.
 *  \ingroup ECF
 *  \ingroup Op
 *
 *  Hierachical Fair Competition (HCF) operator inspired by the work of Jianjun Hu
 *  and Erik Goodman (Michigan State University). The operator is actually
 *  implemented as a migration operator that is at the same time a replacement
 *  strategy. The breeder tree of the replacement strategy is called to
 *  generate the new individuals.
 *
 *  The operator acts on the population by migrating individuals from low-index
 *  to high-index demes. Individuals are migrating into the actual deme i from
 *  the migration buffer of deme i-1 (no migration in for deme 0). Then individuals
 *  better than the fitness threshold for deme i are moved into its migration buffer
 *  (no migration out for the last deme). If the deme is too small, new individuals
 *  are generated by the breeder tree to fill the deme. If the deme is too big, the
 *  worse individuals are erased from the deme.
 *
 *  An internal table of fitness threshold is kept internaly in the HFC operator.
 *  This fitness threshold is the value used to decide which individuals are migrated
 *  between deme. The HFC percentile value T (parameter 'ec.hfc.percentile') states
 *  to use fitness of the individual of deme i+1 at generation g-1 that is better than
 *  T percent of the individuals in the population as the fitness threshold for
 *  migrating individuals of deme i at generation g.
 *
 *  For an example of a XML configuration file with HFC operator, see file
 *  "symbreg-hfc.conf" in symbolic regression example.
 *
 *  References:
 *  Jianjun Hu and E. Goodman. Adaptive Hierarchical Fair Competition Model for
 *  Parallel Evolutionary Algorithms. Genetic and Evolutionary Computation
 *  Conference 2002, New York.
 *
 */
class HierarchicalFairCompetitionOp : public ReplacementStrategyOp {

public:

  //! HierarchicalFairCompetitionOp allocator type.
  typedef AllocatorT<HierarchicalFairCompetitionOp,ReplacementStrategyOp::Alloc>
          Alloc;
  //! HierarchicalFairCompetitionOp handle type.
  typedef PointerT<HierarchicalFairCompetitionOp,ReplacementStrategyOp::Handle>
          Handle;
  //! HierarchicalFairCompetitionOp bag type.
  typedef ContainerT<HierarchicalFairCompetitionOp,ReplacementStrategyOp::Bag>
          Bag;

           HierarchicalFairCompetitionOp(string inName="HierarchicalFairCompetitionOp");
  virtual ~HierarchicalFairCompetitionOp() { }

  virtual void initialize(System& ioSystem);
  virtual void operate(Deme& ioDeme, Context& ioContext);

protected:

  Individual::Bag generateIndividuals(unsigned int inN, Deme& ioDeme, Context& ioContext) const;

  Fitness::Bag      mFitnessThresholds;  //!< Fitness thresholds used for migration.
  Float::Handle     mHFCPercentile;      //!< HFC percentile used for to select fitness thresholds.
  UInt::Handle      mMigrationInterval;  //!< Random ring migration interval (in generation).
  UInt::Handle      mNumberMigrants;     //!< Number of migrants.
  UIntArray::Handle mPopSize;            //!< Population size for the evolution.

};

}

#endif // Beagle_HierarchicalFairCompetitionOp_hpp

