<< back to HepSim manual

Creating Delphes files

Fast simulations in the HepSim are posted under the rfast link. The detectors configurations are posted to this link.

Generally, you do not need to install Delphes to run fast simulations. You can run fast simulations using the HepSim singularity container. This topic is described in HepSim singularity container section.

Below is the description how to use Delphes if you do not want to use the HepSim docker container.

Creating Delphes files

Here we describe how to make fast detector simulation files using separate external libraries, without installing FastHepSim. Use the Delphes fast detector simulation program to process the MC events. Delphes can read ProMC files directly. First, make sure that ProMC and ROOT library is installed:


This should point to the installation paths of ProMC and ROOT. The detectors configurations for Delphes together with appropriate Delphes package are posted to this link. Copy the ZIP file with Delphes card and Delphes package and compile it.

Here is an example of how to re-create fast simulations for “rfast100” tag, which corresponds to the detector “delphes_atlas1” (look at the detector definition page).

det="delphes_atlas1" # define detector
wget http://atlaswww.hep.anl.gov/hepsim/soft/detectors/$det.zip
unzip $det.zip
cd $det
tar --strip-components=1 -zvxf Delphes*.tar.gz # untar in the current directory
./configure; make                              # configure and compile                                     

The last command should create the binary file “DelphesProMC”. Now you can process a ProMC file:

wget http://mc.hep.anl.gov/asc/hepsim/events/pp/14tev/mg5_ttbar_jet/mg5_ttbar_jet_001.promc
./DelphesProMC card.tcl mg5_ttbar_jet_001.root mg5_ttbar_jet_001.promc

This commands creates a ROOT file with fast simulations.

Detector configuration files [detector].zip include the Delphes source code used to make the simulation tag, and the input control card “card.tcl” that defines the geometry. Look at this link.

You can create a complete list of input files. Here is how to do this:

hs-ls [setname] simple     > input.list     # list of ProMC files (without URL path)
hs-ls [setname] simple-url > input_url.list # list with URL from the main server
# create a setup array with input files
declare -a wwwarray  
while read -r line
    let "n = $n + 1"
done < "inputlist_url.txt"

where [setname] is the dataset name, such as “tev100_ttbar_mg5”. If you know URL of the mirror, replaces [setname] with qualified URL pointing to your dataset. Now, you have the necessary tools. Fetch the list of URLs with input files, and make a loop over files.

One can also run Delphes in an automated mode, without the above scripts. You need to use “hs-exec” command.

hs-exec DelphesProMC card.tcl output.root [URL] [Nfiles]

where [URL] is HepSim location of files and [Nfiles] is the number of files for processing. The output ROOT will be located inside “hepsim_output” directory.

Here is a small example:

hs-exec DelphesProMC card.tcl output.root http://mc.hep.anl.gov/asc/hepsim/events/pp/14tev/mg5_ttbar_jet/ 5

which processes 5 files from HiggsToTTbar sample. Skip “5” at the end to process all files.

Creating files manually

If you want to create a new simulations with updated Delphes and input cards, follow these steps:

(1) Download current Delphes (or higher) and compile it as:

tar -zvxf Delphes-X.X.Xtar.gz
cd Delphes-X.X.X.tar.gz

where “X.X.X” is the version of Delphes. This creates the converter “DelphesProMC” (among others), if “PROMC” environmental variable is detected.

(2) Copy and modify the detector configuration files. The configuration files with the extension “tcl” can be found in this link

Often, the line “TauTagging” from the Delphes control card. We do not use the tau tagging module since it requires complete event records with all mother particles. Since ProMC files are often slimmed by removing some unstable low pT particles and showered partons, Delphes will fail on this line. If you need tau tagging, please use ProMC files with complete particle record.

Download Monte Carlo files from the 100 HepSim repository. For example, get a file with 5000 ttbar events generated for a 100 TeV collider:

wget http://mc.hep.anl.gov/asc/hepsim/events/pp/100tev/ttbar_mg5/mg5_ttbar_100tev_001.promc

and then create a ROOT file with reconstructed objects after a fast detector simulation (FCC detector):

./DelphesProMC card.tcl  mg5_ttbar_100tev_001.root mg5_ttbar_100tev_001.promc

On the fly reconstruction

HepSim can be used to create ROOT (Delphes) files fast simulation program on the fly. The latter approach allows to make changes to the detector geometry by the end-users and, at the the same time, perform an analysis. The output ROOT file only includes histograms defined by the user (but you can also add custom ROOT tree). To do this, use the FastHepSim package that includes Delphes-3.2.0 and ProMC 1.5, as well as an example analysis program. You can find a description of the current HCAL studies that use such an approach.

Follow these steps:

wget http://atlaswww.hep.anl.gov/asc/hepsim/soft/FastHepSim.tgz
tar -zvxf FastHepSim.tgz
cd FastHepSim/libraries/

This installs “FastHepSim” which includes Delphes, ProMC and hs-tools to work with HepSim. Then setup the environment

cd .. # go to the root directory
source setup.sh

Next, go to the analysis example:

cd analysis

This compiles the analysis program (analysis.cc) that fills jetPT and muonPT histograms. Now we need to bring data from HepSim and put them somewhere. For this example, we will copy data to the “data” directory:

hs-get http://mc.hep.anl.gov/asc/hepsim/events/pp/100tev/higgs_ttbar_mg5 data 2 3

This copies 3 files in 2 threads and put them to the directory “data”. Now we are ready to run over these 3 files:

./Make_input data  # creates inputdata.txt
./analysis delphes_card_FCC_basic_notau.tcl histo.root inputdata.txt

The first command creates a file “inputdata.txt” with input data. Then the program “analysis” reads the configuration file, data and generates “histo.root” with output histograms. This example uses “delphes_card_FCC_basic_notau.tcl” Delphes configuration file describing a basic FCC detector geometry. Note that we have removed tau tagging since we run over slimmed events with missing mothers of particles.

If you want to access other objects (photons, electrons, b-jets), use Delphes definitions of arrays inside the source code “analysis.cc”. You can put external files into the src/ directory where it will be found by Makefile.

If you still want to look at the event structure in the form of ROOT tree, run the usual Delphes command:

../libraries/Delphes/DelphesProMC  delphes_card_FCC_basic_notau.tcl  output.root data/mg5_Httbar_100tev_001.promc

where output.root will contain all reconstructed objects. In this case, add “TreeWriter” after “ScalarHT”. If the input file contains complete (non-slimmed) record, one can add “tau” reconstruction (“TauTagging” line).

Try also more sophisticated detector-geometry cards:

  • examples/delphes_card_Snowmass_NoPileUp.tcl - similar to Snowmass 2013. It has CA (fat) jets and B-tagging
  • examples/delphes_card_ATLASLIKE.tcl - similar to ATLAS detector (comes with Delphes)

Note that “TreeWriter” module should be enabled when creating ROOT files, and disabled when using analysis mode.

Tim Kallage made a correction for DPF Delphes card that corrects b-tagging. Download it from snowmass_fixed.tcl.txt

A note for ANL cluster

For ANL cluster, you do not need to install Delphes. Simply run the reconstruction as:

source /share/sl6/set_asc.sh
$DELPHES/DelphesProMC delphes_card_FCC_notau.tcl mg5_ttbar_100tev_001.root mg5_ttbar_100tev_001.promc

The cards are located in $DELPHES/examples.

If you want to run over multiple ProMC files without manual download, use this command:

java -cp hepsim.jar hepsim.Exec DelphesProMC delphes.tcl output.root [URL] [Nfiles]

where [URL] is HepSim location of files and [Nfiles] is the number of files for processing. The output ROOT will be located inside the “hepsim_output” directory. Here is a small example:

java -cp hepsim.jar hepsim.Exec DelphesProMC delphes.tcl output.root  http://mc.hep.anl.gov/asc/hepsim/events/pp/100tev/higgs_ttbar_mg5 5

which processes 5 files from Higgs to TTbar sample. Skip “5” at the end to process all files.

Record slimming

Particle records from the generators based on LO/NLO+parton showers calculations (PYTHIA, HERWIG, MADGRAPH) are often “slimmed” to reduce file sizes. In the case when records are slimmed, the following algorithm is used:

(status=1 && pT>0.3 GeV ) or   # keep final states with pT>0.3 GeV 
(PID=5 || PID=6)  or           # keep b or top quark 
(PID>22 && PID<38)  or         # keep exotics and Higgs
(PID>10 && PID<17)  or         # keep all leptons and neutrinos 

where PID is absolute value of particle codes. Leptons ane neutrinos are also affected by the slimming pT cut. Note: for 100 TeV collisions, the pT cut is increased from 0.3 to 0.4 GeV. For NLO calculations with a few partons + PDF weights, the complete event records are stored.

In the case when the slimming is applied, file sizes are reduced by x2 - x3. In some situation, slimming can affect detector simulation. For example, you should turn of tau reconstruction in Delphes when slimming is used.