Index: /trunk/SophyaLib/Manual/modifs.tex
===================================================================
--- /trunk/SophyaLib/Manual/modifs.tex	(revision 3855)
+++ /trunk/SophyaLib/Manual/modifs.tex	(revision 3856)
@@ -65,4 +65,5 @@
 V = 2.140  &   \hspace{10mm}  &  Sept-Oct 2009 - NO tag  \\
 V = 2.150  &   \hspace{10mm}  &  Mars 2010 - NO tag  \\
+V = 2.2  &   \hspace{10mm}  &  Septembre 2010 - tag CVS \\
 
 \end{tabular}
@@ -93,5 +94,13 @@
 \titre{BuildMgr}
 \begin{itemize}
-\item[\rond] Juillet 2010 : Ajout de l'option {\tt -arch32} de compilation en 32 bits pour linux
+\item[\rond] Juillet/Aout 2010 : Ajout des options et arguments suivants au script configure
+\begin{verbatim}
+ -arch32 de compilation en 32 bits pour linux
+ -followlink pour suivi des liens symboliques lors des recherches
+     de fichiers par find. Pas de suivi des liens par defaut 
+ -epip pour chemin de librairies et include file PI (Motif ...)
+ -wgrdl activation compil et link piapp avec GNU-readline
+\end{verbatim}
+ {\tt -arch32} de compilation en 32 bits pour linux
 \item[\rond] Mars 2010 : Ajout de l'option {\tt -ldble128} dans le script configure pour la gestion conditionnelle 
 du flag compilation {\bf SO\_LDBLE128 } dans machdefs.h.  Ce flag active la dclaration des nombres en 
@@ -176,4 +185,6 @@
 \titre{NTools}
 \begin{itemize}
+\item[rond] Aout 2010 : Ajout de la classe d'interpolation lineaire {\bf SLinInterp1D} et programme 
+test Tests/tstinterp.cc 
 \item[\rond] Oct 2008 : Instanciation explicite des classes  
 \tcls{Image} et \tcls{ArrayFitter} pour T=uint\_4, uint\_8
Index: /trunk/SophyaLib/Manual/sophya.tex
===================================================================
--- /trunk/SophyaLib/Manual/sophya.tex	(revision 3855)
+++ /trunk/SophyaLib/Manual/sophya.tex	(revision 3856)
@@ -31,4 +31,5 @@
 \newcommand{\carre}{$\Box \ $}
 
+\newcommand{\bitem}[1]{\item[]{\bf #1} }
 
 \begin{document}
@@ -36,5 +37,5 @@
 \begin{titlepage}
 %  The title page - top of the page with the title of the paper
-\titrehp{Sophya  \\ An overview }
+\titrehp{SOPHYA user's guide }
 %  Authors list
 \auteurs{
@@ -48,5 +49,5 @@
 \vspace{1cm}
 \begin{center}
-{\bf \Large Sophya Version: 2.2 (V\_Sep2010) }
+{\bf \Large SOPHYA Version: 2.2 (V\_Sep2010) }
 \end{center}
 \titrebp{1}
@@ -149,5 +150,5 @@
 \item[] {\bf SysTools/} This module contains classes implementing 
 an interface to various OS specific services, such 
-threads and dynamic link/shared library handling.
+as threads and dynamic link/shared library handling.
 
 \end{itemize}
@@ -190,6 +191,6 @@
 SOPHYA library.
 \begin{itemize}
-\item[] {\bf Tests/} Simple test programs. Many of these test programs can be also used 
-as examples for using SOPHYA. 
+\item[] {\bf Tests/} Simple test programs. Many of these test programs can also be 
+used as examples for using SOPHYA. 
 \item[] {\bf PrgUtil/} Various utility programs (runcxx, scanppf, scanfits, \ldots)
 \item[] {\bf PrgMap/} Programs performing operations on skymaps: projections, 
@@ -225,13 +226,19 @@
 \item[] {\bf DemoPIApp/} Sample scripts and programs for (s)piapp 
 interactive analysis tools.
+\item[] {\bf DemoData/} data files (PPF, FITS \ldots) useful for the (s)piapp 
+user's manual examples.
 \end{itemize}   
 
-The following modules contains additional programs or libraries, based on SOPHYA :
+The following modules contains additional programs or libraries, which rely on SOPHYA:
 \begin{itemize}
 \item[] {\bf AnaLC} contains program files extracted from the EROS/PEIDA software
 and adapted to be compiled with SOPHYA. It can be used in particular to read and analyse
-EROS light curve data files. 
-\item[] {\bf LUC} {\bf L}ittle {\bf U}niverse {\bf C}alculator is a module containing classes to 
+EROS light curve data files (fichiers de suivi). 
+\item[] {\bf LUC}  ( {\bf L}ittle {\bf U}niverse {\bf C}alculator) is a module containing classes to 
 perform basic computation related to the universe geometry (FRW metric).
+\item[] {\bf SimLSS} Tools for the {\bf Sim}ulation and analysis of cosmological 
+{\bf L}arge {\bf S}cale {\bf S}tructures
+\item[] {\bf PIPhoto} is an interface module for (s)piapp and ImageMagick for 
+import/export of graphics in image format (jpeg, gif \ldots) in piapp.
 \item[] {\bf PMixer/} skymixer and related programs. This module is {\bf obsolete}.
 \end{itemize}
@@ -360,5 +367,5 @@
 classes / methods in SOPHYA. \\
 A major exception is the reference sharing mechanism, where different instances
-of a class may  shared memory locations. This reference sharing mechanism has been
+of a class may  share memory locations. This reference sharing mechanism has been
 made thread-safe in SOPHYA, from version V=2.1. \\
 As a consequence, different execution threads can access non overlapping sub-arrays
@@ -367,5 +374,5 @@
 NTuple and DataTable objects can be activated, on an object per object basis. \\
 The {\tt ZThread, ZMutex \ldots} classes in the {\bf SysTools } module offer a relatively 
-easy way of writing multi-threaded programs.   
+easy way of writing multi-threaded programs (See \ref{mtpsop}).
 
 \subsection{the runcxx program}
@@ -848,5 +855,5 @@
  
  \subsection{Pseudo-random number generators}
- \index{Random numbers}
+ \index{Random numbers}  \label{randgen}
 \begin{figure}[hbt]
 \dclsbb{ AnyDataObj }{ RandomGeneratorInterface } 
@@ -937,5 +944,5 @@
 int N = 10;
 // B.2- Compute and print a sequence of random number, 
-//      should be compared to the sequance A.5
+//      should be compared to the sequence A.5
 for(int i=0; i<N; i++) 
   cout << "-- I=" << i << "  rand_flat01= " << rgr.Flat01() 
@@ -971,6 +978,6 @@
 \item Capability to handle {\bf large - multidimensional - dense} 
 arrays, for numerical data types. Although we have used templates, for
-data type specialisation, the actual code, apart inline functions is
-not in header files. Instead, we use explicit instanciation, and the 
+data type specialisation, the actual code, apart from inline functions is
+not in the header files. Instead, we use explicit instanciation, and the 
 compiled code for the various numerical types of arrays is the
 library .
@@ -1125,4 +1132,19 @@
 The services provided in other modules, such as {\bf LinAlg} should
 be preferred in such cases.
+
+\subsubsection{TVectors and std::vector}
+SOPHYA \tcls{TVector} objects can be constructed or filled from \tcls{std::vector} objects.
+TVector objects can also be converted to std::vector.
+\begin{verbatim}
+TVector(const vector<T>& v, short lcv=BaseArray::AutoVectorType);
+TVector<T>::FillFr(const vector<T>& v,bool noresize=false);
+TVector<T>::FillTo(vector<T>& v,bool addtoend=false);
+\end{verbatim}
+
+In addition, \tcls{std::vector} objects can be written to, read from PPF streams
+through the class \tcls{PPFWrapperSTLVector} (file ppfwrapstlv.h). The std::vector
+PPF handler is currently registered  for the following data types: \\
+\hspace*{5mm} {\tt string, int\_2, uint\_2, int\_4, uint\_4, int\_8, uint\_8 } \\
+\hspace*{5mm} {\tt r\_4 , r\_8, complex$<$r\_4$>$ ,  complex$<$r\_8$>$ }
 
 \subsection{Working with sub-arrays and Ranges}
@@ -1695,6 +1717,6 @@
 (float/double).They are arranged in columns. Each line is often called an event.
 These objects are frequently used to analyze data.
-The piapp graphicals tools can plot a column against an other one
-with respect to various selection cuts. \\
+The piapp interactive analysis tool can be used to create 1D, 2D and 3D plots using the date from 
+NTuples and DataTables. \\
 Here is an example of creation and filling~:
 \begin{verbatim}
@@ -1818,9 +1840,9 @@
 \end{verbatim}
    
-\subsection{Writing, viewing \dots }
+\subsection{Persistence and visualisation }
 %%
 Histogram and NTuple/DataTable objects have PPF handlers and 
-can be written to or read from PPF files. Sophya graphical tool (spiapp) can 
-automatically display and operate on all these objects.
+can be written to or read from PPF files. Sophya interactive analysis tool 
+(spiapp) can automatically display and operate on all of these objects.
 The following example shows how to write the previously created objects
 into such a file~:
@@ -1842,5 +1864,6 @@
 fitting, sorting and ODE solving. FFTs are also provided (Mayer,FFTPack).
 
-\subsection{Fitting}
+\subsection{Optimisation and parameter fitting}
+\subsubsection{GeneralFit: non linear fitting}
 \index{Fitting} \index{Minimisation}
 Fitting is done with two classes {\tt GeneralFit} and {\tt GeneralFitData}
@@ -1908,7 +1931,32 @@
 in the HTML pages of the Sophya manual.
 
-\subsection{Simplex method}
+\subsubsection{Simplex method}
 The class {\bf MinZSimplex} implements the simplex method for non linear 
-optimization / minimization. See the SOPHYA manual for more information.
+optimization / minimization. See the SOPHYA reference manual and the 
+Tests/tsimplex.cc for more information.
+
+\subsection{Interpolation}
+\index{Interpolation} \index{SLinInterp1D}
+The class {\bf SLinInterp1D} (file slininterp.h) can be used for linear 1D interpolation. 
+\begin{verbatim}
+#include "slininterp.h"
+#include "srandgen.h"
+  ...
+vector<double> ys;
+double xmin = 0.5;
+double xmax = 0.;
+for(int i=0; i<=12; i++) {
+  xmax = xmin+i*0.1;
+  yreg.push_back(sin(xmax)*cos(2.2*xmax));
+}
+SLinInterp1D interpYR(xmin, xmax, yreg);
+cout << interpYR
+for(int i=0; i<=12; i++) {
+  double x = drand01()*2.;
+  cout << " Interpol result for X=" << x << " -> " << interpYR(x) 
+       << " ?= " << sin(x)*cos(2.2*x) << endl;
+}
+\end{verbatim}
+The {\bf CSpline} and {\bf CSpline2} classes perform one dimensional and two dimensional spline interpolation.
 
 \subsection{Polynomial}
@@ -2064,5 +2112,5 @@
 
 \subsection{Thread management classes}
-\index{ZThread} \index{ZMutex} 
+\index{ZThread} \index{ZMutex}  \label{thrcls}
 A basic interface to POSIX threads is also provided
 through the \index{threads} {\bf ZThread}, {\bf ZMutex} and {\bf ZSync}
@@ -2079,5 +2127,5 @@
   zt1.setAction(fun1, arg[1]);
   ZThread zt2;
-  zt2.setAction(fun2, arg[1]);
+  zt2.setAction(fun2, arg[2]);
   cout << " Starting threads ... " << endl;
   zt1.start();
@@ -2088,15 +2136,19 @@
 \end{verbatim}
 The classes {\bf ZMutex} \index{mutex} and {\bf ZSync} can be used 
-to perform synchronisation and signaling between threads.
-Example multithread programs using these classes can be found in
-the {\bf Tests} module : \\
-\hspace{10mm} {\tt zthr.cc  , tmtdt.cc , tmtrnd.cc }
+to perform synchronisation and signaling between threads. Each {\bf ZMutex} object
+contains a pair of mutex and condition variable.
+The {\bf ParallelExecutor } class can be used for parallel simultaneous execution 
+of several function of objects inheriting from {\bf  ParallelTaskInterface}. 
+Some hints about parallel programming and usage of these classes can be found in 
+\index{ParallelExecutor} \index{ ParallelTaskInterface }
+\ref{mtpsop}. 
 
 \begin{figure}[hbt]
+\dclsa{ParallelExecutor}
+\dclsbb{ParallelTaskInterface}{ParallelTaskFunction}
 \dclsbb{ZThread}{ParalExThread}
-\dclsa{ParallelExecutor}
+\dclsa{ZMutex}
 \end{figure}
-%%  CHECK 
-{\bf \large DECRIRE l'utilisation des nouvelles classes ParallelExecutor ... }
+
 
 \subsection{Dynamic linker and C++ compiler classes}
@@ -2150,5 +2202,6 @@
 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. 
+as the control and test blocs. A description of this command interpreter syntax 
+and possibilities can be found in the (s)piapp user's guide.
 \begin{verbatim}
 #include "commander.h"
@@ -2277,8 +2330,7 @@
 \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
+\subsection{Persistence and visualisation }
+The different SkyMap objects have PPF handlers and written to or read from PPF files.
+The following example shows how to save the previously created objects
 into such a file~:
 \begin{verbatim}
@@ -2300,6 +2352,6 @@
 \end{verbatim}
 
-Sophya graphical tools (spiapp) can automatically display and operate
-all these objects.
+Sophya interactive analysis tool (spiapp) can automatically display and operate
+on SkyMap objects. 
 
 \newpage
@@ -2333,4 +2385,7 @@
 \subsection{Module SkyT}
 \index{RadSpectra} \index{SpectralResponse} 
+\begin{center}
+{\bf \large THIS MODULE NEEDS EXTENSIVE CHECKING/DEBUGGING AND REDESIGN } 
+\end{center}
 The SkyT module is composed of two types of classes:
 \begin{itemize}
@@ -2432,4 +2487,5 @@
 \begin{enumerate}
 \item Saving an array and a HealPix map to a Fits file
+\index{HEALPix-FITS}
 \begin{verbatim}
 #include "fitsioserver.h"
@@ -2482,6 +2538,7 @@
 %%% 
 \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
+binary tables. The example below show reading the DataTable created in the example
 in section \ref{datatables} from a PPF file and saving it to a fits file.
+\index{DataTable-FITS}
 \begin{verbatim}
 #include "swfitsdtable.h"
@@ -2513,4 +2570,80 @@
 \end{figure}
 
+\subsection{Fits Array I/O in chunk }
+Array read/write from/to FITS files (Image HDU) is rather straightforward, in particular thanks to 
+the overloaded stream operators, as in the examples given above and here:
+\index{Array-FITS}
+\begin{verbatim}
+//  ---- Writing an array to fits file
+//  Create and open a fits file named myfile.fits
+FitsInOutFile fos("!myarr.fits", FitsInOutFile ::Fits_Create);
+TArray<r_8> a(50,30);
+// ... fill the array
+// Write the array to file
+fos << a;
+
+// ---- Reading an array from file myarr.fits
+// Open the fits file for reading
+FitsInOutFile fis("myarr.fits", FitsInOutFile::Fits_RO);
+TArray<r_8> a;
+// Read in the array 
+fis >> a;
+\end{verbatim}
+
+It is also possible to write arrays FITS Image HDU in chunks  or read arrays in chunk, 
+using the following methods : \\
+\begin{verbatim}
+void FitsArrayHandler<T>::ReadAtOffset(FitsInOutFile& is, sa_size_t* offset);
+void FitsArrayHandler<T>::WriteAtOffset(FitsInOutFile& os, sa_size_t* offset);
+\end{verbatim} 
+The sample code below show how a FITS file corresponding to a 3D data cube of $5\times4\times3$  elements 
+can be created and written as a series of 2D slices:
+\begin{verbatim}
+// Make sure FitsIOServer module is initialised :
+FitsIOServerInit();
+// Open/create the output file, named mycube.fits (overwrite it)
+FitsInOutFile fos("!mycube.fits", FitsInOutFile ::Fits_Create);
+// Define the cube size 
+LONGLONG size[3] = {5,4,3};
+// Create a 2D array corresponding to an x-y cube slice 
+TArray<int_4> slice(size[0], size[1]);
+// Create an IMAGE HDU: cube size and slice data type
+fos.CreateImageHDU(FitsTypes::ImageType(slice(0,0)), 3, size);
+// initialize the array content 
+slice = RegularSequence();
+// Create a Fits handler for the array 
+FitsArrayHandler<int_4> fh(slice);
+// Write the 3 slices to the file 
+sa_size_t offset[3];
+offset[0]=0; offset[1]=0; 
+for(int k=0;k<size[2]; k++) {
+  slice += (int_4)(k*100);
+  offset[2]=k;
+  fh.WriteAtOffset(fos,offset);
+}
+\end{verbatim}
+The example below show how to read arrays from Image HDU in chunk:
+\begin{verbatim}
+// Make sure FitsIOServer module is initialised :
+FitsIOServerInit();
+// Open the existing file mycube.fits for reading
+FitsInOutFile fis("mycube.fits", FitsInOutFile::Fits_RO);
+// Get the array size
+int naxis=BASEARRAY_MAXNDIMS;
+LONGLONG axes[BASEARRAY_MAXNDIMS];
+fis.GetImageHDUInfo(naxis, axes);
+// Read in the data as 2D slices 
+TArray<int_4> slice(axes[0], axes[1]);
+FitsArrayHandler<int_4> fh(slice);
+sa_size_t offset[3];
+offset[0]=0; offset[1]=0; 
+for(int k=0;k<axes[2]; k++) {
+  offset[2]=k;
+  fh.ReadAtOffset(fis,offset);
+  cout << " Slice k=" << k << " Sx=" << axes[0] << " Sy=" << axes[1] << endl;
+  slice.Print(cout,slice.Size());  cout << endl;
+}
+\end{verbatim}
+ 
 \subsection{SwFitsDataTable and other classes}
 \label{SwFitsDataTable}
@@ -2583,11 +2716,153 @@
 Depending on the configuration options during library build, only 
 transforms on double precision data might be available.
-
-\section{Multi-thread and parallel programming with Sophya} 
- 
+Usage example:
+\begin{verbatim}
+int nx=500, ny=500;
+TArray<r_8> img(nx, ny);
+// fill in the image 
+....
+// Compute Fourier transform of the image
+TArray< complex<r_8> > fourimg;
+FFTWServer ffts;                     
+ffts.setNormalize(true);  
+ffts.FFTForward(img, fourimg);
+// perform some filtering in Fourier domain
+// modifying the fourier coefficients fourimg
+...
+// Compute back the new (filtered) image
+TArray<r_8> img2(nx, ny);
+ffts.FFTBackward(fourimg, img2);
+\end{verbatim}
+
+\section{Multi-thread and parallel programming with SOPHYA} 
+ \label{mtpsop}
+A general introduction to parallel programming model in the Shared Memory multi-Processor
+systems and the POSIX thread model is well beyond the scope of this 
+document. Interested readers can find some introductory texts on the following 
+web pages:
+\begin{enumerate}
+\item Symmetric multiprocessing, \\
+\href{http://en.wikipedia.org/wiki/Symmetric\_multiprocessing } {http://en.wikipedia.org/wiki/Symmetric\_multiprocessing }
+\item POSIX Threads Tutorial {\it  Mark Hays, Software Interest Group }\\
+\href{ http://math.arizona.edu/\~swig/documentation/pthreads/ } {http://math.arizona.edu/\~swig/documentation/pthreads/} 
+\item POSIX Threads Programming {\it Blaise Barney, Lawrence Livermore National Laboratory } \\
+\href{ https://computing.llnl.gov/tutorials/pthreads/ } {https://computing.llnl.gov/tutorials/pthreads/  } 
+\end{enumerate} 
+In this section, we present some tips and example, focusing on the use of SOPHYA thread management classes. 
+Few examples of multithread programs using these classes can be found in the {\bf Tests} module : \\
+\hspace{10mm} {\tt zthr.cc  , tmtdt.cc , tmtrnd.cc }
+
+\subsection{General guidelines} 
+\begin{enumerate}
+\item In general, most classes in SOPHYA are inherently thread-safe, as they do not have global (static) data class 
+members and methods operate on instance data members. This is in particular the case of data objects 
+in SOPHYA: \\
+\tcls{NDataBlock}. \tcls{TArray}, Histo, DataTable, NTuple, \tcls{SphericalMap} \ldots \\
+This means that different instances of these classes can be used within threads without any precaution. 
+The SOPHYA reference sharing mechanism being itself thread safe. 
+\item Once the handlers have been registered, the SOPHYA persistence mechanism is in principle thread safe, 
+as long as I/O is performed on different files in different threads. Synchronisation through mutex should
+be implemented if the same PPF file (PInPersist/POutPersist object) is being used in different threads. 
+\item If you want to use the same NTuple or DataTable or SwPPFDataTable object in different threads, you have 
+to call the method {\tt SetThreadSafe()} on the corresponding object:
+\begin{verbatim}
+---> Set fg=true for thread safe operations 
+void NTuple::SetThreadSafe(bool fg);
+void BaseDataTable::SetThreadSafe(bool fg);  
+\end{verbatim}
+\item Some computation functions or classes in SOPHYA use currently global data and are not thread-safe.
+FFTPackServer, FFTWServer and SphericalTransform servers are not thread safe.  FFTWServer is not currently 
+thread safe as the creation of fftw\_plan is not thread safe in fftw library. 
+\item the cfitsio library is not thread safe, making the services of the FitsIOServer NON thread-safe 
+\item Many functions in the standard libraries are NOT thread-safe. This is the case of the usual random generators.
+Refer to section \ref{randgen} for using random generators in multi-thread applications.
+\end{enumerate}
+
+\subsection{Using ZThread and ZMutex }
+\begin{itemize}
+\item Define and implement a class inheriting from the {\bf ZThread} class (zthread.h). 
+This class should overwrite  the {\tt virtual void ZThread::run() } method of the base class 
+which has to perform the actual computation. 
+At the end of the computation in the {\tt run()} method, the {\tt setRC(int rc) } can be called to set 
+the return code of the thread object. 
+\item If the actual computation is performed by a function having a single {\tt void *} argument, 
+the ZThread base class can directly be used.  See the example in paragraph \ref{thrcls}. 
+\item The actual  thread is created by the {\tt start()} method. This method has to be called 
+on each  ZThread object to perform the computation. The {\tt start() } method return immediately 
+after the creation of the underlying thread object. 
+\item The method {\tt join() } can be used to wait for the thread termination.
+\item {\bf ZMutex} objects should be used to control to data (memory location) shared 
+by several threads.  These ZMutex objects would usually be attributes (data members) of the 
+ZThread objects or classes used by the ZThread objects.  Consider a variable {\tt int count }
+which is accessed by two different threads. Thread A changes (increment or decrement for example) 
+the value of {\tt count}, while thread B waits until {\tt count} reaches a given threshold, before 
+performing some actions and resetting {\tt count}. Access to {\tt count} should be protected by 
+a ZMutex object; The actual code would then look like:
+\begin{verbatim}
+// count and its associated ZMutex declaration 
+int count = 0;
+int threshold=10;
+ZMutex mex;
+.......
+// ----- Code executed by thread A 
+mex.lock();
+count++;
+mex.unlock();
+mex.signal();
+// Alternatively, mex.broadcast() can be called to wake up 
+// several threads waiting on the ZMutex condition variable
+.......
+// ----- Code executed by thread B
+mex.lock();
+while (count<threshold) mex.wait();
+// here, count has reached or exceeded the threshold
+// Do some action, and reset count
+count=0;
+mex.unlock();
+\end{verbatim} 
+\end{itemize}
+
+\subsection{Using ParallelExecutor }
+The {\bf ParallelExecutor } class (parlex.h) objects can be used to perform a computation divided into 
+parts which can be performed independently and in parallel in different threads. A typical 
+would be the application of a complex function to all elements in an array. 
+\begin{itemize}
+\item Define and implement a class inheriting from the {\bf ParallelTaskInterface} class. This class should 
+implement the pure virtual method {\tt int  execute(int tid)}. {\tt tid} is the thread identifier, or rank in the 
+set of parallel threads assigned to perform the computation. The first thread has a rank=0 and 
+{\tt ParallelTaskInterface::getNbParallelThreads() } method can be used to find the total 
+number of threads assigned to the task in the parallel execution context. 
+\item Create an {\bf ParallelExecutor} object passing to it the ParallelTask object and the number of
+threads, or alternatively, a vector of ParallelTask object pointers. 
+\item The set of threads are started by calling the {\tt ParallelExecutor::start() } method. The created threads
+will be in a waiting state, until the {\tt ParallelExecutor::execute() } is called.
+\item The call to {\tt execute() } triggers the execution of the {\tt ParallelTask::execute(tid) } methods
+for all of the parallel threads in the context. The {\tt execute() }  method returns when all the threads
+have finished executing the {\tt ParallelTask::execute(tid) } .
+\item The threads will then be again in a waiting state, ready for a new call to {\tt execute() }. 
+The threads will terminate when the  ParallelExecutor object is destroyed.
+\end{itemize}
+
+\begin{verbatim}
+// Class MyTask implements ParallelTaskInterface
+MyTask ptask(...);
+// Create a parallel execution context with 4 threads
+ParallelExecutor parex(ptask,4);
+// Start the threads 
+parex.start();
+// Loop over several data sets that 
+int NDS=5;
+for(int i=0; i<NDS; i++ {
+  // Prepare the data 
+  ...
+  // Do the parallel computation 
+  parex.execute();
+} 
+\end{verbatim}
+
 \newpage
 \section{Building and installing Sophya}
 \subsection{Supported platforms}
-Presently, the SOPHYA and PI libraries and tools has been compiled and tested with 
+Presently, the SOPHYA and PI libraries and tools have been compiled and tested with 
 the following compiler/platform pairs:
 
@@ -2645,5 +2920,5 @@
 {\tt \$SOPHYABASE} environment variable.
 
-\subsection{Build instructions} 
+\subsection{Build and install procedure} 
 \label{build}
 The build procedure has two main steps: 
@@ -2656,63 +2931,77 @@
 \end{enumerate}
 
-{\tt BuildMgr/configure } is a c-shell script with a number of arguments:
+{\tt BuildMgr/configure } is a c-shell script with a number of arguments. Please note
+ that this is NOT an autoconf generated script, but a custom c-shell script and it does 
+not create the makefiles.  The c-shell (or tcsh) must be accessible to run this script.  
 \begin{verbatim}
 csh> ./configure -h
 configure [-sbase SOPHYABASE] [-scxx SOPHYACXX] [-incln] 
   [-minc mymake.inc]  [-compopt 'cc/cxxOptions'] 
-  [-arch64] [-arch32] [-sasz64] [-ldble128] [-nofpic] [-nothsafe] [-boundcheck] [-sodebug]
-  [-extp dir1 -extp dir2 ...] [-extip dir1 -extip dir2 ... ] [-extlp dir1 -extlp dir2 ... ]
+  [-arch64] [-arch32] [-sasz64] [-ldble128] 
+  [-nofpic] [-nothsafe] [-boundcheck] [-sodebug]
+  [-extp dir1 -extp dir2 ...] [-extip dir1 -extip dir2 ... ]
+  [-extlp dir1 -extlp dir2 ... ] [-followlink] 
   [-noextlib] [-noext fits] [-noext fftw] [-noext lapack] [-noext astro]
-  [-noPI] [-slballinone]
   [-alsofftwfloat] [-usefftw2] [-uselapack2] 
+  [-wgrdl] [-epip mdir1 -epip mdir2 ...]  [-noPI] [-slballinone]
   (See SOPHYA manual/web pages for a detailed description of configure options)
 \end{verbatim}
 \begin{itemize}
-\item[] -sbase : define SOPHYA installation base directory. \$SOPHYABASE is used 
-if not specified.
-\item[] -scxx : selects the C++ compiler. \$SOPHYACXX  s used 
-if not specified.
-\item[] -incln : creates symbolic link for include files, instead of copying them. 
-\item[] -minc : give an explicit name for the file used to generate 
-\$SOPHYABASE/include/sophyamake.inc. If {\tt -minc} is not specified, one of
-the files in BuildMgr/ directory is selected, based on the system name and the 
-compiler {\tt  Linux\_g++\_make.inc , OSF1\_cxx\_make.inc , AIX\_xlC\_make.inc \ldots} 
-\item[] -compopt : additional compiler options \\[2mm]
-\item[] -arch64 : select/force 64 bits compilation mode. This is the default on 64 bits Linux systems and AIX.
-\item[] -arch32  : select/force 32 bits compilation mode. useful on 64 bits Linux systems or AIX
-\item[] -sasz64 : select 8 byte (64 bits) size for array indices, useful if you need to allocate an manipulate 
-large arrays, with more than $2^32$ elements along a single array dimension.
-\item[] -ldble128 : set the flags activating {\tt long double} (128 bits) arrays. \\[2mm]
-\item[] -nofpic : disable -fPIC (Position Independent Code) generation flag 
-\item[] -nothsafe : disable thread-safety procedures in SOPHYA : reference sharing \ldots. 
- ( activate the conditional compilation flag {\tt SO\_NOTHSAFE } )
-\item[] -boundcheck : compile SOPHYA and bound checking activated when accessing array elements
-( activate conditional compilation flag {\tt SO\_BOUNDCHECKING } )
-\item[] -sodebug : activate conditional compilation flag {\tt SOPHYA\_DEBUG }  \\[2mm]
-\item[] -extp : Adds the specied path to the search path of the external libraries 
-include files and archive library.
-\item[] -extip : Adds the specied path to the search path of the external libraries 
-include files.
-\item[] -extp : Adds the specied path to the search path of the external libraries 
-archive (libxxx.a).
-\item[] -noextlib : Disable compiling of modules referencing external libraries.
-\item[] -noext : Disable compiling of the specified module (with reference to external
-library : {\tt -noext fits , -noext fftw  -noext lapack -noext astro } \\[2mm]
-\item[] -usefftw2: Use FFTW V2 instead of the default FFTW V3 - A preprocessor
-flag will be defined in sspvflags.h 
-\item[] -uselapack2: Lapack V2 is being used (defaulr V3) - A preprocessor
-flag will be defined in sspvflags.h 
-\item[] -alsofftwfloat : compile single precision (float) version  of the Fourier 
+\item General parameters and options: \\[1mm]
+{\bf -sbase {\it path} }  define SOPHYA installation base directory. \$SOPHYABASE is used 
+if not specified \\
+{\bf -scxx {\it cmd} } selects the C++ compiler. \$SOPHYACXX  is used if not specified. \\
+{\bf -incln }  creates symbolic link for include files, instead of copying them. \\
+{\bf -minc {\it filename} } give an explicit name for the file used as the seed to create  the file \\
+{\tt \$SOPHYABASE/include/sophyamake.inc}. \hspace{2mm}
+If  -minc is not specified, one of the files in BuildMgr/ directory is selected, based on the 
+system name and the compiler: \\ 
+{\tt  Linux\_g++\_make.inc , OSF1\_cxx\_make.inc , AIX\_xlC\_make.inc \ldots}  \\
+{\bf -compopt {\it opt} } can be used to specify additional compiler options 
+\item Conditional compilation flags related to SOPHYA configuration (see {\tt machdefs.h} )\\[1mm]
+{\bf -arch64 }  select/force 64 bits compilation mode. This is the default on 64 bits Linux systems and AIX. \\
+{\bf -arch32  } select/force 32 bits compilation mode. useful on 64 bits Linux systems or AIX. \\
+{\bf -sasz64 } select 8 byte (64 bits) size for array indices, useful if you need to allocate an manipulate 
+large arrays, with more than $2^32$ elements along a single array dimension. \\
+{\bf -ldble128 } set the flags activating {\tt long double} (128 bits) arrays.  \\
+{\bf -nofpic } disable -fPIC (Position Independent Code) generation flag \\
+{\bf -nothsafe } disable thread-safety protection procedures in SOPHYA : reference sharing \ldots. 
+ ( activate the conditional compilation flag {\tt SO\_NOTHSAFE } ) \\
+{\bf -boundcheck } compile SOPHYA with bound checking activated when accessing array elements
+( conditional compilation flag {\tt SO\_BOUNDCHECKING } ) \\
+{\bf -sodebug } activate conditional compilation flag {\tt SOPHYA\_DEBUG } for debugging the library. 
+\item  External libraries \\[1mm]
+{\bf -extp {\it path} } Adds the specified path to the search path of the external libraries 
+include files and archive library. \\
+{\bf -extip {\it path} } Adds the specified path to the search path of the external libraries 
+include files. \\
+{\bf -extlp {\it path} } Adds the specified path to the search path of the external libraries 
+archive (libxxx.a). \\
+{\bf -followlink}  follow symbolic links when searching for include files and libraries
+(-L option of the find command). default: don't follow symbolic links. \\
+{\bf -noextlib } Disable compilation of all modules referencing external libraries. \\
+{\bf -noext {\it modname} }  Disable compiling of the specified module (with reference to external
+library : {\tt -noext fits , -noext fftw  -noext lapack -noext astro } \\
+{\bf -usefftw2 } Use FFTW V2 instead of the default FFTW V3 - A preprocessor
+flag will be defined in sspvflags.h \\
+{\bf -uselapack2 } Use Lapack V2 istead of the default V3 - A preprocessor
+flag will be defined in sspvflags.h \\
+{\bf -alsofftwfloat } compile single precision (float) version  of the Fourier 
 transform methods (module IFFTW, class FFTWServer). A preprocessor
 flag will be defined in sspvflags.h and float version of the FFTW library 
 (libfftw3f.a) will be linked with SOPHYA, in addition to the default double
-precision library (libfftw3.a).
-\item[] -noPI : has currently no effect 
-\item[] -slballinone: 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. 
+precision library (libfftw3.a). \\
+{\bf -slballinone}  Use of  a single shared library for all SOPHYA, PI and 
+external library interface modules. A compilation flag 
+will be defined in sspvflags.h . See also target {\tt slballinone} below. 
+\item PI and piapp specific options  \\[1mm]
+{\bf -wgrdl } compile and link piapp with GNU readline library \\
+{\bf -epip {\it path} }  Adds the specified path to the search path for include 
+files and libraries for Motif, and GNU readline, if applicable. \\
+{\bf  -noPI } ignore PI modules 
 \end{itemize}
 
-{\large \bf configure steps } \\[1mm]
+\subsubsection{Configure steps }
+
 The configure script performs the following actions :
 \begin{enumerate}
@@ -2729,5 +3018,5 @@
 \end{enumerate}
 
-{\large \bf Example } \\[1mm]
+\subsubsection{Compile and install, an example } 
 
 In the example below, we assume that we want to install Sophya from a 
@@ -2846,5 +3135,92 @@
 \end{itemize}
 
-
+\subsection{Test programs}
+The module {\bf Tests} contains a number of test programs:
+\begin{enumerate}
+\item  {\bf tobjio } tests part of SOPHYA persistence (PPF files) 
+\begin{verbatim}
+csh> tobjio A
+ ===> check the created file tobjio.ppf using scanppf 
+csh> scanppf tobjio.ppf
+csh> tobjio B
+ ===> OK if RC=0 
+\end{verbatim}
+\item {\bf arrt } and {\bf carrt} perform some checks on TArray modules, including I/O, 
+sub-array extraction, array conversion and memory organisation, as well as array operations.
+\begin{verbatim}
+csh> arrt check 
+csh> carrt ac
+csh> carrt oso 
+csh> carrt odo  
+ ===> OK if RC=0 
+csh> carrt ace
+ ===> OK if RC=9  (throw an exception)
+\end{verbatim}
+\item {\bf spar } is a TArray performance measurement tool 
+\begin{verbatim}
+csh> time spar 2 10 800 1000 
+csh> time spar 2 1000 80 100 
+\end{verbatim}
+\item {\bf tssqmx } checks DiagonalMatrix, SymmetricMatrix and LowerTriangularMatrix classes
+\begin{verbatim}
+csh> tssqmx d 
+csh> tssqmx s
+csh> tssqmx t
+ ===> OK if RC=0 
+\end{verbatim}
+\item  {\bf ttimestamp } and {\bf tnt } perform some checks on various SOPHYA objects ( DVList, TimeStamp, NTuple \ldots)
+\begin{verbatim}
+csh> ttimestamp 
+ ===> OK if RC=0 
+csh> tnt d 
+ ===> DVList test, check the output
+csh> tnt n 
+ ===> NTuple test, check the output
+csh> tnt DT 
+ ===> DataTable test, check the output
+csh> tnt DT 
+ ===> SwPPFDataTable test, check the output
+\end{verbatim}
+\item {\bf tfft } checks the operation of FFTPackServer and FFTWServer in 1D transforms
+\begin{verbatim}
+# FFTPackServer tests in double 
+csh> tfft 1531 P D 0 50 0.0002
+csh> tfft 1220 P D 0 50 0.0002
+ ===> OK if RC=0 
+# FFTPackServer tests in float 
+csh> tfft 1531 P F 0 50 0.0002
+csh> tfft 1220 P F 0 50 0.0002
+ ===> OK if RC=0 
+# FFTWServer tests in double 
+csh> tfft 1531 W D 0 50 0.0002
+csh> tfft 1220 W D 0 50 0.0002
+ ===> OK if RC=0 
+\end{verbatim}
+\item {\bf lpk} checks the LinAlg interface module
+\begin{verbatim}
+csh> lpk inverse 100,100 0
+ ===> OK if RC=0 
+csh> lpk linsolve 100,100 0
+ ===> OK if RC=0 
+csh> lpk lss 100,50 0
+ ===> OK if RC=0 
+csh> lpk svd 100,50 0
+ ===> OK if RC=0 
+## These checks can be combined in a single call to lpk 
+csh> lpk all 100,50 0
+\end{verbatim}
+\item {\bf tmtdt } tests several aspects of SOPHYA : threads (ZThread, ZMutex \ldots), DataTables \ldots 
+\begin{verbatim}
+csh> tmtdt NT 50000 2
+ ===> OK if RC=0 
+csh> tmtdt DT 50000 2
+ ===> OK if RC=0 
+csh> tmtdt SWPPF 50000 2
+ ===> OK if RC=0 
+# cfitsio is NOT thread safe, test SwFitsDataTable with a single thread
+csh> tmtdt SWFITS 50000 1
+\end{verbatim}
+
+\end{enumerate}
 
 \newpage
