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

Timestamp:

Jul 4, 2006, 7:14:37 PM (19 years ago)

Author:

ansari

Message:

suite documentation SOPHYA (DataTable, Spheres ...) Reza 04/07/2006

File:

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

trunk/SophyaLib/Manual/sophya.tex

@@ -25 +25 @@
 
 \makeindex     %  Constitution d'index
+
+\newcommand{\rond}{$\bullet \ $}
+\newcommand{\etoile}{$\star \ $}
+\newcommand{\cercle}{$\circ \ $}
+\newcommand{\carre}{$\Box \ $}
+
 
 \begin{document}
@@ -43 +49 @@
 \vspace{1cm}
 \begin{center}
-{\bf \Large Sophya Version: 1.929 (V\_Fev2006) }
+{\bf \Large Sophya Version: 1.966 (V\_Jun2006) }
 % Document revision 1.0 }
 \end{center}
@@ -63 +69 @@
 modules presented here have a much broader scope and can be
 used in scientific data analysis and modeling/simulation. 
-Whenever possible, we use existing numerical package and libraries, 
-encapsulating them whenever
-possible. 
+Whenever possible, we use existing numerical packages and libraries, 
+encapsulating them in classes in order to facilitate their usage.
 \par
-\vspace*{2mm}
+Our main requirements in designing SOPHYA classes can be summarized as
+follow:
+\begin{itemize}
+\item[\rond] Provide a comprehensive set of data containers, such as arrays and tables 
+(tuple) covering the most common needs in scientific simulation and data analysis
+softwares.
+\item[\rond] Take advantage of the C++ language and define methods and operators 
+for most basic operation, such as arithmetic operations, in a rather intuitive way, while
+maintaining performances comparable to low level coding in other languages 
+(C, Fortran, F90 \ldots) 
+\item[\rond] Simplify memory management for programmers using the class library.
+This has been a strong requirement for most SOPHYA classes. Automatic reference 
+sharing and memory management is implemented in SOPHYA classes intended 
+for large size objects. We recommend to allocate SOPHYA objects on the stack,
+including when objects are returned by methods or functions. 
+See section \ref{memgt} for more information.
+\item[\rond] Archiving, importing (reading) and exporting (writing) data in a 
+efficient and consistent way is a major concern in many scientific software 
+and projects. SOPHYA provide a native data I/O or persistence system, 
+(PPF, \ref{ppfdesc}) as well as import/export  services for ASCII and FITS formats.
+\end{itemize}
+
+% \vspace*{2mm}
 This documents
 presents only a brief overview of the class library, 
@@ -74 +101 @@
 web site: % {\bf http://www.sophya.org}.
 \href{http://www.sophya.org}{http://www.sophya.org}. 
-\par
-\vspace*{2mm}
+%%%
+%%%
+\subsection{SOPHYA modules}
 The source directory tree 
 \footnote{ CVS: cvsserver.lal.in2p3.fr:/exp/eros/CVSSophya} 
@@ -117 +145 @@
 \begin{itemize}
 \item[] {\bf FitsIOServer/} Classes for handling file input-output 
-in FITS format using the cfitsio library.
-\item[] {\bf LinAlg/} Interface with Lapack linear algebra package
-\item[] {\bf IFFTW/} Interface with FFTW package (libfftw.a)
+in FITS format using the cfitsio library. 
+FITS is maintained by NASA and SAO and is available from: \\
+\href{http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html}
+{http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html}
+\item[] {\bf LinAlg/} Interface with Lapack linear algebra package.
+Lapack is a linear algebra package and can be downloaded from: \\ 
+\href{http://www.netlib.org/lapack/}{http://www.netlib.org/lapack/}
+\item[] {\bf IFFTW/} Interface with FFTW package (libfftw.a).
+FFTW is a package for performing Fourier transforms, written in C.
+Documentation and source code can be found at: \\
+\href{http://www.fftw.org/}{http://www.fftw.org/}
 \item[] {\bf XAstroPack/} Interface to some common astronomical 
 computation libraries. Presently, this module uses an external library
 extracted from the {\bf Xephem } source code. The corresponding source 
 code is also available from SOPHYA cvs repository, module {\bf XephemAstroLib}. 
+Information on Xephem can be found at : \\
+\href{http://www.clearskyinstitute.com/xephem/}{http://www.clearskyinstitute.com/xephem/}
 \item[] {\bf MinuitAdapt/} Wrapper classes to CERN minimization routines (Minuit). 
 
@@ -160 +198 @@
 \end{itemize}   
 
-Modules containing examples and demo programs:
+Modules containing examples and demo programs and scripts:
 \begin{itemize}
 \item[] {\bf Examples/} Sample SOPHYA codes and example programs and
@@ -178 +216 @@
 \subsection{Directories, environment variables, configuration files}
 The environment variable {\bf SOPHYABASE}  is used 
-to define the path where the Sophya libraries and executable are installed.
+to define the path where the Sophya libraries and binaries are installed.
 \begin{itemize}
 \item \$SOPHYABASE/include : Include (.h) files
 \item \$SOPHYABASE/lib : Path for the archive libraries (.a)
 \item \$SOPHYABASE/slb: Shared library path (.so)
-\item \$SOPHYABASE/exe : Executable file path
+\item \$SOPHYABASE/exe : Path for binary program files
 \end{itemize}
 
@@ -300 +338 @@
 
 \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
@@ -360 +399 @@
 
 \subsection{SOPHYA persistence}
+\label{ppfdesc}
 \index{PPersist} \index{PInPersist} \index{POutPersist}
 \begin{figure}[hbt]
@@ -1026 +1066 @@
 doing various operations on one or two dimensional histograms
 {\tt Histo} and {\tt Histo2D} as well as profile histograms {\tt HProf}. \\
-This module also contains {\tt NTuple} and {\tt XNTuple} which are
-more or less the same that the binary FITS tables.
-
-\subsection{1D Histograms}
+This module also contains {\tt NTuple} and {\tt DataTable} which are
+more or less the same as the binary or ascii FITS tables.
+
+\subsection{Histograms}
+\subsubsection{1D Histograms}
 \index{Histo}
 For 1D histograms, various numerical methods are provided such as
@@ -1049 +1090 @@
 \end{verbatim}
 
-\subsection{2D Histograms}
+\subsubsection{2D Histograms}
 \index{Histo2D}
 Much of these operations are also valid for 2D histograms. 1D projection
@@ -1069 +1110 @@
 \end{verbatim}
 
-\subsection{Profile Histograms}
+\subsubsection{Profile Histograms}
 \index{HProf}
 Profiles histograms {\bf HProf} contains the mean and the 
@@ -1079 +1120 @@
 
 \subsection{Data tables (tuples)}
+\begin{figure}[hbt]
+\dclsbb{AnyDataObj}{NTuple}
+\dclsccc{AnyDataObj}{BaseDataTable}{DataTable}
+\dclscc{BaseDataTable}{SwPPFDataTable}
+\end{figure}
+
+\subsubsection{NTuple}
 \index{NTuple}
 NTuple are memory resident tables of 32 or 64 bits floating values 
@@ -1111 +1159 @@
 very large data sets, through swap space on disk. 
 
+\subsubsection{DataTables}
 \index{DataTable} 
-
 The class {\bf DataTable} extends significantly the functionalities provided by 
 NTuple. DataTable is a memory resident implementation of the interface 
@@ -1139 +1187 @@
 \end{verbatim}
 
-\begin{figure}[hbt]
-\dclsccc{AnyDataObj}{BaseDataTable}{DataTable}
-\dclscc{BaseDataTable}{SwPPFDataTable}
-\end{figure}
 
 \index{SwPPFDataTable}
@@ -1149 +1193 @@
 can be created and manipulated through tis class
 
+\index{DataTableRow}
+The class {\bf DataTableRow } is an auxiliary class which simplifies the manipulation
+of BaseDataTable object rows. 
+\begin{verbatim}
+   #include "datatable.h"
+   // ...
+   // Create a table with 3 columns
+   DataTable dtrow(64);
+   dtrow.AddStringColumn("sline");
+   dtrow.AddIntegerColumn("line");
+   dtrow.AddDateTimeColumn("datime");
+   
+   TimeStamp ts, ts2;  // Initialize current date and time
+   string sline;
+   // Create a table row with the required structure
+   DataTableRow row = dtrow.EmptyRow();
+   // Fill the table
+   for(int k = 0; k<25; k++) {
+     sline = "L-";
+     sline += (string)MuTyV(k);
+     row["sline"] = sline;
+     row[1] = k;
+     ts2.Set(ts.ToDays()+(double)k);
+     row["datime"] = ts2;
+     dtrow.AddRow(row);
+  }
+  // Acces and print two of the table rows :
+  cout << dtrow.GetRow(6, row) << endl;
+  cout << dtrow.GetRow(6, row) << endl;  
+\end{verbatim}
+ 
 \subsection{Writing, viewing \dots }
 
@@ -1431 +1506 @@
 \dclsccc{PixelMap}{Sphericalmap}{SphereHEALPix}
 \dclsc{SphereThetaPhi}
+\dclsc{SphereECP}
 \dclsb{LocalMap}
-\caption{partial class diagram for pixelization classes  in Sophya}
+\caption{partial class diagram for spherical map classes  in Sophya}
 \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 {Spherical maps}
-There are two kinds of spherical maps according pixelization algorithms. SphereHEALPix represents spheres pixelized following the HEALPIix algorithm (E. Hivon, K. Gorski)
+SkyMap module provides three kinds of complete ($4 \pi$) spherical maps according to the
+pixelization scheme. 
+SphereHEALPix represents spheres pixelized following the HEALPIix algorithm (E. Hivon, K. Gorski)
 \footnote{see the HEALPix Homepage: http://www.eso.org/kgorski/healpix/ }
 , SphereThetaPhi represents spheres pixelized following an algorithm developed at LAL-ORSAY. The example below shows creating and filling of a SphereHEALPix with nside = 8 (it will be 12*8*8= 768 pixels) :
 \index{\tcls{SphereHEALPix}} 
-\index{\tcls{SphereThetaPhi}} 
 
 \begin{verbatim}
@@ -1451 +1528 @@
 SphereThetaPhi is used in a similar way with an argument representing number of slices in theta (Euler angle) for an hemisphere.
 \index{\tcls{SphereThetaPhi}}
+The SphereECP class correspond to the cylindrical projection and can be used for representing
+partial or full spherical maps. However, it has the disadvantage of having non uniform pixel 
+size.
+\index{\tcls{SphereECP}}
 
 \subsection {Local maps}