Fork me on GitHub

Changeset 133 in svn for trunk/paper


Ignore:
Timestamp:
Jan 6, 2009, 12:28:23 AM (16 years ago)
Author:
Xavier Rouby
Message:

with the new appendix. Uncorrected...

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/paper/notes.tex

    r129 r133  
    679679\onecolumn
    680680\appendix
    681 
     681 
    682682\section{User manual}
    683 
    684 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/}
    685 
     683 
     684The 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/"}
     685 
    686686\subsection{Getting started}
    687 
     687 
    688688In order to run \textsc{Delphes} on your system, first download is sources and compile it:\\
    689689\begin{quote}
    690690\begin{verbatim}
    691 me@mylaptop:~$ wget http://www.fynu.ucl.ac.be/users/s.ovyn/files/Delphes_V_*.*.tar
    692 me@mylaptop:~$ tar -xvf Delphes_V_*.*. tar
    693 me@mylaptop:~$ cd Delphes_V_*.*
    694 me@mylaptop:~$ ./genMakefile.tcl > Makefile
    695 me@mylaptop:~$ make
     691me@mylap:~$ http://www.fynu.ucl.ac.be/users/s.ovyn/Delphes/files/Delphes_V_*.tar.gz
     692me@mylap:~$ tar -xvf Delphes_V_*.tar.gz
     693me@mylap:~$ cd Delphes_V_*.*
     694me@mylap:~$ ./genMakefile.tcl > Makefile
     695me@mylap:~$ make
    696696\end{verbatim}
    697697\end{quote}   
    698 
    699 
    700698\subsection{Running \textsc{Delphes} on your events}
    701 
     699 
     700In 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 }).
     701 
     702\begin{quote}
     703\begin{verbatim}
     704me@mylaptop:~$ ./Delphes inputlist.list OutputRootFileName.root
     705\end{verbatim}
     706\end{quote}
     707 
    702708\subsubsection{Setting the run configuration}
    703 
    704 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.
    705 {\b The run card }\\
    706 
     709 
     710The 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.
     711Please 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.
     712 
     713\begin{enumerate}
     714 
     715\item{\bf The run card }
     716 
    707717Contains all needed information to run \textsc{Delphes}
    708718\begin{itemize}
    709  
    710 \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.
    711  
    712 \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}.
    713  
    714 \item An example (the default detector card) can be found in {\verb files/DataCardDet.dat }
    715 \end{itemize}
    716 
    717 {\b The trigger card }\\
    718 Contains the definition of all trigger bits
    719 \begin{itemize}
    720  
    721 \item Cuts can be applied on the transverse momentum of electrons, muons, jets, tau-jets, photons and transverse missing energy.
    722 \item Be careful that the following structured should be used:
    723   \begin{enumerate}
    724   \item One trigger bit per line, the first entry in the line is the name of the trigger bit
    725   \item If the trigger bit uses the presence of multiple identical objects, their transverse momentum thresholds must be defined in decreasing order
    726   \item The different object requirements must be separated by a {\verb && } flag
    727   \item Example of a trigger bit line:\\
    728     \begin{quote}
    729 \begin{verbatim}       
    730 DoubleElec  >> ELEC1_PT: '20' && ELEC2_PT: '10'   
     719 \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.
     720 \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}.
     721 \end{itemize}
     722 
     723If no datacard is provided ny the user, the default one is used that contains the followings smearing and running parameters:
     724\begin{quote}
     725\begin{verbatim}
     726# Detector characteristics
     727CEN_max_tracker    2.5     // Maximum tracker coverage
     728CEN_max_calo_cen   3.0     // central calorimeter coverage
     729CEN_max_calo_fwd   5.0     // forward calorimeter pseudorapidity coverage
     730CEN_max_mu         2.4     // muon chambers pseudorapidity coverage
     731 
     732# Energy resolution for electron/photon
     733# \sigma/E = C + N/E + S/\sqrt{E}
     734ELG_Scen          0.05     // S term for central ECAL
     735ELG_Ncen          0.25     // N term for central ECAL
     736ELG_Ccen          0.005    // C term for central ECAL
     737ELG_Cfwd          0.107    // S term for FCAL
     738ELG_Sfwd          2.084    // C term for FCAL
     739ELG_Nfwd          0.0      // N term for FCAL
     740 
     741# Energy resolution for hadrons in ecal/hcal/hf
     742# \sigma/E = C + N/E + S/\sqrt{E}
     743HAD_Shcal         1.5      // S term for central HCAL
     744HAD_Nhcal         0.       // N term for central HCAL
     745HAD_Chcal         0.05     // C term for central HCAL
     746HAD_Shf           2.7      // S term for FCAL
     747HAD_Nhf           0.       // N term for FCAL
     748HAD_Chf           0.13     // C term for FCAL
     749 
     750# Muon smearing
     751MU_SmearPt        0.01
     752 
     753# Tracking efficiencies
     754TRACK_ptmin       0.9      // minimal pT
     755TRACK_eff         100      // efficiency associated to the tracking
     756 
     757# Calorimetric towers
     758TOWER_number         40
     759### list of the edges of each tower in eta for eta>0 assuming
     760###a symmetric detector in eta<0
     761### the list starts with the lower edge of the most central tower
     762### the list ends with the higher edged of the most forward tower
     763### there should be NTOWER+1 values
     764TOWER_eta_edges 0.    0.087 0.174 0.261 0.348 0.435 0.522 0.609 0.696 0.783
     765               0.870 0.957 1.044 1.131 1.218 1.305 1.392 1.479 1.566 1.653
     766               1.740 1.830 1.930 2.043 2.172 2.322 2.500 2.650 2.868 2.950
     767               3.125 3.300 3.475 3.650 3.825 4.000 4.175 4.350 4.525 4.700
     768               5.000
     769 
     770### list of the tower size in phi (in degrees), assuming that all
     771### towers are similar in phi for a given eta value
     772### the list starts with the phi-size of the most central tower (eta=0)
     773### the list ends with the phi-size of the most forward tower
     774### there should be NTOWER values
     775#TOWER_dphi 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 10
     776           10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 20 20
     777 
     778# Thresholds for reconstructed objetcs
     779PTCUT_elec       10.0
     780PTCUT_muon       10.0
     781PTCUT_jet        20.0
     782PTCUT_gamma      10.0
     783PTCUT_taujet     10.0
     784 
     785# General jet variable
     786JET_coneradius   0.7      // generic jet radius
     787JET_jetalgo      1        // Jet aglorithm selection
     788JET_seed         1.0      // minimum seed to start jet reconstruction
     789 
     790# Tagging definition
     791BTAG_b           40
     792BTAG_mistag_c    10
     793BTAG_mistag_l    1
     794 
     795# FLAGS
     796FLAG_bfield      0        // 1 to run the bfield propagation else 0
     797FLAG_vfd         1        // 1 to run the very forward detectors else 0
     798FLAG_trigger     1        // 1 to run the trigger selection else 0
     799FLAG_frog        1        // 1 to run the FROG event display
     800 
     801# In case BField propagation allowed
     802TRACK_radius      129     // radius of the BField coverage
     803TRACK_length      300     // length of the BField coverage
     804TRACK_bfield_x    0       // X composant of the BField
     805TRACK_bfield_y    0       // Y composant of the BField
     806TRACK_bfield_z    3.8     // Z composant of the BField
     807 
     808# In case Very forward detectors allowed
     809VFD_min_calo_vfd  5.2     // very forward calorimeter (if any) like CASTOR
     810VFD_max_calo_vfd  6.6
     811VFD_min_zdc       8.3
     812VFD_s_zdc         140     // distance of the ZDC, from the IP, in [m]
     813 
     814RP_220_s          220     // distance of the RP to the IP, in meters
     815RP_220_x          0.002   // distance of the RP to the beam, in meters
     816RP_420_s          420     // distance of the RP to the IP, in meters
     817RP_420_x          0.004   // distance of the RP to the beam, in meters
     818 
     819# In case FROG event display allowed
     820NEvents_Frog      100
     821 
    731822\end{verbatim}
    732     \end{quote}
    733   \end{enumerate}
    734 \item An example (the default trigger card) can be found <a href="files/trigger.dat" title="Home">here</a></li>
    735 \end{itemize}
    736 
     823\end{quote}
     824 
     825 
     826\item{\bf The trigger card }
     827 
     828Contains 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:
     829 
     830\begin{quote}
     831\begin{tabular}{ll}
     832{\it Trigger flag} & {\it Corresponding object}\\
     833{\verb ELEC_PT } & electron \\
     834{\verb MUON_PT } & muon \\
     835{\verb JET_PT } & jet \\
     836{\verb TAUJET_PT } & tau-jet \\
     837{\verb ETMIS_PT } & transverse missing energy \\
     838{\verb GAMMA_PT } & photon \\
     839\end{tabular}
     840\end{quote}
     841 
     842Moreover, 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:
     843\begin{quote}
     844\begin{verbatim}   DoubleElec                  >> ELEC_PT: '20' && ELEC_PT: '10'   SingleElec and Single Muon  >> ELEC_PT: '20' && MUON_PT: '15'
     845\end{verbatim}
     846\end{quote}
     847 
     848An example (the default trigger card) can be found in {\verb files/trigger.dat }.
     849 
     850\end{enumerate}
     851 
    737852\subsubsection{Running the code}
    738 Create the above cards (data/mydetector.dat and data/mytrigger.dat)
    739 Create a text file containing the list of input files that will be used by \textsc{Delphes} (with extension *.lhe, *.root or *.hep)
     853 
     854Create 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)
    740855To run the code, type the following
    741856\begin{quote}
     
    744859\end{verbatim}
    745860\end{quote}
    746 
    747 
     861 
     862 
     863\subsection{Getting the \textsc{Delphes} information}
     864 
     865\subsubsection{Contents of the \textsc{Delphes} \textsc{root} trees}
     866 
     867As 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:
     868 
     869\begin{quote}
     870\begin{tabular}{lll}
     871{\bf GEN \textsc{tree}} & &\\
     872Particle & generator particles from \textsc{hepevt}     & {\verb TRootGenParticle }\\
     873{\bf Analysis \textsc{tree}} & & \\
     874Jet        & Jet collection                             & {\verb TRootJet }\\
     875TauJet     & Collection of jets tagged as $\tau$-jets   & {\verb TRootTauJet }\\
     876Electron   & Collection of electrons                    & {\verb TRootElectron }\\
     877Muon       & Collection of muons                        & {\verb TRootMuon }\\
     878Photon     & Collection of photons                      & {\verb TRootPhoton }\\
     879Tracks     & Tracker tracks                             & {\verb TRootTracks }\\
     880ETmis      & Transverse missing energy information      & {\verb TRootETmis }\\
     881CaloTower  & Calorimetric towers                        & {\verb TRootCalo }\\
     882ZDChits    & ?????                                      & {\verb TRootZdcHits }\\
     883RP220hits  & ?????                                      & {\verb TRootRomanPotHits }\\
     884FP420hits  &?????                                       & {\verb TRootRomanPotHits }\\
     885{\bf Trigger  } & &\\
     886TrigResult & Acceptance of different trigger bits       & {\verb TRootTrigger }\\
     887\end{tabular}
     888\end{quote}
     889 
     890The 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:
     891 
     892\begin{quote}
     893\begin{verbatim}
     894 
     895 float E;  // particle energy in GeV
     896 float Px; // particle momentum vector (x component) in GeV
     897 float Py; // particle momentum vector (y component) in GeV
     898 float Pz; // particle momentum vector (z component) in GeV
     899 
     900 float PT; // particle transverse momentum in GeV
     901 float Eta; // particle pseudorapidity  float Phi; // particle azimuthal angle in rad
     902\end{verbatim}
     903\end{quote}
     904 
     905In addition to their four-momentum and related quantities, additional properties are available for specific objects. Those are summarized in the following table:
     906\begin{quote}
     907\begin{tabular}{ll}
     908{\bf \texttt{Particle} leave } &\\    \texttt{  int PID;      }&\texttt{ // particle HEP ID number }\\
     909   \texttt{  int Status;   }&\texttt{ // particle status }\\
     910   \texttt{  int M1;       }&\texttt{ // particle 1st mother }\\
     911   \texttt{  int M2;       }&\texttt{ // particle 2nd mother }\\
     912   \texttt{  int D1;       }&\texttt{ // particle 1st daughter }\\
     913   \texttt{  int D2;       }&\texttt{ // particle 2nd daughter }\\
     914   \texttt{  float Charge; }&\texttt{ // electrical charge }\\
     915   \texttt{  float T;      }&\texttt{ // particle vertex position (t component) }\\
     916   \texttt{  float X;      }&\texttt{ // particle vertex position (x component) }\\
     917   \texttt{  float Y;      }&\texttt{ // particle vertex position (y component) }\\
     918   \texttt{  float Z;      }&\texttt{ // particle vertex position (z component) }\\
     919   \texttt{  float M;      }&\texttt{ // particle mass }\\
     920{\bf \texttt{Electron} and \texttt{Muon} leaves } &\\
     921   \texttt{ int Charge } &\\
     922   \texttt{ bool IsolFlag } &\\
     923{\bf \texttt{Jet} leave }  &\\
     924   \texttt{ bool Btag } &\\
     925{\bf \texttt{ZDChits} leave } &\\
     926   \texttt{float T;        }&\texttt{ // time of flight [s] }\\
     927   \texttt{ int side;      }&\texttt{ // -1 or +1 }\\
     928\end{tabular}
     929\end{quote}
     930 
    748931\subsection{Running an analysis on your \textsc{Delphes} events}
    749 
    750 Two examples of codes running on the output root file of \textsc{Delphes} are coming with the package
    751 \begin{enumerate}
    752 \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:
    753   \begin{quote}
     932 
     933To 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:
     934 \begin{quote}
    754935\begin{verbatim}
    755936./Analysis_Ex input_file.list output_file.root
    756937\end{verbatim}
    757   \end{quote}
    758  
    759 \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:
    760   \begin{quote}
     938 \end{quote}
     939 
     940 
     941 
     942\subsubsection{sdflksdjf}
     943The \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:
     944 \begin{quote}
    761945\begin{verbatim}
    762946./Trigger_Only input_file.root data/trigger.dat
    763947\end{verbatim}
    764   \end{quote}
    765  
    766 \end{enumerate}
    767 
     948 \end{quote}
     949 
    768950\subsection{Running the \textsc{Frog} event display}
    769 
    770 
    771 
    772 
     951 
    773952\begin{itemize}
    774953\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.
     
    776955\item Go back into the main directory and type {\verb ./Utilities/FROG/frog }.
    777956\end{itemize}
    778 
    779 
    780 In the list of input files, all files should have the same type
    781 
    782  in other words, the effect related to the particle showers that would happen in the calorimeters are not taken into account.
    783 
     957 
    784958\end{document}
Note: See TracChangeset for help on using the changeset viewer.