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

\documentclass[twoside,11pt]{article}
%  Package standard : Utilisation de caracteres accentues, mode francais et graphique
\usepackage{url}
\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}

%  Definition pour Docs Sophya
\usepackage{defsophya}

%  Constitution d'index
\usepackage{makeidx}
\makeindex     

\begin{document}

\begin{titlepage}
%  The title page - top of the page with the title of the paper
\titrehp{Sophya  \\ An overview }
%  Authors list
\auteurs{
R. Ansari            &  ansari@lal.in2p3.fr       \\
E. Aubourg           &  aubourg@hep.saclay.cea.fr \\
G. Le Meur           &  lemeur@lal.in2p3.fr       \\
C. Magneville        &  cmv@hep.saclay.cea.fr     \\
S. Henrot-Versille   &  versille@in2p3.fr     
}
% \auteursall
%  The title page - bottom of the page with the paper number
\vspace{1cm}
\begin{center}
{\bf \Large Document being updated !}
\end{center}
\titrebp{1}
\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 mission problem.
  The source directory tree 
\footnote{ CVS: cvsserver.lal.in2p3.fr:/exp/eros/CVSPlanck} 
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) 
\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, 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 \\
({\tt SpectralResponse, RadSpectra, BlackBody} \ldots)
\item[] {\bf Samba/} Spherical harmonic analysis.
\end{itemize}

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

Other modules:
\begin{itemize}
\item[] {\bf Tests/} Simple test programs
\item[] {\bf PrgUtil/} Various utility programs (runcxx, scanppf, scanfits, \ldots)
\item[] {\bf PMixer/} skymixer and related 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 {\bf http://www.lal.in2p3.fr/recherche/eros/PeidaDoc/} } 
and {\bf PIext/} modules are not currently part 
of the SOPHYA CVS structure.
\end{itemize}   

\newpage 

\section{Using Sophya}
Basic usage of Sophya classes are described in in the following sections.
Complete Sophya documentation can be found at our web site: \\
{\bf http://hfi-l2.in2p3.fr}. 

\subsection{Environment variables}
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)

For modules using external libraries, the {\bf EXTLIBDIR} 
environment variable should contain the path to these libraries
and corresponding include files.
C-FitsIO anf FFTW include files should be accessible through: \\
{\tt \$EXTLIBDIR/Include/FitsIO } \\
{\tt \$EXTLIBDIR/Include/FFTW } \\
The corresponding libraries are expected to be found in: \\
{\tt \$EXTLIBDIR/Linux-g++/Libs} \\

\subsection{User makefiles}
The file {\tt \$DPCBASEREP/Include/MakefileUser.h} defines the compilation 
flags 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, 
and link it against the sophya libraries. The object and executable 
file names are: \\ 
{\tt \$HOME/`uname`-\$EROSCXX/Objs/trivial.o} \\
{\tt \$HOME/`uname`-\$EROSCXX/Exec/trivial}.
\par 
The file {\tt \$DPCBASEREP/Include/makefile\_example} provides another 
example makefile.

\subsection{the runcxx program}
\index{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
complete program file, containing the basic set C++ include files,
the necessary include files for SOPHYA SysTools, TArray, HiStats 
and NTools modules, and the main program with exception handling.
Other Sophya modules can be included using the {\tt -import} flag.
\begin{verbatim}
csh> runcxx -h
SOPHYA Version  0.9 Revision 97 (V_Oct2000) -- Nov  9 2000 16:20:52 cxx
 runcxx : compiling and running of a piece of C++ code
   Usage: runcxx [-compopt CompileOptions] [-linkopt LinkOptions]
                 [-tmpdir TmpDirectory] [-f C++CodeFileName]
                 [-inc includefile] [-inc includefile ...]
                 [-import modulename] [-import modulename ...]
                 [-uarg UserArg1 UserArg2 ...]
   if no file name is specified, read from standard input
   modulenames: SkyMap, Samba, SkyT, FitsIOServer, LinAlg, IFFTW
\end{verbatim}
Most examples in this manual can be tested using runcxx. The 
example below shows how to compile, link and run a sample
code.
\begin{verbatim}
//  File example.icc
Matrix a(3,3);
a = IdentityMatrix(1.);
cout << a ; 
// Executing this sample code
csh> runcxx -f example.icc
\end{verbatim}
 

\section{Copy constructor and assignment operator}
In C++, objects can be copied by assignment or by initialization.
Copying by initialization corresponds to creating an object and
initializing its value through the copy constructor.
The copy constructor has its first argument as a reference, or
const reference to the object's class type. It can have  
more arguments, if default values are provided.
Copying by assignment applies to an existing object and
is performed through the assignment operator (=). 
The copy constructor implements this for identical type objects:
\begin{verbatim}
class MyObject {
public:
  MyObject();      // Default constructor
  MyObject(MyObject const & a);  // Copy constructor
  MyObject & operator = (MyObject const & a) // Assignment operator
}
\end{verbatim}
The copy constructors play an important role, as they are 
called when class objects are passed by value, 
returned by value, or thrown as an exception. 
\begin{verbatim}
// A function declaration with an argument of type MyObject,
// passed by value, and returning a MyObject
MyObject f(MyObject x) 
{
  MyObject r;
  ...
  return(r);  // Copy constructor is called here
}
// Calling the function :
MyObject a;
f(a);        // Copy constructor called for a
\end{verbatim}
It should be noted that the C++ syntax is ambiguous for the 
assignment operator. {\tt MyObject x; x=y; } and 
{\tt MyObject x=y;} have different meaning.
\begin{verbatim}
MyObject a;        // default constructor call
MyObject b(a);     // copy constructor call
MyObject bb = a;   // identical to bb(a) : copy constructor call
MyObject c;        // default constructor call
c = a;             // assignment operator call
\end{verbatim}

As a general rule in SOPHYA, objects which implements 
reference sharing on their data members have a copy constructor
which shares the data, while the assignment operator copies or
duplicate the data.

\section{Module SysTools}

{\bf SysTools} contains utility classes such as {\tt DataCards} or 
{\tt DVlist}, an hierarchy of exception classes for Sophya, a template
class {\tcls{NDataBlock}} for handling reference counting on numerical
arrays, as well as classes providing the services for implementing simple
serialization. 
\vspace*{5mm}

\subsection{SOPHYA persistence}
\index{PPersist} \index{PInPersist} \index{POutPersist}
\begin{figure}[hbt]
\dclsa{PPersist}
\dclsbb{PIOPersist}{PInPersist}
\dclsb{POutPersist}
\caption{partial class diagram for classes handling persistence in Sophya}
\end{figure}
A simple persistence mechanism is defined in SOPHYA. Its main 
features are:
\begin{itemize}
\item[] Portable file format, containing the description of the data structures
and object hierarchy. \\
{\bf PPF} {\bf P}ortable {\bf P}ersistence file {\bf F}ormat.
\item[] Handling of read/write for mutiply referenced objects.
\item[] All write operations are carried using sequential access only. This
holds also for read operations, unless positional tags are used. 
SOPHYA persistence services can thus be used to transfer objects
through network links.
\item[] The serialisation (reading/writing) for objects for a given class
is implemented through a delegate object. The delegate class inherits
from {\tt PPersist} class.
\end{itemize}
A complete description of SOPHYA persistence mechanism and guidelines
for writing delegate classes for handling object persistence is beyond
the scope of this document. The example in the next paragraph shows
simple use of SOPHYA persistence.

\subsection{\tcls{NDataBlock}}
\index{\tcls{NDataBlock}}
\begin{figure}[hbt]
\dclsbb{AnyDataObj}{\tcls{NDataBlock}}
\dclsbb{PPersist}{\tcls{FIO\_NDataBlock}}
\end{figure}
The {\bf \tcls{NDataBlock}} is designed to handle reference counting 
and sharing of memory blocs (contiguous arrays) for numerical data 
types. Initialisation, resizing, basic arithmetic operations, as
well as persistence handling services are provided. 
The persistence handler class ({\tt \tcls{FIO\_NDataBlock}}) insures
that a single copy of data is written for multiply referenced objects,
and the data is shared among objects when reading. 
\par
The example below shows writing of NDataBlock objects through the 
use of overloaded operator $ << $ :
\begin{verbatim}
#include "fiondblock.h"
// ...
POutPersist pos("aa.ppf");
NDataBlock<r_4> rdb(40);
rdb = 567.89;
pos << rdb;
// We can also use the PutObject method
NDataBlock<int_4> idb(20);
idb = 123;
pos.PutObject(idb);
\end{verbatim}
The following sample programs show the reading of the created PPF file : 
\begin{verbatim}
PInPersist pis("aa.ppf");
NDataBlock<r_4> rdb;
pis >> rdb;
cout << rdb;
NDataBlock<int_4> idb;
cout << idb;
\end{verbatim}

\subsection{Using DVList}
\index{DVList} \index{MuTyV}
\begin{figure}[hbt]
\dclsbb{AnyDataObj}{DVList}
\dclsbb{PPersist}{\tclsc{ObjFileIO}{DVList}}
\end{figure}
The {\bf DVList} class objects can be used to create and manage list
of values, associated with names. A list of pairs of (MuTyV, name(string))
is maintained by DVList objects. {\bf MuTyV} is a simple class
capable of holding string, integer, float or complex values, 
providing easy conversion methods between these objects.
\begin{verbatim}
// Using MuTyV objects
MuTyV s("hello");  // string type value
MuTyV x;
x = "3.14159626";    // string type value, ascii representation for Pi
double d = x;        // x converted to double = 3.141596
x = 314;             // x contains the integer value = 314
// Using DVList
DVList  dvl;
dvl("Pi") = 3.14159626;            // float value, named Pi
dvl("Log2") = 0.30102999;          // float value, named Log2
dvl("FileName") = "myfile.fits";   // string value, named myfile.fits
// Printing DVList object
cout << dvl;
\end{verbatim}

\subsection{Using DataCards}
\index{DataCards}
The {\bf DataCards} class can be used to read parameters from a file.
Each line in the file starting with \@ defines a set of values
associated with a keyword. In the example below, we read the 
parameters corresponding with the keyword {\tt SIZE} from the 
file {\tt ex.d}. We suppose that {\tt ex.d} contains the line: \\
{\tt @SIZE 400 250} \\
\begin{verbatim}
#include "datacards.h"
// ...
// Initializing DataCards object dc from file ex.d
DataCards dc( "ex.d" );
// Getting the first and second parameters for keyword size
// We define a default value 100
int size_x = dc.IParam("SIZE", 0, 100);
int size_y = dc.IParam("SIZE", 1, 100);
cout << " size_x= " << size_x << " size_y= " << size_y << endl;
\end{verbatim} 

\subsection{Dynamic linker}
\index{PDynLinkMgr}
The class {\bf PDynLinkMgr} can be used for managing shared libraries
at run time. The example below shows the run time linking of a function:\\
{\tt extern "C" { void myfunc(); } } \\
\begin{verbatim}
#include "pdlmgr.h"
// ...
string soname = "mylib.so";
string funcname = "myfunc";
PDynLinkMgr dyl(soname);
DlFunction f = dyl.GetFunction(funcname); 
if (f != NULL) { 
// Calling the function 
  f();    
}
\end{verbatim}

\subsection{CxxCompilerLinker class}
\index{CxxCompilerLinker}
This class provides the services to compile C++ code and building 
shared libraries, using the same compiler and options which have 
been used to create the SOPHYA shared library. 
The sample program below illustrates using this class to build
the shared library (myfunc.so) from the source file myfunc.cc :
\begin{verbatim}
#include "cxxcmplnk.h"
// ...
string flnm = "myfunc.cc";
string oname, soname;
int rc;
CxxCompilerLinker cxx;
// The Compile method provides a default object file name
rc = cxx.Compile(flnm, oname);
if (rc != 0 ) { // Error when compiling ... }
// The BuildSO method provides a default shared object file name
rc = cxx.BuildSO(oname, soname);
if (rc != 0 ) { // Error when creating shared object ... }
\end{verbatim}

\section{Module TArray}
\index{\tcls{TArray}}
{\bf TArray} module contains template classes for handling standard 
operations on numerical arrays. Using the class {\tt \tcls{TArray} },
it is possible to create and manipulate up to 5-dimension numerical
arrays {\tt (int, float, double, complex, \ldots)}. The include
file {\tt array.h} declares all the classes and definitions 
in module TArray. {\bf Array} is a typdef for arrays 
with double precision floating value elements. \\
{\tt typedef TArray$<$r\_8$>$ Array ; }

\begin{figure}[hbt]
\dclsccc{AnyDataObj}{BaseArray}{\tcls{TArray}}
\dclsbb{PPersist}{\tcls{FIO\_TArray}}
\end{figure}


\subsection{Using arrays}
\index{Sequence} \index{RandomSequence} \index{RegularSequence} 
\index{EnumeratedSequence}
The example below shows basic usage of arrays, creation, initialization
and arithmetic operations. Different kind of {\bf Sequence} objects
can be used for initializing arrays. 

\begin{figure}[hbt]
\dclsbb{Sequence}{RandomSequence}
\dclsb{RegularSequence}
\dclsb{EnumeratedSequence}
\end{figure}

The example below shows basic usage of arrays: 
\begin{verbatim}
// Creating and initializing a 1-D array of integers
TArray<int> ia(5);
EnumeratedSequence es;
es = 24, 35, 46, 57, 68;
ia = es;
cout << "Array<int> ia = " << ia;
// 2-D array of floats 
TArray<r_4> b(6,4), c(6,4);
// Initializing b with a constant
b = 2.71828;
// Filling c with random numbers  
c = RandomSequence(); 
// Arithmetic operations
TArray<r_4> d = b+0.3f*c;
cout << "Array<float> d = " << d;
\end{verbatim}

The copy constructor shares the array data, while the assignment operator
copies the array elements, as illustrated in the following example:
\begin{verbatim}
TArray<int> a1(4,3);
a1 = RegularSequence(0,2);
// Array a2 and a1 shares their data 
TArray<int> a2(a1);
// a3 and a1 have the same size and identical elements
TArray<int> a3;
a3 = a1;
// Changing one of the a2 elements
a2(1,1,0) = 555;
// a1(1,1) is also changed to 555, but not a3(1,1)
cout << "Array<int> a1 = " << a1;
cout << "Array<int> a3 = " << a3;
\end{verbatim} 

\subsection{Matrices and vectors}
\index{\tcls{TMatrix}}  \index{\tcls{TVector}}
\begin{figure}[hbt]
\dclsccc{\tcls{TArray}}{\tcls{TMatrix}}{\tcls{TVector}}
\end{figure}
Vectors and matrices are 2 dimensional arrays. The array size
along one dimension is equal 1 for vectors. Column vectors
have {\tt NCols() = 1} and row vectors have {\tt NRows() = 1}.
Mathematical expressions involving matrices and vectors can easily 
be translated into C++ code using {\tt TMatrix} and 
{\tt TVector} objects. {\bf Matrix} and {\bf Vector} are 
typedefs for double precision float matrices and vectors.
The operator {\bf *} beteween matrices is redefined to 
perform matrix multiplication. One can then write: \\
\begin{verbatim}
  // We create a row vector
  Vector v(1000, BaseArray::RowVector);
  // Initialize values with a random sequence
  v = RandomSequence();
  // Compute the vector length (norm)
  double norm = (v*v.Transpose()).toScalar();
  cout << "Norm(v) = " << norm << endl;
\end{verbatim}

This module contains also simple Gauss matrix inversion algorithm
which can be used to solve linear systems, as illustrated by the 
example below:
\begin{verbatim}
#include "sopemtx.h"
// ...
// Creation of a random 5x5 matrix
Matrix A(5,5);
A = RandomSequence(RandomSequence::Flat);
Vector X0(5);
X0 = RandomSequence(RandomSequence::Gaussian);
// Computing B = A*X0
Vector B = A*X0;
// Solving the system A*X = B 
Vector X;
LinSolve(A, B, X);
// Checking the result
Vector diff = X-X0;
cout << "X-X0= " << diff ;
double min,max;
diff.MinMax(min, max);
cout << " Min(X-X0) = " << min << " Max(X-X0) = " << max << endl; 
\end{verbatim}

\subsection{Working with sub-arrays and Ranges}
A powerful mechanism is included in array classes for working with 
sub-arrays. The class {\bf Range} can be used to specify range of array 
indexes in any of the array dimensions. Any regularly spaced index
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 
dimensional stream (Vector) has been written using sub-arrays:  

\begin{verbatim}
// Input Vector containing a noisy periodic signal
  Vector in(1024), out(1024);
  in = RandomSequence(RandomSequence::Gaussian, 0., 1.);
  for(int kk=0; kk<in.Size(); kk++)
    in(kk) += 2*sin(kk*0.05);
// Compute the output vector by a simple low pass filter
  Vector out(1024);
  int w = 2;
  for(int k=w; k<in.Size()-w; k++)
    out(k) = in(Range(k-w, k+w).Sum()/(2.*w+1.);
\end{verbatim}

\subsection{Memory organisation}
{\tt \tcls{TArray} } can handle numerical arrays with various memory 
organisation, as long as the spacing (steps) along each axis is 
regular. The five axis are labeled X,Y,Z,T,U. The examples below
illustrates the memory location for a 2-dimensional, $N_x=4 \times N_y=3$.
The first index is along the X axis and the second index along the Y axis.
\begin{verbatim}
    | (0,0)  (0,1)  (0,2)  (0,3) |
    | (1,0)  (1,1)  (1,2)  (1,3) |
    | (2,0)  (2,1)  (2,2)  (2,3) |
\end{verbatim}
In the first case, the array is completely packed 
($Step_X=1, Step_Y=N_X=4$), with zero offset,
while in the second case, $Step_X=2, Step_Y=10, Offset=10$:
\begin{verbatim}
    | 0  1  2  3  |         | 10 12 14 16 |
Ex1 | 4  5  6  7  |     Ex2 | 20 22 24 26 |
    | 8  9  10 11 |         | 30 32 34 36 | 
\end{verbatim} 

For matrices and vectors, an optional argument ({\tt MemoryMapping}) 
can be used to select the memory mapping, where two basic schemes 
are available: \\
{\tt CMemoryMapping} and {\tt FortranMemoryMapping}. \\
In the case where {\tt CMemoryMapping} is used, a given matrix line
is packed in memory, while the columns are packed when 
{\tt FortranMemoryMapping} is used. The first index when addressing 
the matrix elements (line number index) runs along
the Y-axis if  {\tt CMemoryMapping} is used, and along the X-axis
in the case of {\tt FortranMemoryMapping}. 
Arithmetic operations between matrices
with different memory organisation is allowed as long as 
the two matrices have the same sizes (Number of rows and columns). 
The following code example and the corresponding output illustrates 
these two memory mappings.
\begin{verbatim}
TArray<r_4> X(4,2); 
X = RegularSequence(1,1);
cout << "Array X= " << X << endl;
TMatrix<r_4> X_C(X, true, BaseArray::CMemoryMapping);
cout << "Matrix X_C (CMemoryMapping) = " << X_C << endl;
TMatrix<r_4> X_F(X, true, BaseArray::FortranMemoryMapping);
cout << "Matrix X_F (FortranMemoryMapping) = " << X_F << endl;
\end{verbatim}
This code would produce the following output (X\_F = Transpose(X\_C)) :
\begin{verbatim}
Array X= 
--- TArray<f>  ND=2 SizeX*Y*...= 4x2 ---
1, 2, 3, 4
5, 6, 7, 8

Matrix X_C (CMemoryMapping) = 
--- TMatrix<f>(NRows=2, NCols=4) ND=2 SizeX*Y*...= 4x2 ---
1, 2, 3, 4
5, 6, 7, 8

Matrix X_F (FortranMemoryMapping) = 
--- TMatrix<f>(NRows=4, NCols=2) ND=2 SizeX*Y*...= 4x2 ---
1, 5
2, 6
3, 7
4, 8
\end{verbatim}

\newpage 

\section{Module HiStats}
\begin{figure}[hbt]
\dclsccc{AnyDataObj}{Histo}{HProf}
\dclsbb{AnyDataObj}{Histo2D}
\dclsbb{AnyDataObj}{Ntuple}
\dclsb{XNtuple}
\caption{partial class diagram for histograms and ntuples}
\end{figure}

{\bf HiStats} contains classes for creating, filling, printing and
doing various operations on one or two dimensional histograms
{\tt Histo} and {\tt Histo2D} as well as profile histograms {\tt HProf}. \\
This module also contains {\tt NTuple} and {\tt XNTuple} which are
more or less the same that the binary FITS tables.

\subsection{1D Histograms}

For 1D histograms, various numerical methods are provided such as
computing means and sigmas, finding maxima, fitting, rebinning,
integrating \dots \\
The example below shows creating and filling a one dimensionnal histogram
of 100 bins from $-5.$ to $+5.$ to create a gaussian normal distribution
with errors~:
\begin{verbatim}
#include "histos.h"
// ...
Histo H(-0.5,0.5,100);
H.Errors();
for(int i=0;i<25000;i++) {
  double x = NorRand();
  H.Add(x);
}
H.Print(80);
\end{verbatim}

\subsection{2D Histograms}

Much of these operations are also valid for 2D histograms. 1D projection
or slices can be set~:
\begin{verbatim}
#include "histos2.h"
// ...
Histo H2(-1.,1.,100,0.,60.,50);
H2.SetProjX(); // create the 1D histo for X projection
H2.SetBandX(25.,35.); // create 1D histo  projection for 25.<y<35.
H2.SetBandX(35.,45.); // create 1D histo  projection for 35.<y<45.
H2.SetBandX(40.,55.); // create 1D histo  projection for 40.<y<55.
//... fill H2 with what ever you want
H2.Print();
Histo *hx = H2.HProjX();
  hx->Print(80);
Histo *hbx2 = HBandX(1); // Get the second X band (35.<y<45.)
  hbx2->Print(80);
\end{verbatim}

\subsection{Profile Histograms}

Profiles histograms contains the mean and the sigma of the distribution
of the values filled in each bin. The sigma can be changed to
the error on the mean. When filled, the profile histogram looks
like a 1D histogram and much of the operations that can be done on 1D histo
may be applied onto profile histograms.

\subsection{Ntuples}

NTuple are memory resident tables of 32 bits floating values (float).
They are arranged in columns. Each line is often called an event.
These objects are frequently used to analyze data.
Graphicals tools (spiapp) can plot a column against an other one
with respect to various selection cuts. \\
Here is an example of creation and filling~:
\begin{verbatim}
#include "ntuple.h"
#include "srandgen.h"
// ...
char* nament[4] = {"i","x","y","ey"};
r_4 xnt[4];
NTuple NT(4,nament);
for(i=0;i<5000;i++) {
  xnt[0] = i+1;
  xnt[1] = 5.*drandpm1();       // a random value between -5 and +5
  xnt[2] = 100.*exp(-0.5*xnt[1]*xnt[1]) + 1.;
  xnt[3] = sqrt(xnt[2]);
  xnt[2] += xnt[3] * NorRand(); // add a random gaussian error
  NT.Fill(xnt);
}
\end{verbatim}

XNtuple are sophisticated NTuple : they accept various types
of column values (float,double,int,...) and can be as big as
needed (they used buffers on hard disk).

\subsection{Writing, viewing \dots }

All these objects have been design to be written to or read from a persistant file.
The following example shows how to write the previously created objects
into such a file~:
\begin{verbatim}
//-- Writing
{
char *fileout = "myfile.ppf";
string tag;
POutPersist outppf(fileout);
tag = "H";   outppf.PutObject(H,tag);
tag = "H2";   outppf.PutObject(H2,tag);
tag = "NT";   outppf.PutObject(NT,tag);
}  // closing ``}'' destroy ``outppf'' and automatically close the file !
\end{verbatim}

Sophya graphical tools (spiapp) can automatically display and operate
all these objects.

\section{Module SkyMap}
\begin{figure}[hbt]
\dclsbb{AnyDataObj}{PixelMap}
\dclsccc{PixelMap}{Sphericalmap}{SphereHEALPix}
\dclsc{SphereThetaPhi}
\dclsb{LocalMap}
\caption{partial class diagram for pixelization classes  in Sophya}
\end{figure}
The {\bf SkyMap} module provides classes for creating, filling, reading pixelized spherical  and 2D-maps. The types of values stored in pixels can be int, float, double , complex etc. according to the specialization of the template type. 
\subsection {Spherical maps}
There are two kinds of spherical maps according pixelization algorithms. SphereHEALPix represents spheres pixelized following the HEALPIix algorithm (E. Yvon, K. Gorski), SphereThetaPhi represents spheres pixelized following an algorithm developed at LAL-ORSAY. The example below shows creating and filling of a SphereHEALPix with nside = 8 (it will be 12*8*8= 768 pixels) :

\begin{verbatim}
#include ``spherehealpix.h''
// ...
SphereHEALPix<double> sph(8);
for (int k=0; k< sph.NbPixels(); k++) sph(k) = (double)(10*k);
\end{verbatim}

SphereThetaPhi is used in a similar way with an argument representing number of slices in theta (Euler angle) for an hemisphere.
\subsection {Local maps}
A local map is a 2 dimensional array, with i as column index and j as row index. The map is supposed to lie on a plan tangent to the celestial sphere in a point whose coordinates are (x0,y0) on the local map and (theta0, phi0) on the sphere. The range of the map is defined by two values of angles covered respectively by all the pixels in x direction and all the pixels in y direction (SetSize()). Default value of (x0, y0) is middle of the map, center of pixel(nx/2, ny/2).

Internally, a map is first defined within this reference plane and tranported until the point (theta0, phi0) in such a way that both axes are kept parallel to meridian and parallel lines of the sphere. The user can define its own map with axes rotated with respect to reference axes (this rotation is characterized by angle between the local parallel line and the wanted x-axis-- method SetOrigin(...))

The example below shows creating and filling of a LocalMap with 4 columns and 5 rows. The origin is set to default. The map covers a sphere portion defined by two angles of 30. degrees (methods \textit{SetOrigin()} and \textit{SetSize()} must be called in order to completely define the map).
\begin{verbatim}
#include "localmap.h"  
//..............       
  LocalMap<r_4> locmap(4,5);
  for (int k=0; k<locmap.NbPixels();k++) locmap(k)=10.*k;
  locmap.SetOrigin();
  locmap.SetSize(30.,30.);
\end{verbatim}

\subsection{Writing, viewing \dots }

All these objects have been design to be written to or read from a persistant file.
The following example shows how to write the previously created objects
into such a file~:
\begin{verbatim}
//-- Writing

#include "fiospherehealpix.h" 
//................

char *fileout = "myfile.ppf";
POutPersist outppf(fileout);
FIO_SphereHEALPix<r_8> outsph(sph);
outsph.Write(outppf);
FIO_LocalMap<r_8> outloc(locmap);
outloc.Write(outppf);

\end{verbatim}

Sophya graphical tools (spiapp) can automatically display and operate
all these objects.


\section{Module NTools}

This module provides elementary numerical tools for numerical integration,
fitting, sorting and ODE solving. FFTs are also provided (Mayer,FFTPack).

\subsection{Fitting}

Fitting is done with two classes {\tt GeneralFit} and {\tt GeneralFitData}
and is based on the Levenberg-Marquardt method.
GeneralFitData is a class which provide a description of the data
to be fitted. GeneralFit is the fitter class. Parametrized functions
can be given as classes which inherit {\tt GeneralFunction}
or as simple C functions. Classes of pre-defined functions are provided
(see files fct1dfit.h and fct2dfit.h). The user interface is very close
from that of the CERN {\tt Minuit} fitter.
Number of objects (Histo, HProf \dots ) are interfaced with GeneralFit
and can be easily fitted. \\
Here is a very simple example for fitting the previously created NTuple
with a gaussian~:
\begin{verbatim}
#include "fct1dfit.h"
// ...

// Read from ppf file
NTuple nt;
{
PInPersist pis("myfile.ppf");
string tag = "NT";  pis.GetObject(nt,tag);
}

// Fill GeneralData
GeneralData mGdata(nt.NEntry());
for(int i=0; i<nt.NEntry(); i++)
  mGdata.AddData1(xnt[1],xnt[2],xnt[3]); // Fill x, y and error on y
mGData.PrintStatus();

// Function for fitting : y = f(x) + noise
Gauss1DPol mFunction; // gaussian + constant

// Prepare for fit
GeneralFit mFit(&mFunction);  // create a fitter for the choosen function
mFit.SetData(&mGData);        // connect data to the fitter

// Set and initialize the parameters (that's non-linear fitting!)
//           (num par, name, guess start, step, [limits min and max])
mFit.SetParam(0,"high",90.,1..);
mFit.SetParam(1,"xcenter",0.05,0.01);
mFit.SetParam(2,"sigma",sig,0.05,0.01,10.);
                              // Give limits to avoid division by zero
mFit.SetParam(3,"constant",0.,1.);

// Fit and print result
int rcfit = mFit.Fit();
mFit.PrintFit();
if(rcfit>0) {)
  cout<<"Reduce_Chisquare = "<<mFit.GetChi2Red()
      <<" nstep="<<mFit.GetNStep()<<" rc="<<rcfit<<endl;
} else {
  cout<<"Fit_Error, rc = "<<rcfit<<"  nstep="<<mFit.GetNStep()<<endl;
  mFit.PrintFitErr(rcfit);
}

// Get the result for further use
TVector<r_8> ParResult = mFit.GetParm();
cout<<ParResult;
\end{verbatim}

Much more usefull possibilities and detailed informations might be found
in the HTML pages of the Sophya manual.

\subsection{Polynomial}

Polynomials of 1 or 2 variables are supported ({\tt Poly} and {\tt Poly2}).
Various operations are supported~:
\begin{itemize}
\item elementary operations between polynomials $(+,-,*,/) $
\item setting or getting coefficients
\item computing the value of the polynomial for a given value
      of the variable(s),
\item derivating
\item computing roots (degre 1 or 2)
\item fitting the polynomial to vectors of data.
\end{itemize}
Here is an example of polynomial fitting~:
\begin{verbatim}
#include "poly.h"
// ...
Poly pol(2);
pol[0] = 100.; pol[1] = 0.; pol[2] = 0.01; // Setting coefficients
TVector<r_8> x(100);
TVector<r_8> y(100);
TVector<r_8> ey(100);
for(int i=0;i<100;i++) {
  x(i)  = i;
  ey(i) = 10.;
  y(i)  = pol((double) i) + ey(i)*NorRand();
  ey(i) *= ey(i)
}

TVector<r_8> errcoef;
Poly polfit;
polfit.Fit(x,y,ey,2,errcoef);

cout<<"Fit Result"<<polfit<<endl;
cout<<"Errors :"<<errcoef;
\end{verbatim}

Similar operations can be done on polynomials with 2 variables.

\section{Module Samba}

The module provides several classes for spherical harmonic analysis. The main class is \textit{SphericalTranformServer}. It contains methods for analysis and synthesis of spherical maps. The following example fills a vector of Cl's, generate a spherical map from these Cl's. This map is analyzed back to Cl's...
\begin{verbatim}
#include "skymap.h"
#include "samba.h"
....................

// Generate input spectra  a + b* l + c * gaussienne(l, 50, 20)
int lmax = 92;
Vector clin(lmax);
for(int l=0; l<lmax; l++) {
  double xx = (l-50.)/10.;
  clin(l) = 1.e-2 -1.e-4*l + 0.1*exp(-xx*xx);
}

// Compute map from spectra
SphericalTransformServer<r_8> ylmserver;
int m = 128;  // HealPix pixelisation parameter
SphereHEALPix<r_8> map(m);
ylmserver.GenerateFromCl(map, m,  clin, 0.);
// Compute power spectrum from map
Vector clout = ylmserver.DecomposeToCl(map, lmax,  0.);
\end{verbatim}

\section{Module SkyT}

\section{Module FitsIOServer}
\begin{figure}[hbt]
\dclsbb{FitsFile}{FitsInFile}
\dclsb{FitsOutFile}
\end{figure}

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 :
\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}



\newpage
\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{ 
          \rule{20mm}{0.5mm} 
        {\bf \large the use of GNU make is mandatory} 
        \rule{20mm}{0.5mm} }
 
\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 slball
\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}

\subsection{Mgr module}
This module contains scripts which can be used for generating the 
makefiles for each module.
\begin{itemize}
\item {\bf Makefile} Top level Makefile for builiding the libraries.
\item {\bf Makefile.h} contains the defintion 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 \$DPCBASEREP} and {\tt \$DPCDEVREP}
\item {\bf install\_sophya} c-shell script for installing the Sophya package.
Usually from {\tt \$DPCDEVREP} to {\tt \$DPCBASEREP}
\item {\bf mkmflien} c-shell script for making symbolic links or copying
include files to {\tt \$DPCDEVREP/Include} or {\tt \$DPCBASEREP/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.

\end{itemize}
 
\newpage
\appendix
\section{SOPHYA Exceptions}
\index{Exception classes} \index{PThrowable} \index{PError} \index{PException}
SOPHYA library defines a set of exceptions which are used 
for signaling error conditions. The figure below shows a partial 
class diagram for exception classes in SOPHYA.
\begin{figure}[hbt]
\dclsbb{PThrowable}{PError}
\dclscc{PError}{AllocationError}
\dclscc{PError}{NullPtrError}
\dclscc{PError}{ForbiddenError}
\dclscc{PError}{AssertionFailedError}
\dclsbb{PThrowable}{PException}
\dclscc{PException}{IOExc}
\dclscc{PException}{SzMismatchError}
\dclscc{PException}{RangeCheckError}
\dclscc{PException}{ParmError}
\dclscc{PException}{TypeMismatchExc}
\dclscc{PException}{MathExc}
\dclscc{PException}{CaughtSignalExc}
\caption{partial class diagram for exception handling in Sophya}
\end{figure}

For simple programs, it is a good practice to handle 
the exceptions at least at high level, in the {\tt main()} function. 
The example below shows the exception handling and the usage 
of Sophya persistence.
 
\input{ex1.inc}


\newpage
\addcontentsline{toc}{section}{Index}
\printindex 
\end{document}