Changeset 3438 in Sophya for trunk/SophyaLib/Manual

Timestamp:

Dec 12, 2007, 10:34:59 PM (18 years ago)

Author:

ansari

Message:

Ajout aknowledgments ds docs et + chapitre 5 ds piapp.tex (expression plotting) - Reza 12/12/2007

Location:

trunk/SophyaLib/Manual

Files:

• modifs.tex (modified) (3 diffs)
• piahelp.tex (modified) (2 diffs)
• piapp.tex (modified) (9 diffs)
• sophya.tex (modified) (5 diffs)

trunk/SophyaLib/Manual/modifs.tex

@@ -56 +56 @@
 V = 2.0  &   \hspace{10mm}  &  Septembre 2006 - tag CVS \\
 V = 2.046  &   \hspace{10mm}  &  Ao\^{u}t 2007 - NO tag  \\
-V = 2.1  &   \hspace{10mm}  &  Novemvre 2007 - tag CVS \\
+V = 2.1  &   \hspace{10mm}  &  Novembre 2007 - tag CVS \\
 
 \end{tabular}
@@ -205 +205 @@
 \titre{PI/piapp}
 \begin{itemize}
+\item[\rond] Novembre 2007 {\bf PIext/ProgPI}: \\
+- Ajout commande de trace d'ellipse d'erreur {\tt errorellipse} \\
+- Axes en degres (0..360, -90..90) pour la projection molleweide et adaptation de la commande {\tt mollgrid}. Suppression de mollgridsph. \\
+- Ajout fonctions tetphi2mollX/Y() et longlat2mollX/Y() ds les fichiers d'expressi
+on ntuple generes par piapp pour trace sur projection de type molleweide. \\
+- Ajout flag [-s] a openppf . openfits/savefits comme alias de readfits/writefits.
+- Verification arret thread Reveil avant destruction de l'objet. 
 \item[\rond] Octobre 2007 {\bf (PI/PIext)}: Ajout methodes de redirection stdout/stderr vers un objet PIConsole, 
 a travers un fichier disque (fichiers PI/piapplx.h .cc) avec possibilite de recopie sur stdout/stderr 
@@ -260 +267 @@
 pour la prise en charge des objets DVList. 
 Accs aux variables par {\tt \$\{dvlName.varName\} } 
-\item Accs ˆ l'objet DVList attachŽ aux TArray, TMatrix, DataTable par \\
+\item Accs ˆ l'objet DVList attachŽ aux TArray, TMatrix, DataTable et NTuple par \\
 \hspace*{5mm}  {\tt \$\{objName.info.varName\} }
 \item L'adaptateur de DataTable permet aussi d'accŽder aux lignes de la table par \\

trunk/SophyaLib/Manual/piahelp.tex

@@ -474 +474 @@
 - HistoErr: i,x,val,err2,nb,_nl
 - Histo2DErr: i,j,x,y,val,err2,nb,_nl
-- Vector/Matrix: n,r,c,val,real,imag,mod,phas,_nl
+- Vector/Matrix/Image: n,r,c,val,real,imag,mod,phas,_nl
 - TArray: n,x,y,z,t,u,val,real,imag,mod,phas,_nl
-- Image: i,j,x,y,val(=pix),_nl
 - GeneralFitData: x0,ex0 x1,ex1 ...  xn,exn   y,ey   ok  ,_nl
-- LocalMap/SphereThetaPhi/SphereHEALPix: 
+- SphereThetaPhi/SphereHEALPix/SphereECP/LocalMap: 
 -         i,k,val,real,imag,mod,phas,teta,phi,_nl
 - FITS Binary/ASCII table: fits column names,_nl
@@ -1189 +1188 @@
 o <Ctl>E : Command editing -> Goto the end of line 
 o <Ctl>K : Command editing -> Clear to the end of line 
-o <Ctl>C : Command editing -> Clear the line 
+o <Ctl>C : Stop/break command execution by PIACmd/Commander
 o Cursor left,right : Command editing -> Move cursor 
 o Cursor Up,Down : recall command from history buffer 

trunk/SophyaLib/Manual/piapp.tex

@@ -110 +110 @@
 loaded at run time.  
 \end{itemize}
+
+\subsection{Acknowlegments}
+Many people have contributed to the development SOPHYA and/or the PI library 
+and (s)piapp interactive analysis tool.
+we are grateful to the following people:
+
+\begin{tabular}{lcl}
+Reza Ansari & \hspace{5mm} & (LAL-Univ.Paris Sud, Orsay) \\
+Eric Aubourg & & (DAPNIA-CEA/APC, Saclay) \\
+Sophie Henrot-Versille & & (LAL-IN2P3/CNRS, Orsay) \\
+Alex Kim & & (LBL, Berkeley) \\
+Guy Le Meur & & (LAL-IN2P3/CNRS, Orsay) \\
+Eric Lesquoy & & (DAPNIA-CEA, Saclay) \\
+Christophe Magneville & & (DAPNIA-CEA, Saclay) \\
+Bruno Mansoux & & (LAL-IN2P3/CNRS, Orsay) \\
+Olivier Perdereau & & (LAL-IN2P3/CNRS, Orsay) \\
+Nicolas Regnault & & (LPNHE-IN2P3/CNRS, Paris) \\
+Benoit Revenu & & (APC/Univ.Paris 7, Paris) \\
+Francois Touze & & (LAL-IN2P3/CNRS, Orsay) \\
+\end{tabular}
+
+We thank also the persons who have helped us by useful suggestions, among others : \\
+S. Bargot, S. Du, S. Plasczczynski, C. Renault and D. Yvon.
+
 %%%
 \begin{figure}[ht!]
@@ -991 +1015 @@
 %%%%%%%%%%%%%%% Section 5 :   analyse a la paw
 \newpage
-\section{Tables and interactive analysis}
+\section{Tables and Expression Plotting}
 \label{tableplot}
+A powerful data analysis technic available in piapp is 
+2D, 3D plot, and histogramming applied to arbitrary analytical 
+expression of table columns.
+This analysis technic has been introduced by the popular 
+CERN \href{http://paw.web.cern.ch/paw/}{\bf PAW} 
+({\bf P}hysics {\bf A}nalysis {\bf Workstation}) 
+\footnote{PAW home page : http://paw.web.cern.ch/paw/ } program
+and the underlying HBOOK fortran library.
+Compared to PAW, piapp extends in many respects this capability,
+piapp offers in particular the possibility to manipulate many 
+objects as if they where a DataTable, or NTuple. 
+There are also additional 2D and 3D representations e.g. 
+{\tt plot2de} \myppageref{plot2de},  
+{\tt plot2dw} \myppageref{plot2dw},  
+{\tt plot2dc} \myppageref{plot2dc} and
+{\tt plot3dw} \myppageref{plot3dw}.
+
+\subsection{How does it work ?}
+
+The Expression.Plotting commands in piapp operate on objects through the 
+{\bf NTupleInterface} class methods. Some classes like NTuple or BaseDataTable
+inherit from NTupleInterface, while for the other classes, the corresponding 
+NObjMgrAdapter class exposes an object conforming to NTupleInterface through the 
+method : \\
+\hspace*{5mm} {\tt  NTupleInterface* NObjMgrAdapter::GetNTupleInterface()} \\
+A C file (PIATmp\_xxx/expf\_pia\_dl.c) is created by piapp containing the 
+specified expressions, which should conform to the C-language syntax.
+In addition to the functions in {\tt math.h} (sin, cos, log \ldots), 
+the following functions are defined by piapp and can be used:
+\begin{itemize}
+\item Flat random number generators: {\tt drand01() , drandpm1() }
+\item Gaussian random number generator: {\tt GauRand() }
+\item Angle conversion: {\tt deg2rad(double d), rad2deg(double r) }
+\item $(\theta,\varphi)$ to Molleweide X,Y projection: \\
+\hspace*{5mm}{\tt double tetphi2mollX(double theta, double phi)} \\
+\hspace*{5mm}{\tt double tetphi2mollY(double theta)} 
+\item Longitude(0..360) deg., Latitude(-90..90) deg. conversion to Molleweide X,Y: \\
+\hspace*{5mm}{\tt double longlat2mollX(double longit, double lat) } \\
+\hspace*{5mm}{\tt double longlat2mollY(double lat) }
+\end{itemize}
+
+The processing steps for an Expression.Plotting in piapp :
+\begin{enumerate}
+\item Creation of the C-file. 
+\item On the fly compilation of the generated file.
+\item The resulting shared-object is loaded and linked with the application
+\item Loop over the NTupleInterface object rows. The created function is called
+with the data from each row
+\item The return values are used to fill an histogram, or a matrix/vector or
+another NTuple or to produce a 2D or 3D graphic display. 
+\end{enumerate}
+
+Although rather complex, the efficiency gain during processing data easily compensates
+for the overhead of the compilation step.
+  
+\subsection{Column/variable names}
+
+When working with real 2-D tables (NTuple, DataTable \ldots), the column names
+are the name of the variables which can be used in the C-expressions.
+There is an additional variable, called {\tt \_nl}, automatically
+provided by piapp, corresponding the table row number, starting from 0.
+
+For the other objects in piapp, the variable names are listed below:
+\begin{itemize}
+\item[\rond] For 2D table objects {\bf (NTuple,DataTable,\ldots)}:  ColumnNames,\_nl
+\item[\rond] For FITS files opened through {\tt fitsadapt} command: FITSColumnNames,\_nl
+\item[\rond] For {\bf Histo1D/HProf} objects : i,x,val,err,nb,\_nl
+\item[\rond] For {\bf Histo2D} objects : i,j,x,y,val,err,\_nl
+\item[\rond] For {\bf HistoErr} objects : i,x,val,err2,nb,\_nl
+\item[\rond] For {\bf Histo2DErr} objects : i,j,x,y,val,err2,nb,\_nl
+\item[\rond] For {\bf \tcls{TVector}, \tcls{TMatrix} , \tcls{Image} } objects : \\
+ \hspace*{10mm}  n,r,c,val,real,imag,mod,phas,\_nl
+\item[\rond] For {\bf \tcls{TArray}} objects : n,x,y,z,t,u,val,real,imag,mod,phas,\_nl
+\item[\rond] For {\bf GeneralFitData} objects : x0,ex0 x1,ex1 ...  xn,exn  y,ey ,ok,\_nl
+\item[\rond] For {\bf \tcls{SphereHEALPix} , \tcls{SphereThetaPhi} , \tcls{SphereECP}
+\tcls{LocalMap} } objects : \hspace{10mm} i,k,val,real,imag,mod,phas,teta,phi,\_nl
+\end{itemize}  
 
 %%%%%%%%%%%%%%% Section 6 :  command interpreter 
@@ -1029 +1130 @@
 managed by {\bf NamedObjMgr} (See below).
 
+\subsubsection{Interpreter/Commander variables}
 \begin{itemize}
 \item[\rond] {\bf Definition and initialisation of variables }  
@@ -1087 +1189 @@
 
 \par
-
-\item[\rond] {\bf Special variables } 
+\end{itemize}
+
+\subsubsection{Special variables}
 \begin{itemize}
 \item {\tt \$retval} ou {\tt \$retstr}  :  the string specified in the last {\bf return} statement 
@@ -1098 +1201 @@
 \end{itemize}
 
-\item[\rond] {\bf Objects/Application level variables} \\
+\subsubsection{Environment variables} 
+Environment variables can simply be accessed by {\tt \$varenvname}. 
+However,  the environment variables have the lowest priority during substitution.
+Interpreter's variables have the highest priority, followed 
+by the application level variables.
+
+\subsubsection{Objects/Application level variables} 
 For some classes managed by NamedObjMgr, 
 PIACmd provide acces to some of the attributes of the object by 
@@ -1107 +1216 @@
 {\tt \${vname} }  is replaced by its value, even if an interpreter variable with the 
 same name has been defined. 
+\begin{itemize}
+\item[\rond] Accessing object attributes
 \begin{verbatim}
 # -------- Example with a Vector
@@ -1115 +1226 @@
 #           used to get list of valid attributes
 piapp[3] echo ${va.?}
-TMatrix.Att: rank size/nelts nrow/nrows ncol/ncols sum 
+TMatrix.Att: rank size/nelts nrow/nrows ncol/ncols sum sumsq norm min ...
 #  Compound names, in the form  name.att must be inclosed in
 #    braces {name.att}
@@ -1129 +1240 @@
 \end{verbatim}
 
-\item[\rond] {\bf Environment variables} can simply be accessed by {\tt \$varenvname}. 
-However,  the environment variables have the lowest priority during substitution.
-Interpreter's variables have the highest priority, followed 
-by the application level variables.
-
+\item[\rond] Accessing object.Info() \\
+For objects having an DVList Info() object (TArray/TVector/TMatrix , NTuple, DataTable, SwPPFDataTable, it is possible to access DVList members by the corresponding names : \\
+\hspace*{10mm} {\tt \$\{objName.info.varName\} } 
+\item[\rond] Getting DataTable rows \\
+For NTuple and BaseDataTable objects (DataTable, SwPPFDataTable, SwFitsDataTable), it is 
+possible to get a string representation of a given row, by specifying 
+\$\{tableName.row\} followed by the row number (starting from 0) : \\
+\hspace*{10mm} {\tt \$\{tableName.row.num\} } 
 \end{itemize}
+
  
 
@@ -1264 +1379 @@
 \end{itemize}
 
+Executing commands in a separate thread is useful for CPU or data intensive 
+commands. Most {\bf Expr.Plotting} 
+(plot2d, plot2dw, plot2de, plot3d, ntloop, fillvec, fillmtx \ldots) 
+and some of the {\bf pawCmd} (n/plot n/proj) are thread safe. However, due to the 
+current mutex lock management for these Expr.Plotting/pawCmd commands, only one 
+such command can run concurrently with other piapp threads. 
+Some of the commands in the {\bf CxxExecutorCmd} (
+c++exec, c++execfrf, c++create, c++createfrf, c++compile, c++link) are also thread safe.
+The same remark concerning lock management applies to these commands, while 
+CxxExecutorCmd commands can run in parallel with Expr.Plotting commands.
+
+
 %%%%%%%%%%%%%%% Section 7 :  c++ execution
 \newpage

trunk/SophyaLib/Manual/sophya.tex

@@ -43 +43 @@
 G. Le Meur           &  lemeur@lal.in2p3.fr       \\
 C. Magneville        &  cmv@hep.saclay.cea.fr     \\
-S. Henrot-Versille   &  versille@in2p3.fr     
 }
 % \auteursall
@@ -102 +101 @@
 %%%
 %%%
+\subsection{Acknowlegments}
+Many people have contributed to the development SOPHYA and/or the PI library 
+and (s)piapp interactive analysis tool.
+we are grateful to the following people:
+
+\begin{tabular}{lcl}
+Reza Ansari & \hspace{5mm} & (LAL-Univ.Paris Sud, Orsay) \\
+Eric Aubourg & & (DAPNIA-CEA/APC, Saclay) \\
+Sophie Henrot-Versille & & (LAL-IN2P3/CNRS, Orsay) \\
+Alex Kim & & (LBL, Berkeley) \\
+Guy Le Meur & & (LAL-IN2P3/CNRS, Orsay) \\
+Eric Lesquoy & & (DAPNIA-CEA, Saclay) \\
+Christophe Magneville & & (DAPNIA-CEA, Saclay) \\
+Bruno Mansoux & & (LAL-IN2P3/CNRS, Orsay) \\
+Olivier Perdereau & & (LAL-IN2P3/CNRS, Orsay) \\
+Nicolas Regnault & & (LPNHE-IN2P3/CNRS, Paris) \\
+Benoit Revenu & & (APC/Univ.Paris 7, Paris) \\
+Francois Touze & & (LAL-IN2P3/CNRS, Orsay) \\
+\end{tabular}
+
+We thank also the persons who have helped us by useful suggestions, among others : \\
+S. Bargot, S. Du, S. Plasczczynski, C. Renault and D. Yvon.
+
 \subsection{SOPHYA modules}
 \label{sopmodules}
@@ -1767 +1789 @@
 in the HTML pages of the Sophya manual.
 
+\subsection{Simplex method}
+The class {\bf MinZSimplex} implements the simplex method for non linear 
+optimization / minimization. See the SOPHYA manual for more information.
+
 \subsection{Polynomial}
 \index{Polynomial} \index{Poly} \index{Poly2}
@@ -2040 +2066 @@
 %%%
 \subsection {Spherical maps}
-SkyMap module provides three kinds of complete ($4 \pi$) spherical maps according to the
+SkyMap module provides three classes for representing data with pixels distributed over complete ($4 \pi$ steradians) spheres. These classes implements the common interface defined 
+in the base class \tcls{SphericalMap} with three different algorithms or 
 pixelization scheme. 
-SphereHEALPix represents spheres pixelized following the HEALPIix algorithm (E. Hivon, K. Gorski)
-\footnote{see the HEALPix Homepage: http://www.eso.org/kgorski/healpix/ }
-, 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) :
-\index{\tcls{SphereHEALPix}} 
+The spherical maps can be instanciated for the followind data types: \\
+\hspace*{5mm} int\_4 , r\_4 (float) , r\_8 (double) , complex$<$r\_4$>$ , complex$<$r\_8$>$. \\
+The SphereHEALPix can in addition be instanciated for T=uint\_2.
+
+\begin{enumerate}
+\item \index{\tcls{SphereHEALPix}} 
+{\bf \tcls{SphereHEALPix}} implements the HEALPix 
+({\bf H}ierarchical {\bf E}qual {\bf A}rea iso{\bf L}atitude {\bf Pix}elization) scheme, 
+developped originaly by K. Gorski \& E. Hivon. Refer to 
+\href{http://healpix.jpl.nasa.gov/}{HEALPix home page} for 
+detailed information about this pixelisation scheme and related software
+\footnote{HEALPix home page: http://healpix.jpl.nasa.gov/ }.
+FITS read/write for SphereHEALPix objects is handled by the \tcls{FITS\_SphereHEALPix}
+class in module FitsIOServer.
+\item \index{\tcls{SphereThetaPhi}} 
+{\bf \tcls{SphereThetaPhi}} represents spheres pixelized following an algorithm 
+developed at LAL-ORSAY, for SOPHYA. 
+The sphere is divided into a number of rings or slices
+along the parallels, corresponding to different values of the angle $\theta$.
+Each slice is then divided into a number of pixels, with an aspect ratio close 
+to one (square pixels). Pixels are exactly iso-latitude and very uniform in surface,
+over the sphere. 
+
+\item \index{\tcls{SphereECP}}
+
+The {\bf \tcls{SphereECP}} class correspond to the cylindrical projection.
+Like SphereThetaPhi class, the sphere is divided into a number of rings
+or slices, and each ring is divided into a constant number of pixels
+along the $\varphi$ direction. Although the \tcls{SphereECP} does not have 
+equal area pixels when used for complete spheres, it can be used for 
+representing partial or full spherical maps. 
+\end{enumerate}
+
+The example below shows creating and filling of a 
+SphereHEALPix with nside = 8 
+(The sphere will have $12 \times 8 \times 8= 768$ pixels) :
 
 \begin{verbatim}
@@ -2054 +2113 @@
 \end{verbatim}
 
-SphereThetaPhi is used in a similar way with an argument representing number of slices in theta (Euler angle) for an hemisphere.
+Pixels at an angular posistion can be directly accessed through the operator \\
+\hspace*{15mm} T \tcls{SphericalMap}::operator()($\theta, \varphi$) :
+\begin{verbatim}
+#include "vector3d.h"
+#include "spherethetaphi.h"
+...
+// Create a sphere with 40 arcmin resolution
+int M = SphereThetaPhi<r_4>::ResolToSizeIndex(
+        Angle(40., Angle::ArcMin).ToRadian() );
+SphereThetaPhi<r_4> sphtp(M);
+double tet, phi;
+for (int k=0; k< sphtp.NbPixels(); k++) {
+  sphtp.PixThetaPhi(k, tet, phi);
+  sphtp(k) = cos(5.*tet)*sin(7.*phi);
+}
+cout << sphtp;
+// To save sphtp to file sphtp (if executed through runcxx)
+KeepObj(sphtp);
+\end{verbatim}
+
 \index{\tcls{SphereThetaPhi}}
-The SphereECP class correspond to the cylindrical projection and can be used for representing
-partial or full spherical maps. However, it has the disadvantage of having non uniform pixel 
-size.
-\index{\tcls{SphereECP}}
 
 \subsection {Local maps}