Changeset 3438 in Sophya for trunk/SophyaLib/Manual/piapp.tex

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

File:

• trunk/SophyaLib/Manual/piapp.tex (modified) (9 diffs)

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