Changeset 1362 in Sophya for trunk

Timestamp:

Dec 22, 2000, 5:53:02 PM (25 years ago)

Author:

ansari

Message:

MAJ documentation Reza 22/12/2000

Location:

trunk/SophyaLib/Manual

Files:

• defsophya.sty (modified) (1 diff)
• sophya.tex (modified) (16 diffs)

trunk/SophyaLib/Manual/defsophya.sty

@@ -2 +2 @@
 %  Definition of template class \tcls{Vector} --> Vector<T>
 \newcommand{\tcls}[1] {#1$<$T$>$}   
+\newcommand{\tclsc}[2] {#1$<$#2$>$}   
 %  Putting a class name in a box
 \newcommand{\clsbox}[1] { \framebox[40mm][c]{\mbox{\rule[-1mm]{0mm}{5mm} \bf #1} } }

trunk/SophyaLib/Manual/sophya.tex

@@ -15 +15 @@
 \usepackage{defsophya}
 
-
+%  Constitution d'index
+\usepackage{makeidx}
+\makeindex     
 
 \begin{document}
@@ -32 +34 @@
 % \auteursall
 %  The title page - bottom of the page with the paper number
+\vspace{1cm}
+\begin{center}
+{\bf \Large Document being updated !}
+\end{center}
 \titrebp{1}
 \end{titlepage}
@@ -41 +47 @@
 \section{Introduction}
 
-   {\bf SOPHYA} ({\bf SO}ftware for {\bf PHY}sics {\bf A}nalysis) 
+{\bf SOPHYA} ({\bf SO}ftware for {\bf PHY}sics {\bf A}nalysis) 
 is a collection of C++ classes designed for numerical and
 physics analysis software development. Our goal is to provide
@@ -55 +61 @@
 and Planck mission problem.
   The source directory tree 
-\footnote{ CVS server: cvsserver.lal.in2p3.fr:/projects/Eros/CVSPlanck} 
+\footnote{ CVS: cvsserver.lal.in2p3.fr:/exp/eros/CVSPlanck} 
 is organised into a number of modules. 
 
@@ -112 +118 @@
 
 \section{Using Sophya}
+Basic usage of Sophya classes are described in in the following sections.
+Complete Sophya documentation can be found at our web site: \\
+{\bf http://hfi-l2.in2p3.fr}. 
+
+\subsection{Environment variables}
 Two environment variables {\bf DPCBASEREP} and {\bf EROSCXX} are used 
 to define the path where the Sophya libraries and executable are installed.
@@ -140 +151 @@
 {\tt \$EXTLIBDIR/Linux-g++/Libs} \\
 
+\subsection{User makefiles}
 The file {\tt \$DPCBASEREP/Include/MakefileUser.h} defines the compilation 
 flags and the list of Sophya libraries. It should be included in the 
@@ -168 +180 @@
 example makefile.
 
-Basic usage of Sophya classes are described in in the following sections.
-Complete Sophya documentation can be found at our web site: \\
-{\bf http://hfi-l2.in2p3.fr}. 
-
+\subsection{the runcxx program}
+\index{runcxx}
+{\bf runcxx} is a simple program which can be used to compile, link
+and run simple C++ programs. It handles the creation of a
+complete program file, containing the basic set C++ include files,
+the necessary include files for SOPHYA SysTools, TArray, HiStats 
+and NTools modules, and the main program with exception handling.
+Other Sophya modules can be included using the {\tt -import} flag.
+\begin{verbatim}
+csh> runcxx -h
+SOPHYA Version  0.9 Revision 97 (V_Oct2000) -- Nov  9 2000 16:20:52 cxx
+ runcxx : compiling and running of a piece of C++ code
+   Usage: runcxx [-compopt CompileOptions] [-linkopt LinkOptions]
+                 [-tmpdir TmpDirectory] [-f C++CodeFileName]
+                 [-inc includefile] [-inc includefile ...]
+                 [-import modulename] [-import modulename ...]
+                 [-uarg UserArg1 UserArg2 ...]
+   if no file name is specified, read from standard input
+   modulenames: SkyMap, Samba, SkyT, FitsIOServer, LinAlg, IFFTW
+\end{verbatim}
+Most examples in this manual can be tested using runcxx. 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
+csh> runcxx -f example.icc
+\end{verbatim}
+ 
+
+\section{Copy constructor and assignment operator}
+In C++, objects can be copied by assignment or by initialization.
+Copying by initialization corresponds to creating an object and
+initializing 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{Module SysTools}
@@ -183 +273 @@
 
 \subsection{SOPHYA persistence}
+\index{PPersist} \index{PInPersist} \index{POutPersist}
 \begin{figure}[hbt]
 \dclsa{PPersist}
@@ -210 +301 @@
 
 \subsection{\tcls{NDataBlock}}
+\index{\tcls{NDataBlock}}
+\begin{figure}[hbt]
+\dclsbb{AnyDataObj}{\tcls{NDataBlock}}
+\dclsbb{PPersist}{\tcls{FIO\_NDataBlock}}
+\end{figure}
 The {\bf \tcls{NDataBlock}} is designed to handle reference counting 
 and sharing of memory blocs (contiguous arrays) for numerical data 
@@ -242 +338 @@
 \end{verbatim}
 
+\subsection{Using DVList}
+\index{DVList} \index{MuTyV}
+\begin{figure}[hbt]
+\dclsbb{AnyDataObj}{DVList}
+\dclsbb{PPersist}{\tclsc{ObjFileIO}{DVList}}
+\end{figure}
+The {\bf DVList} class objects can be used to create and manage list
+of values, associated with names. A list of pairs of (MuTyV, name(string))
+is maintained by DVList objects. {\bf MuTyV} is a simple class
+capable of holding string, integer, float or complex values, 
+providing easy conversion methods between these objects.
+\begin{verbatim}
+// Using MuTyV objects
+MuTyV s("hello");  // string type value
+MuTyV x;
+x = "3.14159626";    // string type value, ascii representation for Pi
+double d = x;        // x converted to double = 3.141596
+x = 314;             // x contains the integer value = 314
+// Using DVList
+DVList  dvl;
+dvl("Pi") = 3.14159626;            // float value, named Pi
+dvl("Log2") = 0.30102999;          // float value, named Log2
+dvl("FileName") = "myfile.fits";   // string value, named myfile.fits
+// Printing DVList object
+cout << dvl;
+\end{verbatim}
+
 \subsection{Using DataCards}
+\index{DataCards}
 The {\bf DataCards} class can be used to read parameters from a file.
 Each line in the file starting with \@ defines a set of values
@@ -262 +386 @@
 
 \subsection{Dynamic linker}
+\index{PDynLinkMgr}
 The class {\bf PDynLinkMgr} can be used for managing shared libraries
 at run time. The example below shows the run time linking of a function:\\
@@ -279 +404 @@
 
 \subsection{CxxCompilerLinker class}
+\index{CxxCompilerLinker}
 This class provides the services to compile C++ code and building 
 shared libraries, using the same compiler and options which have 
@@ -300 +426 @@
 
 \section{Module TArray}
+\index{\tcls{TArray}}
 {\bf TArray} module contains template classes for handling standard 
 operations on numerical arrays. Using the class {\tt \tcls{TArray} },
 it is possible to create and manipulate up to 5-dimension numerical
-arrays {\tt (int, float, double, complex, \ldots)}.   
+arrays {\tt (int, float, double, complex, \ldots)}. The include
+file {\tt array.h} declares all the classes and definitions 
+in module TArray.  
 
 \begin{figure}[hbt]
 \dclsccc{AnyDataObj}{BaseArray}{\tcls{TArray}}
-\ldots \\
+\dclsbb{PPersist}{\tcls{FIO\_TArray}}
+\end{figure}
+
+
+\subsection{Using arrays}
+\index{Sequence} \index{RandomSequence} \index{RegularSequence} 
+\index{EnumeratedSequence}
+The example below shows basic usage of arrays, creation, initialization
+and arithmetic operations. Different kind of {\bf Sequence} objects
+can be used for initializing arrays.
+\begin{figure}[hbt]
+\dclsbb{Sequence}{RandomSequence}
+\dclsb{RegularSequence}
+\dclsb{EnumeratedSequence}
+\end{figure}
+
+The example below shows basic usage of arrays: 
+\begin{verbatim}
+// Creating and initializing a 1-D array of integers
+TArray<int> ia(5);
+EnumeratedSequence es;
+es = 24, 35, 46, 57, 68;
+ia = es;
+cout << "Array<int> ia = " << ia;
+// 2-D array of float filled with random numbers  
+// 2-D array of floats 
+TArray<r_4> b(6,4), c(6,4);
+// Initializing b with a constant
+b = 2.71828;
+// Filling c with random numbers  
+c = RandomSequence(); 
+// Arithmetic operations
+TArray<r_4> d = b+0.3f*c;
+cout << "Array<float> d = " << d;
+\end{verbatim}
+
+The copy constructor shares the array data, while the assignment operator
+copies the array elements, as illustrated in the following example:
+\begin{verbatim}
+TArray<int> a1(4,3);
+a1 = RegularSequence(0,2);
+// Array a2 and a1 shares their data 
+TArray<int> a2(a1);
+// a3 and a1 have the same size and identical elements
+TArray<int> a3;
+a3 = a1;
+// Changing one of the a2 elements
+a2(1,1,0) = 555;
+// a1(1,1) is also changed to 555, but not a3(1,1)
+cout << "Array<int> a1 = " << a1;
+cout << "Array<int> a3 = " << a3;
+\end{verbatim} 
+
+\subsection{Working with sub-arrays and Ranges}
+
+
+\subsection{Matrices and vectors}
+\index{\tcls{TMatrix}}  \index{\tcls{TVector}}
+\begin{figure}[hbt]
 \dclsccc{\tcls{TArray}}{\tcls{TMatrix}}{\tcls{TVector}}
-\caption{partial class diagram for arrays, matrices and vectors}
 \end{figure}
-
-
-\subsection{Using arrays}
-
-The example below shows basic usage of arrays: 
-\begin{verbatim}
-#include "array.h"
-// ...
-// Creation , filling of a Matrix
-  TMatrix<r_4> ma(7,9);
-  ma = RegularSequence(0.1, 0.05);   
-  cout << "\n ma = " << ma << endl; 
-\end{verbatim}
+Vectors and matrices are 2 dimensional arrays. The array size
+along one dimension is equal 1 for vectors. Column vectors
+have {\tt NCols() = 1} and row vectors have {\tt NRows() = 1}.
 
 Example of a simple low-pass filter on a one dimensional array (Vector) 
@@ -497 +673 @@
 needed (they used buffers on hard disk).
 
-\subsection{Writing, seeing \dots }
+\subsection{Writing, viewing \dots }
 
 All these objects have been design to be written to or read from a persistant file.
@@ -760 +936 @@
 \newpage
 \appendix
-\section{Exception handling: An example}
+\section{SOPHYA Exceptions}
+\index{Exception classes} \index{PThrowable} \index{PError} \index{PException}
+SOPHYA library defines a set of exceptions which are used 
+for signaling error conditions. The figure below shows a partial 
+class diagram for exception classes in SOPHYA.
+\begin{figure}[hbt]
+\dclsbb{PThrowable}{PError}
+\dclscc{PError}{AllocationError}
+\dclscc{PError}{NullPtrError}
+\dclscc{PError}{ForbiddenError}
+\dclscc{PError}{AssertionFailedError}
+\dclsbb{PThrowable}{PException}
+\dclscc{PException}{IOExc}
+\dclscc{PException}{SzMismatchError}
+\dclscc{PException}{RangeCheckError}
+\dclscc{PException}{ParmError}
+\dclscc{PException}{TypeMismatchExc}
+\dclscc{PException}{MathExc}
+\dclscc{PException}{CaughtSignalExc}
+\caption{partial class diagram for exception handling in Sophya}
+\end{figure}
+
 For simple programs, it is a good practice to handle 
 the exceptions at least at high level, in the {\tt main()} function. 
@@ -769 +966 @@
 
 
+\newpage
+\addcontentsline{toc}{section}{Index}
+\printindex 
 \end{document}
+