Ajout des commentaires autour de VNS

git-svn-id: svn://scm.gforge.inria.fr/svnroot/paradiseo@1930 331e1502-861f-0410-8da2-ba01fb791d7f

trunk/paradiseo-mo/src/explorer/moVNSexplorer.h

@@ -34,7 +34,6 @@
 #include <neighborhood/moVariableNeighborhoodSelection.h>
 #include <eoOp.h>
 #include <acceptCrit/moAcceptanceCriterion.h>
-#include <algo/moDummyLS.h>
 
 /**
  * Explorer for the "Variable Neighborhood Search" metaheuristic
@@ -47,11 +46,9 @@ public:
   typedef typename Neighbor::EOT EOT;
 
   /**
-   * Constructor
+   * Default constructor
-   * @param _neighborhood the neighborhood
+   * @param _selection selection the "neighborhood" search heuristics during the search
-   * @param _eval the evaluation function
+   * @param _acceptCrit acceptance criteria which compare and accept or not the two solutions
-   * @param _neighborComparator a neighbor comparator
-   * @param _solNeighborComparator solution vs neighbor comparator
    */
   moVNSexplorer(moVariableNeighborhoodSelection<EOT> & _selection,
 		moAcceptanceCriterion<Neighbor>& _acceptCrit):
@@ -59,7 +56,7 @@ public:
   {}
 
   /**
-   * Destructor
+   * Empty destructor
    */
   ~moVNSexplorer() {
   }
@@ -92,7 +89,7 @@ public:
   virtual void terminate(EOT & _solution) {};
 
   /**
-   * Explore the neighborhood of a solution
+   * Explore the neighborhood of a solution by the "neighborhood" search heuristics
    * @param _solution the current solution
    */
   virtual void operator()(EOT & _solution) {
@@ -100,12 +97,8 @@ public:
     eoMonOp<EOT> & ls    = selection.getLocalSearch();
 
     current = _solution;
-    std::cout << "current avec shake: "<< current << std::endl;
     shake(current);
-    std::cout << "current apres shake: "<< current << std::endl;
     ls(current);
-    std::cout << "current apres ls: "<< ls.className() ;
-    std::cout << " sol: " << current << std::endl;
   }
 
   /**
@@ -118,7 +111,7 @@ public:
   };
 
   /**
-   * move the solution with the best neighbor
+   * move the solution with to current accepted solution
    * @param _solution the solution to move
    */
   virtual void move(EOT & _solution) {
@@ -128,7 +121,7 @@ public:
   /**
    * accept test if an amelirated neighbor was be found according to acceptance criteria
    * @param _solution the solution
-   * @return true if the best neighbor ameliorate the fitness
+   * @return true if the neighbor ameliorate the fitness
    */
   virtual bool accept(EOT & _solution) {
     return acceptCrit(_solution, current);
@@ -143,21 +136,11 @@ public:
   }
 
 private:  
-  //moDummyLS<Neighbor> dummyLS;
   moVariableNeighborhoodSelection<EOT>& selection;
   moAcceptanceCriterion<Neighbor>& acceptCrit;
-  //eoMonOp<EOT>* ls;
-  //eoMonOp<EOT>& shake;
   bool stop;
 
   EOT current;
-
-  /*
-    class moDummyEval: public eoEvalFunc<EOT>{
-    public:
-    void operator()(EOT& hop){}
-    }dummyEval;
-  */
 };
 
 

trunk/paradiseo-mo/src/neighborhood/moBackwardVectorVNSelection.h

@@ -32,16 +32,28 @@
 
 #include <neighborhood/moVectorVNSelection.h>
 
+/**
+ *  This class is used for the Variable Neighborhood Search explorer inherits from moVectorVNSelection
+ *  The search heuristics are saved in vectors
+ *  They are given in backward order from the last ones to the first ones
+ *
+ */
 template< class EOT >
 class moBackwardVectorVNSelection: public moVectorVNSelection<EOT>{
 
   using moVectorVNSelection<EOT>::LSvector;
-  using moVectorVNSelection<EOT>::shakeVector;
   using moVectorVNSelection<EOT>::current;
   
 public:
   
-  moBackwardVectorVNSelection(eoMonOp<EOT>& _firstLS, eoMonOp<EOT>& _firstShake, bool _cycle):moVectorVNSelection<EOT>(_firstLS, _firstShake), cycle(_cycle){}
+  /**
+   * Default constructor with first search heuristics
+   *
+   * @param _firstLS first local search 
+   * @param _firstShake first heuristic which perturbs the solution
+   * @param _cycle when true, the first heuristics follows the last ones. Otherwise the search stop.
+   */
+  moBackwardVectorVNSelection(eoMonOp<EOT>& _firstLS, eoMonOp<EOT>& _firstShake, bool _cycle = true) : moVectorVNSelection<EOT>(_firstLS, _firstShake), cycle(_cycle){}
   
   /**
    * Return the class id.
@@ -52,34 +64,35 @@ public:
   }
 
   /**
-   * test if there is still some neighborhood to explore
+   * test if there is still some heuristics 
-   * @return true if there is some neighborhood to explore
+   *
+   * @param _solution the current solution
+   * @return true if there is some heuristics
    */
   virtual bool cont(EOT& _solution){
     return (cycle || (current > 0));
   }
 
   /**
-   * put the current neighborhood on the first one
+   * put the current heuristics on the first ones
+   *
+   * @param _solution the current solution
    */
   virtual void init(EOT& _solution){
     current = LSvector.size() - 1;
-    std::cout << "current LS: " << current << std::endl;
-    std::cout << _solution << std::endl;
-
   }
 
   /**
-   * put the current neighborhood on the next one
+   * put the current heuristics on the next ones
+   *
+   * @param _solution the current solution
    */
   virtual void next(EOT& _solution){
     current = (current + LSvector.size() -1) % LSvector.size();
-    std::cout << "current LS: " << current << std::endl;
-    std::cout << _solution << std::endl;
-
   }
 
 private:
+  // boolean to indicate the last heuristics follow the first ones
   bool cycle;
   
 };

trunk/paradiseo-mo/src/neighborhood/moForwardVectorVNSelection.h

@@ -32,16 +32,28 @@
 
 #include <neighborhood/moVectorVNSelection.h>
 
+/**
+ *  This class is used for the Variable Neighborhood Search explorer inherits from moVectorVNSelection
+ *  The search heuristics are saved in vectors
+ *  They are given in forward order from the first ones to the last ones
+ *
+ */
 template< class EOT >
 class moForwardVectorVNSelection: public moVectorVNSelection<EOT>{
 
   using moVectorVNSelection<EOT>::LSvector;
-  using moVectorVNSelection<EOT>::shakeVector;
   using moVectorVNSelection<EOT>::current;
 
 public:
 
-  moForwardVectorVNSelection(eoMonOp<EOT>& _firstLS, eoMonOp<EOT>& _firstShake, bool _cycle):moVectorVNSelection<EOT>(_firstLS, _firstShake), cycle(_cycle){}
+  /**
+   * Default constructor with first search heuristics
+   *
+   * @param _firstLS first local search 
+   * @param _firstShake first heuristic which perturbs the solution
+   * @param _cycle when true, the first heuristics follows the last ones. Otherwise the search stop.
+   */
+  moForwardVectorVNSelection(eoMonOp<EOT>& _firstLS, eoMonOp<EOT>& _firstShake, bool _cycle = true) : moVectorVNSelection<EOT>(_firstLS, _firstShake), cycle(_cycle){}
 
   /**
    * Return the class id.
@@ -52,37 +64,35 @@ public:
   }
 
   /**
-   * test if there is still some neighborhood to explore
+   * test if there is still some heuristics 
-   * @return true if there is some neighborhood to explore
+   *
+   * @param _solution the current solution
+   * @return true if there is some heuristics
    */
   virtual bool cont(EOT& _solution){
     return (cycle || (current <= (LSvector.size() - 2)));
-    std::cout << "current LS: " << current << std::endl;
-    std::cout << _solution << std::endl;
-
   }
 
   /**
-   * put the current neighborhood on the first one
+   * put the current heuristics on the first ones
+   *
+   * @param _solution the current solution
    */
   virtual void init(EOT& _solution){
     current = 0;
-    //    std::cout << "current LS: " << _ls->className() << " " << current << std::endl;
-    //    std::cout << _solution << std::endl;
-
   }
 
   /**
-   * put the current neighborhood on the next one
+   * put the current heuristics on the next ones
+   *
+   * @param _solution the current solution
    */
   virtual void next(EOT& _solution){
     current = (current + 1) % LSvector.size();
-    std::cout << "current LS: " << current << std::endl;
-    std::cout << _solution << std::endl;
   }
 
 private:
-
+  // boolean to indicate the first heuristics follow the last ones
   bool cycle;
 
 };

trunk/paradiseo-mo/src/neighborhood/moRndVectorVNSelection.h

@@ -35,15 +35,28 @@
 
 #include <neighborhood/moVectorVNSelection.h>
 
+/**
+ *  This class is used for the Variable Neighborhood Search explorer inherits from moVectorVNSelection
+ *  The search heuristics are saved in vectors
+ *  They are given in random order (at each initialization the order is changed)
+ *
+ */
 template< class EOT >
-class moRndVectorVNSelection: public moVectorVNSelection<EOT>{
+class moRndVectorVNSelection: public moVectorVNSelection<EOT>
-
+{
   using moVectorVNSelection<EOT>::LSvector;
-  using moVectorVNSelection<EOT>::shakeVector;
+  //  using moVectorVNSelection<EOT>::shakeVector;
   using moVectorVNSelection<EOT>::current;
 
 public:
 
+  /**
+   * Default constructor with first search heuristics
+   *
+   * @param _firstLS first local search 
+   * @param _firstShake first heuristic which perturbs the solution
+   * @param _cycle when true, the first heuristics follows the last ones. Otherwise the search stop.
+   */
   moRndVectorVNSelection(eoMonOp<EOT>& _firstLS, eoMonOp<EOT>& _firstShake, bool _cycle = true) : moVectorVNSelection<EOT>(_firstLS, _firstShake), cycle(_cycle){}
 
   /**
@@ -55,15 +68,19 @@ public:
   }
 
   /**
-   * test if there is still some neighborhood to explore
+   * test if there is still some heuristics 
-   * @return true if there is some neighborhood to explore
+   *
+   * @param _solution the current solution
+   * @return true if there is some heuristics
    */
   virtual bool cont(EOT& _solution){
     return ( cycle || (currentOrder <= (order.size() - 2)) );
   }
 
   /**
-   * put the current neighborhood on the first one
+   * put the current heuristics on the first ones
+   *
+   * @param _solution the current solution
    */
   virtual void init(EOT& _solution) {
     if(order.size() == 0)
@@ -77,7 +94,9 @@ public:
   }
 
   /**
-   * put the current neighborhood on the next one
+   * put the current heuristics on the next ones
+   *
+   * @param _solution the current solution
    */
   virtual void next(EOT& _solution){
     currentOrder = (currentOrder + 1) % order.size();
@@ -86,10 +105,13 @@ public:
   }
 
 private:
-
+  // boolean to indicate the first heuristics follow the last ones
   bool cycle;
+  // index in order vector
   unsigned int currentOrder;
+  // the index of heuristics in random order
   std::vector<unsigned int> order;
+  // random generator
   UF_random_generator<unsigned int> gen;
 
 };

trunk/paradiseo-mo/src/neighborhood/moVariableNeighborhoodSelection.h

@@ -33,6 +33,13 @@ Contact: paradiseo-help@lists.gforge.inria.fr
 #include <eoOp.h>
 #include <vector>
 
+/**
+ *  This class is used for the Variable Neighborhood Search explorer
+ *  It gives the sequence of search heuristics based on the different "neighborhoods" 
+ *  The class is built such as the moNeighborhood" with init, next, cont
+ *    and two methods to get the heuristics which shake the solution, and which give the local search
+ *
+ */
 template< class EOT >
 class moVariableNeighborhoodSelection
 {
@@ -47,18 +54,18 @@ public:
   }
 
   /**
-     * test if there is still some neighborhood to explore
+   * test if there is still some search heuristics to use
    * @return true if there is some neighborhood to explore
    */
   virtual bool cont(EOT& _solution) = 0;
 
   /**
-     * put the current neighborhood on the first one
+   * put on the first search heuristics
    */
   virtual void init(EOT& _solution) = 0;
 
   /**
-     * put the current neighborhood on the next one
+   * put the next search heuristics
    */
   virtual void next(EOT& _solution) = 0;
   

trunk/paradiseo-mo/src/neighborhood/moVectorVNSelection.h

@@ -33,17 +33,36 @@
 #include <neighborhood/moVariableNeighborhoodSelection.h>
 #include <eoOp.h>
 
+/**
+ *  This class is used for the Variable Neighborhood Search explorer inherits from moVariableNeighborhoodSelection
+ *  The search heuristics are saved in vectors
+ *  The way to croos the vector is not defined here
+ *
+ */
 template< class EOT >
 class moVectorVNSelection: public moVariableNeighborhoodSelection<EOT>{
 
 public:
 
+  /**
+   * Default constructor with first search heuristics
+   *
+   * @param _firstLS first local search 
+   * @param _firstShake first heuristic which perturbs the solution
+   */
   moVectorVNSelection(eoMonOp<EOT>& _firstLS, eoMonOp<EOT>& _firstShake){
     LSvector.push_back(&_firstLS);
     shakeVector.push_back(&_firstShake);
+
     current = 0;
   }
   
+  /**
+   * Add some search heuristics
+   *
+   * @param _otherLS the added local search 
+   * @param _otherShake the added heuristic which perturbs the solution
+   */
   void add(eoMonOp<EOT>& _otherLS, eoMonOp<EOT>& _otherShake){
     LSvector.push_back(&_otherLS);
     shakeVector.push_back(&_otherShake);
@@ -72,30 +91,15 @@ public:
    * @return current local search 
    */
   virtual eoMonOp<EOT> & getLocalSearch() {
-    std::cout << "getLS : " << current << " sur " << LSvector.size() << std::endl;
-    std::cout << "getLS : ls = " << LSvector[current]->className() << std::endl;
     return *(LSvector[current]);
   }
 
-  /**
-   * test if there is still some neighborhood to explore
-   * @return true if there is some neighborhood to explore
-   */
-  virtual bool cont(EOT& _solution) = 0;
-
-  /**
-   * put the current neighborhood on the first one
-   */
-  virtual void init(EOT& _solution) = 0;
-
-  /**
-   * put the current neighborhood on the next one
-   */
-  virtual void next(EOT& _solution) = 0;
-
 protected:
+  // vector of local searches
   std::vector<eoMonOp<EOT>* > LSvector;
+  // vector of "shake" heiristics which perturbs the current solution
   std::vector<eoMonOp<EOT>* > shakeVector;
+  // index of the current search heuristics which is applied
   unsigned int current;
 
 };