Changeset 133 in svn

Timestamp:

Jan 6, 2009, 12:28:23 AM (16 years ago)

Author:

Xavier Rouby

Message:

with the new appendix. Uncorrected...

File:

• trunk/paper/notes.tex (modified) (3 diffs)

trunk/paper/notes.tex

@@ -679 +679 @@
 \onecolumn
 \appendix
-
+ 
 \section{User manual}
-
-The available code is a tar file which comes with everything you need to run the \textsc{Delphes} package. Nevertheless in order to visualise the events with the \textsc{Frog} program, you need to install libraries as explained in {\it href="http://projects.hepforge.org/frog/}
-
+ 
+The available code is a tar file which comes with everything you need to run the \textsc{Delphes} package. Nevertheless in order to visualise the events with the \textsc{Frog} program, you need to install libraries as explained in {\it href= ``http://projects.hepforge.org/frog/"}
+ 
 \subsection{Getting started}
-
+ 
 In order to run \textsc{Delphes} on your system, first download is sources and compile it:\\
 \begin{quote}
 \begin{verbatim}
-me@mylaptop:~$ wget http://www.fynu.ucl.ac.be/users/s.ovyn/files/Delphes_V_*.*.tar 
-me@mylaptop:~$ tar -xvf Delphes_V_*.*. tar  
-me@mylaptop:~$ cd Delphes_V_*.* 
-me@mylaptop:~$ ./genMakefile.tcl > Makefile 
-me@mylaptop:~$ make 
+me@mylap:~$ http://www.fynu.ucl.ac.be/users/s.ovyn/Delphes/files/Delphes_V_*.tar.gz
+me@mylap:~$ tar -xvf Delphes_V_*.tar.gz 
+me@mylap:~$ cd Delphes_V_*.*
+me@mylap:~$ ./genMakefile.tcl > Makefile
+me@mylap:~$ make
 \end{verbatim}
 \end{quote}    
-
-
 \subsection{Running \textsc{Delphes} on your events}
-
+ 
+In this chapter, we will explain how to use \textsc{Delphes} to perform a fast simulation of a general purpose detector on your event files. The first step to use \textsc{Delphes} is to create the list of input event files (e.g. {\verb inputlist.list })  file. As an important comment, don't forget that all the files comprised in the list file should have the same type (\texttt{*.hep}, \texttt{*.lhe} or \texttt{*.root}). In the simplest way of running \textsc{Delphes}, you need this input file and you need to specify the name of the output of \textsc{Delphes} that will contain the particle-level information ({\verb GEN } {\verb tree }), the analysis data objects after reconstruction ({\verb Analysis } {\verb tree }), and the results of the trigger emulation ({\verb Trigger } {\verb tree }).
+ 
+\begin{quote}
+\begin{verbatim}
+me@mylaptop:~$ ./Delphes inputlist.list OutputRootFileName.root
+\end{verbatim}
+\end{quote}
+ 
 \subsubsection{Setting the run configuration}
-
-The program is driven by two datacards (default cards are data/DataCardDet.dat and data/trigger.dat) which allow a large spectrum of running conditions. 
-{\b The run card }\\
-
+ 
+The program is driven by two datacards (default cards are {\verb data/DataCardDet.dat } and {\verb data/trigger.dat }) which allow a large spectrum of running conditions.
+Please note that the either you provide those two datacards, either the running will be done using the default parameters defined in the constructor of the class {\verb RESOLution()}. If you chose a different detector or running configuration you will need to edit the datacards accordingly.
+ 
+\begin{enumerate}
+ 
+\item{\bf The run card }
+ 
 Contains all needed information to run \textsc{Delphes}
 \begin{itemize}
-  
-\item The following parameters are available: detector parameters, including calorimeter and tracking coverage and resolution, transverse energy thresholds allowed for reconstructed objects, jet algorithm to use as well as jet parameters. 
-  
-\item Four flags, {\verb FLAG_bfield }, {\verb FLAG_vfd }, {\verb FLAG_trigger } and {\verb FLAG_frog } should be assigned to decide if the magnetic field propagation, the very forward detectors acceptance, the trigger selection and the preparation for \textsc{Frog} display respectively are running by \textsc{Delphes}.
-  
-\item An example (the default detector card) can be found in {\verb files/DataCardDet.dat }
-\end{itemize}
-
-{\b The trigger card }\\
-Contains the definition of all trigger bits
-\begin{itemize}
-  
-\item Cuts can be applied on the transverse momentum of electrons, muons, jets, tau-jets, photons and transverse missing energy.
-\item Be careful that the following structured should be used: 
-  \begin{enumerate}
-  \item One trigger bit per line, the first entry in the line is the name of the trigger bit 
-  \item If the trigger bit uses the presence of multiple identical objects, their transverse momentum thresholds must be defined in decreasing order 
-  \item The different object requirements must be separated by a {\verb && } flag
-  \item Example of a trigger bit line:\\
-    \begin{quote}
-\begin{verbatim}        
-DoubleElec  >> ELEC1_PT: '20' && ELEC2_PT: '10'    
+ \item The following parameters are available: detector parameters, including calorimeter and tracking coverage and resolution, transverse energy thresholds allowed for reconstructed objects, jet algorithm to use as well as jet parameters.
+ \item Four flags, {\verb FLAG_bfield }, {\verb FLAG_vfd }, {\verb FLAG_trigger } and {\verb FLAG_frog } should be assigned to decide if the magnetic field propagation, the very forward detectors acceptance, the trigger selection and the preparation for \textsc{Frog} display respectively are running by \textsc{Delphes}.
+ \end{itemize}
+ 
+If no datacard is provided ny the user, the default one is used that contains the followings smearing and running parameters:
+\begin{quote}
+\begin{verbatim}
+# Detector characteristics
+CEN_max_tracker    2.5     // Maximum tracker coverage
+CEN_max_calo_cen   3.0     // central calorimeter coverage
+CEN_max_calo_fwd   5.0     // forward calorimeter pseudorapidity coverage
+CEN_max_mu         2.4     // muon chambers pseudorapidity coverage
+ 
+# Energy resolution for electron/photon
+# \sigma/E = C + N/E + S/\sqrt{E}
+ELG_Scen          0.05     // S term for central ECAL
+ELG_Ncen          0.25     // N term for central ECAL
+ELG_Ccen          0.005    // C term for central ECAL
+ELG_Cfwd          0.107    // S term for FCAL
+ELG_Sfwd          2.084    // C term for FCAL
+ELG_Nfwd          0.0      // N term for FCAL
+ 
+# Energy resolution for hadrons in ecal/hcal/hf
+# \sigma/E = C + N/E + S/\sqrt{E}
+HAD_Shcal         1.5      // S term for central HCAL
+HAD_Nhcal         0.       // N term for central HCAL
+HAD_Chcal         0.05     // C term for central HCAL
+HAD_Shf           2.7      // S term for FCAL
+HAD_Nhf           0.       // N term for FCAL
+HAD_Chf           0.13     // C term for FCAL
+ 
+# Muon smearing
+MU_SmearPt        0.01
+ 
+# Tracking efficiencies
+TRACK_ptmin       0.9      // minimal pT
+TRACK_eff         100      // efficiency associated to the tracking
+ 
+# Calorimetric towers
+TOWER_number         40
+### list of the edges of each tower in eta for eta>0 assuming
+###a symmetric detector in eta<0
+### the list starts with the lower edge of the most central tower
+### the list ends with the higher edged of the most forward tower
+### there should be NTOWER+1 values
+TOWER_eta_edges 0.    0.087 0.174 0.261 0.348 0.435 0.522 0.609 0.696 0.783
+               0.870 0.957 1.044 1.131 1.218 1.305 1.392 1.479 1.566 1.653
+               1.740 1.830 1.930 2.043 2.172 2.322 2.500 2.650 2.868 2.950
+               3.125 3.300 3.475 3.650 3.825 4.000 4.175 4.350 4.525 4.700
+               5.000
+ 
+### list of the tower size in phi (in degrees), assuming that all
+### towers are similar in phi for a given eta value
+### the list starts with the phi-size of the most central tower (eta=0)
+### the list ends with the phi-size of the most forward tower
+### there should be NTOWER values
+#TOWER_dphi 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 10
+           10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 20 20
+ 
+# Thresholds for reconstructed objetcs
+PTCUT_elec       10.0
+PTCUT_muon       10.0
+PTCUT_jet        20.0
+PTCUT_gamma      10.0
+PTCUT_taujet     10.0
+ 
+# General jet variable
+JET_coneradius   0.7      // generic jet radius
+JET_jetalgo      1        // Jet aglorithm selection
+JET_seed         1.0      // minimum seed to start jet reconstruction
+ 
+# Tagging definition
+BTAG_b           40
+BTAG_mistag_c    10
+BTAG_mistag_l    1
+ 
+# FLAGS
+FLAG_bfield      0        // 1 to run the bfield propagation else 0
+FLAG_vfd         1        // 1 to run the very forward detectors else 0
+FLAG_trigger     1        // 1 to run the trigger selection else 0
+FLAG_frog        1        // 1 to run the FROG event display
+ 
+# In case BField propagation allowed
+TRACK_radius      129     // radius of the BField coverage
+TRACK_length      300     // length of the BField coverage
+TRACK_bfield_x    0       // X composant of the BField
+TRACK_bfield_y    0       // Y composant of the BField
+TRACK_bfield_z    3.8     // Z composant of the BField
+ 
+# In case Very forward detectors allowed
+VFD_min_calo_vfd  5.2     // very forward calorimeter (if any) like CASTOR
+VFD_max_calo_vfd  6.6
+VFD_min_zdc       8.3
+VFD_s_zdc         140     // distance of the ZDC, from the IP, in [m]
+ 
+RP_220_s          220     // distance of the RP to the IP, in meters
+RP_220_x          0.002   // distance of the RP to the beam, in meters
+RP_420_s          420     // distance of the RP to the IP, in meters
+RP_420_x          0.004   // distance of the RP to the beam, in meters
+ 
+# In case FROG event display allowed
+NEvents_Frog      100
+ 
 \end{verbatim}
-    \end{quote}
-  \end{enumerate}
-\item An example (the default trigger card) can be found <a href="files/trigger.dat" title="Home">here</a></li>
-\end{itemize}
-
+\end{quote}
+ 
+ 
+\item{\bf The trigger card }
+ 
+Contains the definition of all trigger bits. Cuts can be applied on the transverse momentum of electrons, muons, jets, tau-jets, photons and transverse missing energy. The following ``codename'' should be used so that \textsc{Delphes} can correctly translate the input list of trigger bit into selection algorithms:
+ 
+\begin{quote}
+\begin{tabular}{ll}
+{\it Trigger flag} & {\it Corresponding object}\\
+{\verb ELEC_PT } & electron \\
+{\verb MUON_PT } & muon \\
+{\verb JET_PT } & jet \\
+{\verb TAUJET_PT } & tau-jet \\
+{\verb ETMIS_PT } & transverse missing energy \\
+{\verb GAMMA_PT } & photon \\
+\end{tabular}
+\end{quote}
+ 
+Moreover, each line in the trigger datacard is allocated to exactly one trigger bit and start with the name of the correcponding trigger. Logical combinaison of several conditions is also possible. If the trigger bit uses the presence of multiple identical objects, the order of their thresholds is not meaningless: they must be defined in decreasing order. Finally, the different requirements on the objects must be separated by a {\verb && } flag. The default trigger card can be found in the data repository of \textsc{Delphes}. An exemple of trigger table consistent with the previous rules is given here:
+\begin{quote}
+\begin{verbatim}   DoubleElec                  >> ELEC_PT: '20' && ELEC_PT: '10'   SingleElec and Single Muon  >> ELEC_PT: '20' && MUON_PT: '15'
+\end{verbatim}
+\end{quote}
+ 
+An example (the default trigger card) can be found in {\verb files/trigger.dat }.
+ 
+\end{enumerate}
+ 
 \subsubsection{Running the code}
-Create the above cards (data/mydetector.dat and data/mytrigger.dat)
-Create a text file containing the list of input files that will be used by \textsc{Delphes} (with extension *.lhe, *.root or *.hep)
+ 
+Create the above cards (data/mydetector.dat and data/mytrigger.dat). Create a text file containing the list of input files that will be used by \textsc{Delphes} (with extension *.lhe, *.root or *.hep)
 To run the code, type the following
 \begin{quote}
@@ -744 +859 @@
 \end{verbatim}
 \end{quote}
-
-
+ 
+ 
+\subsection{Getting the \textsc{Delphes} information}
+ 
+\subsubsection{Contents of the \textsc{Delphes} \textsc{root} trees}
+ 
+As said upwards, the \textsc{Delphes} \textsc{root} file is subdivided into three \textsc{trees}. All the branches available in those \textsc{trees} together with the reconstructed objects they correspond to are summarised here:
+ 
+\begin{quote}
+\begin{tabular}{lll}
+{\bf GEN \textsc{tree}} & &\\
+Particle & generator particles from \textsc{hepevt}     & {\verb TRootGenParticle }\\
+{\bf Analysis \textsc{tree}} & & \\
+Jet        & Jet collection                             & {\verb TRootJet }\\
+TauJet     & Collection of jets tagged as $\tau$-jets   & {\verb TRootTauJet }\\
+Electron   & Collection of electrons                    & {\verb TRootElectron }\\
+Muon       & Collection of muons                        & {\verb TRootMuon }\\
+Photon     & Collection of photons                      & {\verb TRootPhoton }\\
+Tracks     & Tracker tracks                             & {\verb TRootTracks }\\
+ETmis      & Transverse missing energy information      & {\verb TRootETmis }\\
+CaloTower  & Calorimetric towers                        & {\verb TRootCalo }\\
+ZDChits    & ?????                                      & {\verb TRootZdcHits }\\
+RP220hits  & ?????                                      & {\verb TRootRomanPotHits }\\
+FP420hits  &?????                                       & {\verb TRootRomanPotHits }\\
+{\bf Trigger  } & &\\
+TrigResult & Acceptance of different trigger bits       & {\verb TRootTrigger }\\
+\end{tabular}
+\end{quote}
+ 
+The third column shows the names of the corresponding classes to be written in a \textsc{root} tree. All classes except the {\verb TRootTrigger }, the {\verb TRootETmis } and the {\verb TRootRomanPotHits } inherit from the class {\verb TRootParticle} which includes the following member functions for accessing the components:
+ 
+\begin{quote}
+\begin{verbatim}
+ 
+ float E;  // particle energy in GeV
+ float Px; // particle momentum vector (x component) in GeV
+ float Py; // particle momentum vector (y component) in GeV
+ float Pz; // particle momentum vector (z component) in GeV
+ 
+ float PT; // particle transverse momentum in GeV
+ float Eta; // particle pseudorapidity  float Phi; // particle azimuthal angle in rad
+\end{verbatim}
+\end{quote}
+ 
+In addition to their four-momentum and related quantities, additional properties are available for specific objects. Those are summarized in the following table:
+\begin{quote}
+\begin{tabular}{ll}
+{\bf \texttt{Particle} leave } &\\    \texttt{  int PID;      }&\texttt{ // particle HEP ID number }\\
+   \texttt{  int Status;   }&\texttt{ // particle status }\\
+   \texttt{  int M1;       }&\texttt{ // particle 1st mother }\\
+   \texttt{  int M2;       }&\texttt{ // particle 2nd mother }\\
+   \texttt{  int D1;       }&\texttt{ // particle 1st daughter }\\
+   \texttt{  int D2;       }&\texttt{ // particle 2nd daughter }\\
+   \texttt{  float Charge; }&\texttt{ // electrical charge }\\
+   \texttt{  float T;      }&\texttt{ // particle vertex position (t component) }\\
+   \texttt{  float X;      }&\texttt{ // particle vertex position (x component) }\\
+   \texttt{  float Y;      }&\texttt{ // particle vertex position (y component) }\\
+   \texttt{  float Z;      }&\texttt{ // particle vertex position (z component) }\\
+   \texttt{  float M;      }&\texttt{ // particle mass }\\
+{\bf \texttt{Electron} and \texttt{Muon} leaves } &\\
+   \texttt{ int Charge } &\\
+   \texttt{ bool IsolFlag } &\\
+{\bf \texttt{Jet} leave }  &\\
+   \texttt{ bool Btag } &\\
+{\bf \texttt{ZDChits} leave } &\\
+   \texttt{float T;        }&\texttt{ // time of flight [s] }\\
+   \texttt{ int side;      }&\texttt{ // -1 or +1 }\\
+\end{tabular}
+\end{quote}
+ 
 \subsection{Running an analysis on your \textsc{Delphes} events}
-
-Two examples of codes running on the output root file of \textsc{Delphes} are coming with the package
-\begin{enumerate}
-\item The {\verb Examples/Analysis_Ex.cpp } code shows how to access the available reconstructed objects and the trigger information The two following arguments are required: a text file containing the input \textsc{Delphes} root files to run, and the name of the output root file. To run the code:
-  \begin{quote}
+ 
+To analyze the {\verb Root } {\verb TTree } ntuple  of \textsc{Delphes}, the simplest way is to use the {\verb Analysis_Ex.cpp } code which is coming in the {\verb Examples } repository of \textsc{Delphes}. Note that all of this is optional and done to facilitate the analysis, as the output from \textsc{Delphes} is viewable with the standard TBrowser or \textsc{root} and can be analyzed using the MakeClass facility. To run the {\verb Examples/Analysis_Ex.cpp } code, the two following arguments are required: a text file containing the input \textsc{Delphes} root files to run, and the name of the output root file. To run the code:
+ \begin{quote}
 \begin{verbatim}
 ./Analysis_Ex input_file.list output_file.root
 \end{verbatim}
-  \end{quote}
-  
-\item The {\verb Examples/Trigger_Only.cpp } code permits to run the trigger selection separately from the general detector simulation on output \textsc{Delphes} root files. An input \textsc{Delphes} root file is mandatory as argument. The new tree containing the trigger information will be added in these file. The trigger datacard is also necessary. To run the code:
-  \begin{quote}
+ \end{quote}
+ 
+ 
+ 
+\subsubsection{sdflksdjf}
+The \texttt{Examples/Trigger\_Only.cpp} code permits to run the trigger selection separately from the general detector simulation on output \textsc{Delphes} root files. An input \textsc{Delphes} root file is mandatory as argument. The new tree containing the trigger information will be added in these file. The trigger datacard is also necessary. To run the code:
+ \begin{quote}
 \begin{verbatim}
 ./Trigger_Only input_file.root data/trigger.dat
 \end{verbatim}
-  \end{quote}
-  
-\end{enumerate}
-
+ \end{quote}
+ 
 \subsection{Running the \textsc{Frog} event display}
-
-
-
-
+ 
 \begin{itemize}
 \item If the { \verb FLAG_frog } was switched on, two files were created during the run of \textsc{Delphes}: {\verb DelphesToFrog.vis } and {\verb DelphesToFrog.geom }. They contain all the needed information to run frog.
@@ -776 +955 @@
 \item Go back into the main directory and type {\verb ./Utilities/FROG/frog }.
 \end{itemize}
-
-
-In the list of input files, all files should have the same type 
-
- in other words, the effect related to the particle showers that would happen in the calorimeters are not taken into account.
-
+ 
 \end{document}