Changeset 3037 in Sophya for trunk/SophyaLib/Manual

Timestamp:

Jul 18, 2006, 12:28:30 PM (19 years ago)

Author:

ansari

Message:

doc SophyaOverview complete en vue du tag V2 , Reza 18/7/2006

File:

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

trunk/SophyaLib/Manual/sophya.tex

@@ -162 +162 @@
 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). 
+\item[] {\bf MinuitAdapt/} Wrapper classes to CERN minimization routines (Minuit).  \\
+\href{http://wwwinfo.cern.ch/asdoc/minuit/minmain.html}{http://wwwinfo.cern.ch/asdoc/minuit/minmain.html}
 
 \end{itemize}
@@ -270 +271 @@
 
 \subsection{the runcxx program}
-\index{runcxx}
+\index{runcxx} \label{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
@@ -306 +307 @@
 
 \subsection{the scanppf program}
+\index{scanppf} \label{scanppf}
 {\bf scanppf} is a simple SOPHYA application which can be used to check 
 PPF files and list their contents. It can also provide the list of all registered
@@ -323 +325 @@
 \end{verbatim}
 
-\subsection{the scanppf program}
+\subsection{the scanfits program}
+\index{scanfits} \label{scanfits}
 {\bf scanfits} is a SOPHYA program using the FitsIOServer 
 \footnote{FitsIOServer module uses the cfitsio library. scanfits has to be linked with
@@ -333 +336 @@
 \begin{verbatim}
 csh> scanfits -h
- SophyaInitiator::SophyaInitiator() BaseTools Init
  PIOPersist::Initialize() Starting Sophya Persistence management service 
-SOPHYA Version  1.9 Revision 33 (V_Mar2006) -- Apr  3 2006 14:04:07 gcc 3.3 20030304 (Apple Computer, Inc. build 1495)
+SOPHYA Version  2.0 Revision 0 (V_Jul2006) -- Jul 17 2006 14:13:27 cxx 
  Usage: scanfits [flags] filename 
  flags = -V1 -lh -rd -header 
@@ -582 +584 @@
 
 \subsection{\tcls{SegDataBlock} , \tcls{SwSegDataBlock}}
+\index{\tcls{SegDataBlock}}  \index{\tcls{SwSegDataBlock}}
+%%
 \begin{figure}[hbt]
 \dclsccc{AnyDataObj}{\tcls{SegDBInterface}}{ \tcls{SegDataBlock} }
@@ -705 +709 @@
 \end{verbatim} 
 
+\subsection{Arithmetic operations}
+The four usual arithmetic operators ({\bf  + \, - \, * \, / }) are defined
+to perform constant addition, subtraction, multiplication and division. 
+The three operators ({\bf  + \, - \, / }) between two arrays of the same type
+are defined to perform element by element addition, subtraction
+and division. In order to avoid confusion with matrix multiplication, 
+element by element multiplication is defined by overloading the
+operator {\bf \, \&\& \, }, as shown in the example below:
+\begin{verbatim}
+TArray<int_4> a(4,3), b(4,3), c , d, e;
+a = RegularSequence(1.,1.);
+b = RegularSequence(10.,10.);
+cout << a << b ;
+c = a && b; 
+d = c / a;
+e = (c / b) - a;
+cout << c << d << e;
+\end{verbatim}
+
 \subsection{Matrices and vectors}
 \index{\tcls{TMatrix}}  \index{\tcls{TVector}}
@@ -849 +872 @@
 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 
+{\bf FitsIOServer} module. Only 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
@@ -1197 +1220 @@
    #include "datatable.h"
    // ...
+   {
    DataTable dt(64);
    dt.AddFloatColumn("X0_f");
@@ -1211 +1235 @@
    POutPersist po("dtable.ppf");
    po << dt ;
-
+   }
 \end{verbatim}
 
@@ -1503 +1527 @@
 \subsection{Resource usage (CPU, memory \ldots) }
  The class {\bf ResourceUsage} \index{ResourceUsage}
-and {\bf Timer} {\index{Timer} provides access to information 
+and {\bf Timer} \index{Timer} provides access to information 
 about various resource usage (memory, CPU, ...).
-The class {\bf Timer} {\index{time (CPU, elapsed)} and c-functions
+The class {\bf Timer} \index{time (CPU, elapsed)} and c-functions
 {\tt InitTim() , PrtTim(const char * Comm) } can be used to print 
 the amount of CPU and elapsed time in programs.
@@ -1521 +1545 @@
 
 \subsection{Thread management classes}
-A basic interface to POSIX threads \index{thread} is also provided
+\index{ZThread} \index{ZMutex} 
+A basic interface to POSIX threads is also provided
 through the \index{threads} {\bf ZThread}, {\bf ZMutex} and {\bf ZSync}
 classes. The best way to use thread management classes is by inheriting
@@ -1708 +1733 @@
 
 \subsection{Module SkyT}
-\index{RadSpectra} \index{SpectralResponse} \index
+\index{RadSpectra} \index{SpectralResponse} 
 The SkyT module is composed of two types of classes:
 \begin{itemize}
@@ -1743 +1768 @@
 \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
+This module provides classes for handling file input-output in FITS 
+\footnote{http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html} 
+format using the cfitsio library. Its
 design is similar to  the SOPHYA persistence (see Module BaseTools). 
 Delegate classes or handlers perform the actual read/write from/to fits files. 
+\par
 Compared to the SOPHYA native persistence (PPF format),
 FITS format has the advantage of being used extensively, and handled 
@@ -1755 +1781 @@
 many SOPHYA objects can be saved in FITS files, FITS persistence has 
 some limitations. For example, FITS does not currently handle complex arrays.
-\par
+\subsection{FITS streams}
+\index{FITS} \index{FitsInOutFile} 
+%%
 The class {\bf FitsInOutFile} can be seen as a wrapper class for the cfitsio library functions.  
 This class has been introduced in 2005 (V=1.9), when the module has been 
 extensively  changed. In order to keep backward compatibility, the old fits wrapper 
-classes ({\bf  FitsFile, FitsInFile, FitsOutFile} has been changed to inherit from
+classes ({\bf  FitsFile, FitsInFile, FitsOutFile}) has been changed to inherit from
  {\bf FitsInOutFile}.  The use of class FitsFile and specific services of these old classes 
  should  be avoided, but FitsInFile, FitsOutFile can be safely considered a specialisation
  of FitsInOutFile for read/input and write/output operations respectively.
+ Most c-fitsio errors are converted to an exception: {\bf FitsIOException}.
+ \par
+ File names are passed to cfitsio library. It is thus possible to use cfitsio file name conventions,
+ such as {\bf ! } as the first character, for overwriting existing files (when creating files).
  The diagram below shows the class hierarchy for cfitsio wrapper classes.
 \begin{figure}[hbt]
@@ -1771 +1803 @@
 %%%%
 \subsection{FITS handlers}
+\index{FitsManager}
 Handlers classes inheriting from {\bf FitsHandlerInterface} perform write/read operations
 for AnyDataObj objects to/from FitsInOutFile streams. The {\bf FitsManager} class provides
 top level services for object read/write in FITS files. 
-In most cases, \\
-{\tt FitsInOutFile\& $<<$ } and  {\tt FitsInOutFile\& $>>$ } or  \\
- {\tt FitsOutFile\& $<<$ } and  {\tt FitsInFile\& $>>$ }  \\
- operators can be used 
-write and read objects.  The two main types of fits data structures, images and tables 
+\par  In most cases, 
+\hspace{5mm} {\tt FitsInOutFile\& $<<$ } \, and \,  {\tt FitsInOutFile\& $>>$ } \hspace{5mm}
+operators can be used to write and read objects.  
+\par
+The two main types of fits data structures, images and tables 
 {\tt (IMAGE\_HDU , BINARY\_TBL , ASCII\_TBL)} are handled by the generic handlers: \\
-{\bf \tcls{FitsArrayHandler}}  and {\bf FitsHandler$<$BaseDataTable$>$}.  \\
+{\bf \tcls{FitsArrayHandler}}  and {\bf FitsHandler$<$BaseDataTable$>$}.  
+\par
 A number of more specific handlers are also available, in particular for NTuple,
 \tcls{SphereHealPix} and \tcls{SphereThetaPhi}.  \\[2mm]
@@ -1788 +1822 @@
 through the {\bf FitsManager} class. \\[2mm] 
 %%%
-The examples below illustrates the usage of FitsIOServer classes.
+The examples below illustrates the usage of FitsIOServer classes. They can be compiled
+and executed using runcxx, without the {\tt include} lines: \\[1mm]
+\hspace*{5mm} {\tt csh> runcxx -import SkyMap -import FitsIOServer -inc fiosinit.h } 
+%%%
 \begin{enumerate}
 \item Saving an array and a HealPix map to a Fits file
@@ -1794 +1831 @@
 #include "fitsioserver.h"
 #include "fiosinit.h"
-
 // ....
 {
@@ -1809 +1845 @@
 sph = 48.3;
 FitsManager::Write(fos, sph);
+// --- The << operator could have been used instead :    fos << sph;
 }
 \end{verbatim}
@@ -1834 +1871 @@
 SphereHEALPix<r_8> sph;
 FitsManager::Read(fis, sph);
-fis.MoveAbsToHDU(2);
+// --- The >> operator could have been used instead :    fis >> sph;
 sph.Show();
 }
@@ -1842 +1879 @@
 \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}
+in section \ref{datatables} from a PPF file and saving it to a fits file.
+\begin{verbatim}
+#include "swfitsdtable.h"
+// ....
 {
-FitsIOServerInit();   //  Initialisation 
-FitsInOutFile fos("dtable.fits", FitsInOutFile ::Fits_Create);
+FitsIOServerInit();   //  FitsIOServer Initialisation 
+//--- Reading in DataTable object from PPF file
+PInPersist pin("dtable.ppf");
+DataTable dt;
+pin >> dt;
+dt.Show(); 
+//--- Saving table to FITS
+FitsInOutFile fos("!dtable.fits", FitsInOutFile ::Fits_Create);
+fos << dt;
 }
 \end{verbatim}
 %%%%
 \end{enumerate}
-
-
+%%%
 A partial class diagram of FITS persistence handling classes is shown below. The 
 class {\tt FitsIOhandler} conforms to the old FitsIOServer module design and 
@@ -1865 +1910 @@
 
 \subsection{SwFitsDataTable and other classes}
-
-\subsection{scanfits}
-
+\index{SwFitsDataTable} 
+The {\bf SwFitsDataTable} class implements the BaseDataTable interface
+using a FITS file as swap space. Compared to SwPPFDataTable, they can be 
+used in R/W mode (reading from the table, when it is being created / filled).
+They can be used in a way similar to DataTable and SwPPFDataTable. 
+When creating the table, a {\tt FitsInOutFile } stream, opened for writing has
+to be passed to the creator. No further operation is needed. 
+\begin{verbatim}
+// ....
+FitsInOutFile so("!myswtable.fits", FitsInOutFile::Fits_Create);
+SwFitsDataTable dt(so, 16);
+// define table columns
+dt.AddIntegerColumn("X0_i");
+dt.AddFloatColumn("X1_f");
+// ... Fill the table
+r_8 x[5];
+for(int i=0; i<63; i++) {
+    x[0] = (i%9)-4.;  x[1] = (i/9)-3.;  
+    dt.AddLine(x);
+}
+\end{verbatim}
+The class {\bf FitsBTNtuIntf } provide an alternative tool to read FITS tables. 
+{\bf FitsABTColRd} , {\bf FitsABTWriter } and {\bf FitsImg2DWriter } can also 
+be used to manipulate FITS files.
+\par 
+The {\bf scanfits} program can be used to check FITS files and analyse their
+content (See \ref{scanfits}).
+
+%%%%   
 \newpage
 \section{LinAlg and IFFTW modules}
@@ -1931 +2002 @@
 {\bf FitsIOServer} is the example of such a module, where the {\tt libcfitsio.a}
 is used.
-par
+\par
 The object files from a given Sophya module are grouped in an archive library 
 with the module's name ({\tt libmodulename.a}). All Sophya modules 
@@ -1940 +2011 @@
 Alternatively, it is possible to group all modules in a single shared 
 library {\tt libAsophyaextPI.so}.
+\par 
+Each library module has a {\tt Makefile} which compiles the source files
+and build the correspond static (archive) library using the compilation
+rules and flags defined in {\tt \$SOPHYABASE/include/sophyamake.inc}.
+Each program module has a {\tt Makefile} which compiles and link the 
+corresponding programs using the compilation rules and libraries
+defined in {\$SOPHYABASE/include/sophyamake.inc}. 
+The top level Makefile in BuildMgr/ compiles each library modules
+and builds shared libraries. 
+\par 
+The series of Makefiles use the link to {\tt sophyamake.inc} in BuildMgr.
+There are also the {\tt smakefile} series which uses the explicit path, using
+{\tt \$SOPHYABASE} environment variable.
 
 \subsection{Installation} 
@@ -2050 +2134 @@
 \end{verbatim}
 
-\subsection{Platform specific notes }
+If no further modification or update of source files is foreseen, it is possible 
+to remove all .o files:
+\begin{verbatim}
+#  To clean $SOPHYABASE/obj directory :
+csh> make cleanobj
+\end{verbatim}
+
+
+\subsection{Notes}
 \begin{itemize}
+\item[{\bf Makefile}] List of top level Makefile build targets 
+\begin{verbatim}
+> libs extlibs PI = all 
+> slb slbext slbpi = slball    (OR = slballinone)
+> clean  cleanobj
+> tests prgutil prgmap progpi = prgall 
+> basetests piapp (ou progpi)  pmixer 
+\end{verbatim}
+\item[{\bf MacOS X}] A high performance mathematic and signal processing
+library, including LAPACK and BLAS is packaged in Darwin/MacOS X (10.3, 10.4) : \\
+\hspace*{5mm} {\bf -framework Accelerate}
+\item[{\bf Tru64/OSF}] An optimised math library with LAPACK and BLAS might 
+optionaly be installed {\bf (-lcxlm) }. On our system, this libray contained Lapack V2.
+So we used the LAPACK, as compiled from the public sources, and linked with 
+the Tru64 native BLAS.
+\item[{\bf  IRIX64}] We used the math library with LAPACK V2 and BLAS 
+from SGI : {\bf -lcomplib.sgimath}
 \item[{\bf AIX}] There seem to be a problem on AIX when several shared 
 libraries are used. We have been able to run SOPHYA programs either 
 using static libraries, or a single shared library (libAsophyaextPI.so) 
 if extlibs and PI are needed, in addition to stand alone SOPHYA modules.
+It has not been possible to link SOPHYA with fortran libraries
+\item[{\bf Mgr}] This module contains makefiles and build scripts
+that were used in SOPHYA up to version 1.7 (2004) : OBSOLETE.
 \end{itemize}
 
@@ -2077 +2189 @@
 \end{itemize}
 
-\noindent {\large \bf NOTE}  \hspace{5mm} 
-The {\bf Mgr} module contains makefiles and build scripts
-whih were used in SOPHYA up to version 1.7 (2004).
-It should not be used anymore.