source: Sophya/trunk/SophyaLib/Manual/sophya.tex@ 980

\documentclass[twoside,11pt]{article}
%  Package standard : Utilisation de caracteres accentues, mode francais et graphique
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[english]{babel}
\usepackage{graphicx}
% package a mettre pour faire du pdf
\usepackage{palatino}

%  Extension de symboles mathematiques
\usepackage{amssymb}

\usepackage{defsophya}



\begin{document}

\begin{titlepage}
\titrehp{Sophya  \\ An overview }
\auteurs{
R. Ansari     &  ansari@lal.in2p3.fr       \\
G. Le Meur    &  lemeur@lal.in2p3.fr       \\
C. Magneville &  cmv@hep.saclay.cea.fr     \\
S. Versille   &  versille@lal.in2p3.fr     
}
% \auteursall
\titrebp{2}
\end{titlepage}

\tableofcontents

\newpage

\section{Introduction}

   {\bf SOPHYA} ({\bf SO}ftware for {\bf PHY}sics {\bf A}nalysis) 
is a collection of C++ classes designed for numerical and
physics analysis software development. Our goal is to provide
easy to use, yet powerful classes which can be used by scientists.
We have decided to use as much as possible available 
numerical analysis libraries, encapsulating them whenever
possible.
  
  The SOPHYA design and implementation has been carried out
with the specific goal of providing the general framework for
the Planck-HFI data processing software. However, most of the 
packages presented here have a more general scope than the CMB analysis
and Planck surveyor mission problem.
  The source directory tree 
\footnote{ CVS server: cvsserver.lal.in2p3.fr:/projects/Eros/CVSEros} 
is organised into a number of modules. 

\begin{itemize}
\item[] {\bf Mgr/}  Scripts for code management, 
makefile generation and software installation
\item[] {\bf SysTools/} General architecture support classes such 
as {\tt PPersist, NDataBlock<T>}, and few utility classes 
({\tt DataCard, DVList} \ldots). 
\item[] {\bf TArray/} template numerical arrays, vectors and matrices
({\tt PixelMap<T> SphericalMap<T>} \ldots) and few geometry 
handling utility classes.
\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 \\
({\tt Histo Histo2D NTuple XNTuple} \ldots)
\end{itemize}

The modules listed below are more tightly related to the 
CMB (Cosmic Microwave Background) data analysis problem:
\begin{itemize}
\item[] {\bf SkyMap/} Local and full sky maps 
\item[] {\bf SkyT/} 
classes for spectral emission and detector frequency response modelling \\
({\tt SpectralResponse, RadSpectra, BlackBody} \ldots)
\item[] {\bf Samba/} few classes for map and TOD analysis.
\item[] {\bf PMixer/} skymixer and related programs
\end{itemize}

The following modules contain the interface classes with 
external libraries:
\begin{itemize}
\item[] {\bf FitsIOSrever/} 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
\end{itemize}

Other modules:
\begin{itemize}
\item[] {\bf Tests/} Simple test programs
\item[] {\bf ProgPI/}  interactive analysis tool - It should be noted that 
this module uses the SOPHYA class library and is based on {\bf PI}
which is a C++ library defining a complete GUI program 
architecture. An additional module (PIext) define the interactive
analysis program framework and the interfaces with the objects
in SOPHYA.  The {\bf PI/} \footnote{the PI package documentation 
is available from {\tt http://www.lal.in2p3.fr/recherche/eros/PeidaDoc/} } 
and {\bf PIext/} modules are not currently part 
of the SOPHYA CVS structure.
\end{itemize}   

\section{Using Sophya}
Two environment variables {\bf DPCBASEREP} and {\bf EROSCXX} are used 
to define the path where the Sophya libraries and executable are installed.
{\bf DPCBASEREP} defines the base directory path and {\bf EROSCXX} the 
name of the C++ compiler. The complete path is built using {\bf DPCBASEREP},
the operating system name (as obtained by the {\tt uname} command), and
the compiler name. In the example below, we show the complete path
for a {\tt Linux} system, using the GNU g++ compiler:

\begin{itemize}
\item \$DPCBASEREP/Include : Include (.h) files
\item \$DPCBASEREP/Linux-g++/Libs : Path for the archive libraries (.a)
\item \$DPCBASEREP/Linux-g++/ShLibs : Shared library path (.so)
\item \$DPCBASEREP/Linux-g++/Exec : Executable file path
\end{itemize}

In order to use the shared libraries, the {\bf LD\_LIBRARY\_PATH} variable
should contain the Sophya shared library path 
({\tt \$DPCBASEREP/Linux-g++/ShLibs } when using g++ compiler on Linux)

The file {\tt \$DPCBASEREP/Include/MakefileUser.h} defines the compilation 
flag and the list of Sophya libraries. It should be included in the 
user's makefile. The default compilation rules assumes that the object (.o) 
and executable files would be put in the following diretories: \\
{\tt \$HOME/`uname`-\$EROSCXX/Objs} \\ 
{\tt \$HOME/`uname`-\$EROSCXX/Exec}.
In the case of a {\tt Linux} system and using {\tt g++} as the C++ compiler, 
these two directories would be translated to \\
{\tt \$HOME/Linux-g++/Objs} and {\tt \$HOME/Linux-g++/Exec}. 
The GNU make program should be used.
\par
The file {\tt \$DPCBASEREP/Include/makefile\_auto} defines the rules to compile
a given source program, and link it against the Sophya libraries to produce
an executable. The example below shows the steps to compile a program named
{\tt trivial.cc }.
\begin{verbatim}
csh> cp $DPCBASEREP/Include/makefile_auto makefile
csh> make trivial
\end{verbatim}
This command should compile the {\tt trivial.cc} file, producing 
{\tt \$HOME/`uname`-\$EROSCXX/Objs/trivial.o} and link it against the sophya
libraries to produce {\tt \$HOME/`uname`-\$EROSCXX/Exec/trivial}.
\par 
The file {\tt \$DPCBASEREP/Include/makefile\_example} provides another 
example makefile.


\section{Building and installing Sophya}
Presently, the Sophya library compilation has been tested with the following
compiler/platform pairs:

\begin{center}
\begin{tabular}{ll}
Compaq/DEC OSF1  &     cxx  (6.0 , 6.2)  \\
Linux            &     g++  (2.91 , 2.95)  \\
Linux            &     KCC  (3.4)   \\
Solaris          &     g++  (2.95)  \\
SGI IRIX64       &     CC           \\
\end{tabular}
\end{center}

Some of the modules in the Sophya package uses external libraries. The 
{\bf FitsIOServer} is the example of such a module, where the {\tt libcfitsio.a}
is used.
The build procedure expects to find the include files and the libraries in: \\
{\tt \$EXTLIBDIR/Include/FitsIO } \\
{\tt \$EXTLIBDIR/`uname`-\$EROSCXX/Libs} \\

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 
 are grouped in a single shared library ({\tt libsophya.so}), while the 
modules with reference to external libraries are grouped in 
({\tt libextsophya.so}). The {\bf PI} and {\bf PIext} modules are 
grouped in ({\tt libPI.so}).

The environment variables {\bf DPCDEVREP}, {\bf EXTLIBDIR} and {\bf EROSCXX}
must be defined in order to install the Sophya package.
In the example below, we assume that we want to install Sophya from a 
released (tagged) version in the source directory {\tt \$SRC} in the
{\tt /usr/local/Sophya} diretory, using {\tt g++}. We assume that 
the external libraries directory tree has been set up in 
{\tt /usr/local/ExtLibs/}. \\[3mm]
\centerline{\bf \large the use of GNU make is mandatory.} 
\vspace*{3mm}
\begin{verbatim}
# We select our C++ compiler
csh> setenv EROSCXX g++
# Setup the build directory
csh> mkdir /usr/local/Sophya/
csh> setenv DPCDEVREP /usr/local/Sophya/
csh> setenv EXTLIBDIR /usr/local/ExtLibs/
# Use the top level makefile in Mgr/ 
csh> cd $SRC
csh> cp Mgr/Makefile Makefile
# Step 1: Create the directory tree and copy the include files (.h)
csh> make depend
# Step 2: Compile the modules without external library reference
csh> make libs
# Step 3: Compile the modules WITH  external library reference (optional) 
csh> make extlibs
# Step 4: Build libsophya.so
csh> make slb
# Step 5: Build libextsophya.so (optional)
csh> make slbext
# Step 6: Compile the PI and PIext modules (optional)
csh> make PI
# Step 7: Build the corresponding shared library libPI.so (optional)
csh> make slbpi
\end{verbatim}

To compile all modules and build the shared libraries, it is possible 
to use:
\begin{verbatim}
# Step 2,3,6
csh> make all
# Step 4,5,7
csh> make slb
\end{verbatim}

At this step, all libraries sould have been made. Programs using
Sophya libraries can now be built:
\begin{verbatim}
# To compile test programs
csh> cd Tests
csh> make arrt ...
csh> cd ..
# To compile other programs, for example from the PMixer module
csh> cd PMixer
csh> make
csh> cd ..
# To build (s)piapp (libPI.so is needed)
csh> cd ProgPI
csh> make 
csh> cd ..
\end{verbatim}

\section{Mgr/ module}
This module contains scripts which can be used for ge
blabla ...

\section{SysTools module}
This is a dclsa{AAAA} \\[2mm]
\dclsa{AAA}
This is a dclsb{BBBB}{BBBB} \\[2mm]
\dclsbb{BBBB}{BBBB}
This is a dclsc{CCCCC}{CCCCC}{CCCCC} \\[2mm]
\dclsccc{\tcls{CCCCC}}{CCCCC}{CCCCC}


\begin{figure}
\dclsa{DataCard}
\dclsbb{AnyDataObj}{NDataBlock$<$T$>$}
\dclsccc{BaseArray}{TArray}{TMatrix}
\dclsb{NDataBlock$<$T$>$}
\dclscc{TArray}{TMatrix}
\dclsc{\tcls{Tvector}}
\caption{ Partial class diagram}
\end{figure}


PixelMap<T> --- LocalMap<T>
                SphericalMap<T>  --- SphereThetaPhi<T>
                                     SphereHEALPix<T>


\end{document}