HOWTO Use EvtGen to simulate particle decays in GlueX
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.
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] Enddecay
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
DECAY.DEC can be specified using the environment variables
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; Enddecay End
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
gen_amp, and then simulate additional particle decays with EvtGen using the
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
Other options can be set on the command line or in the environmental variables specified above. The online help output is given below:
ifarm1801.jlab.org> decay_evtgen -h Warning in <UnknownClass::SetDisplay>: DISPLAY not set, setting it to login1.jlab.org:0.0 Unknown option "-h" Usage: 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 EVTGEN_PARTICLE_DEFINITIONS and EVTGEN_DECAY_FILE respectively. For more documentation on EvtGen, go to https://evtgen.hepforge.org/ options: -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:
ifarm1801.jlab.org> 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.)
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 cobrems.conf #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 -1 #EvtGen particle name eta
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.