/* -*- C++ -*-

 *

 * This file is a part of LEMON, a generic C++ optimization library

 *

 * Copyright (C) 2003-2008

 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport

 * (Egervary Research Group on Combinatorial Optimization, EGRES).

 *

 * Permission to use, modify and distribute this software is granted

 * provided that this copyright notice appears in all copies. For

 * precise terms see the accompanying LICENSE file.

 *

 * This software is provided "AS IS" with no warranty of any kind,

 * express or implied, and with no claim as to its suitability for any

 * purpose.

 *

 */

#ifndef LEMON_SIMANN_H

#define LEMON_SIMANN_H

/// \ingroup experimental

/// \file

/// \brief Simulated annealing framework.

///

/// \todo A test and some demo should be added

/// \todo Doc should be improved

/// \author Akos Ladanyi

#include <cstdlib>

#include <lemon/math.h>

#include <limits>

#include <lemon/time_measure.h>

#include <lemon/random.h>

namespace lemon {

  class SimAnnBase;

  /// \brief A base class for controllers.

  class ControllerBase {

  public:

    friend class SimAnnBase;

    /// \brief Pointer to the simulated annealing base class.

    SimAnnBase *simann;

    /// \brief Initializes the controller.

    virtual void init() {}

    /// \brief This is called by the simulated annealing class when a

    /// neighbouring state gets accepted.

    virtual void acceptEvent() {}

    /// \brief This is called by the simulated annealing class when the

    /// accepted neighbouring state's cost is less than the best found one's.

    virtual void improveEvent() {}

    /// \brief This is called by the simulated annealing class when a

    /// neighbouring state gets rejected.

    virtual void rejectEvent() {}

    /// \brief Decides whether to continue the annealing process or not.

    virtual bool next() = 0;

    /// \brief Decides whether to accept the current solution or not.

    virtual bool accept() = 0;

    /// \brief Destructor.

    virtual ~ControllerBase() {}

  };

  /// \brief Skeleton of an entity class.

  class EntityBase {

  public:

    /// \brief Makes a minor change to the entity.

    /// \return the new cost

    virtual double mutate() = 0;

    /// \brief Restores the entity to its previous state i.e. reverts the

    /// effects of the last mutate().

    virtual void revert() = 0;

    /// \brief Makes a copy of the entity.

    virtual EntityBase* clone() = 0;

    /// \brief Makes a major change to the entity.

    virtual void randomize() = 0;

    /// \brief Destructor.

    virtual ~EntityBase() {}

  };

  /// \brief Simulated annealing abstract base class.

  ///

  /// Can be used to derive a custom simulated annealing class if \ref SimAnn

  /// doesn't fit your needs.

  class SimAnnBase {

  private:

    /// \brief Pointer to the controller.

    ControllerBase *controller;

    /// \brief Cost of the current solution.

    double curr_cost;

    /// \brief Cost of the best solution.

    double best_cost;

    /// \brief Cost of the previous solution.

    double prev_cost;

    /// \brief Cost of the solution preceding the previous one.

    double prev_prev_cost;

    /// \brief Number of iterations.

    long iter;

    /// \brief Number of iterations which did not improve the solution since

    /// the last improvement.

    long last_impr;

  protected:

    /// \brief Step to a neighbouring state.

    virtual double mutate() = 0;

    /// \brief Reverts the last mutate().

    virtual void revert() = 0;

    /// \brief Saves the current solution as the best one.

    virtual void saveAsBest() = 0;

    /// \brief Does initializations before each run.

    virtual void init() {

      controller->init();

      curr_cost = prev_cost = prev_prev_cost = best_cost =

        std::numeric_limits<double>::infinity();

      iter = last_impr = 0;

    }

  public:

    /// \brief Sets the controller class to use.

    void setController(ControllerBase &_controller) {

      controller = &_controller;

      controller->simann = this;

    }

    /// \brief Returns the cost of the current solution.

    double getCurrCost() const { return curr_cost; }

    /// \brief Returns the cost of the previous solution.

    double getPrevCost() const { return prev_cost; }

    /// \brief Returns the cost of the best solution.

    double getBestCost() const { return best_cost; }

    /// \brief Returns the number of iterations done.

    long getIter() const { return iter; }

    /// \brief Returns the ordinal number of the last iteration when the

    /// solution was improved.

    long getLastImpr() const { return last_impr; }

    /// \brief Performs one iteration.

    bool step() {

      iter++;

      prev_prev_cost = prev_cost;

      prev_cost = curr_cost;

      curr_cost = mutate();

      if (controller->accept()) {

        controller->acceptEvent();

        last_impr = iter;

        if (curr_cost < best_cost) {

          best_cost = curr_cost;

          saveAsBest();

          controller->improveEvent();

        }

      }

      else {

        revert();

        curr_cost = prev_cost;

        prev_cost = prev_prev_cost;

        controller->rejectEvent();

      }

      return controller->next();

    }

    /// \brief Performs a given number of iterations.

    /// \param n the number of iterations

    bool step(int n) {

      for(; n > 0 && step(); --n) ;

      return !n;

    }

    /// \brief Starts the annealing process.

    void run() {

      init();

      do { } while (step());

    }

    /// \brief Destructor.

    virtual ~SimAnnBase() {}

  };

  /// \ingroup metah

  ///

  /// \brief Simulated annealing class.

  class SimAnn : public SimAnnBase {

  private:

    /// \brief Pointer to the current entity.

    EntityBase *curr_ent;

    /// \brief Pointer to the best entity.

    EntityBase *best_ent;

    /// \brief Does initializations before each run.

    void init() {

      SimAnnBase::init();

      if (best_ent) delete best_ent;

      best_ent = NULL;

      curr_ent->randomize();

    }

  public:

    /// \brief Constructor.

    SimAnn() : curr_ent(NULL), best_ent(NULL) {}

    /// \brief Destructor.

    virtual ~SimAnn() {

      if (best_ent) delete best_ent;

    }

    /// \brief Step to a neighbouring state.

    double mutate() {

      return curr_ent->mutate();

    }

    /// \brief Reverts the last mutate().

    void revert() {

      curr_ent->revert();

    }

    /// \brief Saves the current solution as the best one.

    void saveAsBest() { 

      if (best_ent) delete best_ent;

      best_ent = curr_ent->clone();

    }

    /// \brief Sets the current entity.

    void setEntity(EntityBase &_ent) {

      curr_ent = &_ent;

    }

    /// \brief Returns a copy of the best found entity.

    EntityBase* getBestEntity() { return best_ent->clone(); }

  };

  /// \brief A simple controller for the simulated annealing class.

  ///

  /// This controller starts from a given initial temperature and evenly

  /// decreases it.

  class SimpleController : public ControllerBase {

  private:

    /// \brief Maximum number of iterations.

    long max_iter;

    /// \brief Maximum number of iterations which do not improve the

    /// solution.

    long max_no_impr;

    /// \brief Temperature.

    double temp;

    /// \brief Annealing factor.

    double ann_fact;

    /// \brief Constructor.

    /// \param _max_iter maximum number of iterations

    /// \param _max_no_impr maximum number of consecutive iterations which do

    ///        not yield a better solution

    /// \param _temp initial temperature

    /// \param _ann_fact annealing factor

  public:

    SimpleController(long _max_iter = 500000, long _max_no_impr = 20000,

    double _temp = 1000.0, double _ann_fact = 0.9999) : max_iter(_max_iter),

      max_no_impr(_max_no_impr), temp(_temp), ann_fact(_ann_fact)

    {

    }

    /// \brief This is called when a neighbouring state gets accepted.

    void acceptEvent() {}

    /// \brief This is called when the accepted neighbouring state's cost is

    /// less than the best found one's.

    void improveEvent() {}

    /// \brief This is called when a neighbouring state gets rejected.

    void rejectEvent() {}

    /// \brief Decides whether to continue the annealing process or not. Also

    /// decreases the temperature.

    bool next() {

      temp *= ann_fact;

      bool quit = (simann->getIter() > max_iter) ||

        (simann->getIter() - simann->getLastImpr() > max_no_impr);

      return !quit;

    }

    /// \brief Decides whether to accept the current solution or not.

    bool accept() {

      double cost_diff = simann->getCurrCost() - simann->getPrevCost();

      return (rnd() <= exp(-(cost_diff / temp)));

    }

    /// \brief Destructor.

    virtual ~SimpleController() {}

  };

  /// \brief A controller with preset running time for the simulated annealing

  /// class.

  ///

  /// With this controller you can set the running time of the annealing

  /// process in advance. It works the following way: the controller measures

  /// a kind of divergence. The divergence is the difference of the average

  /// cost of the recently found solutions the cost of the best found one. In

  /// case this divergence is greater than a given threshold, then we decrease

  /// the annealing factor, that is we cool the system faster. In case the

  /// divergence is lower than the threshold, then we increase the temperature.

  /// The threshold is a function of the elapsed time which reaches zero at the

  /// desired end time.

  class AdvancedController : public ControllerBase {

  private:

    /// \brief Timer class to measure the elapsed time.

    Timer timer;

    /// \brief Calculates the threshold value.

    /// \param time the elapsed time in seconds

    virtual double threshold(double time) {

      return (-1.0) * start_threshold / end_time * time + start_threshold;

    }

    /// \brief Parameter used to calculate the running average.

    double alpha;

    /// \brief Parameter used to decrease the annealing factor.

    double beta;

    /// \brief Parameter used to increase the temperature.

    double gamma;

    /// \brief The time at the end of the algorithm.

    double end_time;

    /// \brief The time at the start of the algorithm.

    double start_time;

    /// \brief Starting threshold.

    double start_threshold;

    /// \brief Average cost of recent solutions.

    double avg_cost;

    /// \brief Temperature.

    double temp;

    /// \brief Annealing factor.

    double ann_fact;

    /// \brief Initial annealing factor.

    double init_ann_fact;

    /// \brief True when the annealing process has been started.

    bool start;

  public:

    /// \brief Constructor.

    /// \param _end_time running time in seconds

    /// \param _alpha parameter used to calculate the running average

    /// \param _beta parameter used to decrease the annealing factor

    /// \param _gamma parameter used to increase the temperature

    /// \param _ann_fact initial annealing factor

    AdvancedController(double _end_time, double _alpha = 0.2,

    double _beta = 0.9, double _gamma = 1.6, double _ann_fact = 0.9999) :

    alpha(_alpha), beta(_beta), gamma(_gamma), end_time(_end_time),

    ann_fact(_ann_fact), init_ann_fact(_ann_fact), start(false)

    {

    }

    /// \brief Does initializations before each run.

    void init() {

      avg_cost = simann->getCurrCost();

    }

    /// \brief This is called when a neighbouring state gets accepted.

    void acceptEvent() {

      avg_cost = alpha * simann->getCurrCost() + (1.0 - alpha) * avg_cost;

      if (!start) {

        static int cnt = 0;

        cnt++;

        if (cnt >= 100) {

          // calculate starting threshold and starting temperature

          start_threshold = 5.0 * fabs(simann->getBestCost() - avg_cost);

          temp = 10000.0;

          start = true;

          timer.restart();

        }

      }

    }

    /// \brief Decides whether to continue the annealing process or not.

    bool next() {

      if (!start) {

        return true;

      }

      else {

        double elapsed_time = timer.realTime();

        if (fabs(avg_cost - simann->getBestCost()) > threshold(elapsed_time)) {

          // decrease the annealing factor

          ann_fact *= beta;

        }

        else {

          // increase the temperature

          temp *= gamma;

          // reset the annealing factor

          ann_fact = init_ann_fact;

        }

        temp *= ann_fact;

        return elapsed_time < end_time;

      }

    }

    /// \brief Decides whether to accept the current solution or not.

    bool accept() {

      if (!start) {

        return true;

      }

      else {

        double cost_diff = simann->getCurrCost() - simann->getPrevCost();

        return (rnd() <= exp(-(cost_diff / temp)));

      }

    }

    /// \brief Destructor.

    virtual ~AdvancedController() {}

  };

}

#endif