Changeset 3839 in Sophya for trunk/SophyaLib/Manual/sophya.tex

Timestamp:

Aug 9, 2010, 7:32:00 PM (15 years ago)

Author:

ansari

Message:

MAJ sophya.tex pour V2.2 en cours, Reza 09/08/2010

File:

• trunk/SophyaLib/Manual/sophya.tex (modified) (17 diffs)

trunk/SophyaLib/Manual/sophya.tex

@@ -48 +48 @@
 \vspace{1cm}
 \begin{center}
-{\bf \Large Sophya Version: 2.2 (V\_Jan2010) }
+{\bf \Large Sophya Version: 2.2 (V\_Sep2010) }
 \end{center}
 \titrebp{1}
@@ -103 +103 @@
 \subsection{Acknowlegments}
 Many people have contributed to the development SOPHYA and/or the PI library 
-and (s)piapp interactive analysis tool.
-we are grateful to the following people:
+and (s)piapp interactive analysis tool, in particular:
 
 \begin{tabular}{lcl}
@@ -159 +158 @@
 \item[] {\bf SkyT/} 
 classes for spectral emission and detector frequency response modelling \\
-({\tt SpectralResponse, RadSpectra, BlackBody} \ldots)
+({\tt SpectralResponse, RadSpectra, BlackBody} \ldots). This module needs extensive 
+checking and corrections.
 \item[] {\bf Samba/} Spherical harmonic analysis, noise generators \ldots 
 \end{itemize}
@@ -234 +234 @@
 \item[] {\bf LUC} {\bf L}ittle {\bf U}niverse {\bf C}alculator is a module containing classes to 
 perform basic computation related to the universe geometry (FRW metric).
-\item[] {\bf PMixer/} skymixer and related programs
+\item[] {\bf PMixer/} skymixer and related programs. This module is {\bf obsolete}.
 \end{itemize}
 
@@ -590 +590 @@
 PPF format version (currently V3), the file endiannes {\tt (BIG-ENDIAN , LITTLE-ENDIAN)}
 and the file creation date and time. It should be noted that the present SOPHYA version 
-(V=2.1) does not allow updating an existing PPF file.
+(V=2.2) does not allow updating an existing PPF file.
 \item[\rond] A collection of tagged data items and data structuring tags. 
 the PPF tags are one byte (8 bits) long and may be followed by a length information
@@ -847 +847 @@
 \end{itemize}
  
- \subsection{Random numbers}
- \index{RandomGenerator}
+ \subsection{Pseudo-random number generators}
+ \index{Random numbers}
 \begin{figure}[hbt]
 \dclsbb{ AnyDataObj }{ RandomGeneratorInterface } 
@@ -855 +855 @@
 \dclsbb{ RandomGeneratorInterface }{ FMTRandGen }
 \end{figure}
-%%   CHECK 
-{\bf \large SECTION A METTRE A JOUR } \\
- The C-functions defined in the file BaseTools/srandgen.h can be used
- for generating sequence of random numbers with different PDF (probability 
- distribution functions : flat, gaussian, poisson \ldots.
- However, we advise to use the {\bf RandomGenerator} class which provides
-can be used in multi-threaded programs. In this case, a different instance of
-the  RandomGenerator class should be created in each thread running in parallel.
-In addition, this class has a PPF handler which saves the complete state of the class and 
-the underlying generatoir to the PPF stream. This can be used to generate very long sequence
-of random numbers, distributed over several runs.
-\begin{verbatim}
-sa_size_t N = 1000;
-Vector vf(2*N), vg(2*N);
-{
-// Instanciate the random generator
-RandomGenerator rg;
-// Generate some sequence of random numbers
-for(sa_size_t i=0; i<N; i++) {
-  vf(i) = rg.Flat01();
-  vg(i) = rg.Gaussian(); 
-  }
-// Save the generator to file rg.ppf
+The {\bf RandomGeneratorInterface } is a pure virtual class which 
+defines the interface for random number generator classes and implements the 
+generation algorithm for few probability distribution functions:
+flat, Gaussian, Poisson, Exponential, 2D gaussian \ldots. The pure virtual method
+{\tt Next() } should be implemented by inheriting  classes.
+ \index{RandomGeneratorInterface}
+
+Several implementations using different pseud-random generators are provided by SOPHYA:
+\begin{enumerate}
+\item {\bf DR48RandGen} uses the well known {\tt drand48() }  pseudo-random
+sequence generator. It implements also the possibility of initializing the generator state, as well saving and 
+restoring the generator state through the SOPHYA PPF mechanism. The  {\tt drand48() }  and thus 
+{\bf DR48RandGen} objects are not NOT thread safe. Different instances of {\bf DR48RandGen}  share 
+the same underlying 48 bit state.
+\item {\bf ThSDR48RandGen} is a thread safe version of DR48RandGen. Using the constructor flag, in can 
+be instanciated to reproduce the non thread-safe behaviour of DR48RandGen. 
+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.  
+\index{ ThSDR48RandGen} 
+\item {\bf FMTRandGen } ids an implementation of RandomGeneratorInterface using 
+the SIMD-oriented Fast Mersenne Twister (SFMT). It uses the code developed by 
+Mutsuo Saito and Makoto Matsumoto from Hiroshima University. For more information on this 
+method, refer to \\
+\href{http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html} 
+{ttp://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html} \\
+The instances of FMTRandGen are thread safe, each instance having its own internal state 
+and produces an independent sequence of random numbers. 
+\index{FMTRandGen }
+\end{enumerate}
+
+A number of c-like functions are defined in the file BaseTools/srandgen.h and can be used 
+to generate random sequences: \\
+{\tt drand01() , drandpm1() ,  GaussianRand() , PoissonRand \ldots} \\
+These functions use a global instance  of RandomGeneratorInterface class which can be 
+defined and accessed through the static methods:\\
+\hspace*{5mm} { \tt RandomGeneratorInterface* RandomGeneratorInterface::GetGlobalRandGenP() } \\
+\hspace*{5mm} { \tt void SetGlobalRandGenP(RandomGeneratorInterface* rgp) } \\
+
+In multi-threaded programs, an instance of ThSDR48RandGen or FMTRandGen 
+should be created in each thread running in parallel and needing to generate random sequences. 
+All the three classes discussed here implement the automatic initialization method defined 
+{\tt (AutoInit() ) } defined in the interface class and implement a number of other initialization
+methods {\tt (SetSeed() )}.  SOPHYA provides also PPF handlers for these classes 
+which can be used to save the complete  state of the object and the underlying generator to PPF files. 
+The generator object state can be restored subsequently from the PPF file. This feature can be used 
+to generate very long sequence of random numbers, distributed over several runs.
+The example below illustrates the use of the generator classes and state save/restore 
+through PPF files:
+\begin{enumerate} 
+\item We create and use a {\bf ThSDR48RandGen} object in a first program. Its sate is saved 
+to the PPF file rg.ppf at some point in the program. 
+\begin{verbatim}
+// ------ program A 
+// 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;  
-}
-// ....
-{
-// Create and read the generator from file rg.ppf
-RandomGenerator rg;
-PInPersist pi("rg.ppf");
-pi >> rg;  
-// Continue the generation sequence
-for(sa_size_t i=N; i<2*N; i++) {
-  vf(i) = rg.Flat01();
-  vg(i) = rg.Gaussian(); 
-  }
-}
-\end{verbatim}
+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;
+\end{verbatim}
+
+\item The pseudo-random generator object state is restored in a second program from the previously created 
+PPF file, before being used :
+ \begin{verbatim}  
+// ------ program B
+// 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;
+\end{verbatim}
+\end{enumerate}
 
 %%%%%%%%%%%%
@@ -1161 +1210 @@
 \end{verbatim}
 
-\subsection{Input, Output}
+
+\subsection{Persistence, IO}
 Arrays can easily be saved to, or restored from files in different formats.
 SOPHYA library can handle array I/O to ASCII formatted files, to PPF streams, 
@@ -1370 +1420 @@
 \noindent {\bf Shared data access :} It is possible to access a complex array 
 elements (real and imaginary parts) through the template functions defined 
-in {\tt arrctcast.h} and discussed above. The example below shows how to use 
-these functions.
+in {\tt arrctcast.h} and discussed above. Four specific template functions are 
+defined for shared data access to complex arrays: 
+\begin{itemize}
+\item {\bf SDRealPart } return a float/double TArray, when applied to an
+array with complex elements, corresponding the the {\bf real} part of the complex values.
+\item {\bf SDImagPart } return a float/double TArray, when applied to an
+array with complex elements, corresponding the the {\bf imaginary} part of the complex values.
+\item {\bf ArrCastC2R } return a float/double TArray, when applied to an
+array with complex elements. The data is shared between the two arrays, the real array 
+containing real and imaginary parts as successive elements. 
+\item {\bf ArrCastR2C } return a complex valued TArray, when applied to a float/double array. 
+\end{itemize} 
+The example below shows how to use these functions:
 
 \begin{verbatim}
@@ -1497 +1558 @@
 \end{verbatim}
 
+
+\subsection{Special Square Matrices (SSQM) }
+SOPHYA V2.2 introduces new classes for handling special square matrices (diagonal, symmetric, triangular \ldots).
+The figure below shows the corresponding class hierarchy:
+\begin{figure}[hbt]
+\dclsccc{AnyDataObj}{\tcls{SpecialSquareMatrix}}{ \tcls{ DiagonalMatrix } }
+\dclsc{ \tcls{ LowerTriangularMatrix } } 
+\dclsc{ \tcls{ SymmetricMatrix } } 
+\end{figure}
+
+\index{ \tcls{DiagonalMatrix} }
+\index{ \tcls{SymmetricMatrix} }
+\index{ \tcls{TriangularMatrix} }
+
+Theses classes provides methods similar to TArray/TMatrix objects for manipulating these special kind of matrices.
+However, no sub-matrix extraction method is provided. The  following features are currently implemented:
+\begin{itemize}
+\item These classes implements reference sharing and behave in a way similar to TArray objects. The copy 
+constructor shares the data, while the equal operator (=) performs an element by element copy. 
+\item The {\bf FIO\_SpecialSquareMatrix$<$T$>$ } manages the persistence (I/O) in PPF format for these classes. 
+\item Constructor from and conversion to general {\bf TMatrix$<$T$>$ } objects. 
+ Non relevant elements are ignored when constructing from a general matrix and the special square matrix can be 
+converted to the general matrix through the {\tt ConvertToStdMatrix () }.
+\item Definition of element access operator {\tt mx(r,c) } as well as global assignment operator {\tt mx = a; mxb=mxa; }.
+operator {\tt mx[k] } can be used to access the non zero element k. 
+\item Addition, subtraction of a constant, multiplication or division by a constant, as well as  
+\item Element by element addition, subtraction, multiplication and division methods between same type of SSQM 
+matrices. As in the cases of general matrices, the four binary operators ( + , - , \&\& ,   /) are overloaded to perform 
+these operations. 
+\item Matrix multiplication operation between same type SSQM objects or between a general matrix and an SSQM
+object is defined through the methods: \\
+{\\ Multiply() , MultiplyXG(), MultiplyGX(),  X=D,S,T } \\
+The binary multiplication operator ( * ) is then overloaded to perform matrix multiplication.   
+\end{itemize}
+The sample code below illustrates the use of these special matrices:
+\begin{verbatim} 
+// 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;
+\end{verbatim} 
 
 \newpage 
@@ -2473 +2584 @@
 transforms on double precision data might be available.
 
+\section{Multi-thread and parallel programming with Sophya} 
+ 
 \newpage
 \section{Building and installing Sophya}
 \subsection{Supported platforms}
-Presently, the Sophya library has been tested with the following
-compiler/platform pairs:
+Presently, the SOPHYA and PI libraries and tools has been compiled and tested with 
+the following compiler/platform pairs:
 
 \begin{center}
@@ -2484 +2597 @@
 OS & compiler \\
 \hline
-Linux (32 bits)          &     g++  (3.x \, 4.0)  \\
-Linux  (SCL, 32)          &     icc - Intel compiler (9.0)   \\
-Linux  (SCL, 64)          &     g++  3.3 \, 3.4  \\
-MacOSX/Darwin (PowerPC) 10.3 \, 10.4  &         g++ (3.3  \, 4.0)\\
-MacOSX/Darwin (Intel) 10.4  &         g++ (4.0)\\
-HP/Compaq/DEC Tru64 ( OSF1)  &     cxx  (6.1  6.3)  \\
-SGI IRIX64       &     CC   (7.3)   \\
-IBM AIX (5.3)      &     xlC   (8.0)   \\
+Linux  (SL5, 64)          &     g++  4.1  \\
+Linux  (SL5, 64)          &     icc - Intel compiler (10.1)   \\
+Linux Ubuntu             &    g++ 4.4 \\
+MacOSX/Darwin 10.3 (PowerPC) \, 10.4  (Intel) &   Apple g++ 3.3  \, 4.0 \\
+MacOSX/Darwin 10.5 (Intel)  &  Apple   g++ 4.0 \\
+MacOSX/Darwin 10.6 (Intel)   Snow Leopard &  Apple  g++ 4.2 \\
+IBM AIX 5.3      &     xlC   8.0   \\
+HP/Compaq/DEC Tru64 ( OSF1)  &     cxx  6.1 \, 6.3  \\
 \hline
 \end{tabular}
 \end{center}
+
+The SOPHYA and PI library and associated tools (spiapp, runcxx \ldots) were ported and tested 
+on the Silicon Graphics (SGI)  IRIX system and the corresponding native c++ compiler ( IRIX64, CC  7.3 ),
+up to SOPHYA V2.1 (V\_Nov2007). 
 
 \subsection{Library and makefile structure}
@@ -2544 +2661 @@
 configure [-sbase SOPHYABASE] [-scxx SOPHYACXX] [-incln] 
   [-minc mymake.inc]  [-compopt 'cc/cxxOptions'] 
-  [-arch64] [-sasz64] [-nofpic] [-nothsafe] [-boundcheck] [-sodebug]
+  [-arch64] [-arch32] [-sasz64] [-ldble128] [-nofpic] [-nothsafe] [-boundcheck] [-sodebug]
   [-extp dir1 -extp dir2 ...] [-extip dir1 -extip dir2 ... ] [-extlp dir1 -extlp dir2 ... ]
   [-noextlib] [-noext fits] [-noext fftw] [-noext lapack] [-noext astro]
@@ -2560 +2677 @@
 \$SOPHYABASE/include/sophyamake.inc. If {\tt -minc} is not specified, one of
 the files in BuildMgr/ directory is selected, based on the system name and the 
-compiler {\tt  Linux\_g++\_make.inc , OSF1\_cxx\_make.inc , AIX\_xlC\_make.inc \ldots}
+compiler {\tt  Linux\_g++\_make.inc , OSF1\_cxx\_make.inc , AIX\_xlC\_make.inc \ldots} 
+\item[] -compopt : additional compiler options \\[2mm]
+\item[] -arch64 : select/force 64 bits compilation mode. This is the default on 64 bits Linux systems and AIX.
+\item[] -arch32  : select/force 32 bits compilation mode. useful on 64 bits Linux systems or AIX
+\item[] -sasz64 : select 8 byte (64 bits) size for array indices, useful if you need to allocate an manipulate 
+large arrays, with more than $2^32$ elements along a single array dimension.
+\item[] -ldble128 : set the flags activating {\tt long double} (128 bits) arrays. \\[2mm]
+\item[] -nofpic : disable -fPIC (Position Independent Code) generation flag 
+\item[] -nothsafe : disable thread-safety procedures in SOPHYA : reference sharing \ldots. 
+ ( activate the conditional compilation flag {\tt SO\_NOTHSAFE } )
+\item[] -boundcheck : compile SOPHYA and bound checking activated when accessing array elements
+( activate conditional compilation flag {\tt SO\_BOUNDCHECKING } )
+\item[] -sodebug : activate conditional compilation flag {\tt SOPHYA\_DEBUG }  \\[2mm]
 \item[] -extp : Adds the specied path to the search path of the external libraries 
 include files and archive library.
@@ -2569 +2698 @@
 \item[] -noextlib : Disable compiling of modules referencing external libraries.
 \item[] -noext : Disable compiling of the specified module (with reference to external
-library : {\tt -noext fits , -noext fftw \ldots }
+library : {\tt -noext fits , -noext fftw  -noext lapack -noext astro } \\[2mm]
 \item[] -usefftw2: Use FFTW V2 instead of the default FFTW V3 - A preprocessor
 flag will be defined in sspvflags.h 
@@ -2588 +2717 @@
 The configure script performs the following actions :
 \begin{enumerate}
-\item Creating directory tree under {\tt \$SOPHYABASE }
-\item Cpoying include files (or creating symbolic) in {\tt \$SOPHYABASE/include/ }
+\item Creates directory tree under {\tt \$SOPHYABASE }
+\item Copy include files to {\tt \$SOPHYABASE/include/ }  (or creates symbolic link) 
 \item Search for external libraries include files and create the necessary links 
 in {\tt \$SOPHYABASE/include}
@@ -2724 +2853 @@
 \index{Exception classes} \index{PThrowable} \index{PError} \index{PException}
 SOPHYA library defines a set of exceptions which are used 
-for signalling error conditions. The figure below shows a partial 
-class diagram for exception classes in SOPHYA.
+for signalling error conditions. From version V2.2 , all SOPHYA exceptions inherit from 
+the standard C++ exception class ( {\bf std::std::exception}). The method {\tt const char* what()} is 
+thus implemented and returns the corresponding error message.
+The figure below shows a partial class diagram for exception classes in SOPHYA.
 \begin{figure}[hbt]
 \dclsbb{PThrowable}{PError}