Chapter ‍13 Fast Detector Simulation and External Analysis

• 13.1 Interfacing ROOT
• 13.2 Interfacing RIVET
• 13.3 Fast Detector Simulation with DELPHES

Events from a Monte Carlo event generator are further used in an analysis, most often combined with a detector simulation. Event files from the generator are then classified whether they are (i) parton level (coming from the hard matrix element) for which mostly LHE or HepMC event formats are used, particle level (after parton shower and hadronization) - usually in HepMC or LCIO format -, or detector level objects. The latter is the realm of packages like ROOT or specific software from the experimental software frameworks. While detailed experimental studies take into account the best-possible detector description in a so-called full simulation via Geant which takes several seconds per event, fast studies are made with parameterized fast detector simulations like in Delphes or SGV. In the following, we discuss the options to interface external packages for these purposes or to pipe events from WHIZARD to such external packages.

13.1 Interfacing ROOT

One of the most distributed analysis framework is ROOT ‍[101]. In WHIZARD for the moment there is no direct interface to the ROOT framework. The easiest way to write out particle-level events in the ROOT or RootTree format is to use WHIZARD’s interface to HepMC3: this modern incarnation of the HepMC format has different writer classes, where the writer class for ROOT and RootTree files is supported by WHIZARD’s HepMC3 interface. For this to work, one only has to make sure that HepMC3 has been built with ROOT support, and that the WHIZARD configure has to detect the ROOT setup on the computing environment. For more details cf. the installation section ‍2.2.9. If this has been successfully linked, then WHIZARD can use its own HepMC3 interface to write out ROOT or RootTree formats.

This can be done by setting the following options in the SINDARIN files:

  $hepmc3_mode = "Root"

or

  $hepmc3_mode = "RootTree"

For more details cf. ‍the ROOT manual and documentation therein.

13.2 Interfacing RIVET

Rivet ‍[102] is a very mighty analysis framework which has been developed to make experimental analyses from the LHC experiments available for non-collaboration members. It can be easily used to analyze events and produce high-quality plots for differential distributions and experimental observables. Since version 3 ‍[103] there is now also a lot of functionality that comes very handy for plotting differential distributions at fixed order in NLO calculations, e.g. negative weights in bins or how to treat imperfectly balanced events and counterevents close to bin boundaries etc. For the moment, WHIZARD does not have a dedicated interface to Rivet, so the preferred method is to write out events, best in the HepMC or HepMC3 format and then read them into Rivet. A more sophisticated interface is foreseen for a future version of WHIZARD, while there are already development versions where WHIZARD detects all the Rivet infrastructure and libraries. But they are not yet used.

For more details and practical examples cf. ‍the Rivet manual. This describes in detail especially the Rivet installation. A typical error that occurs on systems where no ROOT is installed (cf. ‍Sec. ‍13.1) is the one these Missing TPython.h missing headers. Then Rivet can nevertheless be easily built without ROOT support by setting

  --disable-root

in the rivet-bootstrap script. For an installation of Rivet it is favorable to include the location of the Rivet Python scripts in the PYTHONPATH environment variable. They can be accessed from the Rivet configuration script as

  <path_to_rivet-config>/rivet-config --pythonpath

If the Python path is not known within the environment variables, then one commonly encounters error like No module named rivet or Import error: no module named yoda when running Rivet scripts like e.g. yodamerge.

If you use a Rivet version older than v3.1.1 there is no support for HepMC3 yet, so when using HepMC3 with WHIZARD please use the backwards compatibility mode of HepMC3in the SINDARIN file:

  $hepmc3_mode = "HepMC2"

When using MPI parallelized runs of WHIZARD there will a large number of different .hepmc files (also if some grid architecture has produced these event files in junks). Then one has to first merge these event files.

Here, we quickly explain how to steer Rivet for your own analysis. For more details, please confer the Rivet manual.

1. The command

   rivet-mkanalysis <name>

   creates a template Rivet plugin for the analysis <name>.cc, a template info file <name>.info amd a template file for the plot generation <name>.plot. Note that this overwrites potentially existing files in this folder with the same name.
2. Now, analysis statements like e.g. cuts etc. can be implemented in <name>.cc. For analysis of parton-level events without parton showering, the cuts can be equivalent to those in WHIZARD, i.e. the generator-level cuts can be as strict as the analysis cuts to avoid generating unnecessary events. If parton showering is applied it is better to have looser generator than analysis cuts to avoid undesired plot artifacts.
3. Next, one executes the command (the shared library name might be different e.g. on Darwin or BSD OS)

   rivet-buildplugin Rivet<name>.so <name>.cc

   This creates an executable Rivet analysis library Rivet<name>.so. The custom analysis should now appear in the output of

   rivet --list <name>

   If this is not the case, the analysis path has to be exported first as RIVET_ANALYSIS_PATH=$PWD.
4. We are now ready to use the custom analysis to analyze the .hepmc events by executing the command

   rivet --pwd --analysis=<name> -o <outfile>.yoda <path/to/hepmcfiles>

   and save the produced histograms of the analysis in the .yoda format. In general the option --ignore-beams for Rivet should be used to prevent Rivet to stumble over beam remnants. This is also relevant for lepton collider processes with electron PDFs. For a large number of events, event files can become very big. To avoid writing them all on disk, a FIFO for the <path/to/hepmcfiles> can be used.
5. Different yoda files can now be merged into a single file using the command

   <yodamerge --add -o <name>_full.yoda <name>_01.yoda ...

   This should be applied e.g. for the case of fixed-order NLO differential distributions where Born, real and virtual components have been generated separately.
6. Finally, plots can be produced: after listing all the histograms to be plotted in the plot file <name>.plot, the command

   rivet-mkhtml <name>_full.yoda

   translates the .yoda file into a histogram file in the .dat format. These plots can either be visually enhanced by modifying the <name>.plot file as is described on the webpage https://rivet.hepforge.org/make-plots.html, or by using any other external plotting tool like e.g. Gnuplot for the .dat files.

Clearly, this gives only a rough sketch on how to use Rivet for an analysis. For more details, please consult the Rivet webpage and the Rivet manual.

13.3 Fast Detector Simulation with DELPHES

Fast detector simulation allows relatively quick checks whether experimental analyses actually work in a semi-realistic detector study. There are some older tools for fast simulation like e.g. ‍PGS (which is no longer actively maintained) and SGV which is default fast simulation for ILC studies. For LHC and general future hadron collider studies, Delphes ‍[104] is the most commonly used tool for fast detector simulation.

The details on how to obtain and build Delphes can be obtained from their webpage, https://cp3.irmp.ucl.ac.be/projects/delphes. It depends both on ‍Tcl/Tk as well as ROOT ‍(cf. Sec. ‍13.1. Interfacing any Monte Carlo event generator with a fast detector simulation like Delphes is rather trivial: Delphes ships with up to five executables

  DelphesHepMC
  DelphesLHEF
  DelphesPythia8
  DelphesROOT
  DelphesSTDHEP

DelphesPythia8 is a direct interface between PYTHIA8 and Delphes, so detector-level events are directly produced via an API interface between PYTHIA8 and Delphes. This is the most convenient method which is foreseen for WHIZARD, however not yet implemented. The other four binaries take input files in the HepMC, LHE, STDHEP and ROOT format, apply a fast detector simulation according to the chosen input file and give a ROOT detector-level event file as output.

Executing one of the binaries above without options, the following message will be displayed:

  ./DelphesHepMC
 Usage: DelphesHepMC config_file output_file [input_file(s)]
 config_file - configuration file in Tcl format,
 output_file - output file in ROOT format,
 input_file(s) - input file(s) in HepMC format,
 with no input_file, or when input_file is -, read standard input.

Using Delphes with HepMC event files then works as

  ./DelphesHepMC cards/delphes_card_ATLAS.tcl output.root input.hepmc

For STDHEP files which are directly by WHIZARD without external packages (only assuming that the XDR C libraries are present on the system), execute

  ./DelphesSTDHEP cards/delphes_card_ILD.tcl delphes_output.root input.hep

For LHE files as input, use

  ./DelphesLHEF cards/delphes_card_CLICdet_Stage1.tcl delphes_output.root input.lhef

and for ROOT (particle-level) files use

  ./DelphesROOT cards/delphes_card_CMS.tcl delphes_output.root input.root

In the Delphes cards directory, there is a long list of supported input files for existing and future detectors, a few of which we have displayed here.

Delphes detector-level output files can then be analyzed with ROOT as described in the Delphes manual.