Getting started

In order to run DELPHES on your system, first download is sources and compile it:

  tar -xvf Delphes_V_XXX.tar.gz
  cd Delphes_V_XXX
  ./configure
  make

Running Delphes on your events

Setting the run configuration

The program is driven by two datacards (default cards are data/DetectorCard.dat and data/TriggerCard.dat) which allow a large spectrum of running conditions.

The detector card: contains all needed information to run DELPHES 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. Six flags, FLAG_bfield, FLAG_vfd, FLAG_RP, FLAG_trigger, FLAG_frog and FLAG_lhco should be set in order to configure the magnetic field propagation, the very forward detectors simulation, the use of very forward taggers, the trigger selection, the preparation for FROG display and the creation of an output file in *.lhco text format (respectively). An example (the default detector card) can be found here The trigger card: contains the definition of all trigger bits Cuts can be applied on the transverse momentum of electrons, muons, jets, b-jets, tau-jets, photons and transverse missing energy, as well as isolated electrons and isolated muons. Be careful that the following structured should be used: One trigger bit per line, the first entry in the line is the name of the trigger bit If the trigger bit uses the presence of multiple identical objects, their transverse momentum thresholds must be defined in decreasing order The different object requirements must be separated by a && flag Example of a trigger bit line:

DoubleElec >> ELEC1_PT: '20' && ELEC2_PT: '10'

The input list: contains only the list of input files to process The listfile should contain one data file (with its relative/absolute path if needed) per line All datafiles in the listfile should be of the same type Supported types are StdHEP (.hep), Les Houches LHAF (.lhe), HepMC (.hepmc), HBook-root (.root) The name of the listfile is arbitrary, but it is common to assign it the .list extension name

tar xzf tt_jj_small.hep.tar.gz

This tarball contains the events (tt_jj_small.hep) and the listfile (TEST_small_tt.list). Running the code

Create or modify the above cards (data/DetectorCard.dat and data/TriggerCard.dat) Create a text file containing the list of input files that will be used by DELPHES (with extension *.lhe, *.root or *.hep) To run the code, type the following

me@mylaptop:~$ ./Delphes inputlist.list OutputRootFileName.root data/DetectorCard.dat data/TriggerCard.dat

Running an analysis on your Delphes events

The Examples/Analysis_Ex.cpp code comming with the package shows how to access the available reconstructed objects and the trigger information The two following arguments are required: a text file containing the input DELPHES root files to run, and the name of the output root file. To run the code:

./Analysis_Ex input_file.list output_file.root

Running the trigger on your Delphes events

The Examples/Trigger_Only.cpp code permits to run the trigger selection separately from the general detector simulation on output DELPHES root files. An input 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:

./Trigger_Only input_file.root data/TriggerCard.dat

Create a *.lhco file of your Delphes events

The *lhco file format is a text-ascii data format. An exhaustive description is provided on ​http://v1.jthaler.net/olympicswiki The Examples/LHCO_Only.cpp code permits to create an output text file in the LHCO format separately from the general Delphes.cpp code on output DELPHES root files. An input DELPHES root file is mandatory as argument. The name of the new created file is identical to the input one, but with the .root extension remplaced by _events.lhco. To run the code:

./LHCO_Only input_file.root

Running the FROG event display

If the FLAG_frog was switched on, two files were created during the run of DELPHES: DelphesToFrog.vis and DelphesToFrog.geom. They contain all the needed information to run frog.

To display the events and the geometry, you first need to compile FROG. Go to the Utilities/FROG and type make Go back into the main directory and type ./Utilities/FROG/frog Running DELPHES on Mac OS-X

Small modifications are required in the Makefile. Refer to the corresponding FAQ section.

ROOT basics

For users who are not familiar with ROOT, here are a few useful commands. Starting and exiting ROOT: To start ROOT:

me@mylaptop:~$ root

In order to avoid the display of the banner, you can add the -l option :

me@mylaptop:~$ root -l

Starting ROOT and opening a .root file (e.g. test.root) at the same time:

me@mylaptop:~$ root -l test.root
root [0]
Attaching file test.root as _file0...
Warning in <TClass::TClass>: no dictionary for class TRootGenEvent is available
Warning in <TClass::TClass>: no dictionary for ...

There are a couple of "Warning" lines that appear. This is normal and harmless.

Quitting ROOT

me@mylaptop:~$ root [0] .q

Parsing a .root file:

root [1] TBrowser t
root [2] .ls

The first command line will open a browser that allows you to see the contents and the structure of your .root file. You can then click on the various branches and double-click on the leaves in order to display automatically the corresponding histograms. The second line lists the currently known symbols.

Looking more into a .root file produced by Delphes: Delphes creates a file with three trees, called GEN, Analysis and Trigger. To know how many events are in a tree, for instance Analysis or GEN, use the GetEntries() method:

root [3] Analysis->GetEntries()

Similarly, you can list the branches in a tree, or the leaves in the branches, with GetListOfBranches() and GetListOfLeaves():

root [4] GEN->GetListOfBranches()->ls()

One can use wildcard (*) character to have a generic listing.

root [5] Analysis->GetListOfLeaves()->ls("Electron*")
OBJ: TLeafElement Electron_ Electron_ : 0 at: 0x9d13f60
OBJ: TLeafElement Electron.E E[Electron_] : 0 at: 0x9d13ed0
OBJ: TLeafElement Electron.Px Px[Electron_] : 0 at: 0x9d24f50
...

Drawing distributions: The distributions corresponding to a given variable (e.g. jet energies) can be plot as an histogram by using the Draw method of any tree.

root [6] Analysis->Draw("Jet.E")
root [7] Analysis->Draw("Jet.PT : Jet.Eta")
root [8] Analysis->Draw("Photon.Phi","Photon.E>15")
root [9] Analysis->Draw("RP220hits.E","RP220hits.side>0 && ZDChits.side>0")
root [10] Trigger->Draw("TrigResult.Accepted")

Moreover, drawing one variable with respect to another is possible by using the column character : as in the line root [7] here above. Finally, one or several cuts can be applied as a second argument of the Draw method (see lines [8] and [9]). Alternatively, a double-click in a TBrowser on a given leaf will also display the distribution of the corresponding variable in the form of an histogram.