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

17 files changed, 165 insertions, 32 deletions

diff --git a/core/fitter.hpp b/core/fitter.hpp
index 996d4c1..9caae67 100644
--- a/core/fitter.hpp
+++ b/core/fitter.hpp
@@ -1,5 +1,7 @@
 /**

    \file fitter.hpp

+   \brief classes used to perform model fitting by using optimizer

+   \author Junhua Gu

  */

 

 #ifndef FITTER_HPP

@@ -244,6 +246,13 @@ namespace opt_utilities
       return typeid(*this).name();

     }

     

+    /**

+       Overwrite this function to change the 

+       behavior when destroying a heap-allocated instance.

+       The default function cooperates with then 

+       the do_clone function allocates a new instance with

+       the new operator.

+     */

     virtual void do_destroy()

     {

       delete this;

@@ -284,6 +293,10 @@ namespace opt_utilities
       return this->do_get_data(i);

     }

 

+    /**

+       get the type name

+       \return the name of the type

+     */

     const char* get_type_name()const

     {

       return this->do_get_type_name();

@@ -428,6 +441,11 @@ namespace opt_utilities
       return upper_limit;

     }

 

+    /**

+       Returns a piece of description

+       Usually used as the help information of the parameter

+       \return a piece of description of the parameter

+    */

     const Tstr& get_description()const

     {

       return description;

@@ -465,12 +483,17 @@ namespace opt_utilities
     /**

        set the name of the parameter

        \param _name the name of the parameter

-     */

-

+    */

+    

     void set_name(const Tstr& _name)

     {

       name=_name;

     }

+    

+    /**

+       Set the description

+       \param desc the description to be assigned

+    */

 

     void set_description(const Tstr& desc)

     {

@@ -498,15 +521,36 @@ namespace opt_utilities
     //    int num_free_params;

     param_modifier<Ty,Tx,Tp,Tstr>* p_param_modifier;

   private:

+    /**

+       Clone self, 

+       The default behavior is to allocate a new instance

+       on the heap with new operator and return the pointer.

+       \return a point to the cloned instance

+     */

+    

     virtual model<Ty,Tx,Tp,Tstr>* do_clone()const=0;

 

+    /**

+       Destroy the cloned instance

+     */

+

     virtual void do_destroy()

     {

       delete this;

     }

     

+    /**

+       Should be implemented to evaluate the model

+       \param x the varible

+       \param p the parameter

+       \return the model value

+     */

     virtual Ty do_eval(const Tx& x,const Tp& p)=0;

     

+    /**

+       Can be overrided to return a piece of information of the model.

+       The default implement returns a empty string.

+     */

     virtual Tstr do_get_information()const

     {

       return Tstr();

@@ -594,6 +638,13 @@ namespace opt_utilities
     }

 

   public:

+    /**

+       Get the type name

+       Usually used to return the name of this model, which is often 

+       used as a key when implementing the prototype pattern

+       \return the type name

+     */

+    

     const char* get_type_name()const

     {

       return this->do_get_type_name();

@@ -949,7 +1000,19 @@ namespace opt_utilities
 

 

 

-  public:    

+  public:   

+    /**

+       When the parameter modifier exists,

+       use it to form the complete parameter list to be fed to the model.

+       The basic idea is that say we want to freeze some parameter(s),

+       we will assign a param_modifier to this model, then some parameters

+       vanishes in the fitting, but when in the core of the model, i.e., the

+       do_eval member function, it only accepts a complete list of paramters.

+       Thus we need a function to complete the parameter list from the

+       vanished list.

+       \param p the input incomplete parameter list

+       \return the output complete parameter list to be fed to the do_eval.

+     */

     Tp reform_param(const Tp& p)const

     {

       if(p_param_modifier==0)

@@ -958,7 +1021,11 @@ namespace opt_utilities
 	}

       return p_param_modifier->reform(p);

     }

-

+    /**

+       Perform the inverse operator of reform_param

+       \param p the complete parameter list 

+       \param p the vanished parameter list

+     */

     Tp deform_param(const Tp& p)const

     {

       if(p_param_modifier==0)

@@ -979,13 +1046,15 @@ namespace opt_utilities
       return do_eval(x,reform_param(p));

     }

 

-

+    /**

+       evaluate the model, and ignore the param_modifier.

+       \param p the parameter

+       \return the model value

+     */

     Ty eval_raw(const Tx& x,const Tp& p)

     {

       return do_eval(x,reform_param(p));

     }

-

-    

   };

 

 

@@ -1090,6 +1159,9 @@ namespace opt_utilities
   public:

     /**

        evaluate the model

+       \param x the varible

+       \param p the parameter

+       \return the model value

      */

     Ty eval_model(const Tx& x,const Tp& p)

     {

@@ -1100,6 +1172,13 @@ namespace opt_utilities
       return p_model->eval(x,p);

     }

 

+    /**

+       evaluate the model, ignore the param_modifier

+       \param x the varible

+       \param p the parameter

+       \return the model value       

+     */

+    

     Ty eval_model_raw(const Tx& x,const Tp& p)

     {

       if(p_model==0)

@@ -1234,7 +1313,7 @@ namespace opt_utilities
     }

 

     /**

-       report the status of a parameter

+       report the status of a parameter, e.g., freezed, thaw, etc.

        \param s the name of a parameter

        \return string used to describe the parameter

      */

@@ -1438,19 +1517,14 @@ namespace opt_utilities
 	  p_statistic->set_fitter(*this);

 	}

     }

-	

+    

+    /**

+       Same as load_data

+       \param da the data to be set

+     */

     void set_data_set(const data_set<Ty,Tx>& da)

     {

-      if(p_data_set!=0)

-	{

-	  //delete p_data_set;

-	  p_data_set->destroy();

-	}

-      p_data_set=da.clone();

-      if(p_statistic!=0)

-	{

-	  p_statistic->set_fitter(*this);

-	}

+      load_data(da);

     }

 

   public:

@@ -1542,6 +1616,7 @@ namespace opt_utilities
 

 

     /**

+       Set the param information

        \param pinfo the param information being set

      */

 

@@ -1687,16 +1762,16 @@ namespace opt_utilities
     }

 

   public:

-        /**

+    /**

        default construct

-     */

+    */

     statistic()

       :p_fitter(0)

     {}

     

     /**

        copy construct

-     */

+    */

     statistic(const statistic& rhs)

       :func_obj<Ts,Tp>(static_cast<const func_obj<Ts,Tp>& >(rhs))

       ,p_fitter(rhs.p_fitter)

@@ -1741,7 +1816,10 @@ namespace opt_utilities
       return do_destroy();

     }

 

-

+    /**

+       Return the type name, used in a prototype pattern

+       \return the type name

+     */

     const char* get_type_name()const

     {

       return this->do_get_type_name();

@@ -1823,7 +1901,17 @@ namespace opt_utilities
       return typeid(*this).name();

     }

 

+    /**

+       Form the complete parameter list from a vanished parameter list

+       \param p the vanished parameter list

+       \return the complete parameter list

+     */

     virtual Tp do_reform(const Tp& p)const=0;

+    /**

+       The inverse operator of do_reform

+       \param p the complete parameter list

+       \return the vanished parameter list

+     */

     virtual Tp do_deform(const Tp& p)const=0;

     virtual size_t do_get_num_free_params()const=0;

     virtual Tstr do_report_param_status(const Tstr&)const=0;

@@ -1886,6 +1974,10 @@ namespace opt_utilities
       do_destroy();

     }

 

+    /**

+       Return the type name

+       \return type name

+     */

     const char* get_type_name()const

     {

       return this->do_get_type_name();

diff --git a/core/freeze_param.hpp b/core/freeze_param.hpp
index 1404980..015398e 100644
--- a/core/freeze_param.hpp
+++ b/core/freeze_param.hpp
@@ -1,5 +1,7 @@
 /**
    \file freeze_param.hpp
+   \brief param modifer that used to freeze one or more parameters
+   \author Junhua Gu
 */
 
 #ifndef FREEZE_PARAM_HPP
@@ -172,6 +174,9 @@ namespace opt_utilities
       return result;
     }
 
+    /**
+       Same as operator+
+     */
     freeze_param plus(const freeze_param& fp)const
     {
       freeze_param result(*this);
@@ -211,6 +216,9 @@ namespace opt_utilities
       return *this;
     }
 
+    /**
+       Same as operator+
+     */
     freeze_param& plus_eq(const freeze_param& fp)
     {
       //param_names.insert(param_names.end(),
@@ -262,7 +270,9 @@ namespace opt_utilities
       return *this;
     }
 
-
+    /**
+       Same as operator-=
+     */
     freeze_param& minus_eq(const freeze_param& fp)
     {
       //param_names.insert(param_names.end(),
diff --git a/core/opt_exception.hpp b/core/opt_exception.hpp
index df9030a..37ec863 100644
--- a/core/opt_exception.hpp
+++ b/core/opt_exception.hpp
@@ -1,5 +1,7 @@
 /**
    \file opt_exception.hpp
+   \brief opt_utilities exceptions
+   \author Junhua Gu
 */
 
 #ifndef OPT_EXCEPTION
diff --git a/core/opt_traits.hpp b/core/opt_traits.hpp
index 41b45b1..f2d4590 100644
--- a/core/opt_traits.hpp
+++ b/core/opt_traits.hpp
@@ -1,5 +1,7 @@
 /**
    \file opt_traits.hpp
+   \brief some trait class
+   \author Junhua Gu
  */
 
 #ifndef OPT_TRAITS
diff --git a/core/optimizer.hpp b/core/optimizer.hpp
index bb26bfb..cd78d3d 100644
--- a/core/optimizer.hpp
+++ b/core/optimizer.hpp
@@ -1,6 +1,7 @@
 /**
    \file optimizer.hpp
    \brief the definition of classes optimizer, func_obj, and opt_method
+   \author Junhua Gu
  */
 
 
diff --git a/data_sets/default_data_set.hpp b/data_sets/default_data_set.hpp
index 16de859..d56f810 100644
--- a/data_sets/default_data_set.hpp
+++ b/data_sets/default_data_set.hpp
@@ -1,5 +1,6 @@
 /**
    \file default_data_set.hpp
+   \author Junhua Gu
  */
 
 #ifndef DEFAULT_DATA_SET
diff --git a/data_sets/shared_table_data_set.hpp b/data_sets/shared_table_data_set.hpp
index 6e34808..cf71692 100644
--- a/data_sets/shared_table_data_set.hpp
+++ b/data_sets/shared_table_data_set.hpp
@@ -1,5 +1,6 @@
 /**
-   \file default_data_set.hpp
+   \file shared_table_data_set.hpp
+   \author Junhua Gu
  */
 
 #ifndef SHARED_TABLE_DATA_SET
@@ -14,6 +15,8 @@ namespace opt_utilities
 
   /**
      \brief shared_table implement of the data set
+     When the shared_table_data_set clones self, it doesn't
+     allocate a new instance, but returns a pointer to self.
      \tparam Ty type of y
      \tparam Tx type of x
    */
@@ -25,11 +28,17 @@ namespace opt_utilities
   public:
     std::vector<data<Ty,Tx> > data_vec;
     
+    /**
+       Only returns a pointer to self
+     */
     data_set<Ty,Tx>* do_clone()const
     {
       return (data_set<Ty,Tx>*)(this);
     }
 
+    /**
+       We do nothing here.
+     */
     void do_destroy()
     {
     }
diff --git a/data_sets/sorted_data_set.hpp b/data_sets/sorted_data_set.hpp
index 034a442..fec4e20 100644
--- a/data_sets/sorted_data_set.hpp
+++ b/data_sets/sorted_data_set.hpp
@@ -1,5 +1,6 @@
 /**
    \file sorted_data_set.hpp
+   \author Junhua Gu
 */
 
 #ifndef SORTED_DATA_SET
diff --git a/methods/aga/aga.hpp b/methods/aga/aga.hpp
index 92c3190..624540a 100644
--- a/methods/aga/aga.hpp
+++ b/methods/aga/aga.hpp
@@ -1,6 +1,7 @@
 /**
    \file aga.hpp
    \brief asexual genetic algorithm method
+   \author Junhua Gu
 */
 
 #ifndef AGA_METHOD
diff --git a/methods/bfgs/bfgs.hpp b/methods/bfgs/bfgs.hpp
index 43ba2d3..0be3cf4 100644
--- a/methods/bfgs/bfgs.hpp
+++ b/methods/bfgs/bfgs.hpp
@@ -1,3 +1,9 @@
+/**
+   \file bfgs.hpp
+   \brief BFGS optimization method
+   \author Junhua Gu
+ */
+
 #ifndef BFGS_METHOD
 #define BFGS_METHOD
 #define OPT_HEADER
diff --git a/methods/gsl_simplex/gsl_simplex.hpp b/methods/gsl_simplex/gsl_simplex.hpp
index 232474c..f241205 100644
--- a/methods/gsl_simplex/gsl_simplex.hpp
+++ b/methods/gsl_simplex/gsl_simplex.hpp
@@ -1,5 +1,7 @@
 /**
    \file gsl_simplex.hpp
+   \brief a simple wrapper for the GSL_SIMPLEX method
+   \author Junhua Gu
  */
 
 #ifndef GSL_SIMPLEX_METHOD
diff --git a/methods/lbfgs/lbfgs.h b/methods/lbfgs/lbfgs.h
index 7be84a7..6921f6c 100644
--- a/methods/lbfgs/lbfgs.h
+++ b/methods/lbfgs/lbfgs.h
@@ -24,13 +24,6 @@ typedef double lbfgsfloatval_t;
 #endif
 
 
-/** 
- * \addtogroup liblbfgs_api libLBFGS API
- * @{
- *
- *  The libLBFGS API.
- */
-
 /**
  * Return values of lbfgs().
  * 
diff --git a/methods/lbfgs/lbfgs_method.hpp b/methods/lbfgs/lbfgs_method.hpp
index eecde76..18e1814 100644
--- a/methods/lbfgs/lbfgs_method.hpp
+++ b/methods/lbfgs/lbfgs_method.hpp
@@ -1,3 +1,9 @@
+/**
+   \file lbfgs_method.hpp
+   \brief large bfgs method, used to perform large scale optimization
+   \author Junhua Gu
+ */
+
 #ifndef LBFGS_METHOD
 #define LBFGS_METHOD
 #define OPT_HEADER
diff --git a/methods/powell/powell_method.hpp b/methods/powell/powell_method.hpp
index 270c2b2..041fa93 100644
--- a/methods/powell/powell_method.hpp
+++ b/methods/powell/powell_method.hpp
@@ -1,5 +1,6 @@
 /**
    \file powell_method.hpp
+   \author Junhua Gu
  */
 
 #ifndef POWELL_METHOD
diff --git a/statistics/chisq.hpp b/statistics/chisq.hpp
index c460394..8a3881a 100644
--- a/statistics/chisq.hpp
+++ b/statistics/chisq.hpp
@@ -1,5 +1,7 @@
 /**

    \file chisq.hpp

+   \brief chi-square statistic

+   \author Junhua Gu

  */

 

 #ifndef CHI_SQ_HPP

diff --git a/statistics/cstat.hpp b/statistics/cstat.hpp
index 7193a93..02b7aca 100644
--- a/statistics/cstat.hpp
+++ b/statistics/cstat.hpp
@@ -1,5 +1,7 @@
 /**

    \file cstat.hpp

+   \brief maximum-liklihood statistic

+   \author Junhua Gu

  */

 

 #ifndef CSTAT_HPP

diff --git a/statistics/leastsq.hpp b/statistics/leastsq.hpp
index 6ff3b62..3b5ab37 100644
--- a/statistics/leastsq.hpp
+++ b/statistics/leastsq.hpp
@@ -1,5 +1,7 @@
 /**

    \file leastsq.hpp

+   \brief least square statistic

+   \author Junhua Gu

  */

 

 #ifndef LEAST_SQ_HPP