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

Timestamp:

Dec 7, 2007, 7:06:56 PM (18 years ago)

Author:

ansari

Message:

sophya.tex (overview) complete pour tag V2.1, Reza 07/12/2007

File:

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

trunk/SophyaLib/Manual/sophya.tex

@@ -279 +279 @@
 dot . in unix).
 
+\subsection{Copy constructor and assignment operator}
+\label{memgt}
+In C++, objects can be copied by assignment or by initialisation.
+Copying by initialisation corresponds to creating an object and
+initialising its value through the copy constructor.
+The copy constructor has its first argument as a reference, or
+const reference to the object's class type. It can have  
+more arguments, if default values are provided.
+Copying by assignment applies to an existing object and
+is performed through the assignment operator (=). 
+The copy constructor implements this for identical type objects:
+\begin{verbatim}
+class MyObject {
+public:
+  MyObject();      // Default constructor
+  MyObject(MyObject const & a);  // Copy constructor
+  MyObject & operator = (MyObject const & a) // Assignment operator
+}
+\end{verbatim}
+The copy constructors play an important role, as they are 
+called when class objects are passed by value, 
+returned by value, or thrown as an exception. 
+\begin{verbatim}
+// A function declaration with an argument of type MyObject,
+// passed by value, and returning a MyObject
+MyObject f(MyObject x) 
+{
+  MyObject r;
+  ...
+  return(r);  // Copy constructor is called here
+}
+// Calling the function :
+MyObject a;
+f(a);        // Copy constructor called for a
+\end{verbatim}
+It should be noted that the C++ syntax is ambiguous for the 
+assignment operator. {\tt MyObject x; x=y; } and 
+{\tt MyObject x=y;} have different meaning.
+\begin{verbatim}
+MyObject a;        // default constructor call
+MyObject b(a);     // copy constructor call
+MyObject bb = a;   // identical to bb(a) : copy constructor call
+MyObject c;        // default constructor call
+c = a;             // assignment operator call
+\end{verbatim}
+
+As a general rule in SOPHYA, objects which implements 
+reference sharing on their data members have a copy constructor
+which shares the data, while the assignment operator copies or
+duplicate the data.
+
+\subsection{Multi-thread programming with SOPHYA}
+Multi-thread programming is usually safe as long as different threads DO NOT access
+the same memory locations. SOPHYA is mainly organized as classes having only 
+data members, with very few cases having static data members (memory locations
+common to all instances of a class), or seldom, global variables. \\
+Using different instances of a class in different threads is thus safe for most 
+classes / methods in SOPHYA. \\
+A major exception is the reference sharing mechanism, where different instances
+of a class may  shared memory locations. This reference sharing mechanism has been
+made thread-safe in SOPHYA, from version V=2.1. \\
+As a consequence, different execution threads can access non overlapping sub-arrays
+and access (read/write) the corresponding elements without the need of 
+mutex and thread synchonisation. Moreover, thread safe filling of 
+NTuple and DataTable objects can be activated, on an object per object basis. \\
+The {\tt ZThread, ZMutex \ldots} classes in the {\bf SysTools } module offer a relatively 
+easy way of writing multi-threaded programs.   
+
 \subsection{the runcxx program}
 \index{runcxx} \label{runcxx}
@@ -303 +371 @@
                 LinAlg, IFFTW, XAstroPack 
 \end{verbatim}
-Most examples in this manual can be tested using runcxx. The 
-example below shows how to compile, link and run a sample
+Most examples in this manual can be tested using runcxx. 
+The preprocessor macro {\tt KeepObj()} is defined by runcxx and let the user 
+to save an objet to an PPF file, with the same name as the corresponding variable.
+The example below shows how to compile, link and run a sample
 code.
 \begin{verbatim}
-//  File example.icc
-Matrix a(3,3);
-a = IdentityMatrix(1.);
-cout << a ; 
-// Executing this sample code
+##  File example.icc :
+
+Matrix mxa(3,3);
+mxa = IdentityMatrix(1.);
+cout << mxa ; 
+// Save the object mxa in a PPF file named mxa
+KeepObj(mxa);
+
+## Executing this sample code
 csh> runcxx -f example.icc
 \end{verbatim}
@@ -385 +459 @@
 
 \end{verbatim}
-\newpage
-
-\section{Copy constructor and assignment operator}
-\label{memgt}
-In C++, objects can be copied by assignment or by initialisation.
-Copying by initialisation corresponds to creating an object and
-initialising its value through the copy constructor.
-The copy constructor has its first argument as a reference, or
-const reference to the object's class type. It can have  
-more arguments, if default values are provided.
-Copying by assignment applies to an existing object and
-is performed through the assignment operator (=). 
-The copy constructor implements this for identical type objects:
-\begin{verbatim}
-class MyObject {
-public:
-  MyObject();      // Default constructor
-  MyObject(MyObject const & a);  // Copy constructor
-  MyObject & operator = (MyObject const & a) // Assignment operator
-}
-\end{verbatim}
-The copy constructors play an important role, as they are 
-called when class objects are passed by value, 
-returned by value, or thrown as an exception. 
-\begin{verbatim}
-// A function declaration with an argument of type MyObject,
-// passed by value, and returning a MyObject
-MyObject f(MyObject x) 
-{
-  MyObject r;
-  ...
-  return(r);  // Copy constructor is called here
-}
-// Calling the function :
-MyObject a;
-f(a);        // Copy constructor called for a
-\end{verbatim}
-It should be noted that the C++ syntax is ambiguous for the 
-assignment operator. {\tt MyObject x; x=y; } and 
-{\tt MyObject x=y;} have different meaning.
-\begin{verbatim}
-MyObject a;        // default constructor call
-MyObject b(a);     // copy constructor call
-MyObject bb = a;   // identical to bb(a) : copy constructor call
-MyObject c;        // default constructor call
-c = a;             // assignment operator call
-\end{verbatim}
-
-As a general rule in SOPHYA, objects which implements 
-reference sharing on their data members have a copy constructor
-which shares the data, while the assignment operator copies or
-duplicate the data.
-
-\section{Multi-thread programming with SOPHYA}
-Multi-thread programming is usually safe as long as different threads DO NOT access
-the same memory locations. SOPHYA is mainly organized as classes having only 
-data members, with very few cases having static data members (memory locations
-common to all instances of a class), or seldom, global variables. \\
-Using different instances of a class in different threads is thus safe for most 
-classes / methods in SOPHYA. \\
-A major exception is the reference sharing mechanism, where different instances
-of a class may  shared memory locations. This reference sharing mechanism has been
-made thread-safe in SOPHYA, from version V=2.1. \\
-As a consequence, different execution threads can access non overlapping sub-arrays
-and access (read/write) the corresponding elements without the need of 
-mutex and thread synchonisation. Moreover, thread safe filling of 
-NTuple and DataTable objects can be activated, on an object per object basis. \\
-The {\tt ZThread, ZMutex \ldots} classes in the {\bf SysTools } module offer a relatively 
-easy way of writing multi-threaded programs.   
+
 
 \newpage
@@ -462 +468 @@
 class {\tcls{NDataBlock}} for handling reference counting on numerical
 arrays, as well as classes providing the services for implementing simple
-serialisation. 
+serialisation (object persistence services).
 \vspace*{5mm}
 
@@ -517 +523 @@
 with data objects {\bf AnyDataObject} for write operations.
 \end{itemize}
-A complete description of SOPHYA persistence mechanism and guidelines
-for writing delegate classes for handling object persistence is beyond
-the scope of this document. The most useful methods for using Sophya
-persistence are listed below:
+The most useful methods for using Sophya
+persistence are listed below. A brief description of the PPF file format 
+and some guidelines for writing writing delegate classes for handling 
+object persistence can be found in the following paragraphs.
 \begin{itemize}
 \item[] {\tt POutPersist::PutObject(AnyDataObj \& o)} \\ 
@@ -556 +562 @@
 The {\bf scanppf} program can be used to list the content of a PPF file.
 
+\subsubsection{PPF file format}
+The PPF file consist of :
+\begin{itemize}
+\item[\rond] A file header (3x32=96 bytes) , containing  an identification string, 
+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.
+\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
+for arrays, or strings. The length information might be 4 bytes or 8 bytes long.
+Characters, various length (1,2,4,8 bytes long) signed and unsigned integers, 
+simple or double precision (4/8) bytes floating point and complex numbers are 
+the basic data types handled by PPF streams.
+\begin{verbatim}
+tag=PPS_SIMPLE_Integer4  +  data (4 bytes)
+tag=PPS_SIMPLE_Float4 + data (4 bytes)
+tag=PPS_SIMPLE_Complex8 + data (2x8=16 bytes)
+tag=PPS_STRING + Length (4 bytes) + data (Length bytes)
+tag=PPS_SIMPLE_ARRAY4_UInt2 + Length (4 bytes) + data (2xLength bytes)
+\end{verbatim}
+The two tags  {\tt PPS\_OBJECT} and {\tt PPS\_ENDOBJECT} are used for identifying 
+objects. 
+\item[\rond] The file trailer contains some global statistics such as the total number 
+of objects in file, the list of name tags, with their corresponding positions. 
+These informations are grouped under the identifier tag {\tt  PPS\_NAMETAG\_TABLE }.
+The last byte in file contains the value {\tt PPS\_EOF}
+\end{itemize}
+We show below the result of the analysis of a PPF file using 
+ {\tt PPFBinaryInputStream::AnalyseTags()}. This can easily be done using the 
+ {\bf runcxx} program.
+The PPF file contains four objects: 
+a {\tt TimeStamp} object, two {\tt NDataBlock} objects, the second one sharing its data with 
+the first one. The second NDataBlock is only written as a reference to the first object. The fourth 
+object is a {\tt RandomGenerator} which has an {\tt NDataBlock} object as data member. 
+Notice the corresponding nested structure of object marker tags.
+The first object and the last objects in the file are written associated with a {\bf NameTag}.
+{\small 
+\begin{verbatim}
+ ---------------------------------------------------------- 
+ PPFBinaryInputStream::AnalyseTags(Level= 49)
+   FileName= toto.ppf
+   Version= 3 FileSize= 8884 Creation Date= Fri Dec  7 15:30:58 2007
+
+ NbPosTag=0 NbNameTag=2 NbObjs=4 NbTopLevObjs=3 NbRefs=1 MaxNest=2
+
+<PPS_NAMETAG_MARK> tag at position 60
+<PPS_OBJECT> tag at position 61 ClassId= c09dfe032b341cee  ObjectId= 10
+  <PPS_SIMPLE> tag at position 72 DataType=INTEGER x4
+  <PPS_SIMPLE> tag at position 77 DataType=INTEGER x8
+  <PPS_SIMPLE> tag at position 80 DataType=FLOAT x8
+<PPS_ENDOBJECT> tag at position 89  ObjectId= 10
+<PPS_OBJECT> tag at position 92 ClassId= e670300b367585d1  ObjectId= 21
+  <PPS_SIMPLE_ARRAY4> tag at position a3 DataType=UNSIGNED x8 NElts= 3
+  <PPS_SIMPLE_ARRAY4> tag at position c0 DataType=INTEGER x4 NElts= 50
+<PPS_ENDOBJECT> tag at position 18d  ObjectId= 21
+<PPS_REFERENCE> tag at position 196  ObjectId= 21  OrigPos=92
+<PPS_NAMETAG_MARK> tag at position 1a7
+<PPS_OBJECT> tag at position 1a8 ClassId= eb6c427a5a30caed  ObjectId= 30
+  <PPS_SIMPLE_ARRAY4> tag at position 1b9 DataType=UNSIGNED x4 NElts= 6
+  <PPS_SIMPLE> tag at position 1d6 DataType=UNSIGNED x8
+  <PPS_SIMPLE> tag at position 1df DataType=UNSIGNED x8
+  <PPS_OBJECT> tag at position 1e8 ClassId= 6531a8f47336d4aa  ObjectId= 41
+    <PPS_SIMPLE_ARRAY4> tag at position 1f9 DataType=UNSIGNED x8 NElts= 3
+    <PPS_SIMPLE_ARRAY4> tag at position 216 DataType=FLOAT x8 NElts= 1024
+  <PPS_ENDOBJECT> tag at position 221b  ObjectId= 41
+<PPS_ENDOBJECT> tag at position 2224  ObjectId= 30
+<PPS_NAMETAG_TABLE> tag at position 222d
+<PPS_NAMETAG_ENTRY>  NameTag=rg-randgen NameTagMark Position=1a7
+<PPS_NAMETAG_ENTRY>  NameTag=ts-timestamp NameTagMark Position=60
+<PPS_EOF> tag at position 22b3 TagPos=222d
+ PPFBinaryInputStream::AnalyseTags() - End - Total Number of Tags= 23
+ ---------------------------------------------------------- 
+\end{verbatim}
+}  % fin de small 
+
+\subsubsection{Writing PPF handlers}
+Here are some guidelines for creating PPF handler classes to make 
+a class persistent through the SOPHYA PPersist mechanism. The example
+discussed here can be found in the {\bf Examples} module, in the directory 
+{\bf MyPPF}. 
+\begin{enumerate}
+\item The class should inherit from the {\bf SOPHYA::AnyDataObj} class. 
+   In the example here, we want to make the class {\bf Vfs} persistent
+\begin{verbatim}   
+class Vfs : public SOPHYA::AnyDataObj {
+ ... 
+}
+\end{verbatim}
+%%%%
+\item The PPF handler class 
+should inherit from {\bf SOPHYA::PPersist} . The pure virtual methods 
+of PPersist class (DataObj() , SetDataObj() , ReadSelf(), WriteSelf()
+must be implemented. 
+\begin{verbatim}   
+class PPFHandlerVfs : public SOPHYA::PPersist {
+public:
+  virtual SOPHYA::AnyDataObj* DataObj();
+  virtual void       SetDataObj(SOPHYA::AnyDataObj &);
+protected: 
+  virtual void       ReadSelf(SOPHYA::PInPersist&);
+  virtual void       WriteSelf(SOPHYA::POutPersist&) const;
+}
+\end{verbatim}
+%%%
+It is possible to use the template class {\tt SOPHYA::ObjFileIO<T>}, and 
+specialize it for the tharget class (here {\tt SOPHYA::ObjFileIO<Vfs>}), 
+by defining the two methods :  \\
+\hspace*{5mm} {\tt  SOPHYA::ObjFileIO<Vfs>::ReadSelf(SOPHYA::PInPersist\&) } \\
+\hspace*{5mm}  {\tt  SOPHYA::ObjFileIO<Vfs>::WriteSelf(SOPHYA::POutPersist\&) const }
+%%%%
+\item If it is NOT possible to have the target class inherit from {\bf AnyDataObj}, 
+a wrapper class should be used. The same class can play the role of wrapper
+AND the PPF handler. See the PPF handler / wrapper class for STL vectors : \\
+\hspace*{5mm} {\tt   SOPHYA::PPFWrapperSTLVector<T>} in file BaseTools/ppfwrapstlv.h 
+%%%
+\item Implement the ReadSelf() and WriteSelf() methods of the PPF handler.
+All the I/O services from the following classes can be used : 
+\begin{itemize}
+\item PPFBinaryIOStrem , PPFBinaryInputStream , PInPersist
+\item PPFBinaryIOStrem , PPFBinaryOutputStream , POutPersist
+\end{itemize}
+Writing and reading of the embeded objects for which a handler has been register
+ed can simply be performed by :  \\
+\hspace*{5mm} {\tt   POutPersist::PutObject() } \\
+\hspace*{5mm} {\tt   PInPersist::GetObject() }
+
+{\bf Warning:} The services associated with nametags : \\
+\hspace*{5mm}  {\tt PPFBinaryOutputStream::WriteNameTag() } \\
+\hspace*{5mm}  {\tt PPFBinaryInputStream::GotoNameTag() } \\
+are {\bf NOT} intented to be used in WriteSelf() , ReadSelf()
+%%%%%
+\item The new PPF handler, as well as the list of classes it can handle has to be
+registered prior to use PPF read/write for the target classes. This must be 
+performed during the initialization phase, for example at the beginning of the 
+main() program. Another possibility is to use a module initializer 
+(See {\bf SophyaInitiator} class in file BaseTools/sophyainit.h ) 
+and declare a static instance of the class. Notice that this works only if 
+the system loader handles correcly the call of constructor 
+for the statically declared objects. 
+
+The registration can be performed using the CPP macros defined in 
+BaseTools/ppersist.h
+\begin{verbatim}
+  // First, register the PPF handler ObjFileIO<Vfs> 
+  PPRegister(ObjFileIO<Vfs>);
+  // Register the list of classes which can be handled by ObjFileIO<Vfs> 
+  DObjRegister(ObjFileIO<Vfs>, Vfs);
+\end{verbatim}
+%%%%%%%%%%%%%%%%
+\end{enumerate}
+
+%%%%%%%%%%%%
 \subsection{\tcls{NDataBlock}}
 \index{\tcls{NDataBlock}}
@@ -667 +825 @@
 \end{itemize}
  
+ \subsection{Random numbers}
+ \index{RandomGenerator}
+ 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
+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}
+
+%%%%%%%%%%%%
 \newpage
 \section{Module TArray}
@@ -998 +1197 @@
 TArray<int_4> ia(5,3);
 ia = 8;
-pos << ia;                 // (1) 
+pos << ia;         // (1) 
 ia = 16;
-pos << ia;                 // (2) Only a reference to the previously ia array is written
+pos << ia;        // (2) Only a reference to the previously ia array is written
 ia = 32;
 ia.RenewObjId();    // We change the object Id
-pos << ia;                 //  (3) The complete array is dumped again 
+pos << ia;        //  (3) The complete array is dumped again 
 }
 \end{verbatim}
@@ -1097 +1296 @@
 \item[\bul] Functions returning arrays corresponding to real and imaginary 
 parts of a complex array: {\tt real(za) , imag(za) } 
-({\bf Warning:} Note that the these functions do not provide
-shared memory access to real and imaginary parts.)
+({\bf Warning:} Note that the these functions create an array and copies
+the data from the original complex array. They do not provide
+shared memory access to real and imaginary parts. 
+For shared memory access, use functions {\tt SDRealPart()} and
+{\tt SDImagPart() } (see below). 
 \item[\bul] Functions returning arrays corresponding to the module, 
 phase, and module squared of a complex array:
@@ -1155 +1357 @@
 TArray<r_4> aza = ArrCastC2R(za);
 cout << " za --> aza= " << aza;
+TArray< complex<r_4> > zb;
+zb = ArrCastR2C(aza);
+KeepObj(zb);
 \end{verbatim}
 
@@ -1164 +1369 @@
 The first index is along the X axis and the second index along the Y axis.
 \begin{verbatim}
-    | (0,0)  (0,1)  (0,2)  (0,3) |
-    | (1,0)  (1,1)  (1,2)  (1,3) |
-    | (2,0)  (2,1)  (2,2)  (2,3) |
+    | (0,0)  (1,0)  (2,0)  (3,0) |
+    | (0,1)  (1,1)  (2,1)  (3,1) |
+    | (0,2)  (1,2)  (2,2)  (3,2) |
 \end{verbatim}
 In the first case, the array is completely packed 
@@ -1196 +1401 @@
 
 \begin{verbatim}
+BaseArray::SetDefaultMemoryMapping(BaseArray::CMemoryMapping);
 TArray<r_4> X(4,2); 
 X = RegularSequence(1,1);
 cout << "Array X= " << X << endl;
-TMatrix<r_4> X_C(X, true, BaseArray::CMemoryMapping);
+TMatrix<r_4> X_C(X, true);
 cout << "Matrix X_C (CMemoryMapping) = " << X_C << endl;
-TMatrix<r_4> X_F(X, true, BaseArray::FortranMemoryMapping);
+TMatrix<r_4> X_F(X_C, true);
+X_F.TransposeSelf();    // we make it a FortranMemoryMapping matrix
 cout << "Matrix X_F (FortranMemoryMapping) = " << X_F << endl;
 \end{verbatim}
@@ -1223 +1430 @@
 4, 8
 \end{verbatim}
+
+{\bf Note:} Only the {\tt TMatrix} class is sensitive to the memory organisation. It should also 
+be noted that the first index for a matrix is the row index. For a {\tt TArray} object, the first 
+index correspond always to the X axis. For a matrix in the {\tt CMemoryMapping}, the row
+index is the Y index of the corresponding array, while for a matrix 
+with {\tt FortranMemoryMapping}, the row index is the X index.
+\begin{verbatim}
+#  2D array  arr ,  matrix mx
+TArray<r_4> arr; 
+...
+TMatrix<r_4> mx(arr);
+...
+###   CMemoryMapping  :
+mx( row , col ) -> arr( ix=col, jy= row )
+###   FortranMemoryMapping  :
+mx( row , col ) -> arr( ix=row, jy= col )
+\end{verbatim}
+The following code fragment shows the difference between element access 
+index order for the different memory organisation:
+\begin{verbatim}
+   TArray<int_4> a(5,3);
+   a = RegularSequence(10,2);
+   cout << "Array a = " << a << endl;
+   TMatrix<r_4> mac(a);
+   cout << "Matrix mac (CMemoryMapping) = " << mac << endl;
+   TMatrix<r_4> maf(mac);
+   maf.TransposeSelf();    // we make it a FortranMemoryMapping matrix
+   cout << "Matrix maf (FortranMemoryMapping) = " << maf << endl;
+   // ---- element access
+   cout <<  " Array(ix,jy) : a(2,0)= " << a(2,0) << " a(1,2)= " << a(1,2) 
+        <<   "  a(0,2)= " << a(0,2) << endl;
+   cout <<  " mac(row,col) :  mac(2,0)= " << mac(2,0) << " mac(1,2)= " << mac(1,2) 
+        <<   "  mac(0,2)= " << mac(0,2) << endl;
+   cout <<  " maf(row,col) :  maf(2,0)= " << maf(2,0) << " maf(1,2)= " << maf(1,2) 
+        <<   "  maf(0,2)= " << maf(0,2) << endl;
+\end{verbatim}
+
 
 \newpage 
@@ -1434 +1678 @@
    
 \subsection{Writing, viewing \dots }
-
-All these objects have been design to be written to or read from a persistent file.
+%%
+Histogram and NTuple/DataTable objects have PPF handlers and 
+can be written to or read from PPF files. Sophya graphical tool (spiapp) can 
+automatically display and operate on all these objects.
 The following example shows how to write the previously created objects
 into such a file~:
 \begin{verbatim}
-//-- Writing
 {
 char *fileout = "myfile.ppf";
@@ -1449 +1694 @@
 }  // closing ``}'' destroy ``outppf'' and automatically close the file !
 \end{verbatim}
-
-Sophya graphical tools (spiapp) can automatically display and operate
-all these objects.
 
 \newpage
@@ -1702 +1944 @@
 The classes {\bf ZMutex} \index{mutex} and {\bf ZSync} can be used 
 to perform synchronisation and signaling between threads.
- 
+Example multithread programs using these classes can be found in
+the {\bf Tests} module : \\
+\hspace{10mm} {\tt zthr.cc  , tmtdt.cc , tmtrnd.cc }
+
 \subsection{Dynamic linker and C++ compiler classes}
 \index{PDynLinkMgr}
@@ -1743 +1988 @@
 
 \subsection{Command interpreter}
+\index{Commander}
+\index{Expression evaluation}
 The class {\bf Commander} can be used in interactive programs to provide
 c-shell like command interpreter and scripting capabilties. 
 Arithmetic expression evaluation is implemented through the {\bf CExpressionEvaluator}
-and {\bf RPNExpressionEvaluator} classes. 
+and {\bf RPNExpressionEvaluator} classes. The latter can be used to perform evaluation
+in reverse polish notation (old HP calculators), 
+while the former uses the usual algebraic (c-language like) expressions.
 The command language provides variable manipulation through the usual 
 {\tt \$varname} vector variable and arithmetic expression extensions, as well 
@@ -1772 +2021 @@
 \end{figure}
 The {\bf SkyMap} module provides classes for creating, filling, reading pixelized spherical  and 2D-maps. The types of values stored in pixels can be int, float, double , complex etc. according to the specialization of the template type. 
+\subsection{3D geometry}
+Some of the classes in this module simplify the angle manipulation, or the 3D geometry
+and rotation calculations, such as the {\bf Vector3d} and {\bf UnitVector} classes.
+\index{Vector3d}
+The classes {\bf Vector3d} and {\bf UnitVector}  are useful for angle conversions.
+\index{Angle}
+{\bf LongLat} class and {\bf Angle} class (defined in file vector3d.h) can be used for
+angle conversions :
+\begin{verbatim}
+   // Example to convert 0.035 radians to arcsec
+   double vr = 0.035;
+   cout << "Angle rad= " << vr << " ->arcsec= " << Angle(vr).ToArcSec() << endl;
+   // Example to convert 2.3 arcmin to radian - we use the conversion operator
+   double vam = 2.3;
+   cout << "Angle arcmin= " << vam << " ->rad= " 
+        << (double)Angle(vam, Angle::ArcMin) << endl;
+\end{verbatim}
+%%%
 \subsection {Spherical maps}
 SkyMap module provides three kinds of complete ($4 \pi$) spherical maps according to the
@@ -2113 +2380 @@
 The {\bf FFTWServer} class (in module FFTW) implements FFTServerInterface class 
 methods, for one dimensional and multi-dimensional Fourier 
-transforms on double precision data using the FFTW package
-(available from {\tt http://www.fftw.org}).
+transforms  using the FFTW package (available from {\tt http://www.fftw.org}).
+Depending on the configuration options during library build, only 
+transforms on double precision data might be available.
 
 \newpage
@@ -2393 +2661 @@
 \input{ex1.inc}
 
-
 \newpage
 \addcontentsline{toc}{section}{Index}