Index: trunk/paper/notes.tex
===================================================================
--- trunk/paper/notes.tex	(revision 142)
+++ trunk/paper/notes.tex	(revision 143)
@@ -91,5 +91,5 @@
 A new framework, called \textsc{Delphes}~\cite{bib:Delphes}, is introduced here, for the fast simulation of a general purpose collider experiment. 
 Using the framework, observables can be estimated for specific signal and background channels, as well as their production and measurement rates, under a set of assumptions. 
-Starting from the output of event generators, the simulation of the detector response takes into account the subdetector resolutions, by smearing the kinematical properties of the visible final particles. Tracks of charged particles and calorimetric towers (or \textit{calotowers} are then created.
+Starting from the output of event generators, the simulation of the detector response takes into account the subdetector resolutions, by smearing the kinematics properties of the visible final particles. Tracks of charged particles and calorimetric towers (or \textit{calotowers} are then created.
 
 \textsc{Delphes} includes the most crucial experimental features, like (1) the geometry of both central or forward detectors; (2) lepton isolation; (3) reconstruction of photons, leptons, jets, $b$-jets, $\tau$-jets and missing transverse energy; (4) trigger emulation and (5) an event display (Fig.~\ref{fig:FlowChart}).
@@ -99,9 +99,9 @@
 %\includegraphics[width=0.9\textwidth]{FlowDelphes}
 \includegraphics[scale=0.78]{FlowDelphes}
-\caption{Flow chart describing the principles behind \textsc{Delphes}. Event files coming from external Monte Carlo generators are read by a convertor stage. 
-The kinematical variables of the final state particles are then smeared according to the subdetector resolutions. 
+\caption{Flow chart describing the principles behind \textsc{Delphes}. Event files coming from external Monte Carlo generators are read by a converter stage. 
+The kinematics variables of the final state particles are then smeared according to the subdetector resolutions. 
 Tracks are reconstructed in a simulated dipolar magnetic field and calorimetric towers sample the energy deposits. Based on these, dedicated algorithms are applied for particle identification, isolation and reconstruction. 
 The transport of very forward particle to the near-beam detectors is also simulated. 
-Finally, an output file is written, including generator level and analysis object data. If requested, a fully parametrisable trigger can be emulated. Optionnally, the geometry and visualisation files for the 3D event display can also be produced.
+Finally, an output file is written, including generator level and analysis object data. If requested, a fully parametrisable trigger can be emulated. Optionally, the geometry and visualisation files for the 3D event display can also be produced.
 All user parameters are set in the \textit{Smearing Card} and the \textit{Trigger Card}. }
 \label{fig:FlowChart}
@@ -125,5 +125,5 @@
 A central tracking system (\textsc{tracker}) is surrounded by an electromagnetic and a hadron calorimeters (\textsc{ecal} and \textsc{hcal}, resp.). Two forward calorimeters (\textsc{fcal}) ensure a larger geometric coverage for the measurement of the missing transverse energy. Finally, a muon system (\textsc{muon}) encloses the central detector volume
 The fast simulation of the detector response takes into account geometrical acceptance of sub-detectors and their finite resolution, as defined in the smearing data card\footnote{\texttt{[code] }See the \texttt{RESOLution} class.}. 
-If no such file is provided, predifined values are used. The coverage of the various subsystems used in the default configuration are summarised in Tab.~\ref{tab:defEta}.
+If no such file is provided, predefined values are used. The coverage of the various subsystems used in the default configuration are summarised in Tab.~\ref{tab:defEta}.
 
 \begin{table*}[t]
@@ -177,5 +177,5 @@
 
 
-The particle four-momentum $p^\mu$ are smeared with a parametrisation directly derived from the detector techinal designs\footnote{\texttt{[code] }The response of the detector is applied to the electromagnetic and the hadronic particles through the \texttt{SmearElectron} and \texttt{SmearHadron} functions.}.
+The particle four-momentum $p^\mu$ are smeared with a parametrisation directly derived from the detector technical designs\footnote{\texttt{[code] }The response of the detector is applied to the electromagnetic and the hadronic particles through the \texttt{SmearElectron} and \texttt{SmearHadron} functions.}.
 In the default parametrisation, the calorimeter is assumed to cover the pseudorapidity range $|\eta|<3$ and consists in an electromagnetic and an hadronic part. Coverage between pseudorapidities of $3.0$ and $5.0$ is provided by forward calorimeters, with different response to electromagnetic objects ($e^\pm, \gamma$) or hadrons. 
 Muons and neutrinos are assumed no to interact with the calorimeters\footnote{In the current \textsc{Delphes} version, particles other than electrons ($e^\pm$), photons ($\gamma$), muons ($\mu^\pm$) and neutrinos ($\nu_e$, $\nu_\mu$ and $\nu_\tau$) are simulated as hadrons for their interactions with the calorimeters. The simulation of stable particles beyond the Standard Model should subsequently be handled with care.}.
@@ -229,6 +229,4 @@
 As the detector is assumed to be symmetric in $\phi$ and with respect to the $\eta=0$ plane, the smearing card stores the number of calorimetric towers with $\phi=0$ and $\eta>0$ (default: $40$ towers). For a given $\eta$, the size of the $\phi$ segmentation is also specified. Fig.~\ref{fig:calosegmentation} illustrates the default segmentation of the $(\eta,\phi)$ plane.
 
-
-
 \begin{figure}[!h]
 \begin{center}
@@ -244,6 +242,6 @@
 
 Most of the recent experiments in beam colliders have additional instrumentation along the beamline. These extend the $\eta$ coverage to higher values, for the detection of very forward final-state particles. 
-Zero Degree Calorimeters (\textsc{zdc}) are located at zero angle, i.e. are aligned with the beamline axis at the interaction point, and placed at the distance where the paths of incoming and outgoing beams separate (Fig.~\ref{fig:fdets}). These allow the measurement of stable neutral particles ($\gamma$ and $n$) coming from the interaction point, with large pseudorapirities (e.g. $|\eta_{\textrm{n,}\gamma}| > 8.3$ in \textsc{cms}).
-Forward taggers (called here \textsc{rp220} and \textsc{fp420} as at the \textsc{lhc}) are meant for the measurement of particles following very closely the beam path. To be able to reach these detectors, such particles must have a charge identical to the beam particles, and a momentum very close to the nominal value for the beam. These taggers are near-beam detectors located a few millimeters from the true beam trajectory and this distance defines their acceptance (Tab.~\ref{tab:fdetacceptance}).
+Zero Degree Calorimeters (\textsc{zdc}) are located at zero angle, i.e. are aligned with the beamline axis at the interaction point, and placed at the distance where the paths of incoming and outgoing beams separate (Fig.~\ref{fig:fdets}). These allow the measurement of stable neutral particles ($\gamma$ and $n$) coming from the interaction point, with large pseudorapidities (e.g. $|\eta_{\textrm{n,}\gamma}| > 8.3$ in \textsc{cms}).
+Forward taggers (called here \textsc{rp220} and \textsc{fp420} as at the \textsc{lhc}) are meant for the measurement of particles following very closely the beam path. To be able to reach these detectors, such particles must have a charge identical to the beam particles, and a momentum very close to the nominal value for the beam. These taggers are near-beam detectors located a few millimetres from the true beam trajectory and this distance defines their acceptance (Tab.~\ref{tab:fdetacceptance}).
 
 \begin{figure}[!h]
@@ -293,5 +291,5 @@
 
 Analysis object data contain the final collections of particles ($e^\pm$, $\mu^\pm$, $\gamma$) or objects (light jets, $b$-jets, $\tau$-jets, $E_T^\textrm{miss}$) and are stored\footnote{\texttt{[code] }All these processed data are located under the \texttt{Analysis} tree.} in the output file created by \textsc{Delphes}. 
-In addition, some detector data are added: tracks, calorometric towers and hits in \textsc{zdc}, \textsc{rp220} and \textsc{fp420}. 
+In addition, some detector data are added: tracks, calorimetric towers and hits in \textsc{zdc}, \textsc{rp220} and \textsc{fp420}. 
 While electrons, muons and photons are easily identified, some other objects are more difficult to measure, like jets or missing energy due to invisible particles.
 
@@ -324,5 +322,5 @@
 
 A realistic analysis requires a correct treatment of final state particles which hadronise. Therefore, the most widely currently used jet algorithms have been integrated into the \textsc{Delphes} framework using the \textsc{FastJet} tools~\cite{bib:FastJet}. 
-Six different jet reconstruction schemes are available\footnote{\texttt{[code] }The choice is done by allocating the \texttt{JET\_jetalgo } input parameter in the smearing card.}. The first three belong to the cone algorithm class while the last three are using a sequential recombinaison scheme. For all of them, the towers are used as input of the jet clustering. Jet algorithms also differ with their sensitivity to soft particles or collinear splittings, and with their computing speed performance.
+Six different jet reconstruction schemes are available\footnote{\texttt{[code] }The choice is done by allocating the \texttt{JET\_jetalgo } input parameter in the smearing card.}. The first three belong to the cone algorithm class while the last three are using a sequential recombination scheme. For all of them, the towers are used as input of the jet clustering. Jet algorithms also differ with their sensitivity to soft particles or collinear splittings, and with their computing speed performance.
  
 \subsubsection*{Cone algorithms}
@@ -336,5 +334,5 @@
 In the following versions of \textsc{Delphes}, a new dedicated plug-in will be created on this purpose\footnote{\texttt{[code] }\texttt{JET\_coneradius} and \texttt{JET\_seed} variables in the smearing card.}.
  
-\item {\it CDF MidPoint}~\cite{bib:midpoint}: Algorithm developped for the \textsc{cdf} Run II to reduce infrared and collinear sensitivity compared to purely seed-based cone by adding `midpoints' (energy barycenters) in the list of cone seeds.
+\item {\it CDF MidPoint}~\cite{bib:midpoint}: Algorithm developed for the \textsc{cdf} Run II to reduce infrared and collinear sensitivity compared to purely seed-based cone by adding `midpoints' (energy barycentres) in the list of cone seeds.
  
 \item {\it Seedless Infrared Safe Cone}~\cite{bib:SIScone}: The \textsc{SISCone} algorithm is simultaneously insensitive to additional soft particles and collinear splittings, and fast enough to be used in experimental analysis.
@@ -397,5 +395,5 @@
 
 Jets originating from $\tau$-decays are identified using an identification procedure consistent with the one applied in a full detector simulation~\cite{bib:cmsjetresolution}. 
-The tagging rely on two properties of the $\tau$ lepton. First, $77\%$ of the $\tau$ hadronic decays contain only one charged hadron associated to a few neutrals (Tab.~\ref{tab:taudecay}). Tracks are useful for this criterium. Secondly, the particles arisen from the $\tau$ lepton produce narrow jets in the calorimeter (\textit{collimation}). 
+The tagging rely on two properties of the $\tau$ lepton. First, $77\%$ of the $\tau$ hadronic decays contain only one charged hadron associated to a few neutrals (Tab.~\ref{tab:taudecay}). Tracks are useful for this criterion. Secondly, the particles arisen from the $\tau$ lepton produce narrow jets in the calorimeter (\textit{collimation}). 
 
 \begin{table}[!h]
@@ -539,5 +537,5 @@
 Its quality and validity are assessed by comparing to resolution of the reconstructed data to the \textsc{cms} detector expectations. 
 
-Electrons and muons match by construction to the experiment designs, as the Gaussian smearing of their kinematical properties is defined according to the experiment resolution.
+Electrons and muons match by construction to the experiment designs, as the Gaussian smearing of their kinematics properties is defined according to the experiment resolution.
 Similarly, the $b$-tagging efficiency (for real $b$-jets) and misidentification rates (for fake $b$-jets) are taken from the expected values of the experiment. 
 Unlike these simple objects, jets and missing transverse energy should be carefully cross-checked.
@@ -552,8 +550,8 @@
 \end{equation}
 The jets made of generator-level particles, or \textsc{mc} jets, are obtained by applying the same clustering algorithm to all particles considered as stable after hadronisation.
-Jets produced by \textsc{Delphes} and satisfying the matching criterium are called hereafter \textit{reconstructed jets}.
+Jets produced by \textsc{Delphes} and satisfying the matching criterion are called hereafter \textit{reconstructed jets}.
 
 The ratio of the transverse energies of every reconstructed jet $E_T^\textrm{rec}$ and its corresponding \textsc{mc} jet $E_T^\textrm{MC}$ is calculated in each $\hat{p}_T$ bin.
-The $E_T^\textrm{rec}/E_T^\textrm{MC}$ histogram is fitted with a Gaussian distribution in the interval \mbox{$\pm 2$~\textsc{rms}} centered around the mean value. 
+The $E_T^\textrm{rec}/E_T^\textrm{MC}$ histogram is fitted with a Gaussian distribution in the interval \mbox{$\pm 2$~\textsc{rms}} centred around the mean value. 
 The resolution in each $\hat{p}_T$ bin is obtained by the fit mean $\langle x \rangle$ and variance $\sigma^2(x)$:
 \begin{equation}
@@ -608,5 +606,5 @@
 where the $\alpha$ parameter is depending on the resolution of the calorimeters. 
 
-The \textsc{met} resolution expected for the \textsc{cms} detector for similar events is $\sigma_x = (0.6-0.7) ~ (\Sigma E_T) ~ \mathrm{GeV}^{1/2}$ with no pile-up\footnote{\textit{Pile-up} events are extra simultaneous $pp$ collision occuring at the same bunch crossing.}~\cite{bib:cmsjetresolution}. 
+The \textsc{met} resolution expected for the \textsc{cms} detector for similar events is $\sigma_x = (0.6-0.7) ~ (\Sigma E_T) ~ \mathrm{GeV}^{1/2}$ with no pile-up\footnote{\textit{Pile-up} events are extra simultaneous $pp$ collision occurring at the same bunch crossing.}~\cite{bib:cmsjetresolution}. 
 The same quantity obtained by \textsc{Delphes} is in excellent agreement with the expectations of the general purpose detector, as $\alpha = 0.68$.
 
@@ -651,5 +649,5 @@
 % \end{figure}
  
-Two and three-dimentional representations of the detector configuration can be used for communication purpose, as it clearly shows the geometric coverage of the different detector subsystems. As an illustration, the generic detector geometry assumed in \textsc{Delphes} is shown in Fig.~\ref{fig:GenDet3}
+Two and three-dimensional representations of the detector configuration can be used for communication purpose, as it clearly shows the geometric coverage of the different detector subsystems. As an illustration, the generic detector geometry assumed in \textsc{Delphes} is shown in Fig.~\ref{fig:GenDet3}
 %, \ref{fig:GenDet}
  and~\ref{fig:GenDet2}.  
@@ -667,6 +665,6 @@
  
 Deeper understanding of interesting physics processes is possible by displaying the events themselves. 
-The visibility of each set of objects ($e^\pm$, $\mu^\pm$, $\tau^\pm$, jets, transverse missing energy) is enhanced by a color coding. 
-Moreover, kinematical information of each object is visible by a simple mouse action. 
+The visibility of each set of objects ($e^\pm$, $\mu^\pm$, $\tau^\pm$, jets, transverse missing energy) is enhanced by a colour coding. 
+Moreover, kinematics information of each object is visible by a simple mouse action. 
 As an illustration, an associated photoproduction of a $W$ boson and a $t$ quark is shown in Fig.~\ref{fig:wt}. 
 This corresponds to a $pp(\gamma p \rightarrow Wt)pX$ process, where the $Wt$ couple is induced by an incoming photon emitted by one interacting proton~\cite{bib:wtphotoproduction}. 
@@ -675,14 +673,32 @@
 The experimental signature is a lack of hadronic activity in one forward hemisphere, where the surviving proton escapes. 
 The $t$ quark decays into a $W$ boson and a $b$ quark. 
-Both $W$ bosons decay into leptons ($W \rightarrow \mu \nu_\mu$ and $W \rightarrow \tau \nu_\tau$).
-The balance between the missing transverse energy and the charged lepton pair is clear, as well as the presence of an empty forward region.
- 
+Both $W$ bosons decay into leptons ($W \rightarrow \mu \nu_\mu$ and $W \rightarrow e \nu_e$).
+The balance between the missing transverse energy and the charged lepton pair is clear, as well as the presence of an empty forward region. It is interesting to notice that the reconstruction algorithms build a fake $\tau$-jet around the electron.
+
 \begin{figure}[!h]
 \begin{center}
-\includegraphics[width=\columnwidth]{Events_Delphes_1}
-\caption{Example of $pp(\gamma p \rightarrow Wt)pY$ event, with $t \rightarrow Wb$. One $W$ boson decays into a $\mu \nu_\mu$ pair and the second one into a $\tau \nu_\tau$ pair. The surviving proton leaves a forward hemisphere with no hadronic activity. The isolated muon is shown as the blue vector. The $\tau$-jet is the cone around the green vector, while the reconstructed missing energy is shown in gray. One jet is visible in one forward region, along the beamline axis, opposite to the direction of the escaping proton.}
+%\includegraphics[width=\columnwidth]{Events_Delphes_1}
+\includegraphics[width=\columnwidth]{DisplayWt}
+\caption{Example of $pp(\gamma p \rightarrow Wt)pY$ event, with $t \rightarrow Wb$. 
+One $W$ boson decays into a $\mu \nu_\mu$ pair and the second one into a $e \nu_e$ pair. 
+The surviving proton leaves a forward hemisphere with no hadronic activity. 
+The isolated muon is shown as the blue vector. 
+Around the electron, in red, is reconstructed a fake $\tau$-jet (green vector surrounded by a blue cone), while the reconstructed missing energy (in grey) is very small. One jet is visible in one forward region, along the beamline axis, opposite to the direction of the escaping proton.}
 \label{fig:wt}
 \end{center}
 \end{figure}
+
+For the comparison, Fig.~\ref{fig:gg} depicts an inclusive gluon pair production $pp \rightarrow ggX$.
+The event final state contains more jets, in particular along the beam axis, which is expected as the interacting protons are destroyed by the collision. Two muon candidates and large missing transverse energy are also visible.
+
+\begin{figure}[!h]
+\begin{center}
+%\includegraphics[width=\columnwidth]{Events_Delphes_1}
+\includegraphics[width=\columnwidth]{Displayppgg}
+\caption{Example of inclusive gluon pair production $pp \rightarrow ggX$. Many jets are visible in the event, in particular along the beam axis. Two muons (in blue) are produced and the missing transverse energy is significant in this event (grey vector).}
+\label{fig:gg}
+\end{center}
+\end{figure}
+
 
 \section{Conclusion and perspectives}
@@ -711,5 +727,5 @@
 Moreover, the framework allows trigger emulation and 3D event visualisation.
 
-\textsc{Delphes} has been developped using the parameters of the \textsc{cms} experiment but can be easily extended to \textsc{atlas} and other non-\textsc{lhc} experiments, as at Tevatron or at the \textsc{ilc}. Further developments include a more flexible design for the subdetector assembly and possibly the implementation of an event mixing module for pile-up event simulation.
+\textsc{Delphes} has been developed using the parameters of the \textsc{cms} experiment but can be easily extended to \textsc{atlas} and other non-\textsc{lhc} experiments, as at Tevatron or at the \textsc{ilc}. Further developments include a more flexible design for the subdetector assembly and possibly the implementation of an event mixing module for pile-up event simulation.
 
 
@@ -717,5 +733,5 @@
 \section*{Acknowledgements}
 \addcontentsline{toc}{section}{Acknowledgements}
-The authors would like to thank Vincent Lema\^itre, Muriel Vander Donckt and David d'Enterria for useful discussions and comments, and Loic Quertenmont for support in interfacing \textsc{Frog}. We are also really greatful to Alice Dechambre and Simon de Visscher for being beta testers of the complete package. 
+The authors would like to thank Vincent Lema\^itre, Muriel Vander Donckt and David d'Enterria for useful discussions and comments, and Loic Quertenmont for support in interfacing \textsc{Frog}. We are also really grateful to Alice Dechambre and Simon de Visscher for being beta testers of the complete package. 
 Part of this work was supported by the Belgian Federal Office for Scientific, Technical and Cultural Affairs through the Interuniversity Attraction Pole P6/11. 
 
@@ -763,5 +779,5 @@
 \section{User manual}
  
-The available code is a zipped tar file which comes with everything needed to run the \textsc{Delphes} package, assuming a running. 
+The available code is a zipped tar file which comes with everything needed to run the \textsc{Delphes} package, assuming a running \textsc{root} installation. 
 The package includes \texttt{ExRootAnalysis}~\cite{bib:ExRootAnalysis}, \textsc{Hector}~\cite{bib:Hector}, 
 \textsc{FastJet}~\cite{bib:FastJet}, and \textsc{Frog}~\cite{bib:Frog}, as well as the conversion codes to read standard \mbox{\textsc{s}td\textsc{hep}} input files (\texttt{mcfio} and \texttt{stdhep})~\cite{bib:mcfio}.
@@ -770,17 +786,29 @@
 \subsection{Getting started}
  
-In order to run \textsc{Delphes} on your system, first download is sources and compile it:\\
+In order to run \textsc{Delphes} on your system, first download its sources and compile it:\\
+\texttt{wget http://www.fynu.ucl.ac.be/users/s.ovyn/Delphes/files/Delphes\_V\_*.tar.gz}\\
+Replace the \texttt{*} symbol by the proper version number\footnote{Refer to the download page on the \textsc{Delphes} website \href{http://www.fynu.ucl.ac.be/users/s.ovyn/Delphes/download.html}{http://www.fynu.ucl.ac.be/users/s.ovyn/Delphes/download.html}.}.
+
 \begin{quote}
 \begin{verbatim}
-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
+me@mylaptop:~$ tar -xvf Delphes_V_*.tar.gz 
+me@mylaptop:~$ cd Delphes_V_*.*
+me@mylaptop:~$ ./genMakefile.tcl > Makefile
+me@mylaptop:~$ make
 \end{verbatim}
-\end{quote}    
+\end{quote}
+Due to the large number of external utilities, the number of printed lines during the compilation can be high.
+The user should not pay attention to possible warning messages.
+When compilation is completed, the following message is printed:
+\begin{quote}
+\begin{verbatim}
+me@mylaptop:~$ Delphes has been compiled
+me@mylaptop:~$ Ready to run
+\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 }).
+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 }). 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 file that will contain the generator-level data (\texttt{GEN} tree), the analysis data objects after reconstruction (\texttt{Analysis} tree), and the results of the trigger emulation (\texttt{Trigger} tree).
  
 \begin{quote}
@@ -790,23 +818,24 @@
 \end{quote}
  
-\subsubsection{Setting the run configuration}
+\subsubsection{Setting up the configuration}
  
 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.
+Please note that either the user provides these two datacards, either the running will be done using the default parameters defined in the constructor of the class \texttt{RESOLution}. If you choose 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}
+\item{\bf The smearing card }
+
+The \textit{smearing} or \textit{run} card is by default \texttt{data/DataCard.dat}.
+It contains all pieces of information needed 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 detector parameters, including calorimeter and tracking coverage and resolution, transverse energy thresholds for object reconstruction and jet algorithm parameters.
+ \item four flags ({\verb FLAG_bfield }, {\verb FLAG_vfd }, {\verb FLAG_trigger } and {\verb FLAG_frog }), which should be assigned if the magnetic field propagation, the very forward detectors simulation, the trigger selection and the preparation for \textsc{Frog} display (respectively) have to be run 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:
+If no datacard is provided by the user, the default smearing and running parameters are used:
 \begin{quote}
 \begin{verbatim}
-# Detector characteristics
+# Detector extension, in pseudorapidity units
 CEN_max_tracker    2.5     // Maximum tracker coverage
 CEN_max_calo_cen   3.0     // central calorimeter coverage
@@ -815,5 +844,5 @@
  
 # Energy resolution for electron/photon
-# \sigma/E = C + N/E + S/\sqrt{E}
+# \sigma/E = C + N/E + S/\sqrt{E}, E in GeV
 ELG_Scen          0.05     // S term for central ECAL
 ELG_Ncen          0.25     // N term for central ECAL
@@ -824,5 +853,5 @@
  
 # Energy resolution for hadrons in ecal/hcal/hf
-# \sigma/E = C + N/E + S/\sqrt{E}
+# \sigma/E = C + N/E + S/\sqrt{E}, E in GeV
 HAD_Shcal         1.5      // S term for central HCAL
 HAD_Nhcal         0.       // N term for central HCAL
@@ -833,10 +862,10 @@
  
 # Muon smearing
-MU_SmearPt        0.01
+MU_SmearPt        0.01    // transverse momentum Pt in GeV
  
 # Tracking efficiencies
 TRACK_ptmin       0.9      // minimal pT
-TRACK_eff         100      // efficiency associated to the tracking
- 
+TRACK_eff         100      // efficiency associated to the tracking (%)
+
 # Calorimetric towers
 TOWER_number         40
@@ -860,5 +889,5 @@
            10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 20 20
  
-# Thresholds for reconstructed objetcs
+# Thresholds for reconstructed objects, in GeV
 PTCUT_elec       10.0
 PTCUT_muon       10.0
@@ -869,11 +898,11 @@
 # 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
+JET_jetalgo      1        // Jet algorithm selection
+JET_seed         1.0      // minimum seed to start jet reconstruction, in GeV
+ 
+# Tagging definition 
+BTAG_b           40      // b-tag efficiency (%)
+BTAG_mistag_c    10      // mistagging (%)
+BTAG_mistag_l    1	 // mistagging (%)
  
 # FLAGS
@@ -884,11 +913,12 @@
  
 # 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
+TRACK_radius      129     // radius of the BField coverage, in cm
+TRACK_length      300     // length of the BField coverage, in cm
+TRACK_bfield_x    0       // X composant of the BField, in T
+TRACK_bfield_y    0       // Y composant of the BField, in T
+TRACK_bfield_z    3.8     // Z composant of the BFieldn in T
+ 
+# Very forward detector extension, in pseudorapidity
+# if allowed
 VFD_min_calo_vfd  5.2     // very forward calorimeter (if any) like CASTOR
 VFD_max_calo_vfd  6.6
@@ -906,25 +936,28 @@
 \end{verbatim}
 \end{quote}
- 
+In general, energies and momenta are expressed in GeV, and  magnetic fields in T.
+Geometrical extension are often referred in terms of pseudorapidity $\eta$, as the detectors are supposed to be symmetric in $\phi$.
  
 \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:
+This card contains the definitions of all trigger bits. Cuts can be applied on the transverse momentum $p_T$ of electrons, muons, jets, $\tau$-jets, photons and the missing transverse energy. The following codes 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}\\
+{\it Trigger code} & {\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 TAUJET_PT } & $\tau$-jet \\
+{\verb ETMIS_PT } & missing transverse 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:
+Each line in the trigger datacard is allocated to exactly one trigger bit and starts with the name of the corresponding trigger. Logical combination of several conditions is also possible. If the trigger bit requires the presence of multiple identical objects, the order of their $p_T$ thresholds is very important: they must be defined in \textit{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} (\texttt{data/trigger.dat}). An example 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'
+\begin{verbatim}   
+DoubleElec                  >> ELEC_PT: '20' && ELEC_PT: '10'   
+SingleElec and Single Muon  >> ELEC_PT: '20' && MUON_PT: '15'
 \end{verbatim}
 \end{quote}
@@ -987,5 +1020,5 @@
 \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:
+In addition to their four-momentum and related quantities, additional properties are available for specific objects. Those are summarised in the following table:
 \begin{quote}
 \begin{tabular}{ll}
@@ -1015,5 +1048,5 @@
 \subsection{Running an analysis on your \textsc{Delphes} events}
  
-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:
+To analyse 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 analysed 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}
