Do not use instructions here yet. Please follow official instructions at

Decay files

Adding a new decay file

  1. Fork the DecFiles project on gitlab
  2. Get a local clone to work on your fork
    git clone ssh://<username>/Gen-DecFiles.git Gen/DecFiles
  3. Find if a DecFile you want (or similar enough so you can use it) already exists
  4. Read the event type numbering convention
  5. If you are using an old DecFile as a template, note that it might not follow the established conventions
  6. Test your DecFile (both that it runs and that it produces output you want)
  7. Once you are confident the DecFile is what you want, you can push your changes to your fork (if you didn't do it yet), and create a merge request
  8. A Gauss manager will review your merge request and let you know if changes are needed
  9. After your merge request has been accepted, in a day or two check the slot lhcb-decfilestests in the nightly builds
    1. there are no warning or errors from your decay file at build stage
    2. your file passes test. Look for positive evidence as that will also allow you to check that file was really committed.
    3. If anything fails, please correct and recheck again day after commit. If you do not understand failure, get in touch with

Testing a decay file

This is done in three steps:

Write the decay file and create the options

If you do not already have the environment set up, prepare it to run one of the latest Gauss version (v45rX for Sim08 productions, or v46rX for upgrade productions). In the examples below, v45r9 is used. If you are running on SLC6, setup SLC5 environment (LbLogin -c x86_64-slc5-gcc46-opt).

cd ~/cmtuser
lb-dev Gauss v45r9
cd GaussDev_v45r9

Then get from your fork on gitlab the Gen/DecFiles package.

git clone ssh://<username>/LHCb-SVN-mirrors/Gen-DecFiles.git Gen/DecFiles

Add the new decay file in the dkfiles subdirectory and create the options to be used by Gauss.

cd ~/cmtuser/GaussDev_v45r9

If there is no mistake in the decay file, an option file called is present in the options subdirectory, where NNNNNNNN is the event type number of the decay file.

It is also recommended to run the decay file convention parser

cd ~/cmtuser/GaussDev_v45r9/Gen/DecFiles/cmt
./ ../dkfiles/DecFile.dec

This should check for convention correctness for the event type and some basic mistakes, but it also has some limitations. This is our tool to help in checking, but at the end all failures are individually considered. Feel free to email any comments to lhcb-gauss-manager.

Run Gauss to create a .xgen file

The .xgen file contains the generator level information (both in HepMC and MCParticles format) when running Gauss with only the generator part, without the simulation and Geant4 being activated.

cd ~/cmtuser/GaussDev_v45r9

The number of events to generate (5 by default) is set in the file. It is also a good idea to test the decay file using Pythia8, with the instructions:


Gauss will then produce a file called by default Gauss-NNNNNNNN-5ev-YYYYMMDD.xgen, with a name formed from the event type (NNNNNNNN), the number of events (5ev by default) and the day (in format YYYYMMDD).

Create a MCDecayTreeTuple from the .xgen file

Use DaVinci to read the file produced by Gauss and to create a ROOT file with the information from the generator level history.

lb-run DaVinci latest

where contains

from Configurables import (
from DecayTreeTuple.Configuration import *

"""Configure the variables below with:
decay: Decay you want to inspect, using 'newer' LoKi decay descriptor syntax,
decay_heads: Particles you'd like to see the decay tree of,
datafile: Where the file created by the Gauss generation phase is, and
year: What year the MC is simulating.

decay = "[B0 => ^(Lambda_c~- ==> ^p~- ^K+ ^pi-) ^p+ ^pi- ^pi+]CC"
decay_heads = ["B0", "B~0"]
datafile = "Gauss-11166070-5ev-20140429.xgen"
year = 2012

# For a quick and dirty check, you don't need to edit anything below here.

# Create an MC DTT containing any candidates matching the decay descriptor
mctuple = MCDecayTreeTuple("MCDecayTreeTuple")
mctuple.Decay = decay
mctuple.ToolList = [
# Add a 'number of photons' branch
mctuple.addTupleTool("MCTupleToolKinematic").Verbose = True
mctuple.addTupleTool("LoKi::Hybrid::TupleTool/LoKi_Photos").Variables = {
    "nPhotos": "MCNINTREE(('gamma' == MCABSID))"

# Print the decay tree for any particle in decay_heads
printMC = PrintMCTree()
printMC.ParticleNames = decay_heads

# Name of the .xgen file produced by Gauss
EventSelector().Input = ["DATAFILE='{0}' TYP='POOL_ROOTTREE' Opt='READ'".format(datafile)]

# Configure DaVinci
DaVinci().TupleFile = "DVntuple.root"
DaVinci().Simulation = True
DaVinci().Lumi = False
DaVinci().DataType = str(year)
DaVinci().UserAlgorithms = [printMC, mctuple]

Efficiency of generator level cuts

This number can be extracted from the GeneratorLog.xml file (produced by your gauss job), where the printout is of the form

<efficiency name = "generator level cut">
    <after> 5 </after>
    <before> 27 </before>
    <value> 0.18519 </value>
    <error> 0.074757 </error>

the efficiency is therefore 5/27 in this example

Create a merge request

Once you are sure that the decfile you want to make public is good, you should push the changes to your fork on

  • got to the gitlab page of your fork:<user>/Gen-DecFiles
  • you should see a "Create Merge Request" button at the top-right of the page, if not, click on the plus button under the project title and select "New Merge Request"
  • in the merge request form, fill carefully the title and the description with details about the decfile you are adding


Plan for releases

Following is current plan for deadlines to future releases. Deadlines can shift in case of something unexpected happens.

  • 4/Sep for v27r53
  • 18/Sep for v27r54
  • 2/Oct for v27r55
  • 16/Oct for v27r56
  • 30/Oct for v27r57

-- MarcoClemencic - 2015-12-03

Edit | Attach | Watch | Print version | History: r3 < r2 < r1 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r3 - 2016-11-07 - MichalKreps
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    LHCb All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback