Changeset 3015 in Sophya for trunk/SophyaLib

Timestamp:

Jul 17, 2006, 10:33:09 AM (19 years ago)

Author:

ansari

Message:

Suite preparation documentation SOPHYA pour V2.0 , Reza 17/07/2006

File:

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

trunk/SophyaLib/Manual/sophya.tex

@@ -1 @@
-\documentclass[twoside,11pt]{article}
+\documentclass[twoside,10pt]{article}
 %  Package standard : Utilisation de caracteres accentues, mode francais et graphique
 \usepackage{url}
@@ -215 +215 @@
 
 \subsection{Directories, environment variables, configuration files}
+\label{directories}
 The environment variable {\bf SOPHYABASE}  is used 
 to define the path where the Sophya libraries and binaries are installed.
@@ -220 +221 @@
 \item \$SOPHYABASE/include : Include (.h) files
 \item \$SOPHYABASE/lib : Path for the archive libraries (.a)
-\item \$SOPHYABASE/slb: Shared library path (.so)
+\item \$SOPHYABASE/slb: Shared library path (.so or .dylib on Darwin/MacOS)
 \item \$SOPHYABASE/exe : Path for binary program files
 \end{itemize}
 
-In order to use the shared libraries, the {\bf LD\_LIBRARY\_PATH} variable
-should contain the Sophya shared library path 
-({\tt \$SOPHYABASE/slb }). 
-On Silicon Graphics machines with IRIX64 operating system, 
-the default SOPHYA configuration correspond to the 64 bit architecture. 
-The environment variable { \bf LD\_LIBRARY64\_PATH } defines
-the shared library path in this case and should contain ({\tt \$SOPHYABASE/slb }.
-On IBM machines with AIX, the {\bf LIBPATH} environment variables 
-contains the shared libraries serach path.
-
-When using the dynamic load services in SOPHYA ({\tt PDynLinkMgr}
-class), in runcxx or (s)piapp applications for example, the shared 
-library search path must contain the current working directory (
-dot . in unix).
-
-The configure script creates links for external libraries include files in : 
-\begin{itemize}
-\item \$SOPHYABASE/include/FitsIO : c-fitsio library include files
-\item \$SOPHYABASE/include/FFTW : FFTW library include files
-\item \$SOPHYABASE/include/XAstro : XEphem library include files
-\end{itemize}
-
 The directory { \tt \$SOPHYABASE/include/SophyaConfInfo/ } contains files
 describing the installed configuration of SOPHYA software.
 
 The file { \tt \$SOPHYABASE/include/machdefs.h } contains definitions
-(flags, typedef) used in SOPHYA. 
+(flags, typedef) used in SOPHYA, while some more specific flags,
+are found in  { \tt \$SOPHYABASE/include/sspvflags.h }  
 
 The file { \tt \$SOPHYABASE/include/sophyamake.inc } contains the 
@@ -259 +239 @@
 
 The configure script (BuildMgr/configure) creates the directory tree and the
-above files.
+above files. It also copy (or create symbolic link) for all SOPHYA include 
+files as well as symbolic links for external libraries 
+include files path in {\tt \$SOPHYABASE/include} (FitsIO, FFTW, XAstro \ldots). 
+
+Object files for each module are grouped in a static archive library 
+by the build procedure (libXXX.a for module
+XXX, with XXX = BaseTools, TArray, HiStats,  FitsIOServer  \ldots).
+
+When shared libraries are build, all stand alone SOPHYA modules
+are grouped in  {\tt libsophya.so},  {\tt libextsophya.so} contains 
+the interface modules with external libraries {\bf (FitsIOServer, LinAlg \ldots)},
+while {\bf PI, PIext, PIGcont} modules  are grouped in  {\tt libPI.so}.
+Alternatively, it is possible to group all modules in a single shared 
+library {\tt libAsophyaextPI.so} (See \ref{build})
+
+In order to use the shared libraries, the {\bf LD\_LIBRARY\_PATH} variable
+should contain the Sophya shared library path 
+({\tt \$SOPHYABASE/slb}). 
+On Silicon Graphics machines with IRIX64 operating system, 
+the default SOPHYA configuration correspond to the 64 bit architecture. 
+The environment variable { \bf LD\_LIBRARY64\_PATH } replace in
+this case the usual {\bf LD\_LIBRARY\_PATH} variable.
+On IBM machines with AIX, the {\bf LIBPATH} environment variables 
+contains the shared libraries search path.
+
+When using the dynamic load services in SOPHYA ({\tt PDynLinkMgr}
+class), in runcxx or (s)piapp applications for example, the shared 
+library search path must contain the current working directory (
+dot . in unix).
 
 \subsection{the runcxx program}
@@ -1444 +1452 @@
 \section{Module SysTools}
 The {\bf SysTools} module contains classes implementing interface to some 
-OS specific services. The class {\bf ResourceUsage} \index{ResourceUsage}
+OS specific services, such as thread creation and management, dynamic loading and 
+resource usage information. For example, yhe class {\bf Periodic} provides the 
+necessary services needed to implement the execution of a periodic action.
+
+\subsection{Resource usage (CPU, memory \ldots) }
+ The class {\bf ResourceUsage} \index{ResourceUsage}
 and {\bf Timer} {\index{Timer} provides access to information 
 about various resource usage (memory, CPU, ...).
-The class {\bf Periodic} provides the necessary services needed to 
-implement the execution of a periodic action.
+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.
+
+The following sample code illustrates the use of {\bf ResourceUsage} :
+\begin{verbatim}
+  // How to check resource usage for a given part of the program
+  ResourceUsage res;
+  // --- Part of the program to be checked : Start
+  // ...
+  res.Update();
+  cout << " Memory size increase (KB):" << res.getDeltaMemorySize() << endl;
+  cout << " Resource usage info : \n" << res << endl;
+\end{verbatim}
 
 \subsection{Thread management classes}
 A basic interface to POSIX threads \index{thread} is also provided
-through the \index{ZThread} {\bf ZThread}, {\bf ZMutex} and {\bf ZSync}
-classes.
+through the \index{threads} {\bf ZThread}, {\bf ZMutex} and {\bf ZSync}
+classes. The best way to use thread management classes is by inheriting
+from {\bf ZThread} and redefining the {\tt run() } method. 
+It is also possible to use the default {\tt run() } implementation and associate 
+a function to perform the action, as in the example below :
+\begin{verbatim}
+  // The functions to perform computing
+  void fun1(void *arg) { }
+  void fun2(void *arg) { }
+  // ...
+  ZThread zt1;
+  zt1.setAction(fun1, arg[1]);
+  ZThread zt2;
+  zt2.setAction(fun2, arg[1]);
+  cout << " Starting threads ... " << endl;
+  zt1.start();
+  zt2.start();
+  cout << " Waiting for threads to end ... " << endl;  
+  zt1.join();
+  zt2.join();
+\end{verbatim}
+The classes {\bf ZMutex} \index{mutex} and {\bf ZSync} can be used 
+to perform synchronisation and signaling between threads.
  
 \subsection{Dynamic linker and C++ compiler classes}
@@ -1499 +1545 @@
 Arithmetic expression evaluation is implemented through the {\bf CExpressionEvaluator}
 and {\bf RPNExpressionEvaluator} classes. 
+The command language provides variable manipulation through the usual 
+{\tt \$varname} vector variable and arithmetic expression extensions, as well 
+as the control and test blocs. 
+\begin{verbatim}
+#include "commander.h"
+...
+Commander cmd;
+char* ss[3] = {"foreach f ( AA bbb CCCC ddddd )", "echo $f" , "end"};
+for(int k=0; k<3; k++) {
+  string line = ss[k];
+  cmd.Interpret(line);
+}
+\end{verbatim}
  
 \newpage
@@ -1576 +1635 @@
 
 \newpage
-\section{Module Samba}
+\section{Samba and SkyT}
+\subsection{Samba}
 \index{Spherical Harmonics}
 \index{SphericalTransformServer}
@@ -1602 +1662 @@
 \end{verbatim}
 
-\newpage
-\section{Module SkyT}
-\index{RadSpectra} \index{SpectralResponse}
+\subsection{Module SkyT}
+\index{RadSpectra} \index{SpectralResponse} \index
 The SkyT module is composed of two types of classes:
 \begin{itemize}
@@ -1639 +1698 @@
 \newpage
 \section{Module FitsIOServer}
+\index{FITS} \index{FitsInFile} \index{FitsOutFile}
+This module provides classes for handling file input-output in FITS 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. 
+Compared to the SOPHYA native persistence (PPF format),
+FITS format has the advantage of being used extensively, and handled 
+by a many different software tools. It is a de facto standard in 
+astronomy and astrophysics. 
+However, FITS lacks some of the features present in SOPHYA PPF, and although 
+many SOPHYA objects can be saved in FITS files, FITS persistence has 
+some limitations. For example, FITS does not currently handle complex arrays.
+\par
+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
+ {\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.
+ The diagram below shows the class hierarchy for cfitsio wrapper classes.
 \begin{figure}[hbt]
-\dclsbb{FitsFile}{FitsInFile}
-\dclsb{FitsOutFile}
+\dclsa{FitsInOutFile}
+\dclscc{FitsFile}{FitsInFile}
+\dclscc{FitsFile}{FitsOutFile}
 \end{figure}
-\index{FITS} \index{FitsInFile} \index{FitsOutFile}
-This module provides classes for handling file input-output in FITS format using the cfitsio library. It works like the SOPHYA persistence (see Module SysTools), using delegate objects, but its design is simpler. The following example  writes a matrix (see module TArray) and a spherical map (see module SkyMap)  on a FITS file and reads back from FITS file and creates new objects :
+%%%%
+\par
+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 
+{\tt (IMAGE\_HDU , BINARY\_TBL , ASCII\_TBL)} are handled by the generic handlers: \\
+{\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}. 
+%%%
+The example below illustrates the usage of FitsIOServer classes.
+\begin{enumerate}
+\item Saving an array and a HealPix map to a Fits file
+\begin{verbatim}
+#include "fitsarrhand.h"
+#include "fitsspherehealpix.h" 
+#include "fitsmanager.h" 
+#include "fiosinit.h" 
+// ....
+{
+// Initialize the FitsIOServer module :
+FitsIOServerInit();
+//  Create and open a fits file named myfile.fits
+FitsInOutFile fos("myfile.fits", FitsInOutFile ::Fits_Create);
+// Create and save a 15x11 matrix of integers
+TMatrix<int_4> mxi(15, 11);
+mxi = RegularSequence(10.,10.);
+fos << mxi;
+// Save a HEALPix spherical map using FitsManager services 
+SphereHEALPix<r_8> sph(16);
+sph = 48.3;
+FitsManager::Write(fos, sph);
+}
+\end{verbatim}
+\end{enumerate}
+
+
 \begin{verbatim}
 #include "spherehealpix.h"   
@@ -1696 +1816 @@
 \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:
+A partial class diagram of FITS persistence handling classes is shown below. The 
+class {\tt FitsIOhandler} conforms to the old FitsIOServer module design and 
+should not be used anymore. 
 \begin{figure}[hbt]
-\dclsbb{FitsIOhandler}{FITS\_TArray}
-\dclsb{FITS\_NTuple}
-% \dclsb{FITS\_XNTuple}
-\dclsb{FITS\_SphereHEALPix}
+\dclsbb{FitsHandlerInterface}{FitsArrayHandler$<$T$>$}
+\dclsb{\tcls{FitsHandler}}
+\dclscc{FitsIOhandler}{FITS\_NTuple}
+\dclsc{FITS\_SphereHEALPix}
 % \dclsb{FITS\_LocalMap}
 \end{figure}
@@ -1757 +1877 @@
 OS & compiler \\
 \hline
-HP/Compaq/DEC Tru64 ( OSF1)  &     cxx  (6.1 , 6.3)  \\
 Linux (RH)          &     g++  (3.2)  \\
 Linux  (SCL)          &     icc  (8.1)   (Intel compiler) \\
+MacOSX/Darwin 10.3  &         g++ 3.3  \\
+HP/Compaq/DEC Tru64 ( OSF1)  &     cxx  (6.1 , 6.3)  \\
 SGI IRIX64       &     CC   (7.3)   \\
-MacOSX/Darwin 10.3  &         g++ 3.3  \\
+IBM AIX       &     xlC   (7.x)   \\
 \hline
 \end{tabular}
@@ -1776 +1897 @@
 ({\tt libextsophya.so}). The {\bf PI} and {\bf PIext} modules are 
 grouped in ({\tt libPI.so}).
+Alternatively, it is possible to group all modules in a single shared 
+library {\tt libAsophyaextPI.so}.
 
 \subsection{Installation} 
-
-The build procedure has two main steps: \\
-- The configure step (BuildMgr/configure) setup the directory structure and
-the necessary configuration file. \\
-- The make step compiles the different sources files, create the library and optionaly
+\label{build}
+The build procedure has two main steps: 
+\begin{enumerate}
+\item The configure step (BuildMgr/configure) setup the directory structure and
+the necessary configuration file. Refer to section \ref{directories} for 
+the description of SOPHYA directory tree and files.
+\item The make step compiles the different sources files, create the library and optionaly
 builds all or some of the associated executables. 
-
-\par
+\end{enumerate}
+
 {\tt BuildMgr/configure } is a c-shell script with a number of arguments:
 \begin{verbatim}
@@ -1795 +1920 @@
   [-noextlib -noext fits -noext fftw -noext lapack ]
   [-noext astro -noext minuit]
+  [-usefftw2 -uselapack2] [-singleslb]
 \end{verbatim}
 \begin{itemize}
@@ -1813 +1939 @@
 \item[] -noext : Disable compiling of the specified module (with reference to external
 library. 
+\item[] -usefftw2: FFTW V2 is being used (default FFTW V3) - A compilation flag 
+will be defined in sspvflags.h 
+\item[] -uselapack2: Lapack V2 is being used (defaulr V3) - A compilation flag 
+will be defined in sspvflags.h 
+\item[] -singleslb: A single shared library for all SOPHYA, PI and external library interface
+modules will be build. A compilation flag 
+will be defined in sspvflags.h . `See also target {\tt slballinone} below. 
 \end{itemize}
 
@@ -1829 +1962 @@
 csh> ./configure -sbase /usr/local/Sophya -scxx g++  -extp /usr/local/ExtLibs/ \
 -noext astro -noext minuit 
-# Step 1.b : Check the generated file  $SOPHYABASE/include/
+# Step 1.b : Check the generated file  $SOPHYABASE/include/sophyamake.inc
+csh> ls -lt *.inc 
+csh> more sophyamake.inc 
+\end{verbatim}
+If necessary, edit the generated file {\tt sophyamake.inc } in order to modify 
+compilation flags, library list. The file is rather short and self documented.
+\begin{verbatim}
 # Step 2.a: Compile the modules without external library reference
 csh> make libs
@@ -1845 +1984 @@
 
 To compile all modules and build the shared libraries, it is possible 
-to use:
+to perform the steps 2.a to 2.f using the targets {\tt all} and {\tt slball} 
+defined  in the Makefile
 \begin{verbatim}
 # Step 2.a ... 2.f
-csh> make all slball 
+csh> make all slball
+\end{verbatim}
+
+It is also possible to group all modules in a single shared library using 
+the target {\tt slballinone}. 
+\begin{verbatim}
+# Step 2.a ... 2.f
+csh> make all slballinone
 \end{verbatim}
 
@@ -1854 +2001 @@
 Sophya libraries can now be built:
 \begin{verbatim}
-# To compile test programs
-csh> cd ../PrgUtil
-csh> make 
+# To compile some of the test programs
+csh> make basetests
+# To compile runcxx , scanppf , scanfits 
+csh> make prgutil
 # To build (s)piapp (libPI.so is needed)
-csh> cd ../ProgPI
-csh> make 
-csh> cd ..
-\end{verbatim}
-
-\subsection{Mgr module}
-This module contains scripts which can be used for generating the 
-makefiles for each module.
+csh> make piapp 
+\end{verbatim}
+
+\subsection{Platform specific notes }
 \begin{itemize}
-\item {\bf Makefile} Top level Makefile for building the libraries.
-\item {\bf Makefile.h} contains the definition of compilation flags for the 
-different compilers and systems. This file is used for building the 
-library and generating {\bf MakefileUser.h} (to be included in makefiles).
-\item {\bf Makefile.slb} contains the rules for building shared libraries
-for the different compilers and systems. (to be included in makefiles)
-\item {\bf crerep\_sophya} c-shell script for creating the directory tree
-under {\tt \$SOPHYABASEREP} and {\tt \$SOPHYADEVREP}
-\item {\bf install\_sophya} c-shell script for installing the Sophya package.
-Usually from {\tt \$SOPHYADEVREP} to {\tt \$SOPHYABASEREP}
-\item {\bf mkmflien} c-shell script for making symbolic links or copying
-include files to {\tt \$SOPHYADEVREP/Include} or {\tt \$SOPHYABASEREP/Include}
-\item {\bf mkmf} c-shell script for generating module makefiles and the 
-top level makefile (named GNUmakefile)
-\item {\bf mkmflib} c-shell script for generating each library module 
-makefile (named GNUmakefile)
-\item {\bf mkmfprog} c-shell script for generating makefile for a module
-containing the source for executable programs (named GNUmakefile).
-\item {\bf mkmfPI} c-shell script for generating makefile for PI and PIext
-modules (named GNUmakefile)
-\item {\bf libdirs} List of Sophya modules without reference to external
-libraries.
-\item {\bf extlibdirs} List of Sophya modules with reference to external
-libraries.
-
+\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.
 \end{itemize}
- 
+
+\subsection{Files and scripts in BuildMgr/ }
+\begin{itemize}
+\item[] {\bf Makefile:} Top level Makefile for building SOPHYA.
+{\tt smakefile} is similar to Makefile, except that it uses 
+the smakefiles in each module.
+\item[] {\bf mkmflib:}  c-shell script for creation of library module 
+Makefile / smakefile.
+{\tt  ./mkmflib -sbase /tmp/sbase SUtils } 
+\item[] {\b mkmfprog:} 
+{\tt c-shell script for creation of programs module 
+Makefile / smakefile \\
+{\tt ./mkmfprog -sbase /tmp/sbase ProgPI }
+\item[] {\bf domkmf:} c-shell script - calls mkmflib for all modules \\
+{\tt ./domkmf -sbase /tmp/sbase}
+\item[] Configuration files for different compilers and OS
+(\tt  Linux\_g++\_make.inc , OSF1\_cxx\_make.inc \ldots }. 
+These files are used to generate {\tt sophyamake.inc} 
+\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.
+
+
 \newpage
 \appendix