HOWTO Use EvtGen to simulate particle decays in GlueX

From GlueXWiki
Jump to: navigation, search


Much of the event generator work to this point in GlueX has focused on simulating the production of various states and the decays of broad resonances. EvtGen is an event generator widely used in HENP to simulate the decay of particles and narrow resonances, such as the η, φ, and J/ψ. The models for these decays are implemented in an easily extensible framework, can handle multiple sequential decays, and are calculated based on decay helicity amplitudes. More official documentation can be found at this page.

This document gives a brief introduction to the use of EvtGen in the GlueX software framework.

Simulating Events

Configuration Files

In the standard GlueX software environment, the source code and configuration files are found in the directory given by the environmental variable EVTGENDIR. There are two required configuration files, one of particle definitions and one of decay definitions, and one optional file of decay definitions which override the standard definitions. The format and use of these files is shown in the following.

The standard event definition file can be found in $EVTGENDIR/evt.pdl, and an example of several lines is shown below, including a header that shows what each column means:

*                  name                  id      mass/GeV    width/GeV     max_Dm/GeV    3*charge   2*spin    lifetime*c/mm    PythiaId   
add  p Particle  K_4*+                  329  2.0450000e+00  1.9800000e-01  2.0000000e-01     3     8  0.0000000e+00          0
add  p Particle  h_b(2P)             110553  1.0255000e+01  0.0000000e+00  0.0000000e+00     0     2  0.0000000e+00     110553
add  p Particle  b                        5  5.0000000e+00  0.0000000e+00  0.0000000e+00    -1     1  0.0000000e+00          5
add  p Particle  anti-nu_e              -12  0.0000000e+00  0.0000000e+00  0.0000000e+00     0     1  0.0000000e+00        -12
add  p Particle  D_2*0                  425  2.4626000e+00  4.9000000e-02  3.0900000e-01     0     4  0.0000000e+00        425
add  p Particle  Upsilon                553  9.4603000e+00  5.4020000e-05  5.0000000e-04     0     2  0.0000000e+00        553

Particles are identified by both a name string and an id, which generally follows the PDG MC numbering scheme for clarity, if possible. New particles can be added by adding new lines to the file.

The standard decay definition file can be found in $EVTGENDIR/DECAY.DEC, and has a substantially more complicated format. Let's look at the most important part, the definition of a particle decay, in this case the π0. This is defined as:

Decay pi0
0.988228297 gamma   gamma                                   PHSP; #[Reconstructed PDG2011]
0.011738247 e+      e-      gamma                           PI0_DALITZ; #[Reconstructed PDG2011]
0.000033392 e+      e+      e-      e-                      PHSP;  #[New mode added] #[Reconstructed PDG2011]
0.000000065 e+      e-                                      PHSP;  #[New mode added] #[Reconstructed PDG2011]

Each decay is defined by a "Decay [particle name]" header and an "Enddecay" footer. A particle can have multiple decay modes. Each decay mode is defined by the form: "[probability] [decay particles] [decay model]". The number and ordering of the decay particles depends on the decay model. The default models are given in the EvtGen documentation, and some are also described in this page. In the example here, PHSP is a multi-particle phasespace model, while PI0_DALITZ is a particular model of the π0 → e+e+γ decay. If the probabilities of all the decays for a particle do not add up to 100%, they are all rescaled so that this condition is met.

In the standard GlueX generators, the location of evt.pdl and DECAY.DEC can be specified using the environment variables EVTGEN_DECAY_FILE and EVTGEN_PARTICLE_DEFINITIONS , respectively. You may particularly want to use a local copy of evt.pdl if you are simulating particles which are not defined in the standard definition file, or are varying some resonance parameters.

An optional "user decay" file can be given. The decay definitions in the file override the standard decay definitions, and is the usual way of implementing new or particular decays for a given simulation sample. The file is handled in different ways by different programs, as described below. The file has a similar format to the DECAY.DEC file. Here is an example for simulating the η → π+π-π0 using a particular model for the Dalitz decay:

Decay eta
1.000  pi-     pi+     pi0       ETA_DALITZ_GLUEX  -1.095 0.145 0.0 0.081 0.0 0.141 -0.044;


Notice that this file MUST end with the phase "End", or EvtGen program will complain and end. Also, note that ETA_DALITZ_GLUEX takes several model parameters, again, this is model-dependent.


The most common way to use EvtGen in GlueX is to generate the production kinematics with some other generator, like genr8 or gen_amp, and then simulate additional particle decays with EvtGen using the decay_evtgen program. decay_evtgen takes as input an HDDM file from one of these other generators (e.g. reaction.hddm), and generates a new HDDM file with the additional particle decays simulated (e.g. reaction_decayed.hddm). The only particles not decayed by decay_evtgen are stable particles (e.g. photons, protons, ...), long-lived particles which should be decayed by GEANT (neutral kaons, hyperons, ....), and particles of type 0 (i.e. the internal GlueX ID, NOT PDG ID!). This last option gives some flexibility on where to decay particles - you can implement some decays in other generators, as long as their HDDM type parameter is set to zero, and their PDG ID is properly set.

The optional user decay file is taken to be a file named userDecay.dec in the directory where the program is being executed, but you can use the -u option to specify another file name.

If you are processing the output of gen_schannel (described below), then you must use the -S switch.

Other options can be set on the command line or in the environmental variables specified above. The online help output is given below:> decay_evtgen -h
Warning in <UnknownClass::SetDisplay>: DISPLAY not set, setting it to
Unknown option "-h"

       decay_evtgen [options] file.hddm

Decay thrown particles via EvtGen
The particle types and decays are defined in $EVTGENDIR/evt.pdl 
  and $EVTGENDIR/DECAY.DEC respectively.
The location of these files can be override by the environment variables 

For more documentation on EvtGen, go to


  -nNumEvents               number of events to process (default: all)
  -o"output_file_name"    set the file name used for output (default: append "_decayed")
  -u"user_decay_file_name"    set the file name of the user decay file (default: userDecay.dec)
  -h                        print this usage statement.


Most of our current generators assume some t- or u-channel exchange. But maybe you want to generate some particle in the s-channel and decay this via EvtGen. Then you can use gen_schannel. Here is an example usage:

gen_schannel -N10000 -R30730 -P669 -Ogen.hddm

which will generate 10000 events with run 30730 of intermediate particle ID 669, assuming some nominal beam parameters.

Here is the online help:> gen_schannel
gen_schannel: simple gamma + p -> X generator to be used as input for decay_evtgen.
 Usage:  gen_schannel <options>
   Options:  -N<number of events> (number of events to generate)
             -B<beam.hddm>       (default: cobrems.conf)
             -O<output.hddm>     (default: eta_gen.hddm)
             -P<EvtGen particle number> (default: 0)
             -R<run number>      (default: 10000)
             -h                  (Print this message and exit.)


The genEtaRegge generator has been used for the study of various η and η' decays, and includes both a Regge-based production model and some simple decay modes as well. This document will not discuss the use of genEtaRegge in detail, but will discuss how to use it in a mode where the decays are simulated by EvtGen.

An example configuration file for this case is:

#beam configuration file
#mass[GeV] width[GeV]
0.547853 0.000
#g_eta_gamma_gamma g_rho_eta_gamma g_omega_eta_gamma g_phi_eta_gamma 
0.0429 0.81 0.29 0.38
#Number of decay particles
#EvtGen particle name

The first few lines are common to other uses of genEtaRegge, the difference comes in the last 2 lines. First, the "Number of decay particles" is generally greater than zero for the case that eta decays are handled by genEtaRegge, but to enable decays via EvtGen this should be set to -1. Finally, the last line should be the EvtGen name string of the particle as defined in evt.pdl, generally either "eta" or "eta'".

With this configuration, genEtaRegge will then use EvtGen to decay the generated particle, either using the decays defined in the default DECAY.DEC, or those in the userDecay.dec file that sits in the directory in which the program is being executed, as described above.

Adding New Models