Tauola and Tauola++ Interfaces to CMSSW

Complete: 3

Introduction to Tauola/Tauola++

Tauola is a MC Generator dedicated to generating tau-lepton decays. In CMSSW, Tauola is accessed through the TauolaInterface. The Tauola version in each release can be seen below.

Tauola Version Contents Releases Notes Plans
Tauola++ 1.1.4 Tauola++, TauSpinner Now added to 7_1_X and 7_2_X Include matrix element reweighting for tau decays and for the full Z0/W+/-/H0/H+/-. Also includes transverse component for scalar/pseudo-scalar Higgs. Requested for CMSSW_6_X_Y, CMSSW_5_3_X
Tauola++ 1.1.3 Tauola++, TauSpinner CMSSW_7_0_X, CMSSW_7_1_X Replaces Tauola++ 1.1.1a Requested for CMSSW_7_1_X, CMSSW_6_X_Y, CMSSW_5_3_X
Tauola++ 1.1.1a Tauola++, TauSpinner CMSSW_5_3_X (X>14) Added for TauSpinner which is uses in tau Embedding NA
Tauola++ 1.0.5 Tauola++, CMSSW_6_X_Y Validation was in CMSS_6_0_0_pre5-CMSSW_6_1_0. Accepted in CMSSW_6_2_X NA
Tauola 2.7 (FORTRAN) Tauola, CMSSW_5_X_Y, CMSSW_4_X_Y, CMSSW_3_X_Y   Obsolete - only kept for backward compatibility

Tauola++

Documentation: web-site, paper

Tauola++ is a universal interface which can be used as a "sub-contractor" for most MC generators, including pythia 8. Physics wise, Tauola++ and the most recent version of Tauola should be identical. What Tauola++ offers is a uniform interface that allow Tauola to be used with almost all MC generators.

Tauola++ includes:

Tauola (Fortran)

Documentation: web site, paper

Tauola is the default versions of Tauola in CMSSW

Tauola is currently used as a "sub-contractor" with any Pythia6-based event generation, i.e. use of Pythia6 as a full event generator or processing externally generated partons by any ME MC tools.

Tauola can, in principal, also be used with Herwig6-based event generation (incl. ME partons), but this feature has NOT been sufficiently tested. Thus users are welcome to give it a try to provide feedback, but at present the developers can't guarantee the quality of the output. In general, software of the GeneratorInterface subsystem has been designed to allow transparent use of Tauola (or any other dedicated decay package) with any multi-purpose event generator. However, some necessary pieces of code are still in development; the use of Tauola with generators like Pythia8 or Herwigg++ (ThePEGInterface) wont activate. Tauola is coupled with another packages used in CMSSW, PHOTOS. More details on these two packages can be found here.

How to Generate events with Tauola in CMSSW

Tauola with Plugins [5_3_X and higher]

Currently being merged into the release.....

The ExternalDecay package has now been converted to using plugins. This includes Tauola, Tauola++ and EvtGen. The Tauola is activated by using the below configuration for ExternalDecays parameter-set.

  ExternalDecays = cms.PSet(
        [TauolaInputFlag] = cms.untracked.PSet(
            TauolaPolar,
            TauolaDefaultInputCards
        ),
        parameterSets = cms.vstring('[TauolaInputFlag]')
  ),
 UseExternalGenerators = cms.untracked.bool(True),

Where the [TauolaInputFlag] is one of the following options listed in the tables below (Note: the original [TauolaInputFlag]="Tauola" simply picks the default versions of Tauola in the release).

Tauola Version [TauolaInputTag]
Tauola++ 1.1.4 Tauolapp114
Tauola++ 1.1.3 Tauolapp113a
Tauola++ 1.1.1a Tauolapp111a
Tauola++ 1.0.5 Tauolapp105
Tauola Fortran 2.7 Tauola271215

CMSSW Release Series [TauolaInputTag] Default Versions of Tauola
CMSSW_7_1_X (new releases) Tauolapp114 Tauola++ 1.1.4
CMSSW_7_1_X (older releases) Tauolapp113a Tauola++ 1.1.3
CMSSW_7_0_X NA Tauola++ 1.1.3
CMSSW_6_2_X Tauolapp105 Tauola++ 1.0.5
CMSSW_5_3_X Tauolapp111a, Tauola271215 Tauola Fortran 2.7

Tauola in CMSSW 3_X_Y and 4_X_Y

As of development cycle CMSSW_3_1_0, decays of tau-leptons with Tauola can be activated with the following example block of configuration parameters with any of CMSSW event generation module:

  ExternalDecays = cms.PSet(
        Tauola = cms.untracked.PSet(
            TauolaPolar,
            TauolaDefaultInputCards
        ),
        parameterSets = cms.vstring('Tauola')
 ),
 UseExternalGenerators = cms.untracked.bool(True),

Additonal Features for Tauola

Tauola++ 1.1.4 and Higher

In Interface for Tauola++ and higher, there has been additional options added to allow the user to configure Tauola. The option include effects such as the model used for the hadronic currents, manipulating the spin of configuration of Z0 and Higgs Bosons, and reconfiguring the branching ratio in the decay. These options are activated by defining them in the "parameterSets". An example can be seen below.

  ExternalDecays = cms.PSet(
        Tauola = cms.untracked.PSet(
          UseTauolaPolarization = cms.bool(True),
          InputCards = cms.PSet(
            mdtau = cms.int32(0),
            pjak2 = cms.int32(5),
            pjak1 = cms.int32(5)
          ),
          parameterSets = cms.vstring("setNewCurrents"),
          setNewCurrents = cms.int32(1)
        ),
        parameterSets = cms.vstring('Tauola')
  ),
  UseExternalGenerators = cms.untracked.bool(True),

For the branching ratios, one must use a slightly different notations to include both vectors. Please note: the JAK (the id number of the decay mode) and BR vectors must be the same length. Below is a example where the electron and muon channels are turned off.

  ExternalDecays = cms.PSet(
        Tauola = cms.untracked.PSet(
          UseTauolaPolarization = cms.bool(True),
          InputCards = cms.PSet(
            mdtau = cms.int32(0),
            pjak2 = cms.int32(5),
            pjak1 = cms.int32(5)
          ),
          parameterSets = cms.vstring("setTauBr"),
          setTauBr = cms.PSet(
            JAK = cms.vint32(1,2),
            BR  = cms.vdouble(0.0,0.0)
          ),
        parameterSets = cms.vstring('Tauola')
  ),
  UseExternalGenerators = cms.untracked.bool(True),

A complete list of options available can be seen in the table below(The explanations are quoted from the Tauola++ Manual ):

Parameter Tauola++ Function Type Description
setNewCurrents Tauolapp::Tauola::setNewCurrents(int ) int32 Version 1.1.4 introduces new currents, for 3pi decay modes, based on Resonance Chiral Lagrangian approach and described in the paper (Phys Rev D88,2013, 093012). New currents for the 2pi decay mode(Phys Rev D78,2008, 072006), courtesy of the Belle collaboration, are also available. Tauola++ Manual B.4
spinCorrelationSetAll Tauolapp::Tauola::spin_correlation.setAll(bool flag) bool Turns all spin correlation computations on or off depending on the flag, which can be either true or false. Tauola++ Manual C.1
spinCorrelationGAMMA Tauolapp::Tauola::spin_correlation.GAMMA=flag bool Turns particular spin correlation computation on or off for a given tau parent depending on the flag which can be either true or false. Tauola++ Manual C.1
spinCorrelationZ0 Tauolapp::Tauola::spin_correlation.Z0=flag bool Turns particular spin correlation computation on or off for a given tau parent depending on the flag which can be either true or false. Tauola++ Manual C.1
spinCorrelationHIGGS Tauolapp::Tauola::spin_correlation.HIGGS=flag bool Turns particular spin correlation computation on or off for a given tau parent depending on the flag which can be either true or false. Tauola++ Manual C.1
spinCorrelationHIGGSH Tauolapp::Tauola::spin_correlation.HIGGS_H=flag bool Turns particular spin correlation computation on or off for a given tau parent depending on the flag which can be either true or false. Tauola++ Manual C.1
spinCorrelationHIGGSA Tauolapp::Tauola::spin_correlation.HIGGS_A=flag bool Turns particular spin correlation computation on or off for a given tau parent depending on the flag which can be either true or false. Tauola++ Manual C.1
spinCorrelationHIGGSPLUS Tauolapp::Tauola::spin_correlation.HIGGS_PLUS=flag bool Turns particular spin correlation computation on or off for a given tau parent depending on the flag which can be either true or false. Tauola++ Manual C.1
spinCorrelationHIGGSMINUS Tauolapp::Tauola::spin_correlation.HIGGS_MINUS=flag bool Turns particular spin correlation computation on or off for a given tau parent depending on the flag which can be either true or false. Tauola++ Manual C.1
spinCorrelationWPLUS Tauolapp::Tauola::spin_correlation.W_PLUS=flag bool Turns particular spin correlation computation on or off for a given tau parent depending on the flag which can be either true or false. Tauola++ Manual C.1
spinCorrelationWMINUS Tauolapp::Tauola::spin_correlation.W_MINUS=flag bool Turns particular spin correlation computation on or off for a given tau parent depending on the flag which can be either true or false. Tauola++ Manual C.1
setHiggsScalarPseudoscalarPDG Tauolapp::Tauola::setHiggsScalarPseudoscalarPDG(int pdg code) int The PDG Monte-Carlo code of the Higgs which should be treated by the interface as a scalar-pseudosclar mix. The default value is PDG id 35. Please note that if pdg code is set to the value of an existing spin case (eg. 25, the regular scalar Higgs) the scalar-pseudoscalar case will be assumed. Tauola++ Manual C.6
setHiggsScalarPseudoscalarMixingAngle Tauolapp::Tauola::setHiggsScalarPseudoscalarMixingAngle(double angle) double set the scalar-pseudoscalar mixing angle. Tauola++ Manual C.6
setRadiation Tauolapp::Tauola::setRadiation(bool cut_off) bool Radiative corrections for leptonic tau decays may be switched on or off by setting the switch to true or false respectively. By default this is true. Tauola++ Manual C.4
setRadiationCutOff Tauolapp::Tauola::setRadiationCutOff(bool) bool Set the cut-off for radiative corrections of tau decays. The default of 0.01 means that only a photon of energy (in its rest frame) above 0.01 of half of the decaying particle mass will be explicitly generated. Tauola++ Manual C.4
setEtaK0sPi Tauolapp::Tauola::setEtaK0sPi(vpar[0],vpar[1],vpar[2]) vint The three parameters a, b and c switch on or off the decay of eta, KS0 and pi0. A value of 1 is on and 0 is off. Tauola++ Manual C.5
| setTaukle | Tauolapp::Tauola::setTaukle(vpar[0], vpar[1], vpar[2], vpar[3]) | vdouble | Change the tau sub-channels branching ratio for the a1. Tauola++ Manual C.2
setTauBr Tauolapp::Tauola::setTauBr(vJAK[i],vBR[i]) PSet(vint32,vdouble) Change the tau branching ratio for the channel mode from default to br. Tauola++ Manual C.5

Tauola and Tauola++

The Tauola default blocks can be replaces to use more advanced features of CMSSW Tauola Interface. More specifically:

  ExternalDecays = cms.PSet(
        Tauola = cms.untracked.PSet(
             UseTauolaPolarization = cms.bool(True),
             InputCards = cms.PSet
             (
                pjak1 = cms.int32(0),
                pjak2 = cms.int32(0),
                mdtau = cms.int32(214) # this means  ONE tau L+-,  other taus -> hadrons  
             )
        ),
        parameterSets = cms.vstring('Tauola')
  ),
 UseExternalGenerators = cms.untracked.bool(True),
In this example above we explicitly configure Tauola to decay one tau into the leptonic mode, and the other tau - into the hadronic mode.

By default, Tauola in CMSSW is configured to decay all tau's in a generic way (all known decay modes).

For users convenience and also for the need of central production we are offering a per-fabricated configuration fragment:
GeneratorInterface/ExternalDecays/python/TauolaSettings_cff.py.
A user may import this configuration fragment into her/his application, and use it as follows:

    ExternalDecays = cms.PSet(
        Tauola = cms.untracked.PSet(
            TauolaPolar,
            TauolaDefaultInputCards
        ),
        parameterSets = cms.vstring('Tauola')
    ),
  UseExternalGenerators = cms.untracked.bool(True),

In the /python subdirectory of the Configuration/Generator package you may find several example configuration fragments that show how to use Tauola with Pythia6 event generaion; please feel free to inspect:

The following table (extracted from the Tauola code) can serve as a mini-guide for configuring different decay modes.

*
* below L+- means electron/positron or mu+-                                  *
* mdtau = 0      -  all decay modes according to JAK1 and JAK2 * 
* . . . . . . . . . . . . . . . .  . . . . . . . . . . . . . . . . . . . . . *
* mdtau = 1xx :  could be applied for DIRECT taus (from hard process)        *
* .......                                                                    *
* mdtau = 1   - any taus                *
* mdtau = 100 - only L+-  for any tau                                        *
* mdtau = 101 - only e+-  for any tau                                        *
* mdtau = 102 - only mu+- for any tau                                        *
* mdtau = 110 - ONE L+-,  other taus -> all channels                         *
* mdtau = 111 - ONE e+-,  other taus -> all channels                         * 
* mdtau = 112 - ONE mu+-, other taus -> all channels                         *
* mdtau = 114 - ONE L+-,  other taus -> hadrons                              *
* mdtau = 115 - ONE e+-,  other taus -> hadrons                              *
* mdtau = 116 - ONE mu+-, other taus -> hadrons                              *
* mdtau = 120 - TWO L+-,  other taus -> all channels                         *
* mdtau = 121 - TWO e+-,  other taus -> all channels                         *
* mdtau = 122 - TWO mu+-, other taus -> all channels                         *
* mdtau = 123 - ONE e+-, SECOND mu+-, other taus -> all channels             * 
* mdtau = 124 - TWO L+-,  other taus -> hadrons                              *
* mdtau = 125 - TWO e+-,  other taus -> hadrons                              *
* mdtau = 126 - TWO mu+-, other taus -> hadrons                              *
* mdtau = 127 - ONE e+-, SECOND mu+-, other taus -> hadrons                  *
* mdtau = 130 - only hadronic channels for any tau                           *
* mdtau = 131 - ONE tau  -> hadrons, other taus -> all channels              *
* mdtau = 132 - TWO taus -> hadrons, other taus -> all channels              *
* mdtau = 140 - only nutau and PI+-    for any tau                           *
* mdtau = 141 - ONE tau -> PI+-, other taus -> all channels                  *
* mdtau = 142 - TWO tau -> PI+-, other taus -> all channels                  *
*----------------------------------------------------------------------------*
* mdtau = 2xx   :  could be applied for any taus                             *
* .......                                                                    *
* mdtau = 200 - only L+-  for any tau                                        *
* mdtau = 201 - only e+-  for any tau                                        *
* mdtau = 202 - only mu+- for any tau                                        *
* mdtau = 210 - ONE L+-,  other taus -> all channels                         *
* mdtau = 211 - ONE e+-,  other taus -> all channels                         * 
* mdtau = 212 - ONE mu+-, other taus -> all channels                         *
* mdtau = 214 - ONE L+-,  other taus -> hadrons                              *
* mdtau = 215 - ONE e+-,  other taus -> hadrons                              *
* mdtau = 216 - ONE mu+-, other taus -> hadrons                              *
* mdtau = 220 - TWO L+-,  other taus -> all channels                         *
* mdtau = 221 - TWO e+-,  other taus -> all channels                         *
* mdtau = 222 - TWO mu+-, other taus -> all channels                         *
* mdtau = 223 - ONE e+-, SECOND mu+-, other taus -> all channels             * 
* mdtau = 224 - TWO L+-,  other taus -> hadrons                              *
* mdtau = 225 - TWO e+-,  other taus -> hadrons                              *
* mdtau = 226 - TWO mu+-, other taus -> hadrons                              *
* mdtau = 227 - ONE e+-, SECOND mu+-, other taus -> hadrons                  *
* mdtau = 230 - only hadronic channels for any tau                           *
* mdtau = 231 - ONE tau  -> hadons, other taus -> all channels               *
* mdtau = 232 - TWO taus -> hadons, other taus -> all channels               *
* mdtau = 240 - only nutau and PI+-    for any tau                           *
* mdtau = 241 - ONE tau -> PI+-, other taus -> all channels                  *
* mdtau = 242 - TWO tau -> PI+-, other taus -> all channels                  *
* . . . . . 
* if the event has only ONE tau-lepton the cases with TWO requirements
* the both two required channels are considered simultaneously

How to use TauSpinner in CMSSW

Documention in arXiv:1201.0117,arXiv:1212.2873 and arXiv:1402.2068.

In CMSSW TauSpinner can be run using the TauSpinnerInterface (There is the option to use the weights to "KILL" events using TauSpinnerFilter, or one can directly apply the weight in an analysis.

NOTE: TauSpinner should be run on unpolarized events to add polarization effects. This is because when one tried to unpolarized events, the weights are unbounded (ie blow up to infinity).

How to use TauSpinnerFilter in 5_3_X, 6_2_X and 7_X_Y

These instructions for for the recent version of ExternalDecays with plugins and Tauola++ 1.1.1a or higher. For older release see below.

The TauSpinnerInterface can be run both on HepMCEvents and on GenParticles on AOD. For HepMCEvents the the user should include the:

process.load("GeneratorInterface.TauolaInterface.TauSpinner_cfi") # required statement to load modules
process.TauSpinnerGen # module to be included in your path
to their path. For the GenParticle Collection, the user should include:
process.load("GeneratorInterface.TauolaInterface.TauSpinner_cfi") # required statement to load modules
process.TauSpinnerReco  # module to be included in your path
Both of these edm modules are defined in GeneratorInterface/TauolaInterface/python/TauSpinner_cfi.py for package corresponding to the given release. For the TauSpinner modules, there are several important options: the LHPDF tune; and the CM-energy. The authors of Tauola take no responsibility for the choice of the LHPDF tune, instead it is recommended you use the prefered tune of your PAG or POG. Examples of how to set these variables (one can replace TauSpinnerReco with TauSpinnerGen):
process.TauSpinnerReco .LHAPDFname = cms.untracked.string('MSTW2008nnlo90cl.LHgrid') # the LHAPDF tune the user wishes to use in the re-weighting for Z decays
process.TauSpinnerReco .CMSEnergy = cms.double(8000.0) # the collison energy used for the MC        

TauSpinner produces the following weights

  • TauSpinnerWTisValid - a flag on the status of the weights. True means the weights are usable.
  • TauSpinnerWT - The spin weight to go from unspinner -> spinned
  • TauSpinnerWTFlip - The spin weight to go from Z0 -> H0, H0 -> Z0, W+/- -> H+/- or H+/- -> W+/-
  • TauSpinnerWThplus - The weight for the polarization state h+ (originally included the weight for unspinner -> spinned)
  • TauSpinnerWThminus - The weight for the polarization state h- (originally included the weight for unspinner -> spinned)

Examples of running TauSpinner in CMSSW can be found in:

GeneratorInterface/TauolaInterface/test/TauSpinnerZTest.py
GeneratorInterface/TauolaInterface/test/TauSpinnerWTest.py
GeneratorInterface/TauolaInterface/test/TauSpinnerRecoTest.py

How to use TauSpinnerFilter

Depending on the analysis, one may wish to "KILL" events instead of weighting them. The TauSpinnerFilter allows one to filters or "KILLS" events after TauSpinner is run and can be run using the module

process.load("GeneratorInterface.TauolaInterface.TauSpinnerFilter_cfi") # required statement to load modules
process.TauSpinnerZHFilter # module to be included in your path
and
process.load("GeneratorInterface.TauolaInterface.TauSpinnerFilter_cfi") # required statement to load modules
process.TauSpinnerWHpmFilter # module to be included in your path
for Z0/H0 and W+/-/H+/- respectively. These modules are defined in GeneratorInterface/TauolaInterface/python/TauSpinnerFilter_cfi.py.

Examples of running TauSpinnerFilter can be found in:

GeneratorInterface/TauolaInterface/test/H130GGgluonfusion_8TeV_Tauola_TauSpinner_Example_cfi.py
GeneratorInterface/TauolaInterface/test/DYToLL_M_50_TuneZ2star_8TeV_Tauola_TauSpinner_Example_cfi.py

Note: If you are running Tauola++ and TauSpinner in the same job you must use the same version of Tauola++ for both.

Instructions for older versions of CMSSW_5_3_X and CMSSW_7_0_X

TauSpinner was first added in CMSSW_5_3_X (X>=8) with Tauola++ 1.1.2. In these releases TauSpinner is accessible only from the used code.

For CVS (obsolete July 30, 2013):

cvs cvs co -d TauSpinnerInterface -r V00-00-01 /UserCode/RWTH3b/Tau/TauSpinnerInterface/TauSpinnerInterface/  
For Git the code is located in:
https://github.com/inugent/usercode/blob/master/TauSpinnerInterface/TauSpinnerInterface/
As of July 15 2013, all updates should go into Git repository.

For Tauola++ 1.1.3, requested for validated in CMSSW_7_0_0_pre0 the TauSpinner interface will be included in the GeneratorInterface/ExternalDecays as a plugin.

Review status

Reviewer/Editor and Date (copy from screen) Comments
Main.Ian M. Nugent - 05 Feb 2014 Bring up to date with plugins for ExternalDecays

Responsible: Main.Ian M. Nugent
Last reviewed by: TO BE REVIEWED

Edit | Attach | Watch | Print version | History: r28 < r27 < r26 < r25 < r24 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r28 - 2014-09-05 - IanNugent
 
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    CMSPublic 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