Changeset 3838 in Sophya for trunk/SophyaLib

Timestamp:

Aug 9, 2010, 7:31:12 PM (15 years ago)

Author:

ansari

Message:

MAJ commentaires pour doxygen, passage methode Next() en pure virtual (=0), Reza 09/08/2010

Location:

trunk/SophyaLib

Files:

• BaseTools/randinterf.cc (modified) (3 diffs)
• BaseTools/randinterf.h (modified) (1 diff)
• BaseTools/randr48.cc (modified) (2 diffs)
• BaseTools/randr48.h (modified) (2 diffs)
• TArray/spesqmtx.cc (modified) (1 diff)

trunk/SophyaLib/BaseTools/randinterf.cc

@@ -7 +7 @@
 #include <time.h>
 #include <iostream>
+#include <typeinfo>
+
 #include "pexceptions.h"
 
@@ -65 +67 @@
 void RandomGeneratorInterface::ShowRandom()
 {
-  cout<<"RandomGenerator is RandomGeneratorInterface i.e. UNDEFINED"<<endl;
-}
-
-/////////////////////////////////////////////////////////////////////////
-/////////////////////////////////////////////////////////////////////////
-/////////////////////////////////////////////////////////////////////////
-
+  cout << " RandomGeneratorInterface::ShowRandom() typeid(this)=" << typeid(*this).name() << " @ " 
+       << hex << (unsigned long)(this) << dec << endl;
+  return;
+}
+
+/////////////////////////////////////////////////////////////////////////
+/////////////////////////////////////////////////////////////////////////
+/////////////////////////////////////////////////////////////////////////
+
+/*
 r_8 RandomGeneratorInterface::Next()
 {
@@ -77 +82 @@
   throw MathExc("RandomGeneratorInterface::Next(): undefined code !!!");
 }
+*/
 
 /////////////////////////////////////////////////////////////////////////

trunk/SophyaLib/BaseTools/randinterf.h

@@ -137 +137 @@
 
 protected:
-  //! Return a random number in [0,1] 
-  virtual r_8 Next();
+  /*! \brief Should return a random number in the range [0,1] with flat distribution 
+
+     This pure virtual method should be implemented by inheriting classes  */ 
+  virtual r_8 Next() = 0;
 
 // Selection de type d'algo pour les aleatoires autres que plates

trunk/SophyaLib/BaseTools/randr48.cc

@@ -10 +10 @@
 namespace SOPHYA {
 
+/*!
+   \class DR48RandGen
+   \ingroup BaseTools
+   \brief  Implementation of the RandomGeneratorInterface class using drand48() functions 
+
+   Its PPF handler can be used to save the complete state of the class and the underlying
+   random number generator used.
+
+   \sa SOPHYA::ObjFileIO<ThSDR48RandGen>
+
+*/
+
 static bool dr48_first = true;
 DR48RandGen::DR48RandGen()
@@ -70 +82 @@
    \class ThSDR48RandGen
    \ingroup BaseTools
-   \brief Random number generator
-
-   This class is a thread-safe random number generator.
+   \brief Thread-safe version of DR48RandGen random number generator using drand48() functions.
+
+   
+   Several instances of this class can be used in different threads without the risk of 
+   corrupting the internal state of the drand48() generator. However, in multi-thread applications,
+   there is no guarantee to obtain the same sequence of numbers in each thread.  
    Its PPF handler can be used to save the complete state of the class and the underlying
-   random number generator used.
+   random number generator (drand48() which is used.
 
    \sa SOPHYA::ObjFileIO<ThSDR48RandGen>
 
+   \code 
+   // A.1- Create a thread safe generator based on drand48() 
+   ThSDR48RandGen rg;
+   // A.2- Auto initilize its state (using the system time) 
+   rg.AutoInit();
+   // A.3- compute and print a smal sequence of random numbers 
+   int N = 10;
+   for(int i=0; i<N; i++) 
+     cout << " I=" << i << "  rand_flat01= " << rg.Flat01() << " rand.gaussian= " << rg.Gaussian() << endl;
+   // A.4- Save the generator state for subsequent use
+   POutPersist po("rg.ppf");
+   po << rg;
+   // A.5- compute and print a second sequence of random numbers 
+   for(int i=0; i<N; i++) 
+     cout << "++ I=" << i+N << "  rand_flat01= " << rg.Flat01() << " rand.gaussian= " << rg.Gaussian() << endl;
+   
+   ...  In another program :
+
+   // B.1- Create and initialize the generator from the previously saved state
+   ThSDR48RandGen rgr;
+   PInPersist pin("rg.ppf");
+   pin >> rgr;
+   int N = 10;
+   // B.2- Compute and print a sequence of random number, should be compared to the sequance A.5
+   for(int i=0; i<N; i++) 
+     cout << "-- I=" << i << "  rand_flat01= " << rgr.Flat01() << " rand.gaussian= " << rgr.Gaussian() << endl;
+   
+   
+   \endcode
 */
 
 // Objet statique global pour gestion de lock entre threads
 static ThSafeOp* ths_rand = NULL;
+
+/*! 
+  \brief Constructor with optional specification of the internal buffer size and thread-safety flag 
+  
+  The behaviour of the base class DR48RandGen can be reproduced by specifying tsafe=false
+  \param n : an internal buffer of size n is created and filled through block calls to drand48()
+  \param tsafe : if false, creates a non thread-safe generator 
+*/
 
 ThSDR48RandGen::ThSDR48RandGen(size_t n, bool tsafe) 

trunk/SophyaLib/BaseTools/randr48.h

@@ -15 +15 @@
 
 
-/* ------- SPECIFIQUE Mac Darwin OSX  <= 10.2 (gcc < 3.x) -------- */
-#if defined(Darwin) &&  defined(__GNUC__) && (__GNUC__ < 3)
-#include "osx_values.h"
-/* Declaration de drand48 et srand48 etc , mis ds SysSpec, Reza 11/02/2003 */
-#ifdef __cplusplus
-extern "C" {
-#endif
-unsigned short int * seed48(unsigned short int seed16v[3]);
-void srand48(long seedval);
-#ifdef __cplusplus
-}
-#endif
-#define drand48() ((double)(random())/LONG_MAX)
-#endif
-/* ------- FIN SPECIFIQUE Mac OSX / Darwin V <= 10.2 --------- */
-
-
 namespace SOPHYA {
 
-//! Implementation of the RandomGeneratorInterface class using drand48() functions 
+// Implementation de RandomGeneratorInterface avec drand48()  
 class DR48RandGen : public RandomGeneratorInterface {
 
@@ -60 +43 @@
 //--------------------------------------------------------------------------------
 
-//! Version thread-safe de RandomGeneratorInterface avec drand48() functions 
+// Version thread-safe de  DR48RandGen 
 class ThSDR48RandGen : public DR48RandGen {
 

trunk/SophyaLib/TArray/spesqmtx.cc

@@ -9 +9 @@
 #include "tmatrix.h"
 
-// doit etre mis en dehors du namespace
+namespace SOPHYA {
 /*!
-  \class SOPHYA::SpecialSquareMatrix
+  \class SpecialSquareMatrix
   \ingroup TArray
   \brief The base class for representing and manipulating special square matrices
   Diagonal matrix, Symmetric matrix, Triangular matrix
-
   This class implements the common operations for special square matrices. Only objects 
+
   from the sub-classes (DiagonalMatrix<T>, LowerTriangularMatrix<T>, SymmetricMatrix<T>) 
   can be instanciated. Theses classes offer similar functionalities to the TArray<T> / TMatrix<T> 
   classes, like reference sharing and arithmetic operations. However, no sub-matrix extraction 
   method is provided. 
-  sub matrix extraction method.
+
+  \code 
+  // Create and initialize a diagonal matrix
+  DiagonalMatrix<double> diag(3);
+  diag(0,0)=1.;  diag(1,1)=2.;  diag(2,2)=3.;
+  // use of multiplication by a constant operator
+  diag *= 10.;
+  // check the diagonal matrix
+  cout << diag << diag.ConvertToStdMatrix() << endl;
+  // define and initialize a general matrix
+  TMatrix<double> mx(3,3);
+  mx=RegularSequence();
+  cout << mx;
+  // check the result of a matrix mutiplication
+  cout << mx*diag;
+  \endcode
 */
-
-namespace SOPHYA {
 
 //! Default constructor - SpecialSquareMatrix of size 0, SetSize() should be called before the object is used