Changeset 3034 in Sophya for trunk/SophyaLib/Manual

Timestamp:

Jul 17, 2006, 7:12:21 PM (19 years ago)

Author:

ansari

Message:

suite documentation SOPHYA overview - section FitsIOServer, Reza 17/7/2006

File:

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

trunk/SophyaLib/Manual/sophya.tex

@@ -49 +49 @@
 \vspace{1cm}
 \begin{center}
-{\bf \Large Sophya Version: 1.966 (V\_Jun2006) }
+{\bf \Large Sophya Version: 2.0 (V\_Jul2006) }
 % Document revision 1.0 }
 \end{center}
@@ -312 +312 @@
 csh> scanppf -h
  PIOPersist::Initialize() Starting Sophya Persistence management service 
-SOPHYA Version  1.9 Revision 0 (V_Mai2005) -- May 31 2005 15:11:32 cxx 
+SOPHYA Version  2.0 Revision 0 (V_Jul2006) -- Jul 17 2006 14:13:27 cxx 
  Usage: scanppf [flags] filename 
- flags = -s -n -a0 -a1 -a2 -a3 -lh -lho 
+ flags = -s -n -a0 -a1 -a2 -a3 -lh -lho -lmod 
    -s[=default} : Sequential reading of objects 
    -n : Object reading at NameTags 
@@ -320 +320 @@
    -lh : List PPersist handler classes 
    -lho : List PPersist handler and dataobj classes 
+   -lmod : List initialized/registered modules 
 \end{verbatim}
 
@@ -406 +407 @@
 \vspace*{5mm}
 
+\subsection{Initialisation}
+\index{SophyaInitiator}
+A number of actions have to be taken before 
+some of the services provided by SOPHYA become operational. This is the case
+of SOPHYA persistence, as well as FITS I/O facilities. 
+Initialisation of many SOPHYA modules is performed through an initialiser class,
+which inherits from {\bf SophyaInitiator}. Static instance of each 
+initialiser class exist in the library and the various SOPHYA services
+should be operational when the user code ({\tt main()}) starts.
+However, in some cases the run time loader may not perform correctly the static 
+object initialisation. You may thus need to instanciate the initialiser class
+for the modules you use in the beginning of your main program: \\
+{\tt TArrayInitiator , HiStatsInitiator , SkyMapInitiator \ldots }
+%%%
 \subsection{SOPHYA persistence}
 \label{ppfdesc}
@@ -778 +793 @@
 \begin{center}
 \begin{tabular}{ll}
+\hline \\
 \multicolumn{2}{c}{ {\bf Range} {\tt (start, end, size, step) } } \\[2mm]
 \hline \\
+{\bf Range} {\tt r(7); } &  index range:  \hspace{2mm} 7 \\
 {\bf Range} {\tt r(3,6); } &  index range:  \hspace{2mm} 3,4,5,6 \\
-{\bf Range} {\tt r(3,6,0,1); } &  index range: \hspace{2mm} 3,4,5,6 \\
+{\bf Range} {\tt r(3,7,2); } &  index range: \hspace{2mm} 3,5,7 \\
 {\bf Range} {\tt r(7,0,3,1); } &  index range: \hspace{2mm} 7,8,9 \\
-{\bf Range} {\tt r(10,0,5,2); } &  index range: \hspace{2mm} 10,12,14,16,18 \\
+{\bf Range} {\tt r(10,0,5,2); } &  index range: \hspace{2mm} 10,12,14,16,18 \\[2mm]
+\hline 
 \end{tabular}
 \end{center}
@@ -1168 +1186 @@
 
 \subsubsection{DataTables}
+\label{datatables}
 \index{DataTable} 
 The class {\bf DataTable} extends significantly the functionalities provided by 
@@ -1204 +1223 @@
 The class {\bf DataTableRow } is an auxiliary class which simplifies the manipulation
 of BaseDataTable object rows. 
-\begin{verbatim}
-   #include "datatable.h"
+The example below show how to create and filling a table, using a PPF stream as 
+swap space. In addition, we have used a {\tt DataTableRow} to prepare data 
+for  each table line.
+\begin{verbatim}
+   #include "swppfdtable.h"
    // ...
-   // Create a table with 3 columns
-   DataTable dtrow(64);
+   {
+   // ---------- Create an output PPF stream (file)
+   POutPersist po("swdtable.ppf");
+   // ------------------
+   // Create a table with 3 columns, using the above stream as swap space
+   SwPPFDataTable dtrow(po, 64);
    dtrow.AddStringColumn("sline");
    dtrow.AddIntegerColumn("line");
-   dtrow.AddDateTimeColumn("datime");
-   
+   dtrow.AddDateTimeColumn("datime");   
+   //
    TimeStamp ts, ts2;  // Initialize current date and time
    string sline;
-   // Create a table row with the required structure
+   //---- Create a table row with the required structure
    DataTableRow row = dtrow.EmptyRow();
-   // Fill the table
-   for(int k = 0; k<25; k++) {
+   // ----- Fill the table
+   for(int k = 0; k<2500; k++) {
      sline = "L-";
      sline += (string)MuTyV(k);
@@ -1227 +1253 @@
      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}
- 
+  //------ Write the table itself to the stream, before closing the file
+  po << PPFNameTag("SwTable") << dtrow;
+  }
+\end{verbatim}
+%%
+The  previously created table can easily be read in, as shown below:
+%%
+\begin{verbatim}
+   #include "swppfdtable.h"
+   // ...
+   {
+   // ------ Create the input  PPF stream (file)
+   PInPersist pin("swdtable.ppf");
+   // ------ Read in the SwPPFDataTable object 
+   SwPPFDataTable dtr;
+   pin >> PPFNameTag("SwTable") >> dtr;
+   // ---- Create a table row with the required structure
+   DataTableRow row = dtr.EmptyRow();
+   // ---- Acces and print two of the table rows :
+   cout << dtr.GetRow(6, row) << endl;
+   cout << dtr.GetRow(17, row) << endl;   
+  }
+\end{verbatim}
+   
 \subsection{Writing, viewing \dots }
 
@@ -1698 +1743 @@
 \newpage
 \section{Module FitsIOServer}
+\subsection{FITS streams}
 \index{FITS} \index{FitsInFile} \index{FitsOutFile}
 This module provides classes for handling file input-output in FITS format using the cfitsio library. Its
@@ -1724 +1770 @@
 \end{figure}
 %%%%
-\par
+\subsection{FITS handlers}
 Handlers classes inheriting from {\bf FitsHandlerInterface} perform write/read operations
 for AnyDataObj objects to/from FitsInOutFile streams. The {\bf FitsManager} class provides
@@ -1736 +1782 @@
 {\bf \tcls{FitsArrayHandler}}  and {\bf FitsHandler$<$BaseDataTable$>$}.  \\
 A number of more specific handlers are also available, in particular for NTuple,
-\tcls{SphereHealPix} and \tcls{SphereThetaPhi}. 
+\tcls{SphereHealPix} and \tcls{SphereThetaPhi}.  \\[2mm]
+{\bf Warning:} Some handlers were written with the old FitsIOServer classes and 
+inherit from the intermediate class {\bf FitsIOHandler}. They  
+have been adapted to the new scheme, but may not perform correctly if not used 
+through the {\bf FitsManager} class. \\[2mm] 
 %%%
-The example below illustrates the usage of FitsIOServer classes.
+The examples below illustrates the usage of FitsIOServer classes.
 \begin{enumerate}
 \item Saving an array and a HealPix map to a Fits file
 \begin{verbatim}
 #include "fitsioserver.h"
+#include "fiosinit.h"
+
 // ....
 {
-// Initialize the FitsIOServer module :
+// Make sure FitsIOServer module is initialised :
 FitsIOServerInit();
 //  Create and open a fits file named myfile.fits
@@ -1759 +1811 @@
 }
 \end{verbatim}
+%%%%
+%%%%
+\item Reading objects and the header from the previously created fits file:
+\begin{verbatim}
+{
+FitsIOServerInit();   //  Initialisation 
+// ----  Open the fits file named myfile.fits
+FitsInFile fis("myfile.fits");
+//---- print file information on cout
+cout << fis << endl;
+//--- Read in the array 
+TArray<int_4> arr; 
+fis >> arr;
+arr.Show();
+//--- Position on second HDU 
+fis.MoveAbsToHDU(2);
+//--- read and display header information
+DVList hdu2;
+fis.GetHeaderRecords(hdu2, true, true);
+cout << hdu2;
+//--- read in the HEALPix map 
+SphereHEALPix<r_8> sph;
+FitsManager::Read(fis, sph);
+fis.MoveAbsToHDU(2);
+sph.Show();
+}
+\end{verbatim}
+%%%%%%%
+%%% 
+\item DataTable objects can be read from and written to FITS files as ASCII or
+binary tables. The example belo show reading the DataTable created in the example
+in section \ref{datatables} from a PPF file and saving it to a fits file;
+\begin{verbatim}
+{
+FitsIOServerInit();   //  Initialisation 
+FitsInOutFile fos("dtable.fits", FitsInOutFile ::Fits_Create);
+}
+\end{verbatim}
+%%%%
 \end{enumerate}
 
-
-\begin{verbatim}
-#include "spherehealpix.h"   
-#include "fitsspherehealpix.h" 
-#include "fitstarray.h" 
-#include "tmatrix.h" 
-//...........................
-
-int m=...;
-SphereHEALPix<r_8> sph(m);
-................
-int dim1=...;
-int dim2=...;
-TMatrix<r_8> mat(dim1,dim2);
-............
-
-FITS_SphereHEALPix<r_8> sph_temp(sph);
-FITS_TArray<r_8> mat_temp(mat);
-// writing
-
-FitsOutFile os("myfile.fits");
-sph_temp.Write(os);
-mat_temp.Write(os);
-
-// reading
-FitsInFile is("myfile.fits");
-sph_temp.Read(is);
-mat_temp.Read(is);
-SphereHEALPix<r_8> new_sph=(SphereHEALPix<r_8>)sph_temp;
-TMatrix<r_8> new_mat=(TMatrix<r_8>)mat_temp;
-................ 
-      
-\end{verbatim}
-
-The operators {\tt operator << (FitsOutFile ...)} and 
-{\tt operator >> (FitsInFile ...)} are defined in order 
-to facilitate the FITS file operations:
-\begin{verbatim}
-// Writing an array object to a FITS file
-#include "fitstarray.h" 
-FitsOutFile fio("arr.fits");
-Matrix m(20,30);
-m = 12345.;
-fio << m;
-// .....
-// Reading a binary table to a XNTuple
-#include "fitsxntuple.h" 
-XNTuple xn;
-FitsInFile fii("table.fits");
-fii >> xn;
-\end{verbatim}
 
 A partial class diagram of FITS persistence handling classes is shown below. The 
@@ -1823 +1863 @@
 % \dclsb{FITS\_LocalMap}
 \end{figure}
+
+\subsection{SwFitsDataTable and other classes}
+
+\subsection{scanfits}
 
 \newpage