Changeset 3856 in Sophya


Ignore:
Timestamp:
Aug 12, 2010, 1:03:17 AM (15 years ago)
Author:
ansari
Message:

Derniers ajouts ds document sophya.tex (user's guide) pour V=2.2, Reza 12/08/2010

Location:
trunk/SophyaLib/Manual
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/SophyaLib/Manual/modifs.tex

    r3817 r3856  
    6565V = 2.140  &   \hspace{10mm}  &  Sept-Oct 2009 - NO tag  \\
    6666V = 2.150  &   \hspace{10mm}  &  Mars 2010 - NO tag  \\
     67V = 2.2  &   \hspace{10mm}  &  Septembre 2010 - tag CVS \\
    6768
    6869\end{tabular}
    … …  
    9394\titre{BuildMgr}
    9495\begin{itemize}
    95 \item[\rond] Juillet 2010 : Ajout de l'option {\tt -arch32} de compilation en 32 bits pour linux
     96\item[\rond] Juillet/Aout 2010 : Ajout des options et arguments suivants au script configure
     97\begin{verbatim}
     98 -arch32 de compilation en 32 bits pour linux
     99 -followlink pour suivi des liens symboliques lors des recherches
     100     de fichiers par find. Pas de suivi des liens par defaut
     101 -epip pour chemin de librairies et include file PI (Motif ...)
     102 -wgrdl activation compil et link piapp avec GNU-readline
     103\end{verbatim}
     104 {\tt -arch32} de compilation en 32 bits pour linux
    96105\item[\rond] Mars 2010 : Ajout de l'option {\tt -ldble128} dans le script configure pour la gestion conditionnelle
    97106du flag compilation {\bf SO\_LDBLE128 } dans machdefs.h.  Ce flag active la dŽclaration des nombres en
    … …  
    176185\titre{NTools}
    177186\begin{itemize}
     187\item[rond] Aout 2010 : Ajout de la classe d'interpolation lineaire {\bf SLinInterp1D} et programme
     188test Tests/tstinterp.cc
    178189\item[\rond] Oct 2008 : Instanciation explicite des classes 
    179190\tcls{Image} et \tcls{ArrayFitter} pour T=uint\_4, uint\_8

  • trunk/SophyaLib/Manual/sophya.tex

    r3839 r3856  
    3131\newcommand{\carre}{$\Box \ $}
    3232
     33\newcommand{\bitem}[1]{\item[]{\bf #1} }
    3334
    3435\begin{document}
    … …  
    3637\begin{titlepage}
    3738%  The title page - top of the page with the title of the paper
    38 \titrehp{Sophya  \\ An overview }
     39\titrehp{SOPHYA user's guide }
    3940%  Authors list
    4041\auteurs{
    … …  
    4849\vspace{1cm}
    4950\begin{center}
    50 {\bf \Large Sophya Version: 2.2 (V\_Sep2010) }
     51{\bf \Large SOPHYA Version: 2.2 (V\_Sep2010) }
    5152\end{center}
    5253\titrebp{1}
    … …  
    149150\item[] {\bf SysTools/} This module contains classes implementing
    150151an interface to various OS specific services, such
    151 threads and dynamic link/shared library handling.
     152as threads and dynamic link/shared library handling.
    152153
    153154\end{itemize}
    … …  
    190191SOPHYA library.
    191192\begin{itemize}
    192 \item[] {\bf Tests/} Simple test programs. Many of these test programs can be also used
    193 as examples for using SOPHYA.
     193\item[] {\bf Tests/} Simple test programs. Many of these test programs can also be
     194used as examples for using SOPHYA.
    194195\item[] {\bf PrgUtil/} Various utility programs (runcxx, scanppf, scanfits, \ldots)
    195196\item[] {\bf PrgMap/} Programs performing operations on skymaps: projections,
    … …  
    225226\item[] {\bf DemoPIApp/} Sample scripts and programs for (s)piapp
    226227interactive analysis tools.
     228\item[] {\bf DemoData/} data files (PPF, FITS \ldots) useful for the (s)piapp
     229user's manual examples.
    227230\end{itemize}   
    228231
    229 The following modules contains additional programs or libraries, based on SOPHYA :
     232The following modules contains additional programs or libraries, which rely on SOPHYA:
    230233\begin{itemize}
    231234\item[] {\bf AnaLC} contains program files extracted from the EROS/PEIDA software
    232235and adapted to be compiled with SOPHYA. It can be used in particular to read and analyse
    233 EROS light curve data files.
    234 \item[] {\bf LUC} {\bf L}ittle {\bf U}niverse {\bf C}alculator is a module containing classes to
     236EROS light curve data files (fichiers de suivi).
     237\item[] {\bf LUC}  ( {\bf L}ittle {\bf U}niverse {\bf C}alculator) is a module containing classes to
    235238perform basic computation related to the universe geometry (FRW metric).
     239\item[] {\bf SimLSS} Tools for the {\bf Sim}ulation and analysis of cosmological
     240{\bf L}arge {\bf S}cale {\bf S}tructures
     241\item[] {\bf PIPhoto} is an interface module for (s)piapp and ImageMagick for
     242import/export of graphics in image format (jpeg, gif \ldots) in piapp.
    236243\item[] {\bf PMixer/} skymixer and related programs. This module is {\bf obsolete}.
    237244\end{itemize}
    … …  
    360367classes / methods in SOPHYA. \\
    361368A major exception is the reference sharing mechanism, where different instances
    362 of a class may  shared memory locations. This reference sharing mechanism has been
     369of a class may  share memory locations. This reference sharing mechanism has been
    363370made thread-safe in SOPHYA, from version V=2.1. \\
    364371As a consequence, different execution threads can access non overlapping sub-arrays
    … …  
    367374NTuple and DataTable objects can be activated, on an object per object basis. \\
    368375The {\tt ZThread, ZMutex \ldots} classes in the {\bf SysTools } module offer a relatively
    369 easy way of writing multi-threaded programs.   
     376easy way of writing multi-threaded programs (See \ref{mtpsop}).
    370377
    371378\subsection{the runcxx program}
    … …  
    848855 
    849856 \subsection{Pseudo-random number generators}
    850  \index{Random numbers}
     857 \index{Random numbers}  \label{randgen}
    851858\begin{figure}[hbt]
    852859\dclsbb{ AnyDataObj }{ RandomGeneratorInterface }
    … …  
    937944int N = 10;
    938945// B.2- Compute and print a sequence of random number,
    939 //      should be compared to the sequance A.5
     946//      should be compared to the sequence A.5
    940947for(int i=0; i<N; i++)
    941948  cout << "-- I=" << i << "  rand_flat01= " << rgr.Flat01()
    … …  
    971978\item Capability to handle {\bf large - multidimensional - dense}
    972979arrays, for numerical data types. Although we have used templates, for
    973 data type specialisation, the actual code, apart inline functions is
    974 not in header files. Instead, we use explicit instanciation, and the
     980data type specialisation, the actual code, apart from inline functions is
     981not in the header files. Instead, we use explicit instanciation, and the
    975982compiled code for the various numerical types of arrays is the
    976983library .
    … …  
    11251132The services provided in other modules, such as {\bf LinAlg} should
    11261133be preferred in such cases.
     1134
     1135\subsubsection{TVectors and std::vector}
     1136SOPHYA \tcls{TVector} objects can be constructed or filled from \tcls{std::vector} objects.
     1137TVector objects can also be converted to std::vector.
     1138\begin{verbatim}
     1139TVector(const vector<T>& v, short lcv=BaseArray::AutoVectorType);
     1140TVector<T>::FillFr(const vector<T>& v,bool noresize=false);
     1141TVector<T>::FillTo(vector<T>& v,bool addtoend=false);
     1142\end{verbatim}
     1143
     1144In addition, \tcls{std::vector} objects can be written to, read from PPF streams
     1145through the class \tcls{PPFWrapperSTLVector} (file ppfwrapstlv.h). The std::vector
     1146PPF handler is currently registered  for the following data types: \\
     1147\hspace*{5mm} {\tt string, int\_2, uint\_2, int\_4, uint\_4, int\_8, uint\_8 } \\
     1148\hspace*{5mm} {\tt r\_4 , r\_8, complex$<$r\_4$>$ ,  complex$<$r\_8$>$ }
    11271149
    11281150\subsection{Working with sub-arrays and Ranges}
    … …  
    16951717(float/double).They are arranged in columns. Each line is often called an event.
    16961718These objects are frequently used to analyze data.
    1697 The piapp graphicals tools can plot a column against an other one
    1698 with respect to various selection cuts. \\
     1719The piapp interactive analysis tool can be used to create 1D, 2D and 3D plots using the date from
     1720NTuples and DataTables. \\
    16991721Here is an example of creation and filling~:
    17001722\begin{verbatim}
    … …  
    18181840\end{verbatim}
    18191841   
    1820 \subsection{Writing, viewing \dots }
     1842\subsection{Persistence and visualisation }
    18211843%%
    18221844Histogram and NTuple/DataTable objects have PPF handlers and
    1823 can be written to or read from PPF files. Sophya graphical tool (spiapp) can
    1824 automatically display and operate on all these objects.
     1845can be written to or read from PPF files. Sophya interactive analysis tool
     1846(spiapp) can automatically display and operate on all of these objects.
    18251847The following example shows how to write the previously created objects
    18261848into such a file~:
    … …  
    18421864fitting, sorting and ODE solving. FFTs are also provided (Mayer,FFTPack).
    18431865
    1844 \subsection{Fitting}
     1866\subsection{Optimisation and parameter fitting}
     1867\subsubsection{GeneralFit: non linear fitting}
    18451868\index{Fitting} \index{Minimisation}
    18461869Fitting is done with two classes {\tt GeneralFit} and {\tt GeneralFitData}
    … …  
    19081931in the HTML pages of the Sophya manual.
    19091932
    1910 \subsection{Simplex method}
     1933\subsubsection{Simplex method}
    19111934The class {\bf MinZSimplex} implements the simplex method for non linear
    1912 optimization / minimization. See the SOPHYA manual for more information.
     1935optimization / minimization. See the SOPHYA reference manual and the
     1936Tests/tsimplex.cc for more information.
     1937
     1938\subsection{Interpolation}
     1939\index{Interpolation} \index{SLinInterp1D}
     1940The class {\bf SLinInterp1D} (file slininterp.h) can be used for linear 1D interpolation.
     1941\begin{verbatim}
     1942#include "slininterp.h"
     1943#include "srandgen.h"
     1944  ...
     1945vector<double> ys;
     1946double xmin = 0.5;
     1947double xmax = 0.;
     1948for(int i=0; i<=12; i++) {
     1949  xmax = xmin+i*0.1;
     1950  yreg.push_back(sin(xmax)*cos(2.2*xmax));
     1951}
     1952SLinInterp1D interpYR(xmin, xmax, yreg);
     1953cout << interpYR
     1954for(int i=0; i<=12; i++) {
     1955  double x = drand01()*2.;
     1956  cout << " Interpol result for X=" << x << " -> " << interpYR(x)
     1957       << " ?= " << sin(x)*cos(2.2*x) << endl;
     1958}
     1959\end{verbatim}
     1960The {\bf CSpline} and {\bf CSpline2} classes perform one dimensional and two dimensional spline interpolation.
    19131961
    19141962\subsection{Polynomial}
    … …  
    20642112
    20652113\subsection{Thread management classes}
    2066 \index{ZThread} \index{ZMutex}
     2114\index{ZThread} \index{ZMutex}  \label{thrcls}
    20672115A basic interface to POSIX threads is also provided
    20682116through the \index{threads} {\bf ZThread}, {\bf ZMutex} and {\bf ZSync}
    … …  
    20792127  zt1.setAction(fun1, arg[1]);
    20802128  ZThread zt2;
    2081   zt2.setAction(fun2, arg[1]);
     2129  zt2.setAction(fun2, arg[2]);
    20822130  cout << " Starting threads ... " << endl;
    20832131  zt1.start();
    … …  
    20882136\end{verbatim}
    20892137The classes {\bf ZMutex} \index{mutex} and {\bf ZSync} can be used
    2090 to perform synchronisation and signaling between threads.
    2091 Example multithread programs using these classes can be found in
    2092 the {\bf Tests} module : \\
    2093 \hspace{10mm} {\tt zthr.cc  , tmtdt.cc , tmtrnd.cc }
     2138to perform synchronisation and signaling between threads. Each {\bf ZMutex} object
     2139contains a pair of mutex and condition variable.
     2140The {\bf ParallelExecutor } class can be used for parallel simultaneous execution
     2141of several function of objects inheriting from {\bf  ParallelTaskInterface}.
     2142Some hints about parallel programming and usage of these classes can be found in
     2143\index{ParallelExecutor} \index{ ParallelTaskInterface }
     2144\ref{mtpsop}.
    20942145
    20952146\begin{figure}[hbt]
     2147\dclsa{ParallelExecutor}
     2148\dclsbb{ParallelTaskInterface}{ParallelTaskFunction}
    20962149\dclsbb{ZThread}{ParalExThread}
    2097 \dclsa{ParallelExecutor}
     2150\dclsa{ZMutex}
    20982151\end{figure}
    2099 %%  CHECK
    2100 {\bf \large DECRIRE l'utilisation des nouvelles classes ParallelExecutor ... }
     2152
    21012153
    21022154\subsection{Dynamic linker and C++ compiler classes}
    … …  
    21502202The command language provides variable manipulation through the usual
    21512203{\tt \$varname} vector variable and arithmetic expression extensions, as well
    2152 as the control and test blocs.
     2204as the control and test blocs. A description of this command interpreter syntax
     2205and possibilities can be found in the (s)piapp user's guide.
    21532206\begin{verbatim}
    21542207#include "commander.h"
    … …  
    22772330\end{verbatim}
    22782331
    2279 \subsection{Writing, viewing \dots }
    2280 
    2281 All these objects have been design to be written to or read from a persistant file.
    2282 The following example shows how to write the previously created objects
     2332\subsection{Persistence and visualisation }
     2333The different SkyMap objects have PPF handlers and written to or read from PPF files.
     2334The following example shows how to save the previously created objects
    22832335into such a file~:
    22842336\begin{verbatim}
    … …  
    23002352\end{verbatim}
    23012353
    2302 Sophya graphical tools (spiapp) can automatically display and operate
    2303 all these objects.
     2354Sophya interactive analysis tool (spiapp) can automatically display and operate
     2355on SkyMap objects.
    23042356
    23052357\newpage
    … …  
    23332385\subsection{Module SkyT}
    23342386\index{RadSpectra} \index{SpectralResponse}
     2387\begin{center}
     2388{\bf \large THIS MODULE NEEDS EXTENSIVE CHECKING/DEBUGGING AND REDESIGN }
     2389\end{center}
    23352390The SkyT module is composed of two types of classes:
    23362391\begin{itemize}
    … …  
    24322487\begin{enumerate}
    24332488\item Saving an array and a HealPix map to a Fits file
     2489\index{HEALPix-FITS}
    24342490\begin{verbatim}
    24352491#include "fitsioserver.h"
    … …  
    24822538%%%
    24832539\item DataTable objects can be read from and written to FITS files as ASCII or
    2484 binary tables. The example belo show reading the DataTable created in the example
     2540binary tables. The example below show reading the DataTable created in the example
    24852541in section \ref{datatables} from a PPF file and saving it to a fits file.
     2542\index{DataTable-FITS}
    24862543\begin{verbatim}
    24872544#include "swfitsdtable.h"
    … …  
    25132570\end{figure}
    25142571
     2572\subsection{Fits Array I/O in chunk }
     2573Array read/write from/to FITS files (Image HDU) is rather straightforward, in particular thanks to
     2574the overloaded stream operators, as in the examples given above and here:
     2575\index{Array-FITS}
     2576\begin{verbatim}
     2577//  ---- Writing an array to fits file
     2578//  Create and open a fits file named myfile.fits
     2579FitsInOutFile fos("!myarr.fits", FitsInOutFile ::Fits_Create);
     2580TArray<r_8> a(50,30);
     2581// ... fill the array
     2582// Write the array to file
     2583fos << a;
     2584
     2585// ---- Reading an array from file myarr.fits
     2586// Open the fits file for reading
     2587FitsInOutFile fis("myarr.fits", FitsInOutFile::Fits_RO);
     2588TArray<r_8> a;
     2589// Read in the array
     2590fis >> a;
     2591\end{verbatim}
     2592
     2593It is also possible to write arrays FITS Image HDU in chunks  or read arrays in chunk,
     2594using the following methods : \\
     2595\begin{verbatim}
     2596void FitsArrayHandler<T>::ReadAtOffset(FitsInOutFile& is, sa_size_t* offset);
     2597void FitsArrayHandler<T>::WriteAtOffset(FitsInOutFile& os, sa_size_t* offset);
     2598\end{verbatim}
     2599The sample code below show how a FITS file corresponding to a 3D data cube of $5\times4\times3$  elements
     2600can be created and written as a series of 2D slices:
     2601\begin{verbatim}
     2602// Make sure FitsIOServer module is initialised :
     2603FitsIOServerInit();
     2604// Open/create the output file, named mycube.fits (overwrite it)
     2605FitsInOutFile fos("!mycube.fits", FitsInOutFile ::Fits_Create);
     2606// Define the cube size
     2607LONGLONG size[3] = {5,4,3};
     2608// Create a 2D array corresponding to an x-y cube slice
     2609TArray<int_4> slice(size[0], size[1]);
     2610// Create an IMAGE HDU: cube size and slice data type
     2611fos.CreateImageHDU(FitsTypes::ImageType(slice(0,0)), 3, size);
     2612// initialize the array content
     2613slice = RegularSequence();
     2614// Create a Fits handler for the array
     2615FitsArrayHandler<int_4> fh(slice);
     2616// Write the 3 slices to the file
     2617sa_size_t offset[3];
     2618offset[0]=0; offset[1]=0;
     2619for(int k=0;k<size[2]; k++) {
     2620  slice += (int_4)(k*100);
     2621  offset[2]=k;
     2622  fh.WriteAtOffset(fos,offset);
     2623}
     2624\end{verbatim}
     2625The example below show how to read arrays from Image HDU in chunk:
     2626\begin{verbatim}
     2627// Make sure FitsIOServer module is initialised :
     2628FitsIOServerInit();
     2629// Open the existing file mycube.fits for reading
     2630FitsInOutFile fis("mycube.fits", FitsInOutFile::Fits_RO);
     2631// Get the array size
     2632int naxis=BASEARRAY_MAXNDIMS;
     2633LONGLONG axes[BASEARRAY_MAXNDIMS];
     2634fis.GetImageHDUInfo(naxis, axes);
     2635// Read in the data as 2D slices
     2636TArray<int_4> slice(axes[0], axes[1]);
     2637FitsArrayHandler<int_4> fh(slice);
     2638sa_size_t offset[3];
     2639offset[0]=0; offset[1]=0;
     2640for(int k=0;k<axes[2]; k++) {
     2641  offset[2]=k;
     2642  fh.ReadAtOffset(fis,offset);
     2643  cout << " Slice k=" << k << " Sx=" << axes[0] << " Sy=" << axes[1] << endl;
     2644  slice.Print(cout,slice.Size());  cout << endl;
     2645}
     2646\end{verbatim}
     2647 
    25152648\subsection{SwFitsDataTable and other classes}
    25162649\label{SwFitsDataTable}
    … …  
    25832716Depending on the configuration options during library build, only
    25842717transforms on double precision data might be available.
    2585 
    2586 \section{Multi-thread and parallel programming with Sophya}
    2587  
     2718Usage example:
     2719\begin{verbatim}
     2720int nx=500, ny=500;
     2721TArray<r_8> img(nx, ny);
     2722// fill in the image
     2723....
     2724// Compute Fourier transform of the image
     2725TArray< complex<r_8> > fourimg;
     2726FFTWServer ffts;                     
     2727ffts.setNormalize(true); 
     2728ffts.FFTForward(img, fourimg);
     2729// perform some filtering in Fourier domain
     2730// modifying the fourier coefficients fourimg
     2731...
     2732// Compute back the new (filtered) image
     2733TArray<r_8> img2(nx, ny);
     2734ffts.FFTBackward(fourimg, img2);
     2735\end{verbatim}
     2736
     2737\section{Multi-thread and parallel programming with SOPHYA}
     2738 \label{mtpsop}
     2739A general introduction to parallel programming model in the Shared Memory multi-Processor
     2740systems and the POSIX thread model is well beyond the scope of this
     2741document. Interested readers can find some introductory texts on the following
     2742web pages:
     2743\begin{enumerate}
     2744\item Symmetric multiprocessing, \\
     2745\href{http://en.wikipedia.org/wiki/Symmetric\_multiprocessing } {http://en.wikipedia.org/wiki/Symmetric\_multiprocessing }
     2746\item POSIX Threads Tutorial {\it  Mark Hays, Software Interest Group }\\
     2747\href{ http://math.arizona.edu/\~swig/documentation/pthreads/ } {http://math.arizona.edu/\~swig/documentation/pthreads/}
     2748\item POSIX Threads Programming {\it Blaise Barney, Lawrence Livermore National Laboratory } \\
     2749\href{ https://computing.llnl.gov/tutorials/pthreads/ } {https://computing.llnl.gov/tutorials/pthreads/  }
     2750\end{enumerate}
     2751In this section, we present some tips and example, focusing on the use of SOPHYA thread management classes.
     2752Few examples of multithread programs using these classes can be found in the {\bf Tests} module : \\
     2753\hspace{10mm} {\tt zthr.cc  , tmtdt.cc , tmtrnd.cc }
     2754
     2755\subsection{General guidelines}
     2756\begin{enumerate}
     2757\item In general, most classes in SOPHYA are inherently thread-safe, as they do not have global (static) data class
     2758members and methods operate on instance data members. This is in particular the case of data objects
     2759in SOPHYA: \\
     2760\tcls{NDataBlock}. \tcls{TArray}, Histo, DataTable, NTuple, \tcls{SphericalMap} \ldots \\
     2761This means that different instances of these classes can be used within threads without any precaution.
     2762The SOPHYA reference sharing mechanism being itself thread safe.
     2763\item Once the handlers have been registered, the SOPHYA persistence mechanism is in principle thread safe,
     2764as long as I/O is performed on different files in different threads. Synchronisation through mutex should
     2765be implemented if the same PPF file (PInPersist/POutPersist object) is being used in different threads.
     2766\item If you want to use the same NTuple or DataTable or SwPPFDataTable object in different threads, you have
     2767to call the method {\tt SetThreadSafe()} on the corresponding object:
     2768\begin{verbatim}
     2769---> Set fg=true for thread safe operations
     2770void NTuple::SetThreadSafe(bool fg);
     2771void BaseDataTable::SetThreadSafe(bool fg); 
     2772\end{verbatim}
     2773\item Some computation functions or classes in SOPHYA use currently global data and are not thread-safe.
     2774FFTPackServer, FFTWServer and SphericalTransform servers are not thread safe.  FFTWServer is not currently
     2775thread safe as the creation of fftw\_plan is not thread safe in fftw library.
     2776\item the cfitsio library is not thread safe, making the services of the FitsIOServer NON thread-safe
     2777\item Many functions in the standard libraries are NOT thread-safe. This is the case of the usual random generators.
     2778Refer to section \ref{randgen} for using random generators in multi-thread applications.
     2779\end{enumerate}
     2780
     2781\subsection{Using ZThread and ZMutex }
     2782\begin{itemize}
     2783\item Define and implement a class inheriting from the {\bf ZThread} class (zthread.h).
     2784This class should overwrite  the {\tt virtual void ZThread::run() } method of the base class
     2785which has to perform the actual computation.
     2786At the end of the computation in the {\tt run()} method, the {\tt setRC(int rc) } can be called to set
     2787the return code of the thread object.
     2788\item If the actual computation is performed by a function having a single {\tt void *} argument,
     2789the ZThread base class can directly be used.  See the example in paragraph \ref{thrcls}.
     2790\item The actual  thread is created by the {\tt start()} method. This method has to be called
     2791on each  ZThread object to perform the computation. The {\tt start() } method return immediately
     2792after the creation of the underlying thread object.
     2793\item The method {\tt join() } can be used to wait for the thread termination.
     2794\item {\bf ZMutex} objects should be used to control to data (memory location) shared
     2795by several threads.  These ZMutex objects would usually be attributes (data members) of the
     2796ZThread objects or classes used by the ZThread objects.  Consider a variable {\tt int count }
     2797which is accessed by two different threads. Thread A changes (increment or decrement for example)
     2798the value of {\tt count}, while thread B waits until {\tt count} reaches a given threshold, before
     2799performing some actions and resetting {\tt count}. Access to {\tt count} should be protected by
     2800a ZMutex object; The actual code would then look like:
     2801\begin{verbatim}
     2802// count and its associated ZMutex declaration
     2803int count = 0;
     2804int threshold=10;
     2805ZMutex mex;
     2806.......
     2807// ----- Code executed by thread A
     2808mex.lock();
     2809count++;
     2810mex.unlock();
     2811mex.signal();
     2812// Alternatively, mex.broadcast() can be called to wake up
     2813// several threads waiting on the ZMutex condition variable
     2814.......
     2815// ----- Code executed by thread B
     2816mex.lock();
     2817while (count<threshold) mex.wait();
     2818// here, count has reached or exceeded the threshold
     2819// Do some action, and reset count
     2820count=0;
     2821mex.unlock();
     2822\end{verbatim}
     2823\end{itemize}
     2824
     2825\subsection{Using ParallelExecutor }
     2826The {\bf ParallelExecutor } class (parlex.h) objects can be used to perform a computation divided into
     2827parts which can be performed independently and in parallel in different threads. A typical
     2828would be the application of a complex function to all elements in an array.
     2829\begin{itemize}
     2830\item Define and implement a class inheriting from the {\bf ParallelTaskInterface} class. This class should
     2831implement the pure virtual method {\tt int  execute(int tid)}. {\tt tid} is the thread identifier, or rank in the
     2832set of parallel threads assigned to perform the computation. The first thread has a rank=0 and
     2833{\tt ParallelTaskInterface::getNbParallelThreads() } method can be used to find the total
     2834number of threads assigned to the task in the parallel execution context.
     2835\item Create an {\bf ParallelExecutor} object passing to it the ParallelTask object and the number of
     2836threads, or alternatively, a vector of ParallelTask object pointers.
     2837\item The set of threads are started by calling the {\tt ParallelExecutor::start() } method. The created threads
     2838will be in a waiting state, until the {\tt ParallelExecutor::execute() } is called.
     2839\item The call to {\tt execute() } triggers the execution of the {\tt ParallelTask::execute(tid) } methods
     2840for all of the parallel threads in the context. The {\tt execute() }  method returns when all the threads
     2841have finished executing the {\tt ParallelTask::execute(tid) } .
     2842\item The threads will then be again in a waiting state, ready for a new call to {\tt execute() }.
     2843The threads will terminate when the  ParallelExecutor object is destroyed.
     2844\end{itemize}
     2845
     2846\begin{verbatim}
     2847// Class MyTask implements ParallelTaskInterface
     2848MyTask ptask(...);
     2849// Create a parallel execution context with 4 threads
     2850ParallelExecutor parex(ptask,4);
     2851// Start the threads
     2852parex.start();
     2853// Loop over several data sets that
     2854int NDS=5;
     2855for(int i=0; i<NDS; i++ {
     2856  // Prepare the data
     2857  ...
     2858  // Do the parallel computation
     2859  parex.execute();
     2860}
     2861\end{verbatim}
     2862
    25882863\newpage
    25892864\section{Building and installing Sophya}
    25902865\subsection{Supported platforms}
    2591 Presently, the SOPHYA and PI libraries and tools has been compiled and tested with
     2866Presently, the SOPHYA and PI libraries and tools have been compiled and tested with
    25922867the following compiler/platform pairs:
    25932868
    … …  
    26452920{\tt \$SOPHYABASE} environment variable.
    26462921
    2647 \subsection{Build instructions}
     2922\subsection{Build and install procedure}
    26482923\label{build}
    26492924The build procedure has two main steps:
    … …  
    26562931\end{enumerate}
    26572932
    2658 {\tt BuildMgr/configure } is a c-shell script with a number of arguments:
     2933{\tt BuildMgr/configure } is a c-shell script with a number of arguments. Please note
     2934 that this is NOT an autoconf generated script, but a custom c-shell script and it does
     2935not create the makefiles.  The c-shell (or tcsh) must be accessible to run this script. 
    26592936\begin{verbatim}
    26602937csh> ./configure -h
    26612938configure [-sbase SOPHYABASE] [-scxx SOPHYACXX] [-incln]
    26622939  [-minc mymake.inc]  [-compopt 'cc/cxxOptions']
    2663   [-arch64] [-arch32] [-sasz64] [-ldble128] [-nofpic] [-nothsafe] [-boundcheck] [-sodebug]
    2664   [-extp dir1 -extp dir2 ...] [-extip dir1 -extip dir2 ... ] [-extlp dir1 -extlp dir2 ... ]
     2940  [-arch64] [-arch32] [-sasz64] [-ldble128]
     2941  [-nofpic] [-nothsafe] [-boundcheck] [-sodebug]
     2942  [-extp dir1 -extp dir2 ...] [-extip dir1 -extip dir2 ... ]
     2943  [-extlp dir1 -extlp dir2 ... ] [-followlink]
    26652944  [-noextlib] [-noext fits] [-noext fftw] [-noext lapack] [-noext astro]
    2666   [-noPI] [-slballinone]
    26672945  [-alsofftwfloat] [-usefftw2] [-uselapack2]
     2946  [-wgrdl] [-epip mdir1 -epip mdir2 ...]  [-noPI] [-slballinone]
    26682947  (See SOPHYA manual/web pages for a detailed description of configure options)
    26692948\end{verbatim}
    26702949\begin{itemize}
    2671 \item[] -sbase : define SOPHYA installation base directory. \$SOPHYABASE is used
    2672 if not specified.
    2673 \item[] -scxx : selects the C++ compiler. \$SOPHYACXX  s used
    2674 if not specified.
    2675 \item[] -incln : creates symbolic link for include files, instead of copying them.
    2676 \item[] -minc : give an explicit name for the file used to generate
    2677 \$SOPHYABASE/include/sophyamake.inc. If {\tt -minc} is not specified, one of
    2678 the files in BuildMgr/ directory is selected, based on the system name and the
    2679 compiler {\tt  Linux\_g++\_make.inc , OSF1\_cxx\_make.inc , AIX\_xlC\_make.inc \ldots}
    2680 \item[] -compopt : additional compiler options \\[2mm]
    2681 \item[] -arch64 : select/force 64 bits compilation mode. This is the default on 64 bits Linux systems and AIX.
    2682 \item[] -arch32  : select/force 32 bits compilation mode. useful on 64 bits Linux systems or AIX
    2683 \item[] -sasz64 : select 8 byte (64 bits) size for array indices, useful if you need to allocate an manipulate
    2684 large arrays, with more than $2^32$ elements along a single array dimension.
    2685 \item[] -ldble128 : set the flags activating {\tt long double} (128 bits) arrays. \\[2mm]
    2686 \item[] -nofpic : disable -fPIC (Position Independent Code) generation flag
    2687 \item[] -nothsafe : disable thread-safety procedures in SOPHYA : reference sharing \ldots.
    2688  ( activate the conditional compilation flag {\tt SO\_NOTHSAFE } )
    2689 \item[] -boundcheck : compile SOPHYA and bound checking activated when accessing array elements
    2690 ( activate conditional compilation flag {\tt SO\_BOUNDCHECKING } )
    2691 \item[] -sodebug : activate conditional compilation flag {\tt SOPHYA\_DEBUG }  \\[2mm]
    2692 \item[] -extp : Adds the specied path to the search path of the external libraries
    2693 include files and archive library.
    2694 \item[] -extip : Adds the specied path to the search path of the external libraries
    2695 include files.
    2696 \item[] -extp : Adds the specied path to the search path of the external libraries
    2697 archive (libxxx.a).
    2698 \item[] -noextlib : Disable compiling of modules referencing external libraries.
    2699 \item[] -noext : Disable compiling of the specified module (with reference to external
    2700 library : {\tt -noext fits , -noext fftw  -noext lapack -noext astro } \\[2mm]
    2701 \item[] -usefftw2: Use FFTW V2 instead of the default FFTW V3 - A preprocessor
    2702 flag will be defined in sspvflags.h
    2703 \item[] -uselapack2: Lapack V2 is being used (defaulr V3) - A preprocessor
    2704 flag will be defined in sspvflags.h
    2705 \item[] -alsofftwfloat : compile single precision (float) version  of the Fourier
     2950\item General parameters and options: \\[1mm]
     2951{\bf -sbase {\it path} }  define SOPHYA installation base directory. \$SOPHYABASE is used
     2952if not specified \\
     2953{\bf -scxx {\it cmd} } selects the C++ compiler. \$SOPHYACXX  is used if not specified. \\
     2954{\bf -incln }  creates symbolic link for include files, instead of copying them. \\
     2955{\bf -minc {\it filename} } give an explicit name for the file used as the seed to create  the file \\
     2956{\tt \$SOPHYABASE/include/sophyamake.inc}. \hspace{2mm}
     2957If  -minc is not specified, one of the files in BuildMgr/ directory is selected, based on the
     2958system name and the compiler: \\
     2959{\tt  Linux\_g++\_make.inc , OSF1\_cxx\_make.inc , AIX\_xlC\_make.inc \ldots}  \\
     2960{\bf -compopt {\it opt} } can be used to specify additional compiler options
     2961\item Conditional compilation flags related to SOPHYA configuration (see {\tt machdefs.h} )\\[1mm]
     2962{\bf -arch64 }  select/force 64 bits compilation mode. This is the default on 64 bits Linux systems and AIX. \\
     2963{\bf -arch32  } select/force 32 bits compilation mode. useful on 64 bits Linux systems or AIX. \\
     2964{\bf -sasz64 } select 8 byte (64 bits) size for array indices, useful if you need to allocate an manipulate
     2965large arrays, with more than $2^32$ elements along a single array dimension. \\
     2966{\bf -ldble128 } set the flags activating {\tt long double} (128 bits) arrays.  \\
     2967{\bf -nofpic } disable -fPIC (Position Independent Code) generation flag \\
     2968{\bf -nothsafe } disable thread-safety protection procedures in SOPHYA : reference sharing \ldots.
     2969 ( activate the conditional compilation flag {\tt SO\_NOTHSAFE } ) \\
     2970{\bf -boundcheck } compile SOPHYA with bound checking activated when accessing array elements
     2971( conditional compilation flag {\tt SO\_BOUNDCHECKING } ) \\
     2972{\bf -sodebug } activate conditional compilation flag {\tt SOPHYA\_DEBUG } for debugging the library.
     2973\item  External libraries \\[1mm]
     2974{\bf -extp {\it path} } Adds the specified path to the search path of the external libraries
     2975include files and archive library. \\
     2976{\bf -extip {\it path} } Adds the specified path to the search path of the external libraries
     2977include files. \\
     2978{\bf -extlp {\it path} } Adds the specified path to the search path of the external libraries
     2979archive (libxxx.a). \\
     2980{\bf -followlink}  follow symbolic links when searching for include files and libraries
     2981(-L option of the find command). default: don't follow symbolic links. \\
     2982{\bf -noextlib } Disable compilation of all modules referencing external libraries. \\
     2983{\bf -noext {\it modname} }  Disable compiling of the specified module (with reference to external
     2984library : {\tt -noext fits , -noext fftw  -noext lapack -noext astro } \\
     2985{\bf -usefftw2 } Use FFTW V2 instead of the default FFTW V3 - A preprocessor
     2986flag will be defined in sspvflags.h \\
     2987{\bf -uselapack2 } Use Lapack V2 istead of the default V3 - A preprocessor
     2988flag will be defined in sspvflags.h \\
     2989{\bf -alsofftwfloat } compile single precision (float) version  of the Fourier
    27062990transform methods (module IFFTW, class FFTWServer). A preprocessor
    27072991flag will be defined in sspvflags.h and float version of the FFTW library
    27082992(libfftw3f.a) will be linked with SOPHYA, in addition to the default double
    2709 precision library (libfftw3.a).
    2710 \item[] -noPI : has currently no effect
    2711 \item[] -slballinone: A single shared library for all SOPHYA, PI and external library interface
    2712 modules will be build. A compilation flag
    2713 will be defined in sspvflags.h . \\ See also target {\tt slballinone} below.
     2993precision library (libfftw3.a). \\
     2994{\bf -slballinone}  Use of  a single shared library for all SOPHYA, PI and
     2995external library interface modules. A compilation flag
     2996will be defined in sspvflags.h . See also target {\tt slballinone} below.
     2997\item PI and piapp specific options  \\[1mm]
     2998{\bf -wgrdl } compile and link piapp with GNU readline library \\
     2999{\bf -epip {\it path} }  Adds the specified path to the search path for include
     3000files and libraries for Motif, and GNU readline, if applicable. \\
     3001{\bf  -noPI } ignore PI modules
    27143002\end{itemize}
    27153003
    2716 {\large \bf configure steps } \\[1mm]
     3004\subsubsection{Configure steps }
     3005
    27173006The configure script performs the following actions :
    27183007\begin{enumerate}
    … …  
    27293018\end{enumerate}
    27303019
    2731 {\large \bf Example } \\[1mm]
     3020\subsubsection{Compile and install, an example }
    27323021
    27333022In the example below, we assume that we want to install Sophya from a
    … …  
    28463135\end{itemize}
    28473136
    2848 
     3137\subsection{Test programs}
     3138The module {\bf Tests} contains a number of test programs:
     3139\begin{enumerate}
     3140\item  {\bf tobjio } tests part of SOPHYA persistence (PPF files)
     3141\begin{verbatim}
     3142csh> tobjio A
     3143 ===> check the created file tobjio.ppf using scanppf
     3144csh> scanppf tobjio.ppf
     3145csh> tobjio B
     3146 ===> OK if RC=0
     3147\end{verbatim}
     3148\item {\bf arrt } and {\bf carrt} perform some checks on TArray modules, including I/O,
     3149sub-array extraction, array conversion and memory organisation, as well as array operations.
     3150\begin{verbatim}
     3151csh> arrt check
     3152csh> carrt ac
     3153csh> carrt oso
     3154csh> carrt odo 
     3155 ===> OK if RC=0
     3156csh> carrt ace
     3157 ===> OK if RC=9  (throw an exception)
     3158\end{verbatim}
     3159\item {\bf spar } is a TArray performance measurement tool
     3160\begin{verbatim}
     3161csh> time spar 2 10 800 1000
     3162csh> time spar 2 1000 80 100
     3163\end{verbatim}
     3164\item {\bf tssqmx } checks DiagonalMatrix, SymmetricMatrix and LowerTriangularMatrix classes
     3165\begin{verbatim}
     3166csh> tssqmx d
     3167csh> tssqmx s
     3168csh> tssqmx t
     3169 ===> OK if RC=0
     3170\end{verbatim}
     3171\item  {\bf ttimestamp } and {\bf tnt } perform some checks on various SOPHYA objects ( DVList, TimeStamp, NTuple \ldots)
     3172\begin{verbatim}
     3173csh> ttimestamp
     3174 ===> OK if RC=0
     3175csh> tnt d
     3176 ===> DVList test, check the output
     3177csh> tnt n
     3178 ===> NTuple test, check the output
     3179csh> tnt DT
     3180 ===> DataTable test, check the output
     3181csh> tnt DT
     3182 ===> SwPPFDataTable test, check the output
     3183\end{verbatim}
     3184\item {\bf tfft } checks the operation of FFTPackServer and FFTWServer in 1D transforms
     3185\begin{verbatim}
     3186# FFTPackServer tests in double
     3187csh> tfft 1531 P D 0 50 0.0002
     3188csh> tfft 1220 P D 0 50 0.0002
     3189 ===> OK if RC=0
     3190# FFTPackServer tests in float
     3191csh> tfft 1531 P F 0 50 0.0002
     3192csh> tfft 1220 P F 0 50 0.0002
     3193 ===> OK if RC=0
     3194# FFTWServer tests in double
     3195csh> tfft 1531 W D 0 50 0.0002
     3196csh> tfft 1220 W D 0 50 0.0002
     3197 ===> OK if RC=0
     3198\end{verbatim}
     3199\item {\bf lpk} checks the LinAlg interface module
     3200\begin{verbatim}
     3201csh> lpk inverse 100,100 0
     3202 ===> OK if RC=0
     3203csh> lpk linsolve 100,100 0
     3204 ===> OK if RC=0
     3205csh> lpk lss 100,50 0
     3206 ===> OK if RC=0
     3207csh> lpk svd 100,50 0
     3208 ===> OK if RC=0
     3209## These checks can be combined in a single call to lpk
     3210csh> lpk all 100,50 0
     3211\end{verbatim}
     3212\item {\bf tmtdt } tests several aspects of SOPHYA : threads (ZThread, ZMutex \ldots), DataTables \ldots
     3213\begin{verbatim}
     3214csh> tmtdt NT 50000 2
     3215 ===> OK if RC=0
     3216csh> tmtdt DT 50000 2
     3217 ===> OK if RC=0
     3218csh> tmtdt SWPPF 50000 2
     3219 ===> OK if RC=0
     3220# cfitsio is NOT thread safe, test SwFitsDataTable with a single thread
     3221csh> tmtdt SWFITS 50000 1
     3222\end{verbatim}
     3223
     3224\end{enumerate}
    28493225
    28503226\newpage
Note: See TracChangeset for help on using the changeset viewer.