Common Candidate Modules

Complete:

Purpose of this page

Describe the supported common framework modules to manipulate collections of Particle Candidates.

Candidate Collection Combiners

Combine a number of input candidate collections into a collection of composite particles according to a specified decay pattern.

Combiner types can either create composite objects having, as daughter particles, clones of the input particles, or shallow clones of the input particles, i.e. clones having a reference to the "master" clone in the input collection.

The selection criteria used to filter combined particles can be either specified as a text string or via configurable parameters, using the generic selector mechanism.

Candidate combiners are defined in the package CommonTools/CandAlgos. More details about the supported candidate combiner modules can be found in the document below:

• CandCombiner documentation page

Candidate Histogrammer and Ntuple Modules

Modules that dump configurable sets of histograms are provided. More details can be found in the document below:

• Histogrammer Utilities

CandViewNtpProducer

The module CandViewNtpProducer dumps an EDM-style ntuple saving for each entry in the input collection a set of variables that can be configured from parameter set. The quantities that are stored in the output event can be specified as generic expressions. Each new branch will have the alias specified by the parameter tag.

An example of configuration can be found below:

  ntp = cms.EDproducer("CandViewNtpProducer",
     src = cms.InputTag("genParticles"),
     variables = cms.VPSet(
                       cms.PSet(tag=cms.untracked.string("Pt"),
                                       quantity=cms.untracked.string("pt")),
                       cms.PSet(tag=cms.untracked.string("Eta"),
                                       quantity=cms.untracked.string("eta")),
                       cms.PSet(tag=cms.untracked.string("Phi"),
                                        quantity=cms.untracked.string("phi"))
                 )
)

Find a more comprehensive explanation on how to produce an EDM ntuple with the CandViewNtpProducer at this page:SWGuideEDMNtuples.

Candidate Filters

Filter modules based on collections of candidates.

CandViewCountFilter

Filters an event if the input collection has at least the specified number of entries. The input collection should match edm::View<reco::Candidate>. An example of configuration is the following, filtering an event if at least two muons are present:

  muonFilter = cms.EDFilter("CandViewCountFilter",
    src = cms.InputTag("allMuons"),
    minNumber = cms.uint32(2),
  )

CandCountFilter

Filters an event if the input collection has at least the specified number of entries. The input collection should be of type reco::CandidateCollection. An example of configuration is the following, filtering an event if at least two muons are present:

  muonFilter = cms.EDFilter("CandCountFilter",
    src = cms.InputTag("allMuons"),
    minNumber = cms.uint32(2),
  )

Candidate Selectors

Select candidate collections on the basis of configurable criteria. Candidate selectors, as other common selector modules, are implemented using the generic selector mechanism.

Canididate selectors are defined in the package CMS.PhysicsTools/CandAlgos.

PtMinCandSelector

Selects candidates with p_t larger than a given threshold and saves a collection of clones of the selected objects. An example of configuration is the following:

  bestMuons = cms.EDProducer("PtMinCandSelector",
    src = cms.InputTag("muons"),
    ptMin = cms.double(10)
  )

PtMinCandViewSelector

Selects candidates with p_t larger than a given threshold and saves a collection of clones of the selected objects. The input can be any collection matching edm::View<reco::Candidate>, the output is a collection of references to selected objects (edm::RefToBaseVector<reco::Candidate>). An example of configuration is the following:

  bestMuons = cms.EDFilter("PtMinCandViewSelector",
    src = cms.InputTag("muons"),
    ptMin = cms.double(10)
  )

PtMinCandViewCloneSelector

Selects candidates with p_t larger than a given threshold and saves a collection of clones of the selected objects.The input can be any collection matching edm::View<reco::Candidate>, the output is a collection of clones of selected objects (reco::CandidateCollection). An example of configuration is the following:

  bestMuons = cms.EDFilter("PtMinCandViewCloneSelector",
    src = cms.InputTag("muons"),
    ptMin = cms.double(10)
  )

EtaPtMinCandSelector

Selects candidate having p_t larger than a configurable cut and η within a specified range. Saves a collection of clones of the selected objects. An example of configuration is the following:

  bestMuons = cms.EDProducer("EtaPtMinCandSelector",
    src = cms.InputTag("allMuons"),
    ptMin   = cms.double(10),
    etaMin = cms.double(-2),
    etaMax = cms.double(2)
  )

EtaPtMinCandViewSelector

Selects candidate having p_t larger than a configurable cut and η within a specified range. Saves a collection of clones of the selected objects. The input can be any collection matching edm::View<reco::Candidate>, the output is a collection of references to selected objects (edm::RefToBaseVector<reco::Candidate>). An example of configuration is the following:

  bestMuons = cms.EDFilter("EtaPtMinCandViewSelector",
    src = cms.InputTag("allMuons"),
    ptMin   = cms.double(10),
    etaMin = cms.double(-2),
    etaMax = cms.double(2)
  )

EtMinCandViewSelector

Selects candidates with E_t larger than a given threshold and saves a collection of clones of the selected objects. The input can be any collection matching edm::View<reco::Candidate>, the output is a collection of references to selected objects (edm::RefToBaseVector<reco::Candidate>). An example of configuration is the following:

   bestMuons = cms.EDFilter("EtMinCandViewSelector",
    src = cms.InputTag("muons"),
    etMin = cms.double(10)
  )

CandSelector

Selects candidate on the basis of a cut specified as text string and saves a collection of clones of the selected objects. An example of configuration is the following:

  bestMuons = cms.EDProducer("CandSelector",
    src = cms.InputTag("allMuons"),
    cut = cms.string("pt > 10 & abs( eta ) < 2")
  )

More information on configurable string cuts can be found in:

• Physics Cut Parser.

LargestPtCandSelector

Selects the N candidates having the largest p_t, N being a configurable parameter. Saves a collection of clones of the selected objects. An example of configuration is the following:

  bestMuons = cms.EDProducer("LargestPtCandSelector",
    src = cms.InputTag("allMuons"),
    maxNumber = cms.uint32(3)
  )

LargestPtCandViewSelector

Selects the N candidates having the largest p_t, N being a configurable parameter. Saves a collection of clones of the selected objects. The input can be any collection matching edm::View<reco::Candidate>, the output is a collection of references to selected objects (edm::RefToBaseVector<reco::Candidate>). An example of configuration is the following:

  bestMuons =cms.EDProducer("LargestPtCandViewSelector",
    src = cms.InputTag("allMuons"), 
    maxNumber = cms.uint32(3)
  )

PdgIdCandSelector

Selects candidates with absolute value of the PDG-id in a specified set of values, and saves a collection of clones of the selected objects. An example of configuration is the following:

    leptons = cms.EDProducer("PdgIdCandSelector",
    src = cms.InputTag("genParticles"), 
    pdgId = cms.vint32( 11, 13 )
  )

PdgIdCandViewSelector

Selects candidates with absolute value of the PDG-id in a specified set of values, and saves a collection of clones of the selected objects. The input can be any collection matching edm::View<reco::Candidate>, the output is a collection of references to selected objects (edm::RefToBaseVector<reco::Candidate>). An example of configuration is the following:

  leptons = cms.EDProducer("PdgIdCandSelector",
    src = cms.InputTag("genParticles"), 
    pdgId = cms.vint32( 11, 13 )
  )

PdgIdCandRefSelector

Selects candidates with absolute value of the PDG-id in a specified set of values, and saves a collection of references (reco::CandidateRef) to the selected objects. An example of configuration is the following:

  leptons = cms.EDProducer("PdgIdCandRefSelector",
    src = cms.InputTag("genParticles"), 
   pdgId = cms.vint32( 11, 13 )
  )

Warning: the name of this module is PdgIdCandRefVectorSelector in releases earlier than 1.6.0.

PdgIdAndStatusCandSelector

Selects candidates with absolute value of the PDG-id and status in a specified set of values, and saves a collection of clones of the selected objects. The input collection must be of type reco::CandidateCollection. An example of configuration is the following:

  leptons = cms.EDProducer("PdgIdAndStatusCandViewSelector",
    src = cms.InputTag("genParticles"), 
    pdgId = cms.vint32( 11, 13 ),
    status = cms.vint32( 1, 3 )
  )

PdgIdAndStatusCandViewSelector

Selects candidates with absolute value of the PDG-id and status in a specified set of values, and saves a collection of clones of the selected objects. The input can be any collection matching edm::View<reco::Candidate>, the output is a collection of references to selected objects (edm::RefToBaseVector<reco::Candidate>). An example of configuration is the following:

  leptons = cms.EDProducer("PdgIdAndStatusCandViewSelector",
    src = cms.InputTag("genParticles"), 
    pdgId = cms.vint32( 11, 13 ),
    status = cms.vint32( 1, 3 )
  )

Conversion from HepMC Generator Format

GenParticleProducer

The module GenParticleProducer converts the HepMC GenEvent into a collection of type:

• std::vector<reco::GenParticle>

which is the default generator format in AOD from release 1.6.8. More information about the generator format for AOD can be found in:

• Workbook section on generator particles

The module can be used just including the following file:

include "CMS.PhysicsTools/HepMCCandAlgos/data/genParticles.cfi"

or directly as:

 genParticles = cms.EDProducer("GenParticleProducer",
                  src = cms.InputTag("source")
)

Warning: in release 1_4_X and older, the parameter src must be of type string because the typical input collection value (source) was conflicting with a reserved word.

The following .cfi is also required to access the Particle Data Table:

include "SimGeneral/HepPDTESSource/data/pythiapdt.cfi"

GenParticleCandidateProducer: GenParticleCandidate Conversion from HepMCProduct

The module GenParticleCandidateProducer performs the conversion from HepMCProduct to CandidateCollection containing candidates of GenParticleCandidate type. Its defa default configuration is obtained including the .cfi:

include "CMS.PhysicsTools/HepMCCandAlgos/data/genParticleCandidates.cfi"

The following .cfi is also required to access the Particle Data Table:

include "SimGeneral/HepPDTESSource/data/pythiapdt.cfi"

A number of options is provided with the module, like the possibility to drop intermediate states and shortcut mother-daughter references, drop soft charged or neutral final state particles, drop soft gluons. All those options are disabled by default. The following is an example of a possible configuration enabling some of the features mentioned above:

 genParticleCandidates = cms.EDproducer("GenParticleCandidateProducer",
  src = cms.InputTag("source"),
  stableOnly = cms.bool(false),
  ptMinNeutral = cms.double(0.1),
  ptMinCharged = cms.double(0.5),
  ptMinGluon = cms.double(0.5),
  keepInitialProtons = cms.bool(true),
  excludeUnfragmentedClones = cmc.bool(false),
  excludeList = cms.vstring (
    "string", "cluster",
    "dd_1", "ud_0", "ud_1", "uu_1",
    "sd_0", "sd_1", "su_0", "su_1", "ss_1",
    "cd_0", "cd_1", "cu_0", "cu_1", "cs_0", "cs_1", "cc_1",
    "bd_0", "bd_1", "bu_0", "bu_1", "bs_0", "bs_1", "bc_0", "bc_1", "bb_1",
    "rho0", "rho+", 
    "K*+", "K*0", 
    "K0",
    "Delta0", "Delta+", "Delta++", 
    "Lambda0", 
    "Sigma+", "Sigma*+", "Sigma*0" 
    "Xi0"
  )
)

Warning: in release 1_4_X and older, the parameter src must be of type string because the typical input collection value (source) was conflicting with a reserved word.

FastGenParticleCandidateProducer: Faster GenParticleCandidate Conversion from HepMCProduct

FastGenParticleCandidateProducer is a faster conversion module w.r.t. GenParticleCandidateProducer (typically around 0.7 msec/ev against 1.2 msec/ev), but does not allow any option. It converts all particles found in the HepMC event. The module can be used as the example below:

include "CMS.PhysicsTools/HepMCCandAlgos/data/genParticleCandidatesFast.cfi"

or just as:

genParticleCandidates = cms.EDProducer("GenParticleCandidateProducerFast",
                                src = cms.InputTag("source")
)

Warning: in release 1_4_X and older, the parameter src must be of type string because the typical input collection value (source) was conflicting with a reserved word.

The following .cfi is also required to access the Particle Data Table:

include "SimGeneral/HepPDTESSource/data/pythiapdt.cfi"

GenParticleCandidate2GenParticleProducer

The module GenParticleCandidate2GenParticleProducer converts a collection of generated event in AOD from the type:

• edm::OwnVector<reco::Candidate>, a.k.a.: reco::CandidateCollecton

to one of the type:

• std::vector<reco::GenParticle>, a.k.a.: reco::GenParticleCollection

This can be useful in releases 1.6.8 to convert data produced with releases 1.6.7 or earlier, like CSA07 productions.

It can be used just adding the following .cfi file:

include "CMS.PhysicsTools/HepMCCandAlgos/data/genParticleCandidates2GenParticles.cfi"

Create Candidate Adapters from AOD Objects

You can create candidates from objects of type reco::Track, reco::SuperCluster, reco::CaloTower providing a mass hypothesis. The following modules are provided to create such adapters.

ConcreteChargedCandidateProducer

produces a collection of type reco::CandidateCollection containing objects of type reco::RecoChargedCandidate having a reference to objects of type reco::Track in the specified collections. The mass of the particles have to be specified, since it is not determined by the track fit.

The mass hypothesis has to be specified with one of the following parameters:

• particleType = cms.string( "pi+")
• particleId = cms.int32(211)
• particleMass = cms.double(0.13957)

An example config is shown in the following config. fragment:

  allTracks = cms.EDProducer("ConcreteChargedCandidateProducer",
                    src = cms.InputTag.("ctfWithMaterialTracks"),
                   particleType = cms.string("pi+")
)

The following .cfi is also required to access the Particle Data Table:

from  SimGeneral.HepPDTESSource.pythiapdt_cfi import *

ChargedCandidateProducer is defined in:

• CMS.PhysicsTools/RecoCandAlgos

EcalCandidateProducer

produces a collection of type reco::CandidateCollection containing objects of type reco::RecoEcalCandidate having a reference to objects of type reco::SuperCluster in the specified collections. The mass of the particles have to be specified, since it is not determined by the Ecal measurement.

The mass hypothesis has to be specified with one of the following parameters:

• particleType = cms.string("pi+")
• particleId = cms.int32(211)
• particleMass = cms.double(0.13957)

The following .cfi can be included:

include "CMS.PhysicsTools/RecoCandAlgos/data/allSuperClusters.cfi"

By default the photon mass is assumed. This is equivalent to the following config. fragment:

  allSuperClusters = cms.EDProducer("EcalCandidateProducer",
  src = cms.InputTag("hybridSuperClusterProducer"),
  particleType = cms.string("gamma")
)

The following .cfi is also required to access the Particle Data Table:

include "SimGeneral/HepPDTESSource/data/pythiapdt.cfi"

EcalCandidateProduceris is defined in:

• CMS.PhysicsTools/RecoCandAlgos

CaloTowerCandidateCreator

produces a collection of type reco::CandidateCollection containing objects of type reco::CaloTowerCandidate having a reference to objects of type CaloTower in the specified collections.

A null mass is assumed.

The following .cfi can be included:

include "RecoLocalCalo/CaloTowersCreator/data/calocandidatemaker.cfi"

which is equivalent to the following configuration fragment:

caloTowerCandidates = cms.EDProducer("CaloTowerCandidateCreator",
    src = cms.InputTag("towermaker"),
  # Minimum transverse energy for the tower to be converted to a candidate (GeV)
    minimumEt = cms.double(-1),
  # Minimum energy for the tower to be converted to a candidate (GeV)
    minimumE = cms.double(-1)
)

CaloTowerCandidateCreator is defined in:

• RecoLocalCalo/CaloTowersCreator

Candidate Matching Modules

TrivialDeltaRMatcher

TrivialDeltaRMatcher finds in a collection specified by the parameter matched the object in the collection to any of the objects in a collection specified by the parameter src, and stores an association between the two if the distance in ΔR is smaller than the parameter distMin. The module's output is of type reco::CandMatchMap. An example of usage is the following:

  matchMap = cms.EDproducer("TrivialDeltaRMatcher",
    src =  cms.InputTag("allTracks"),
    matched = cms.InputTag("allMuons"),
    distMin = cms.double(0.1)
  ) 

The corresponding module that works with edm::View<reco::Candidate> as inputs is TrivialDeltaRViewMatcher; its output is of type reco::CandViewMatchMap.

MCTruthDeltaRMatcher

MCTruthDeltaRMatcher is similar to TrivialDeltaRMatcher, but the matching criterion is specialized for matching a collection of GenParticleCandidates. If finds in a collection specified by the parameter matched the object in the collection to any of the objects in a collection specified by the parameter src, and stores an association between the two if the distance in ΔR is smaller than the parameter distMin. Moreover, it only matches objects to GenParticleCandidates in the final state (status = 1), with the same charge. Optionally, it is possible to limit the matched GenParticleCandidates specifying a list of PDG identifiers with the parameter matchPDGId. The module's output is of type reco::CandMatchMap.

An example of usage is the following:

   matchMap = cms.EDProducer("MCTruthDeltaRMatcher",
    src = cms.InputTag("allMuons"),
    matched = cms.InputTag("genParticles"),
    distMin = cms.double(0.1),
    matchPDGId = cms.vint32(13)
  ) 

MCTruthDeltaRMatcherNew

The module MCTruthDeltaRMatcherNew is available from release 1.6.8, and is a generalized version of MCTruthDeltaRMatcher.

If finds in a collection of generator particles of type std::vector<reco::GenParticle>, which is generally the collection with label genParticles, the particles matching the objects in a collection specified by the tag src, and stores an association between the two if the distance in ΔR is smaller than the parameter distMin. It only matches objects to GenParticleCandidates in the final state (status = 1) and with the same charge. Optionally, it is possible to limit the matched GenParticleCandidates specifying a list of PDG identifiers with the parameter matchPDGId. The module's output is of type edm::Association<reco::GenParticleCollection>

The input collection is accessed via edm::View<reco::Candidate>, so it can be of any container of objects (or references to objects) inheriting from reco::Candidate.

An example of usage is the following:

  goodMuonMCMatch = cms.EDProducer("MCTruthDeltaRMatcherNew",
     src = cms.InputTag("goodMuons"),
     matched = cms.InputTag("genParticles"),
     distMin = cms.double(0.15),
     matchPDGId = cms.vint32( 13 ) # muons
)

Other Common Producer Modules

Merging Candidate Collections

Merging more candidate collections can be done with the module CandMerger. An example of its usage is the following, taking collections of type CandidateCollection as input:

    allZ = cms.EDProducer("CandMerger",
         src = cms.VInputTag( "Ztoee", "Ztomumu" )
  )

The module CandViewMerger performs the same job on input collections of any type matching edm::View<reco::Candidate>, saving a collection of type CanddiateCollection as output:

   allZ = ms.EDProducer("CandViewMerger",
       src = cms.VInputTag( "Ztoee", "Ztomumu")
  ) 

Reducing Candidate Collections to Kinematics Content only

A collection of type reco::CandidateCollection may contain Particle Candidates of any type. The module CandReducer copies the kinematics part only of the candidates in order to reduce disk space creating Leaf Candidates. Below is a typical configuration:

  reducedZCandidates = cms.EDProducer("CandReducer",
       src = cms.InpoutTag("ZCandidates")
  ) 

Warning: this module has not been extended yet to support edm::View<reco::Candidate> as input, so it only accepts reco::CandidateCollection as input.

Producing a Collection of Clones

Given a collection containing a concrete candidate subtype (could be for instance a collection of CaloJet, Muon, etc.), it is possible to create a collection of clones stored in a polymorphic container of type reco::CandidateCollection, instead of the original collection. This is done with the generic module CloneProducer<C>, C being the concrete collection type. Specialized modules are instantiated in the package CMS.PhysicsTools/RecoCandAlgos for the most common collection types (reco::ElectronCollection, reco::MuonCollection, reco::CaloJetCollection, ...). Below is a configuration sample:

  muonClones = cms.EDProducer("MuonCloneProducer",
      src = cms.InputTag("globalMuons")
  ) 

The list of the supported specialized modules is the following:

• MuonCloneProducer
• PixelMatchGsfElectronCloneProducer

• include "PhysicsTools/RecoCandAlgos/data/allMuons.cfi"
• include "PhysicsTools/RecoCandAlgos/data/allElectrons .cfi"

Producing a Collection of Shallow Clones

Given a collection containing a concrete candidate subtype (could be for instance a collection of CaloJet, Muon, etc.), it is possible to create a collection of shallow clones, i.e.: clones of the candidates having a reference to the "master" clone in the input collection. This is done with the generic module ShallowCloneProducer<C>, C being the concrete collection type. Specialized modules are instantiated in the package CMS.PhysicsTools/RecoCandAlgos for the most common collection types (reco::ElectronCollection, reco::MuonCollection, reco::CaloJetCollection, ...). Below is a configuration sample:

    muonClones = cms.EDProducer("MuonShallowCloneProducer",
    src = cms.InpuTag("globalMuons")
  )

The list of the supported specialized modules is the following:

• MuonShallowCloneProducer
• CaloJetShallowCloneProducer
• BasicJetShallowCloneProducer
• GenJetShallowCloneProducer
• PixelMatchGsfElectronShallowCloneProducer
• ElectronShallowCloneProducer (Warning: from 130 on electrons are recommended to be taken from the PixelMatchGsfElectronCollection, so this module will be obsolete)
• SiStripElectronShallowCloneProducer (Warning: from 130 on electrons are recommended to be taken from the PixelMatchGsfElectronCollection, so this module will be obsolete)
• PhotonShallowCloneProducer

For muons and pixel-match electrons, the following "standard" .cfi are provided, defining collections of muon and electron candidates in form of shallow clones:

• include "PhysicsTools/RecoCandAlgos/data/allMuonShallowClones.cfi"
• include "PhysicsTools/RecoCandAlgos/data/allElectronsShallowClones.cfi"

Analyzer Modules

*Warning*: the modules described in this section rely on the standard on status codes adopted by Pythia and other generators. Since the status code conventions are not standard, those modules may not work for all generators. For instance, it is known that Hervig could give problematic outputs.

Produce a Set of Standard Kinematic Histograms

The modules CandViewHistoAnalyzer produces a set of standard histograms containing the distributions of the main kinematic variables (p_t, η, φ mass) of a collection of candidates. Some of the histogram boundaries can be changed via configurable parameters. It uses the histogramming service TFileService. The input collection should match edm::View<reco::Candidate>.

  service = TFileService 
    fileName = cms.string("histo.root")
  )

   trackHistos= cms.EDAnalyzer("CandViewHistoAnalyzer",
   src = cms.InputTag("muons"),
   massMin = cms.untracked.double(0),
   massMax = cms.untracked.double(300),
   ptMax = cms.untracked.double(200)
  )

ParticleTreeDrawer Utility

In order to visually look at the generated particle decay tree in a collection of GenParticleCandidates, a module is provided. It can be configured as below, allowing either only the PDG name to be printed, or also extra information, like 4-momentum or status code. Optionally, only particles with one of a given set of status codes will be displayed:

process.load("SimGeneral.HepPDTESSource.pythiapdt_cfi")
process.printTree = cms.EDAnalyzer("ParticleTreeDrawer",
                                   src = cms.InputTag("genParticles"),                                                                 
                                   printP4 = cms.untracked.bool(False),
                                   printPtEtaPhi = cms.untracked.bool(False),
                                   printVertex = cms.untracked.bool(False),
                                   printStatus = cms.untracked.bool(False),
                                   printIndex = cms.untracked.bool(False),
                                   status = cms.untracked.vint32( 3 )
                                   )
process.p = cms.Path( ... * process.printTree)

An example of the decay printout is the following:

p+
+-> g
    +-> g
    |   +-> b
    |   +-> bbar
    |       +-> bbar
    |           +-> string
    |               +-> B*0
    |               |   +-> B0
    |               |   |   +-> D*-
    |               |   |   |   +-> Dbar0
    |               |   |   |   |   +-> K+
    |               |   |   |   |   +-> rho-
    |               |   |   |   |       +-> pi-
    |               |   |   |   |       +-> pi0
    |               |   |   |   |           +-> gamma gamma
    |               |   |   |   +-> pi-
    |               |   |   +-> pi+
    |               |   |   +-> rho-
    |               |   |   |   +-> pi-
    |               |   |   |   +-> pi0
    |               |   |   |       +-> gamma gamma
    |               |   |   +-> pi+
    |               |   |   +-> pi0
    |               |   |       +-> gamma gamma
    |               |   +-> gamma
    |               +-> nbar0
    |               +-> omega
    |               |   +-> pi-
    |               |   +-> pi+
    |               |   +-> pi0
    |               |       +-> gamma gamma
    |               +-> n0
    |               +-> rho0
    |               |   +-> pi- pi+
    |               +-> rho0
    |               |   +-> pi- pi+
    |               +-> omega
    |               |   +-> pi-
    |               |   +-> pi+
    |               |   +-> pi0
    |               |       +-> gamma gamma
    |               +-> Kbar0
    |               |   +-> K_S0
    |               +-> K+
    |               +-> rho-
    |               |   +-> pi-
    |               |   +-> pi0
    |               |       +-> gamma gamma
    |               +-> pi+
    |               +-> rho-
    |               |   +-> pi-
    |               |   +-> pi0
    |               |       +-> gamma gamma
    |               +-> omega
    |               |   +-> pi-
    |               |   +-> pi+
    |               |   +-> pi0
    |               |       +-> gamma gamma
    |               +-> rho+
    |               |   +-> pi+
    |               |   +-> pi0
    |               |       +-> gamma gamma
    |               +-> pi0
    |               |   +-> gamma gamma
    |               +-> K*-
    |               |   +-> Kbar0
    |               |   |   +-> K_L0
    |               |   +-> pi-
    |               +-> K*+
    |                   +-> K0
    |                   |   +-> K_L0
    |                   +-> pi+
    +-> d
        +-> string
            +-> eta
            |   +-> pi0
            |   |   +-> gamma gamma
            |   +-> pi0
            |   |   +-> gamma gamma
            |   +-> pi0
            |       +-> gamma gamma
            +-> K0
            |   +-> K_L0
            +-> K-
            +-> Delta++
            |   +-> p+ pi+
            +-> rho-
                +-> pi-
                +-> pi0
                    +-> gamma gamma
  [ . . . ]

ParticleDecayDrawer Utility

ParticleTreeDrawer may give a complete look of the decay tree, but has two main disadvantages:

• may be too verbose
• a large part of the decay trees is printed twice, since it shows the descending daughters of both incoming protons

The module ParticleDecayDrawer prints in a single line the "hard" interaction (only particles with status = 3) in a collection of GenParticleCandidates. An example of the configuration is reported below, where optionally the 4-momentum can be printed. It is usually :

process.load("SimGeneral.HepPDTESSource.pythiapdt_cfi")
process.printDecay = cms.EDAnalyzer("ParticleDecayDrawer",
    src = cms.InputTag("genParticles"),
    printP4 = cms.untracked.bool(False),
    printPtEtaPhi = cms.untracked.bool(False),
    printVertex = cms.untracked.bool(False)
  )

A typical output could be the following:

   { p+ -> ( g -> g ) } { p+ -> ( g -> g ) } -> h0 -> ( Z0 -> e- e+ ) ( Z0 -> e- e+ )

ParticleListDrawer Utility

The ParticleListDrawer plugin produces the same output you get with the Pythia command PYLIST. The particles are listed in the same order that they are stored in the event. The information printed for each particle is: PdgId, Name, Status, FirstMother, LastMother, FirstDaughter, LastDaughter, number of Mothers and Daughters, pT, Eta, Phi, 4-momentum and mass. Optionally, if you set the configuration parameter printVertex = True, it will also print the (x,y,z) coordinates at which each particle is produced. The index (used to refer also to mother-daughter relationships) is automatically created from the event. The status information is defined here, but is generator dependent.

Where status 3 particles (i.e. particles from the hard process) are defined by the generator, they can have daughters both with status 2 and 3. In Pythia6 this is not the same: mother-daughter relations are correct but special care have to be taken when looking at mother-daughter relation which involve status 2 and 3 particles. In Pythia8, status 3 is never assigned to any particle.

To use the plugin you have only to add the following line (which print only the first event) in your cfg file:

process.load("SimGeneral.HepPDTESSource.pythiapdt_cfi")
process.printTree = cms.EDAnalyzer("ParticleListDrawer",
  maxEventsToPrint = cms.untracked.int32(1),
  printVertex = cms.untracked.bool(False),
  printOnlyHardInteraction = cms.untracked.bool(False), # Print only status=3 particles. This will not work for Pythia8, which does not have any such particles.
  src = cms.InputTag("genParticles")
)

Please, take into account that this plugin produce a long list (order 1 thoused lines for each event), and is called for each event in the job; The standard output could become very big. An example of the output is the following:

[ParticleListDrawer] analysing event run: 200001 event: 1

**********************
* GenEvent           *
**********************

 idx  |    ID -  Name |Stat|  Mo1  Mo2  Da1  Da2 |nMo nDa|    pt       eta     phi   |     px         py         pz        m     |
    0 |  2212 -    p+ |  3 |   -1   -1    2   57 |  0  2 |   0.000  29756.000  0.000 |      0.000      0.000   7000.000    0.000 |
    1 |  2212 -    p+ |  3 |   -1   -1    3   67 |  0  2 |   0.000 -29756.000  0.000 |      0.000      0.000  -7000.000    0.000 |
    2 |     1 -     d |  3 |    0    0    4   56 |  1 17 |   1.292      8.720 -2.569 |     -1.085     -0.700   3957.229    0.513 |
    3 |     1 -     d |  3 |    1    1    5   66 |  1 22 |   1.375     -7.126  0.300 |      1.314      0.406   -854.801   -0.108 |
    4 |    21 -     g |  3 |    2    2    6    7 |  1  2 |   6.910      5.084  2.913 |     -6.731      1.563    557.800   -0.111 |
    5 |    21 -     g |  3 |    3    3    6    7 |  1  2 |  19.261     -2.827  2.702 |    -17.429      8.197   -162.088    0.029 |
    6 |     6 -     t |  3 |    4    5    8    9 |  2  2 | 177.866     -0.068 -2.698 |   -160.680    -76.278    -12.085  175.073 |
    7 |    -6 -  tbar |  3 |    4    5   10   11 |  2  2 | 161.370      1.657  0.562 |    136.520     86.038    407.797  172.326 |
    8 |    24 -    W+ |  3 |    6    6   12   17 |  1  3 | 156.414     -0.421 -2.810 |   -147.876    -50.972    -67.816   77.204 |
    9 |     5 -     b |  3 |    6    6   58   62 |  1  5 |  28.361      1.428 -2.039 |    -12.804    -25.306     55.731    4.800 |
   10 |   -24 -    W- |  3 |    7    7   14   18 |  1  3 |  91.585      2.082  0.290 |     87.774     26.146    361.640   77.947 |
   11 |    -5 -  bbar |  3 |    7    7   23   26 |  1  4 |  77.222      0.567  0.888 |     48.746     59.892     46.157    4.800 |
   12 |    -3 -  sbar |  3 |    8    8   68   73 |  1  6 |  69.275     -0.891 -2.679 |    -61.988    -30.927    -70.267    0.499 |
   13 |     4 -     c |  3 |    8    8   74   83 |  1 10 |  85.684      0.048 -2.913 |    -83.463    -19.383      4.077    1.500 |
   14 |     3 -     s |  3 |   10   10   84   89 |  1  6 |  57.577      1.614 -0.409 |     52.823    -22.908    138.901    0.498 |
   15 |    -4 -  cbar |  3 |   10   10   90   93 |  1  4 |  59.432      1.994  0.975 |     33.363     49.184    214.144    1.498 |
   16 |    22 - gamma |  1 |    3    3   -1   -1 |  1  0 |   0.145     -2.855 -1.336 |      0.034     -0.141     -1.251   -0.000 |
   17 |    24 -    W+ |  2 |    8    8   -1   -1 |  1  0 | 153.906     -0.418 -2.809 |   -145.450    -50.310    -66.190   77.204 |
   18 |   -24 -    W- |  2 |   10   10   -1   -1 |  1  0 |  90.103      2.075  0.296 |     86.186     26.276    353.044   77.947 |
   19 |     4 -     c |  2 |    2    2   94   94 |  1  1 |   0.972      3.493  1.993 |     -0.398      0.886     15.955    1.500 |
   20 |    21 -     g |  2 |    2    2   94   94 |  1  1 |   1.546      1.159 -1.636 |     -0.101     -1.543      2.222    0.001 |
   21 |    21 -     g |  2 |    2    2   -1   -1 |  1  0 |   2.493      0.534 -1.637 |     -0.166     -2.487      1.395    0.001 |
   22 |    21 -     g |  2 |    2    2   -1   -1 |  1  0 |   0.979      0.103 -1.216 |      0.340     -0.918      0.101   -0.000 |
   23 |    21 -     g |  2 |   11   11   -1   -1 |  1  0 |  51.579      0.694  0.978 |     28.811     42.783     38.737    0.018 |
   24 |    21 -     g |  2 |   11   11   -1   -1 |  1  0 |  12.633      0.660  1.014 |      6.674     10.726      8.956   -0.004 |
   25 |    21 -     g |  2 |   11   11   -1   -1 |  1  0 |   2.555      0.445  0.846 |      1.694      1.913      1.174   -0.000 |
   26 |    -5 -  bbar |  2 |   11   11   -1   -1 |  1  0 |  13.852      0.413  0.319 |     13.154      4.341      5.885    4.800 |
   27 |    -4 -  cbar |  2 |    2    2  115  115 |  1  1 |   6.814      1.708  0.628 |      5.515      4.002     18.177    1.500 |
   28 |    21 -     g |  2 |    2    2   -1   -1 |  1  0 |   0.464      0.597  1.070 |      0.222      0.407      0.293   -0.000 |
   29 |    21 -     g |  2 |    2    2  115  115 |  1  1 |   0.762      2.773  2.077 |     -0.369      0.666      6.076   -0.002 |
   30 |    21 -     g |  2 |    2    2   -1   -1 |  1  0 |   1.508      4.642 -2.437 |     -1.149     -0.977     78.264    0.017 |
   31 |    21 -     g |  2 |    2    2   -1   -1 |  1  0 |   4.646      4.043 -1.860 |     -1.323     -4.454    132.323    0.045 |
... 

Review Status

Editor/Reviewer and date	Comments
LucaLista - 04 Dec 2007	page content last editor
JennyWilliams - 19 Mar 2007	typographical editing
AndriusJuodagalvis - 09 Jan 2012	genParticleCandidates -> genParticles

Responsible: LucaLista
Last reviewed by: Reviewer