External Generators

EvtGen can use other external generators to simulate particle decays that are not part of the in-built set of models. The EvtGenExternal sub-directory contains a factory class, EvtExternalGenFactory, that can set up any class that inherits from EvtGenModels/EvtAbsExternalGen, which is a pure abstract interface to other generators. Only two functions need to be overridden: initialise() and doDecay(EvtParticle* theMother).

EvtGen is able to use Pythia8, Photos⁺⁺, and Tauola⁺⁺. Below are some examples that use these features.

Specifying what generators to use

#include "EvtGenExternal/EvtExternalGenList.hh"
#include "EvtGenBase/EvtAbsRadCorr.hh"
#include "EvtGenBase/EvtDecayBase.hh"

// Specify if we want to use Pythia 6 physics codes for decays
bool convertPythiaCodes(false);
// Specify the pythia xml data directory to use the default PYTHIA8DATA location
std::string pythiaDir("");
// Specify the photon type for Photos
std::string photonType("gamma");
// Specify if we want to use the EvtGen random number engine for these generators
bool useEvtGenRandom(true);
// Set up the default external generator list: Photos, Pythia and/or Tauola
EvtExternalGenList genList(convertPythiaCodes, pythiaDir, photonType, useEvtGenRandom);
// Get the interface to the radiative correction engine
EvtAbsRadCorr* radCorrEngine = genList.getPhotosModel();
// Get the interface to the other external generators (Pythia and Tauola)
std::list<EvtDecayBase*> extraModels = genList.getListOfModels();

// Create the EvtGen generator object, passing the external generators
EvtGen myGenerator("decayFile.dec", "evt.pdl", randomEnginePointer, radCorrEngine, &extraModels;);

Example decay files

Photos

Radiative corrections can be enabled by either including the model name PHOTOS just before the actual decay model is specified, or by using the yesPhotos command, which will turn on Photos for all decays, even if PHOTOS is left out when specifying the decay model. For example, here are two ways to include radiative corrections for the decay Υ(4S) → e⁺ e⁻:

Decay Upsilon(4S)
   1.0   e+  e-    PHOTOS VLL;
Enddecay

yesPhotos
Decay Upsilon(4S)
   1.0   e+  e-    VLL;
Enddecay

To turn-off Photos, use the command noPhotos, or leave out the PHOTOS name when specifying the decay model. Remember: yesPhotos (noPhotos) turns Photos on (off) for everything.

Pythia

The general DECAY.DEC file, which lists the complete set of decays for B, D mesons, as well as other particles, contains decays that use the PYTHIA model. Here, Pythia is used as a "fragmentation" model, whereby a combination of partons (or hadrons) are specified, and Pythia is used to hadronise these, creating other particles that EvtGen can then decay further. The syntax of using Pythia decays is given by

Decay MyParticle
   1.0  list_of_decay_daughters_or_partons  PYTHIA  modelNumber;
Enddecay

where modelNumber is an integer specifying the relevant physics model ("matrix element mode") in the Pythia generator. It is possible to use Pythia 6 physics codes for the modelNumber integer by setting the convertPythiaCodes boolean to true (in the EvtExternalGenList constructor); the program will try to find the best Pythia 8 equivalent.

It is also possible to use Pythia for aliased decays. Here is an example that uses Pythia to create hadrons for the decay B⁰ → c s c d (and its charge conjugate):

Alias MyB0 B0
Alias MyAntiB0 anti-B0
ChargeConj MyAntiB0 MyB0

Decay MyB0
1.0    c  anti-s  anti-c   d   PYTHIA  43;
Enddecay
CDecay MyAntiB0

Note that, for ascii decay files, PHOTOS can only be used with the PYTHIA model if the yesPhotos command is used; it is not possible to have "PHOTOS PYTHIA" on the same model definition line.

Another feature that is available is the ability to change Pythia 8 simulation conditions simply using an EvtGen decay file. Any command of the form "Module:Variable=Value" can be passed to Pythia 8 when prefixed by the name PythiaTypeParam, where Type refers to either "Generic", "Alias" or "Both" for specifying whether the parameter is for the generic or alias Pythia decay engines (or both). The 2nd argument must not contain any spaces. For example, to change the multiplicity of weak decays (for both generic and alias):

PythiaBothParam ParticleDecays:multIncreaseWeak=2.0

Xml decay files already have the ability to specify such parameters via the pythiaParam (or pythia6Param) tag.

Tauola

The syntax of using TAUOLA to generate tau decays is given by

Decay MyTau
1.0  TAUOLA tauInt;
Enddecay

where tauInt is an integer that specifies the required tau decay, as specified in Section C.2 in the Tauola manual (charge conjugates are implied):

0 All TAUOLA modes (1 to 22 below)
1 τ⁻ → e⁻ ν_e ν_τ
2 τ⁻ → μ⁻ ν_μ ν_τ
3 τ⁻ → π⁻ ν_τ
4 τ⁻ → ρ⁻ ν_τ
5 τ⁻ → a₁⁻ ν_τ
6 τ⁻ → K⁻ ν_τ
7 τ⁻ → K^*⁻ ν_τ
8 τ⁻ → 2π⁻ π^⁺ π⁰ ν_τ
9 τ⁻ → 3π⁰ π⁻ ν_τ
10 τ⁻ → 2π⁻ π⁺ 2π⁰ ν_τ
11 τ⁻ → 3π⁻ 2π⁺ ν_τ
12 τ⁻ → 3π⁻ 2π⁺ π⁰ ν_τ
13 τ⁻ → 2π⁻ π⁺ 3π⁰ ν_τ
14 τ⁻ → K⁻ K⁺ π⁻ ν_τ
15 τ⁻ → K⁰ K⁰ π⁻ ν_τ
16 τ⁻ → K⁻ K⁰ π⁰ ν_τ
17 τ⁻ → 2π⁰ K^⁻ ν_τ
18 τ⁻ → π⁻ π⁺ K⁻ ν_τ
19 τ⁻ → π⁻ π⁰ K⁰ ν_τ
20 τ⁻ → η π⁻ π⁰ ν_τ
21 τ⁻ → π⁻ π⁰ γ ν_τ
22 τ⁻ → K⁻ K⁰ ν_τ

For example, to generate the tau decays τ⁻ → e⁻ ν_e ν_τ (60%), τ⁻ → ρ⁻ ν_τ (30%) and τ⁻ → 2π⁰ K^⁻ ν_τ (10%), with charge conjugates:

Alias MyTau- tau-
Alias MyTau+ tau+
ChargeConj MyTau+ MyTau-

Decay MyTau-
0.6 TAUOLA 1;
0.3 TAUOLA 4;
0.1 TAUOLA 17;
Enddecay
CDecay MyTau+

Alised tau particles can use the TAUOLA model, but the generated daughters cannot be aliased particles; there is no simple way to ensure that the order of any daughter particle definitions will match the order of the particles generated by Tauola, especially for the modes with many pions in the final state.

To ensure decay mode consistency, any tau particle decay definition (normal or aliased) using TAUOLA should use it for all sub-modes, i.e do not mix TAUOLA and other decay models, such as phase space (PHSP), within the same "Decay" definition. An example which is NOT allowed is:

Decay MyTau+
0.4  TAUOLA 9;
0.5  TAUOLA 2;
0.1  e+ nu_e anti-nu_tau PHSP;  # Decay model is not TAUOLA! Not allowed!
Enddecay

If this is detected, the program will stop and ask you to correct the decay definition(s).

Lastly, for ascii decay files, PHOTOS can only be used with the TAUOLA model if the yesPhotos command is used; it is not possible to have "PHOTOS TAUOLA" on the same model definition line.