This page is obsolete and no longer maintained.

The new address for the Gauss/EvtGen web site is:

http://cern.ch/LHCb-release-area/DOC/gauss/generator/evtgen.php

EvtGen is the package used in Gauss to generate B decays. It was originally developed and it is maintained by David Lange and Anders Ryd from BaBar and CLEO.

Documentation

A detailed documentation about the conventions used in EvtGen or about the decay models available and the way to use them can be found on the EvtGen web page or at this location in pdf. 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 is also available here.

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

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

• only of EvtGen alone. In this case, signal B hadrons will be produced at rest  (see at the end of the page),
• of EvtGen together with Pythia to generate the correct momentum distribution of signal B hadrons in LHCb (described just below).

To d, it is possible to use the Gauss executable with the option file GenStandAlone.opts available in the Gauss package. Using for example Gauss version v25r4 (which is the most recent DC06 version), you have to type on a lxplus machine:

1. GaussEnv v25r4
2. cd ~/cmtuser
3. getpack Sim/Gauss v25r4
4. getpack Gen/DecFiles head
5. cd ~/cmtuser/Gen/DecFiles/v13r0/cmt
6. source setup.csh
7. cd ~/cmtuser/Sim/Gauss/v25r4/cmt
8. edit requirement file to "use DecFiles v13r0 Gen"
9. source setup.csh
10. gmake
11. cd ~/cmtuser/Sim/Gauss/v25r4/options
12. edit "Gauss.opts" file and:
    1. Comment or remove ApplicationMgr.TopAlg += { "Sequencer/Simulation" } ;
    2. Comment or remove #include "$GAUSSOPTS/Simulation.opts"
    3. Comment or remove ApplicationMgr.TopAlg += { "Sequencer/Monitor" } ;
    4. Add #include "$DECFILESROOT/options/XXXXXXXX.opts" at the end of the file.
    5. Uncomment #include "$GAUSSOPTS/GenStandAlone.opts"
    6. In file GenStandAlone.opts comment or remove #include "$GAUSSOPTS/GenStandAlone.opts"
    7. In file GenStandAlone.opts add the lines:

    GaussTape.ItemList = {
    "/Event#1",
    "/Event/Gen#1",
    "/Event/Gen/Header#1",
    "/Event/Gen/Collisions#1",
    "/Event/Gen/HepMCEvents#1"
    };

13. cd ~/cmtuser/Sim/Gauss/v25r4/job
14. ../slc3_ia32_gcc323/Gauss.exe ../options/Gauss.opts

You will obtain a file named Gauss.sim in POOL/ROOT format containing the decay trees generated by EvtGen and optionally 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:

• ApplicationMgr.EvtMax = 10; Sets the number of events to generate.  (in Gauss.opts)
• GaussTape.Output = "DATAFILE='PFN:Gauss.sim' TYP='POOL_ROOTTREE' OPT='RECREATE'"; Change the name of the output file. (in Gauss.opts)
• #include "$DECFILESROOT/options/30000000.opts" Define the signal decay mode to generate (see below for a list) (in Gauss.opts)

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

• "/Event/Gen/SignalDecayTree" Signal B decay tree in B rest frame
• "/Event/Gen/HepMCEvents" Whole event in lab. frame (only if Pythia is activated)

By default, only /Event/Gen/HepMCEvents is saved in the output file. You can choose what to save and add things to save in the option file GenStandAlone.opts. The location "/Event/Gen/SignalDecayTree" is only available in case of events generated with EvtGen only (see at the end of the page) or when generating clean events. The generation of clean events can be activated by job options in the file GenStandAlone.opts.

Please note that as indicated above, not all locations are available depending on the options activated. When trying to save a location that is not available, the program may crash. In this case one should check the consistency between the different options.

By default, EvtGen will be used in conjunction with Pythia and B hadrons will be produced with the correct momentum distribution. If you need only the decay kinematics in the B rest frame, you can use EvtGen alone (it is much faster but generates only B at rest). For this you need to modify the following options:

• Add #include "$GAUSSOPTS/EvtGenStandAlone.opts" at the very end of Gauss.opts (after #include "$DECFILESROOT/options/XXXXXX.opts")
• Add ToolSvc.EvtGenTool.ForcedFragmentation = true; in the file Gauss.opts
• Comment or remove the line Generator.Members += {"PythiaAlg","SetDecayAlg","EvtDecayAlg"}; in Generator.opts

 By default, Gauss generates a mixture of b and b hadrons (with 50-50 proportions if the signal decay mode is not a CP mode and taking into account the CP asymmetries if it is a CP mode decayed according to a CP decay model). If you want to generate only one type of B hadron, you can specify the PDG Id of the hadron you want to generate in Gauss.opts, at the very end of the file. For B⁰ for example:

• ToolSvc.EvtGenTool.BhadronID = {511,-511}; to generate a mixture of B⁰ and B⁰
• ToolSvc.EvtGenTool.BhadronID = {511}; to generate only B⁰'s
• ToolSvc.EvtGenTool.BhadronID = {-511}; to generate only B⁰'s
   

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 GaussInit.RunNumber in Gauss.opts.

Some conventions

In EvtGen, the units are the following:

• energy and momentum in GeV
• 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.

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

Analysis Ntuple

You can analyze directly the file Gauss.sim with a Gaudi algorithm.

You can also use the monitoring algorithm GeneratorFullMonitor which is already present in Gauss. This algorithm is located in the package Sim/GaussMonitor.

To add the algorithm to the execution sequence when generating events with Gauss,

• Uncomment the line #include "$GAUSSOPTS/Monitor.opts" in Gauss.opts
• Uncomment the line ApplicationMgr.TopAlg += { "Sequencer/Monitor" }; in Gauss.opts
• Uncomment the line Monitor.Members = { "GeneratorFullMonitor" }; in Monitor.opts
• Comment the line Monitor.Members += { "MCTruthFullMonitor" }; in Monitor.opts

Then run the job like before.

You will obtain a hbook Ntuple GaussMonitor.hbook 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 :

******************************************************************
* Ntuple ID = 1 Entries = 10 MCTruth
******************************************************************
* Var numb * Type * Packing * Range        * Block    * Name *
******************************************************************
* 1        * I*4  *         * [0,2000]     * AUTO_BLK * NPart
* 2        * R*4  *         *              * AUTO_BLK * e(NPart)
* 3        * R*4  *         *              * AUTO_BLK * px(NPart)
* 4        * R*4  *         *              * AUTO_BLK * py(NPart)
* 5        * R*4  *         *              * AUTO_BLK * pz(NPart)
* 6        * R*4  *         *              * AUTO_BLK * vxProd(NPart)
* 7        * R*4  *         *              * AUTO_BLK * vyProd(NPart)
* 8        * R*4  *         *              * AUTO_BLK * vzProd(NPart)
* 9        * R*4  *         *              * AUTO_BLK * vtProd(NPart)
* 10       * R*4  *         *              * AUTO_BLK * vxDecay(NPart)
* 11       * R*4  *         *              * AUTO_BLK * vyDecay(NPart)
* 12       * R*4  *         *              * AUTO_BLK * vzDecay(NPart)
* 13       * R*4  *         *              * AUTO_BLK * vtDecay(NPart)
* 14       * I*4  *         * [-2147483648 * AUTO_BLK * pdgId(NPart)
* 15       * I*4  *         * [-2147483648 * AUTO_BLK * nDau(NPart)
* 16       * I*4  *         * [-2147483648 * AUTO_BLK * pdgIdMother(NPart)
* 17       * I*4  *         * [-2147483648 * AUTO_BLK * pdgIdDau1(NPart)
* 18       * I*4  *         * [-2147483648 * AUTO_BLK * pdgIdDau2(NPart)
* 19       * I*4  *         * [-2147483648 * AUTO_BLK * pdgIdDau3(NPart)
* 20       * I*4  *         * [-2147483648 * AUTO_BLK * pdgIdDau4(NPart)
* 21       * I*4  *         * [-2147483648 * AUTO_BLK * pdgIdDau5(NPart)
* 22       * I*4  *         * [-2147483648 * AUTO_BLK * pdgIdDau6(NPart)
* 23       * I*4  *         * [-2147483648 * AUTO_BLK * indexMother(NPart)
* 24       * I*4  *         * [-2147483648 * AUTO_BLK * indexInter(NPart)
* 25       * I*4  *         * [0,20]       * AUTO_BLK * NInter
* 26       * I*4  *         * [-2147483648 * AUTO_BLK * isBB(NInter)
********************************************************************

The corresponding Fortran include file is :

*********************************************************
* *
* This file was generated by HUWFUN. *
* *
*********************************************************
*
* Ntuple Id: 1
* Ntuple Title: MCTruth
* Creation: 19/03/2004 16.15.50
*
*********************************************************
*
      REAL e,px,py,pz,vxProd,vyProd,vzProd,vtProd,vxDecay,vyDecay
     + ,vzDecay,vtDecay
      INTEGER NPart,pdgId,nDau,pdgIdMother,pdgIdDau1,pdgIdDau2,pdgIdDau3
     + ,pdgIdDau4,pdgIdDau5,pdgIdDau6,indexMother,indexInter,NInter,isBB
      COMMON /AUTO_BLK/ NPart,e(2000),px(2000),py(2000),pz(2000)
     + ,vxProd(2000),vyProd(2000),vzProd(2000),vtProd(2000)
     + ,vxDecay(2000),vyDecay(2000),vzDecay(2000),vtDecay(2000)
     + ,pdgId(2000),nDau(2000),pdgIdMother(2000),pdgIdDau1(2000)
     + ,pdgIdDau2(2000),pdgIdDau3(2000),pdgIdDau4(2000),pdgIdDau5(2000)
     + ,pdgIdDau6(2000),indexMother(2000),indexInter(2000),NInter
     + ,isBB(20)
 

If you prefer, you can also make a ROOT Ntuple instead. For this, replace "HBOOK" by "ROOT" and "HbookCnv" by "RootHistCnv" in Monitor.opts and add "use RootHistCnv v*" to cmt/requirements.

Last update: 13 December 2006

Please send questions or comments to Patrick Robbe