Changeset 1648 in Sophya for trunk/SophyaLib/Manual

Timestamp:

Sep 11, 2001, 4:05:28 PM (24 years ago)

Author:

ansari

Message:

modifications - MAJ de sophya.tex (overview) pour la version 1.2 , Reza 11/9/2001

File:

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

trunk/SophyaLib/Manual/sophya.tex

@@ -36 +36 @@
 \vspace{1cm}
 \begin{center}
-{\bf \Large Sophya Version: 1.1 (V\_Fev2001) \\ 
-Document revision 1.0 }
+{\bf \Large Sophya Version: 1.2 (V\_Jul2001) }
+% Document revision 1.0 }
 \end{center}
 \titrebp{1}
@@ -55 +55 @@
 numerical analysis libraries, encapsulating them whenever
 possible. Although some the modules in SOPHYA have been 
-designed with the specific goal of providing the general framework for
+designed with the specific goal of providing some of the tools for
 the Planck-HFI data processing software, most of the
 packages presented here have a more general scope than the 
@@ -84 +84 @@
 services.
 \item[] {\bf TArray/} template numerical arrays, vectors and matrices \\
-({\tt PixelMap<T> SphericalMap<T>} \ldots) 
+({\tt TArray<T> TMatrix<T> TVector<T> } \ldots) 
 \item[] {\bf NTools/} Some standard numerical analysis tools 
 (linear, and non linear parameter fitting, FFT, \ldots)
-\item[] {\bf HiStats/}  Histogram-ming and data set handling classes \\
+\item[] {\bf HiStats/}  Histogram-ming and data set handling classes (tuples) \\
 ({\tt Histo Histo2D NTuple XNTuple} \ldots)
+\item[] {\bf SkyMap/} Local and full sky maps, and few geometry 
+handling utility classes. \\
+({\tt PixelMap<T>, LocalMap<T>, SphericalMap<T>, \ldots})
 \end{itemize}
 
@@ -94 +97 @@
 CMB (Cosmic Microwave Background) data analysis problem:
 \begin{itemize}
-\item[] {\bf SkyMap/} Local and full sky maps, and few geometry 
-handling utility classes. \\
-({\tt PixelMap<T>, LocalMap<T>, SphericalMap<T>, \ldots})
 \item[] {\bf SkyT/} 
 classes for spectral emission and detector frequency response modelling \\
@@ -110 +110 @@
 \item[] {\bf LinAlg/} Interface with Lapack linear algebra package
 \item[] {\bf IFFTW/} Interface with FFTW package (libfftw.a)
+\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}. 
 \end{itemize}
 
@@ -307 +311 @@
 and object hierarchy. \\
 {\bf PPF} {\bf P}ortable {\bf P}ersistence file {\bf F}ormat.
+\index{PPF}
 \item[] Handling of read/write for multiply referenced objects.
 \item[] All write operations are carried using sequential access only. This
@@ -614 +619 @@
 range can be specified, using the {\tt start} and {\tt end} index
 and an optional step (or stride). It is also possible to specify
-the {\tt start} index and the number of elements.
-In the following example, a simple low-pas filter, on a one 
+the {\tt start} index and the number of elements: 
+\begin{center}
+
+\begin{tabular}{ll}
+\multicolumn{2}{c}{ {\bf Range} {\tt (start=0, end=0, size=1, step=1) } } \\[2mm]
+\hline \\
+{\bf Range} {\tt r(3,6); } &  index range 3,4,5,6 \\
+{\bf Range} {\tt r(7,0,3); } &  index range 7,8,9 \\
+{\bf Range} {\tt r(10,0,3,5); } &  index range 10,12,14,16,18 \\
+\end{tabular}
+\end{center}
+
+In the following example, a simple low-pass filter, on a one 
 dimensional stream (Vector) has been written using sub-arrays:  
 
@@ -630 +646 @@
     out(k) = in(Range(k-w, k+w).Sum()/(2.*w+1.);
 \end{verbatim}
+
+\subsection{Input, Output}
+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, 
+as well as to files in FITS format.
+FITS format input/output is provided through the classes in 
+{\bf FitsIOServer} module. Onnly arrays with data types 
+supported by the FITS standard can be handled during 
+I/O operations to and from FITS streams (See the FitsIOServer section
+for additional details).
+
+\subsubsection{PPF streams} 
+
+SOPHYA persistence (PPF streams) handles reference sharing, and multiply 
+referenced objects are only written once. A hierarchy of arrays and sub-arrays
+written to a PPF stream is thus completely recovered, when the stream is read.
+The following example illustrates this point:
+\begin{verbatim}
+{
+// Saving an array with a sub-array into a POutPersist file
+Matrix A(3,4);
+A = RegularSequence(10,5);
+// Create a sub-array of A 
+Matrix AS = A(Range(1,2), Range(2,3));
+// Save the two arrays to a PPF stream
+POutPersist pos("aas.ppf");
+pos << A << AS; 
+}
+{
+// Reading arrays from the previously created PPF file aas.ppf
+PInPersist pis("aas.ppf");
+Matrix B,BS;
+pis >> B >> BS;
+// BS is a sub-array of B, modifying BS changes also B
+BS(1,1) = 98765.;
+cout << " B , BS after BS(1,1) = 98765. " 
+     << B << BS << endl; 
+}
+\end{verbatim} 
+The execution of this sample code creates the file {\tt aas.ppf} and 
+its output is reproduced here. Notice that the array hierarch is 
+recovered. BS is a sub-array of B, and modifying BS changes also
+the corresponding element in B.
+\begin{verbatim}
+ B , BS after BS(1,1) = 98765.
+
+--- TMatrix<double>(NRows=3, NCols=4) ND=2 SizeX*Y*...= 4x3 ---
+10 15 20 25
+30 35 40 45
+50 55 60 98765
+
+--- TMatrix<double>(NRows=2, NCols=2) ND=2 SizeX*Y*...= 2x2 ---
+40 45
+60 98765
+\end{verbatim} 
+
+\centerline{\bf Warning: }
+
+There is a drawback in this behaviour: only a single 
+copy of an array is written to a file, even if the array is modified, 
+without being resized and written to a PPF stream. 
+\begin{verbatim}
+{
+POutPersist pos("mca.ppf");
+TArray<int_4> ia(5,3);
+ia = 8;
+pos << ia;
+ia = 16;
+pos << ia;
+ia = 32;
+pos << ia;
+}
+\end{verbatim}
+
+Only a single copy of the data is effectively written to the output 
+PPF file, corresponding to the value 8 for array elements. When we 
+read the three array from the file mca.ppf, the same array elements
+are obtained three times (all elements equal to 8):
+\begin{verbatim}
+{
+PInPersist pis("mca.ppf");
+TArray<int_4> ib;
+pis >> ib;
+cout << " First array read from mca.ppf : " << ib;
+pis >> ib;
+cout << " Second array read from mca.ppf : " << ib;
+pis >> ib;
+cout << " Third array read from mca.ppf : " << ib;
+}
+\end{verbatim}
+
+\subsubsection{ASCII streams} 
+
+The {\bf WriteASCII} method can be used to dump an array to an ASCII 
+formatted file, while the {\bf ReadASCII} method can be used to decode 
+ASCII formatted files. Space or tabs are the possible separators. 
+Complex numbers should be specified as a pair of comma separated 
+real and imaginary parts, enclosed in parenthesis. 
+
+\begin{verbatim}
+{
+// Creating array A and writing it to an ASCII file (aaa.txt)
+Array A(4,6);
+A = RegularSequence(0.5, 0.2);
+ofstream ofs("aaa.txt");
+A.WriteASCII(ofs);
+}
+{
+// Decoding the ASCII file aaa.txt
+ifstream ifs("aaa.txt");
+Array B;
+sa_size_t nr, nc;
+B.ReadASCII(ifs,nr,nc);
+cout << " Array B; B.ReadASCII() from file " << endl;
+cout << B ;
+}
+\end{verbatim}
+
+
+\subsection{Complex arrays}
+The {\bf TArray} module provides few functions for manipulating
+arrays of complex numbers (single and double precision).
+These functions are declared in {\tt matharr.h}.
+\begin{itemize}
+\item[\bul] Creating a complex array through the specification of the 
+real and imaginary parts. 
+\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 present implementation does not provide
+shared memory access to real and imaginary parts.)
+\item[\bul] Functions returning arrays corresponding to the module, 
+phase, and module squared of a complex array:
+ {\tt phase(za) , module(za) , module2(za) } 
+\end{itemize}
+
+\begin{verbatim}
+  TVector<r_4> p_real(10, BaseArray::RowVector);
+  TVector<r_4> p_imag(10, BaseArray::RowVector);
+  p_real = RegularSequence(0., 0.5);
+  p_imag = RegularSequence(0., 0.25);
+  TVector< complex<r_4> > zvec = ComplexArray(p_real, p_imag);
+  cout << " :: zvec= " << zvec;
+  cout << " :: real(zvec) = " << real(zvec) ;
+  cout << " :::: imag(zvec) = " << imag(zvec) ;
+  cout << " :::: module2(zvec) = " << module2(zvec) ;
+  cout << " :::: module(zvec) = " << module(zvec) ;
+  cout << " :::: phase(zvec) = " << phase(zvec) ;
+\end{verbatim}
+
+The decoding of complex numbers from an ASCII formatted stream 
+is illustrated by the next example. As mentionned already, 
+complex numbers should be specified as a pair of comma separated 
+real and imaginary parts, enclosed in parenthesis. 
+
+\begin{verbatim}
+csh> cat zzz.txt
+(1.,-1) (2., 2.5) -3. 12.
+-24. (-6.,7.) 14.2 (8.,64.)
+
+//  Decoding of complex numbers from an ASCII file
+//  Notice that the << operator can be used instead of ReadASCII
+TArray< complex<r_4> > Z;
+ifstream ifs("zzz.txt");
+ifs >> Z;
+cout << " TArray< complex<r_4> > Z from file zzz.txt " << Z ;
+\end{verbatim}
+
 
 \subsection{Memory organisation}
@@ -1205 +1388 @@
 \end{verbatim}
 
+The class {\bf FITS\_AutoReader} provides a limited FITS files reading
+and decoding capabilities. A partial class diagram of FITS persistence 
+handling classes is shown below:
+\begin{figure}[hbt]
+\dclsbb{FitsIOhandler}{FITS\_TArray}
+\dclsb{FITS\_NTuple}
+% \dclsb{FITS\_XNTuple}
+\dclsb{FITS\_SphereHEALPix}
+% \dclsb{FITS\_LocalMap}
+\end{figure}
 
 \newpage