The GAUSS Project

Documentation

Detailed documentation about the EvtGen decay models and how to use them can be found on the EvtGen web page. The original pdf documentation by Ryd et al can be found here. Instructions on how to setup EvtGen in Gauss and how to write decay files are also given in the Gauss manual.

A documentation of the decay model PVVCPLH by Tristan Du Pree is available here.

A documentation of the decay model BTOSLLMS by Nikolai Nikitin is available here.

The description of the changes made to the main DECAY.DEC file in March 2009 by Mark Whitehead is available here.

Two Gauss Tutorial lectures are available for EvtGen:

• An introduction to EvtGen in LHCb
• EvtGen and Decfiles: how to write a dkfile in LHCb

Brief description of the generation sequences in Gauss

There are 1 algorithm (Generation) and several tools used in the generation of signal events in Gauss:

• MinimumBias,
• Inclusive, 
• Special,
• SignalPlain,
• SignalForcedFragmentation, and
• SignalRepeatedHadronization.

And there are 3 methods used to generate signal events (corresponding to the last 3 tools):

• plain Pythia: full events are generated and rejected until it contains the correct hadron type,
• forced fragmentation: an event with a b quark is forced to hadronize with the correct light quark to give the hadron type of the signal,
• repeated hadronization: when an event contains a b quark, it is hadronized several times until the correct hadron type is found (default).

The type of method used is decided by the 1 job options: Generation.SampleGenerationTool which has to be set to the name of the tool to use to generate events.

How to run stand alone EvtGen+Pythia

To perform checks or studies with the generator, it is possible to use Gauss to run only the generation part of the simulation program.

To do this, you should use the Gauss executable with the option file GenStandAlone.opts available in the Gauss package. Using for example Gauss version v37r3p1 (which is the most recent MC09 version), you have to type on a lxplus machine to generate events of type XXXXXXXX (see below for a list):

1. setenvGauss v37r3p1
2. cd ~/cmtuser/Gauss_v37r3p1
3. getpack Sim/Gauss v37r3p1
4. getpack Gen/DecFiles head
5. cd ~/cmtuser/Gauss_v37r3p1/Gen/DecFiles/cmt
6. source setup.csh
7. cd ~/cmtuser/Gauss_v37r3p1/Sim/Gauss/cmt
8. source setup.csh
9. cmt make
10. cd ~/cmtuser/Gauss_v37r3p1/Sim/Gauss/job
11. gaudirun.py $APPCONFIGOPTS/Gauss/MC09-b5TeV-md100.py $APPCONFIGOPTS/Conditions/MC09-20090602-vc-md100.py $LBPYTHIAROOT/options/Pythia.opts $GAUSSOPTS/Gauss-Job.py $GAUSSOPTS/GenStandAlone.py $GAUSSOPTS/MonitorInDetail.opts $DECFILESROOT/options/XXXXXXXX.opts

You will obtain a file named Gauss.sim in POOL/ROOT format containing the decay trees generated by EvtGen and Pythia. The behavior of the job is controlled by the option files in the options directory of Gauss. The main properties that you may change are:

• nEvts = 10 Sets the number of events to generate.  (in Gauss-Job.py)

The output file contains the result of the generation in HepMC format (HepMCEvents containers) in the location:

• "/Event/Gen/HepMCEvents" Whole event in lab. frame

It is possible to write in a specific container, namely "/Event/Gen/SignalDecayTree" only the signal particle and all its decay tree. This is done by adding the option " Generation.SignalRepeatedHadronization.Clean = true ;" in the file Gauss.opts. Then the monitoring algorithm which creates the ROOT ntuple with generator level information can be told to take only the particles coming from the signal particle adding the option " GeneratorFullMonitor.HepMCEvents = "Gen/SignalDecayTree" ; in the file Gauss.opts.

The random seed is controlled by the run number and the event number. To generate independent events,  you have to change for each job the run number with the option GaussGen.RunNumber in Gauss-Job.py.

Some conventions

In EvtGen, the units are the following:

• energy and momentum in MeV
• position and time in mm (time is multiplied by c)

In HepMC format, the mixing is represented this way: if a B meson is produced as B⁰ for example and decays as B⁰, the HepMC record will contain the decay chain B⁰→B⁰. The first B meson is the type at production (tag) and the second B is the type at decay. If there is only one B, both types are the same and the B has not oscillated. If the decay mode of the B is a CP mode, the flavor of the second B is meaningless and the tag is given by the type of the first B. Since the second B has 0 lifetime, both B's will decay at the same position but the production position of the B is the production vertex of the first B.

Analysis Ntuple

A ntuple containing all informations from the generator phase is created and contained by default in the file GaussHistos.root. The ntuple is filled by the monitoring algorithm GeneratorFullMonitor. This algorithm is located in the package Sim/GaussMonitor.

You will obtain a root Ntuple GaussMonitor.root with the content of the HepMC container "/Event/Gen/HepMCEvents". You can modify the code directly to change the content of the Ntuple and to adapt it to your needs. By default, the content of the Ntuple will be :

• NPart Number of particles in the event
• e[NPart] Energy of the particle (MeV)
• px[NPart] Px of the particle (MeV)
• py[NPart] Py of the particle (MeV)
• pz[NPart] Pz of the particle (MeV)
• vxProd[NPart] x of the production vertex (mm)
• vyProd[NPart] y of the production vertex (mm)
• vzProd[NPart] z of the production vertex (mm)
• vtProd[NPart] time of the production vertex (mm)
• vxDecay[NPart] x of the decay vertex (mm)
• vyDecay[NPart] y of the decay vertex (mm)
• vzDecay[NPart] z of the decay vertex (mm)
• vtDecay[NPart] time of the decay vertex (mm)
• pdgId[NPart] PDG id of the particle
• nDau[NPart] Number of decay products of the particle
• pdgIdMother[NPart] PDG id of the mother particle
• pdgIdDau1[NPart] PDG Id of decay product 1
• pdgIdDau2[NPart] PDG Id of decay product 2
• pdgIdDau3[NPart] PDG Id of decay product 3
• pdgIdDau4[NPart] PDG Id of decay product 4
• pdgIdDau5[NPart] PDG Id of decay product 5
• pdgIdDau6[NPart] PDG Id of decay product 6
• indexMother[NPart] Index of the mother particle (!!! starts from one but the array starts from 0, so the real index of the mother particle in the arrays is indexMother-1)
• indexInter[NPart]
• NInter
• isBB[NInter]

A skeleton of a ROOT macro to read the file produced by Gauss can be found here:
{
gROOT->Reset() ;

TFile f( "GaussMonitor.root" ) ;

TTree * T = (TTree*) f.Get( "MCTruth/1" ) ;

Int_t nEvents = T -> GetEntries() ;
printf( "Nentries = %d\n" , nEvents ) ;

Int_t nPart ;
Int_t pdgId[ 2000 ] ;
Int_t nDau[ 2000 ] ;
Int_t pdgIdDau1[ 2000 ] ;
Int_t pdgIdDau2[ 2000 ] ;
Int_t pdgIdDau3[ 2000 ] ;
Int_t pdgIdDau4[ 2000 ] ;
Int_t pdgIdDau5[ 2000 ] ;
Int_t pdgIdDau6[ 2000 ] ;
Int_t pdgIdMother[ 2000 ] ;
Int_t IdMother[ 2000 ] ;
Float_t px[ 2000 ] , py[ 2000 ] , pz[ 2000 ] ;

T -> SetBranchAddress( "NPart" , &nPart ) ;
T -> SetBranchAddress( "pdgId" , &pdgId ) ;
T -> SetBranchAddress( "nDau" , &nDau ) ;
T -> SetBranchAddress( "pdgIdDau1" , &pdgIdDau1 ) ;
T -> SetBranchAddress( "pdgIdDau2" , &pdgIdDau2 ) ;
T -> SetBranchAddress( "pdgIdDau3" , &pdgIdDau3 ) ;
T -> SetBranchAddress( "pdgIdDau4" , &pdgIdDau4 ) ;
T -> SetBranchAddress( "pdgIdDau5" , &pdgIdDau5 ) ;
T -> SetBranchAddress( "pdgIdDau6" , &pdgIdDau6 ) ;
T -> SetBranchAddress( "pdgIdMother" , &pdgIdMother ) ;
T -> SetBranchAddress( "indexMother" , &IdMother ) ;
T -> SetBranchAddress( "px" , &px ) ;
T -> SetBranchAddress( "py" , &py ) ;
T -> SetBranchAddress( "pz" , &pz ) ;

for ( Int_t i = 0 ; i < nEvents ; i++ ) {
T -> GetEntry( i ) ;
.....
}
return 0 ;
}

Decay files available

The following decay modes are predefined in the package DecFiles. To generate a sample according to the decay mode, change the number of the included option file at the end of GenStandAlone.opts. To have more details about what is generated, look at the corresponding options files and decay files in DecFiles/options and DecFiles/dkfiles.

At the beginning of the job, the branching fraction in the generic decay table of the decay mode under study is printed. If this branching fraction is 0 or if there is a message saying that the decay mode is not in DECAY.DEC, please tell me.

When testing decay files, one should use the latest version of the DecFiles package (typing "getpack Gen/DecFiles head" in ~/cmtuser and updating the version of the package in cmt/requirements of Gauss.)

Event Type, Nickname and Decay Mode follow some conventions described in the following LHCb internal note: LHCb-2005-034.

description of the new python script used to create job options from dkfile is in pdf

A table with the event types available, corresponding nickname, authors, when and by whom tested is available from the DecFiles webpages.

Last update: 2 Sep 2009

Please send questions or comments to Patrick Robbe