Changeset 2808 in Sophya for trunk/SophyaLib/NTools/simplex.cc

Timestamp:

Jun 14, 2005, 1:25:05 PM (20 years ago)

Author:

ansari

Message:

MAJ documentation - Reza 14/6/2005

File:

• trunk/SophyaLib/NTools/simplex.cc (modified) (6 diffs)

trunk/SophyaLib/NTools/simplex.cc

@@ -10 +10 @@
 //---------------------------------------------------------------
 // Interface de classe de function multivariable pour le SimplexMinmizer
+/*!
+  \class SOPHYA::MinZFunction
+  \ingroup NTools
+  Interface definition for a function object f(x[]) for which MinZSimplex can 
+  search the minimum.
+  The pure virtual method Value() should be implemented by the derived classes.
+*/
 
 MinZFunction::MinZFunction(unsigned int nvar)
@@ -23 +30 @@
 //-------------------  Classe   MinZFuncXi2  --------------------
 //---------------------------------------------------------------
+/*!
+  \class SOPHYA::MinZXi2
+  \ingroup NTools
+  Implements the MinZFunction interface using a xi2 calculator 
+  \sa GeneralXi2 GeneralFitData
+*/
 MinZFuncXi2::MinZFuncXi2(GeneralXi2* gxi2, GeneralFitData* gd)
   : mGXi2(gxi2) , mGData(gd), MinZFunction(gxi2->NPar())
@@ -174 +187 @@
 }
 
+/*!
+  \class SOPHYA::MinZSimplex
+  \ingroup NTools
+  This class implements non linear minimization (optimization)
+  in a multidimensional space following the \b Simplex method.
+  A \b Simplex is a geometrical figure made of N+1 points in a
+  N-dimensional space. (triangle in a plane, tetrahedron in 3-d space).
+  The minimization method implemented in this class is based on the 
+  algorithm described in "Numerical Recipes, Chapter X". 
+
+  The algorithm has been slightly enhanced :
+  - More complex convergence / stop test 
+  - A new transformation of the simplex has been included (ExpandHigh)
+
+  For each step, on of the following geometrical transform is performed
+  on the Simplex figure:
+  - Reflection : reflection away from the high point (expansion by factor Alpha)
+  - ReflecExpand : reflection way from the high point and expansion by factor Beta2
+  - ContractHigh : Contraction along the high point (factor Beta)
+  - ContractLow : Contraction toward the low point (factor Beta2)
+  - ExpandHigh : Expansion along the high point
+
+  \sa GeneralFit
+
+  The following sample code shows a usage example:
+  \code
+  include "simplex.h"
+  ...
+  // Define our function to be minimized:
+  class MySFunc : public MinZFunction {
+  public:
+    MySFunc() : MinZFunction(2) {}
+    virtual double Value(double const xp[]) 
+    { return (xp[0]*xp[0]+2*xp[1]*xp[1]); }
+  };
+
+  ... 
+
+  MySFunc mysf;
+  MinZSimplex simplex(&mysf);
+  // Guess the center and step for constructing the initial simplex
+  Vector x0(2); x0 = 1.;
+  Vector step(2); step = 2.;
+  simplex.SetInitialPoint(x0);
+  simplex.SetInitialStep(step);
+  Vector oparm(2);
+  int rc = simplex.Minimize(oparm);
+  if (rc != 0) {
+    string srt; 
+    int sr = simplex.StopReason(srt);
+    cout << " Convergence Pb, StopReason= " << sr << " : " << srt << endl;
+    }
+  else {
+    cout << " Converged: NStep= " << simplex.NbIter() 
+         << " OParm= " << oparm << endl;
+    }
+  \endcode
+*/
+
+/*!
+  \brief Auto test function
+  \param tsel : select autotest (0,1,2,3,4)  , tsel<0 -> all
+  \param prtlev : printlevel 
+*/
 int MinZSimplex::AutoTest(int tsel, int prtlev)
 {
@@ -214 +291 @@
 }
 
+//! Constructor from pointer to MinZFunction object 
 MinZSimplex::MinZSimplex(MinZFunction *mzf)
   : mZF(mzf) , mPoint0(mZF->NVar()) , mStep0(mZF->NVar())
@@ -234 +312 @@
 }
 
+//! Perform the minimization 
+/*!
+  Return 0 if success
+  \param fpoint : vector containing the optimal point 
+  
+  Convergence test :
+  \verbatim
+  On minimise f(x) f=mZF->Value() , 
+              f_max = max(f) sur simplex , f_min = min(f) sur simplex 
+              fm = (abs(f_max)+abs(f_min))
+              [Delta f] = abs(f_max-f_min)
+              [Delta f/f]simplex = 2.*Delta f / fm
+              fm2 = (abs(f_max)+abs(f_max(iter-1)))
+              [Delta f_max/f_max]iter = [f_max(iter-1)-f_max]/fm2 
+  Test d'arret :  
+   fm < mTol0                                                       OU 
+   [Delta f/f]simplex              < mTol1   mRep1 fois de suite    OU 
+   [Delta f_max/f_max]iter         < mTol2   mRep2 fois de suite  
+*/
 int MinZSimplex::Minimize(Vector& fpoint)
 {
@@ -411 +508 @@
 }
 
+//! Return the stop reason and fills the corresponding string description
 int MinZSimplex::StopReason(string& s)
 {