[[TOC]]

= Delphes Tutorial - MC4BSM July 2016 =

== Pre-requisites ==

To successfully build Delphes the following prerequisite packages should be installed:

- gcc/tcl:

For linux users gcc/tcl should be already installed. For Mac users you should install XCode.

- ROOT:

can be downloaded from https://root.cern.ch/downloading-root
Go on latest release, and download a version under "Binary distributions".

Once it is installed, type:

{{{
source [path_to_installation]/root/bin/thisroot.sh
}}}

Then simply type in a terminal:

{{{
echo $ROOTSYS
}}}

If a path is shown then root is properly installed.

=== Part I - Getting Started ===

0) Create a tutorial directory:

{{{
mkdir DelphesTutorial
cd DelphesTutorial
}}}

1) Get Delphes:
{{{
git clone https://github.com/delphes/delphes.git
cd delphes
}}}
or, if you don't have "git" installed, simply type:
{{{
wget http://cp3.irmp.ucl.ac.be/downloads/Delphes-3.3.2.tar.gz
tar -zxf Delphes-3.3.2.tar.gz
mv Delphes-3.3.2 delphes
cd delphes
}}}
2) Install it:
{{{
./configure
make -j 4
}}}
3) Download Z' (m= 2 TeV) to WW and dijet (pT > 1 TeV) events in stdhep format
{{{
wget 
wget
gunzip pp_zp_ww.hep.gz
gunzip pp_jj.hep.gz
}}}

4) Finally, let's run Delphes. If the compilation went right, you should have three executables:

- DelphesLHEF  -> should not be used
- DelphesHepMC -> to be used on HepMC input format (*.hepmc)
- DelphesSTDHEP -> to be used on STDHEP input format (*.hep)

Type for instructions (note that output file comes before input file):
{{{
./DelphesSTDHEP
}}}
To run on our your input file, type:
{{{
./DelphesSTDHEP cards/delphes_card_CMS.tcl out_pp_zp_ww.root pp_zp_ww.hep
}}}
5) Open freshly produced Delphes output with ROOT, and explore it.
{{{
root -l  out_pp_zp_ww.root
TBrowser t;
}}}
In the browser, double click on the "out_pp_zp_ww.root", and then on the "Delphes" tree. Play around by double clicking on the various branches/observables.

You can then play plot important observable with a simple selection with the following syntax:
{{{
Delphes->Draw("Muon.PT", "Muon.PT > 20");
Delphes->Draw("Electron.PT", "Electron.PT > 20");
}}}
- Note 1: Delphes - tree name, it can be learnt e.g. from TBrowser
- Note 2: !Muon/Electron - branch name; PT - variable (leaf) of this branch
{{{
Delphes->Draw("Jet.Mass","Electron_size + Muon_size == 1");
Delphes->Draw("Jet.Mass","Electron_size + Muon_size == 1 && Jet.PT > 500");
}}}
Objects are already ordered in PT, you can then plot the leading jet observables in this way:
{{{
Delphes->Draw("Jet[0].Mass");
Delphes->Draw("Jet[0].PT");
}}}
For more information on ROOT trees:

http://cp3.irmp.ucl.ac.be/downloads/RootTreeDescription.html

=== Part II - Understand and modify the configuration file ===

The delphes card can be schematically divided in three parts:
The !ExecutionPath is where the simulation/reconstruction sequence of modules is defined
The list of modules configurations.
The !TreeWriter, where the user defines which objects he stores in the output tree.

You can find an explanation for most Delphes modules here:
https://cp3.irmp.ucl.ac.be/projects/delphes/wiki/WorkBook/Modules

1. Open the card cards/delphes_card_CMS.tcl with your favorite editor and try to make sense of it.

2. Then configure the !FastJetFinder module by switching on the options for substructure:

{{{
###################
# Fast Jet finder
###################

module FastJetFinder FastJetFinder {
  set InputArray EFlowMerger/eflow

  set OutputArray jets

  # algorithm: 1 CDFJetClu, 2 MidPoint, 3 SIScone, 4 kt, 5 Cambridge/Aachen, 6 antikt 
  set JetAlgorithm 5 
  set ParameterR 0.8

  set ComputeNsubjettiness 1
  set Beta 1.0
  set AxisMode 4

  set ComputeTrimming 1
  set RTrim 0.2
  set PtFracTrim 0.05

  set ComputePruning 1
  set ZcutPrun 0.1
  set RcutPrun 0.5
  set RPrun 0.8

  set ComputeSoftDrop 1
  set BetaSoftDrop 0.0
  set SymmetryCutSoftDrop 0.1
  set R0SoftDrop 0.8

  set JetPTMin 20.0
}
}}}

3. Now run Delphes with the newly modified card on both the dijet and Z' samples:
{{{
./DelphesSTDHEP cards/delphes_card_CMS.tcl out_pp_zp_ww_js.root pp_zp_ww.hep
./DelphesSTDHEP cards/delphes_card_CMS.tcl out_pp_jj_js.root pp_jj.hep
}}}

4. Open the files with ROOT TBrowser as in the Getting Started section, and make sure that the new jet substructure variables are properly stored.  

5. Now [https://cp3.irmp.ucl.ac.be/projects/delphes/raw-attachment/wiki/WorkBook/Tutorials/Mc4Bsm/macro.C download] and run this simple event selection macro. It will plot two crucial jet observables that can help in discriminating between a w-jet and a light jet: the jet mass, and the N-subjettiness ratio tau2/tau1. 
{{{
root examples/macro.C'("out_pp_jj_js.root","out_pp_zp_ww_js.root")' 
}}}

6. Now improve the calorimeter resolution in the card, both energy and angular resolutions (roughly by a factor 20) 
{{{
set PhiBins {}
  for {set i -360} {$i <= 360} {incr i} {
    add PhiBins [expr {$i * $pi/360.0}]
  }

  # 0.01 unit in eta up to eta = 2.5
  for {set i -1000} {$i <= 1000} {incr i} {
    set eta [expr {$i * 0.005}]
    add EtaPhiBins $eta $PhiBins
  }


 ...

  # set ECalResolutionFormula {resolution formula as a function of eta and energy}
  # Eta shape from arXiv:1306.2016, Energy shape from arXiv:1502.02701
  set ECalResolutionFormula {                  (abs(eta) <= 1.5) *0.05*(1+0.64*eta^2) * sqrt(energy^2*0.008^2 + energy*0.11^2 + 0.40^2) +
                             (abs(eta) > 1.5 && abs(eta) <= 2.5) *0.05* (2.16 + 5.6*(abs(eta)-2)^2) * sqrt(energy^2*0.008^2 + energy*0.11^2 + 0.40^2) +
                             (abs(eta) > 2.5 && abs(eta) <= 5.0) *0.05* sqrt(energy^2*0.107^2 + energy*2.08^2)}


}}}

7. Re-run Delphes simulation and macro.C with the new configuration and appreciate the effect of improved resolution on the final distributions:
{{{
./DelphesSTDHEP cards/delphes_card_CMS.tcl out_pp_zp_ww_js_nc.root pp_zp_ww.hep
./DelphesSTDHEP cards/delphes_card_CMS.tcl out_pp_jj_js_nc.root pp_jj.hep
root examples/macro.C'("out_pp_jj_js_bc.root","out_pp_zp_ww_js_bc.root")' 
}}}