git-svn-id: file:///home/svn/opt_utilities@47 ed2142bd-67ad-457f-ba7c-d818d4011675

1 files changed, 186 insertions, 27 deletions

diff --git a/core/optimizer.hpp b/core/optimizer.hpp
index 70f35f7..7492bab 100644
--- a/core/optimizer.hpp
+++ b/core/optimizer.hpp
@@ -1,3 +1,9 @@
+/**
+   \file optimizer.hpp
+   \brief the definition of classes optimizer, func_obj, and opt_method
+ */
+
+
 #ifndef OPTIMZER_H_
 #define OPTIMZER_H_
 //#define DEBUG
@@ -23,115 +29,212 @@ namespace opt_utilities
   template <typename rT,typename pT>
   class opt_method;
 
-
-  //////////////Target Function/////////////////////
-  ///An eval function should be implemented/////////
-  ///The eval function return the function value////
-  ///which is wrapped by the func_obj///////////////
-  //////////////////////////////////////////////////
+  /**
+     Virtual class representing an object function.
+     \tparam rT the return type
+     \tparam pT the self-varible type
+   */
   template <typename rT,typename pT>
   class func_obj
     :public std::unary_function<pT,rT>
   {
   private:
-    virtual rT do_eval(const pT&)=0;
+    /**
+      \param x the self-varible
+      \return the value evaluated
+     */
+    virtual rT do_eval(const pT& x)=0;
+    /**
+       \return the clone of an object.
+     */
     virtual func_obj<rT,pT>* do_clone()const=0;
+    /**
+       Destroy the object generated by clone function
+     */
     virtual void do_destroy()
     {
       delete this;
     }
 
   public:
-  public:
+    /**
+       Interface function to perform the clone
+       \return the clone of an pre-existed object.
+     */
     func_obj<rT,pT>* clone()const
     {
       return do_clone();
     }
 
+    /**
+       Interface function to perform the destroy.
+     */
     void destroy()
     {
       do_destroy();
     }
 
+
+    /**
+       Makes the class object like a real function.
+     */
     rT operator()(const pT& p)
     {
       return do_eval(p);
     }
     
 
+    /**
+       The same as operator().
+     */
     rT eval(const pT& p)
     {
       return do_eval(p);
     };
+
+    /**
+       deconstruct function
+     */
     virtual ~func_obj(){};
     //    virtual XT walk(XT,YT)=0;
   };
   
 
-  ///////////////Optimization method//////////////////////
-  
+  /**
+     virtual class representing optimization methods
+     \tparam rT the return type
+     \tparam pT the self-varible type
+   */
   template <typename rT,typename pT>
   class opt_method
   {
-  public:
-    virtual void do_set_optimizer(optimizer<rT,pT>&)=0;
-    virtual void do_set_precision(rT)=0;
+  private:
+    /**
+       Set the optimizer
+       \param op optimizer to be set
+     */
+    virtual void do_set_optimizer(optimizer<rT,pT>& op)=0;
+    /**
+       Set the precision
+       \param th threshold
+     */
+    virtual void do_set_precision(rT th)=0;
+    /**
+       perform the optimization
+       \return final optimized parameter.
+     */
     virtual pT do_optimize()=0;
+    /**
+       \param p start point
+     */
     virtual void do_set_start_point(const pT& p)=0;
+    /**
+       \param p the lower limit
+     */
     virtual void do_set_lower_limit(const pT& p){};
+    /**
+       \param p the upper limit
+     */
     virtual void do_set_upper_limit(const pT& p){};
+    /**
+       \return the clone of current object
+     */
     virtual opt_method<rT,pT>* do_clone()const=0;
-
+    /**
+       destroy the object created by clone()
+     */
     virtual void do_destroy()
     {
       delete this;
     }
   public:
+    /**
+       Interface function for seting optimizer
+       \param op optimizer to be set
+     */
     void  set_optimizer(optimizer<rT,pT>& op)
       {
 	do_set_optimizer(op);
       };
 
+    /**
+       Interface function to set precision
+       \param x the threshold
+     */
     void set_precision(rT x)
     {
       do_set_precision(x);
     }
 
+    /**
+       Interface function to set start point
+       \param p start point
+     */
     void set_start_point(const pT& p)
     {
       do_set_start_point(p);
     }
 
+    /**
+       Interface function to set lower limit
+       \param p the lower limit
+     */
+
     void set_lower_limit(const pT& p)
     {
       do_set_lower_limit(p);
     }
 
+    /**
+       Interface function to set upper limit
+       \param p upper limit
+     */
+
     void set_upper_limit(const pT& p)
     {
       do_set_upper_limit(p);
     }
+
+    /**
+       Interface function for performing the optimization
+       \return the optimized parameter.
+     */
     
     pT optimize()
       {
 	return do_optimize();
       };
     
+
+    /**
+       \return the cloned object.
+     */
     opt_method<rT,pT>* clone()const
     {
       return do_clone();
     }
 
+
+    /**
+       destroy the cloned object.
+     */
     void destroy()
     {
       do_destroy();
     }
 
+    /**
+       deconstruct function
+     */
     virtual ~opt_method(){};
   };
   
   
-  ///////////Optimizer////////////////////////////////////
+  /**
+     The manager for performing the manager
+     \tparam rT the return type
+     \tparam pT the self-varible type
+  */
   template <typename rT,typename pT>
   class optimizer
   {
@@ -139,23 +242,38 @@ namespace opt_utilities
 
   private:
 
-    ////////////pointer to an optimization method objection////////////
-    ////////////The optimization method implements a certain method ///
-    ////////////Currently only Mont-carlo method is implemented////////
+    /**
+       pointer pointing a opt_method object
+     */
     opt_method<rT,pT>* p_opt_method;
+
+    /**
+       pointer pointing a func_obj object
+     */
     func_obj<rT,pT>* p_func_obj;
     
   public:
+    /**
+       default construct function
+     */
      optimizer()
       :p_opt_method(0),p_func_obj(0)
     {}
 
+    /**
+       construct function
+       \param fc object function
+       \param om optimization method
+     */
     optimizer(func_obj<rT,pT>& fc,const opt_method<rT,pT>& om)
       :p_func_obj(fc.clone()),p_opt_method(om.clone())
     {
       p_opt_method->set_optimizer(*this);
     }
     
+    /**
+       copy construct function
+     */
     optimizer(const optimizer& rhs)
       :p_opt_method(0),p_func_obj(0)
     {
@@ -169,6 +287,10 @@ namespace opt_utilities
 	}
     }
 
+
+    /**
+       Assignment operator
+     */
     optimizer& operator=(const optimizer& rhs)
     {
       if(this==&rhs)
@@ -186,7 +308,9 @@ namespace opt_utilities
       return *this;
     }
     
-
+    /**
+       destruct function
+     */
     virtual ~optimizer()
     {
       if(p_func_obj!=0)
@@ -202,7 +326,10 @@ namespace opt_utilities
     };
 
   public:
-    ////////////Re-set target function object///////////////////////////
+    /**
+       set objection function
+       \param fc objection function
+     */
     void set_func_obj(const func_obj<rT,pT>& fc)
     {
       if(p_func_obj!=0)
@@ -217,7 +344,10 @@ namespace opt_utilities
 	}
     }
 
-    ////////////Re-set optimization method//////////////////////////////
+    /**
+       set optimization method
+       \param om optmization method
+     */
     void set_opt_method(const opt_method<rT,pT>& om)
     {
       if(p_opt_method!=0)
@@ -230,6 +360,9 @@ namespace opt_utilities
       p_opt_method->set_optimizer(*this);
     }
 
+    /**
+       \return a reference of internally kept optimization method
+     */
     opt_method<rT,pT>& method()
     {
       if(p_opt_method==0)
@@ -239,6 +372,11 @@ namespace opt_utilities
       return *(this->p_opt_method);
     }
 
+
+    /**
+       set precision
+       \param x threshold
+     */
     void set_precision(rT x)
     {
       if(p_opt_method==0)
@@ -248,6 +386,11 @@ namespace opt_utilities
       p_opt_method->set_precision(x);
     }
 
+    
+    /**
+       set start point
+       \param x start point
+     */
     void set_start_point(const pT& x)
     {
       if(p_opt_method==0)
@@ -257,6 +400,11 @@ namespace opt_utilities
       p_opt_method->set_start_point(x);
     }
     
+
+    /**
+       set lower limit
+       \param x lower limit
+     */
     void set_lower_limit(const pT& x)
     {
       if(p_opt_method==0)
@@ -266,6 +414,11 @@ namespace opt_utilities
       p_opt_method->set_lower_limit(x);
     }
 
+
+    /**
+       set upper limit
+       \param x upper limit
+     */
     void set_upper_limit(const pT& x)
     {
       if(p_opt_method==0)
@@ -276,9 +429,11 @@ namespace opt_utilities
     }
     
 
-    ////////////Just call the eval function in the target function object///
-    ////////////In case the pointer to a target function is uninitialed/////
-    ////////////a zero-value is returned////////////////////////////////////
+    /**
+       call the objection function
+       \param self var
+       \return function value
+     */
     rT eval(const pT& x)
     {
       if(p_func_obj==0)
@@ -290,8 +445,10 @@ namespace opt_utilities
 
 	
 
-    ////////////Just call the optimize() function in the optimization method//
-    ////////////If no optimization method is given, an zero-value is returned/
+    /**
+       perform the optimization
+       \return the optimizated paramater
+     */
     pT optimize()
     {
       if(p_opt_method==0)
@@ -305,7 +462,9 @@ namespace opt_utilities
       return p_opt_method->optimize();
     }
     
-    ////////////Function that offers the access to the target function object///
+    /**
+       \return the pointer to the inner object function
+     */
     func_obj<rT,pT>* ptr_func_obj()
     {
       return p_func_obj;