Heavy Ion Generator Tools

Complete: 5

Goal of this page

The aim of this page is to document the tools used in generating heavy ion events which are not specific to a particular Monte Carlo generator—where the code lives, how to run it, and details of the implementation.



The HiCentralityBiasFilter ensures that the impact parameters of the generated events obey a user-specified distribution. The function and parameters of a Root TF1 are passed via a configuration file.

Code and tags

The code for the HiCentralityBiasFilter plugin is in GeneratorInterface/HiGenCommon/plugins/HiCentralityBiasFilter.cc. This has been included in CMSSW since release CMSSW_3_4_0_pre4. The configuration file mentioned below is not yet included in CMSSW, so one must check out the HEAD version of the package from CVS:
cd $CMSSW_BASE/src
cvs co GeneratorInterface/HiGenCommon/python
scramv1 b

Configuration files

A configuration file for producing a gaussian impact parameter distribution can be found in GeneratorInterface/HiGenCommon/python/HiBiasedCentrality_cfi.py.

How to run

Since HiCentralityBiasFilter is an EDFilter, you simply need to include the above cfi file in your configuration file (cfg.py) and add the corresponding module to the path:
process.centralityFilter= cms.Path(process.hiBiasedCentrality)
process.schedule = cms.Schedule(process.centralityFilter)

Parameter settings

Parameter type Parameter name Description
edm::InputTag src The label of the edm::HepMCProduct produced by the Monte Carlo generator. If not specified this defaults to the standard label generator
string function The definition of the function for the Root TF1, which defines the impact parameter distribution
vector<double> parameters The parameters for the function



When generating heavy-ion Monte Carlo processes with small cross-sections, it is often more CPU-efficient to generate the hard process as a separate pp event, and embed it into the underlying heavy-ion collision. For example one might generate a J/Ψ→μμ event with with PYQUEN and embed into a Lead-Lead event generated with HYDJET. In order for the two separately generated events to have the same primary vertex position, impact parameter etc, it is convenient to read in an already-generated background event (underlying event) then generate the signal (hard process) on-the-fly (i.e. within the same job) using the same parameters. This has been possible as part of the standard MixingModule since CMSSW_3_3_0.

However it is also desirable to be able to filter the signal events that are generated, e.g. to restrict the pT or η range of the particles of interest. Using the exisitng EDFilters meant that if the on-the-fly event didn't produce the right sort of event, the underlying event with which it was to be merged was also thrown away. GenEvtSelectors were developed so that the on-the-fly generation could run until it produces an event which satisfies the conditions the user wants.

Code and tags

The code for GenEvtSelectors lives in the package GeneratorInterface/HiGenCommon. This has been included in CMSSW since release CMSSW_3_4_0_pre4.

The corresponding generator interface must also have GenEvtSelectors implemented. Currently GenEvtSelectors only work with PYQUEN. This part of the code can be found in GeneratorInterface/PyquenInterface/src/PyquenHadronizer.cc.

The configuration files mentioned below are not yet included in CMSSW, so one must check out the HEAD version of the corresponding packages from CVS:

cd $CMSSW_BASE/src
cvs co GeneratorInterface/HiGenCommon/python
cvs co GeneratorInterface/PyquenInterface/python
scramv1 b

Configuration files

The file GeneratorInterface/HiGenCommon/python/ecalTrigSettings_cff.py contains settings for using GenEvtSelectors to select events which would fire an ecal-based trigger. The file GeneratorInterface/PyquenInterface/python/pyquenEcalTrig_cfi.py shows how this is then used to generate PYQUEN events.

Types of GenEvtSelectors

There are different types of GenEvtSelectors, which inherit from the base class, BaseHiGenEvtSelector. The currently implemented ones are:
  • EcalGenEvtSelector - A vector of partons and a vector of particles, along with their status, pt and η are specified. If at least one of the partons (with specified status, pt and η) and one of the particles (with specified status, pt and η) are found in the event, the GenEvtSelector returns true.
    • Example scenario: Neutral particles produced in quark/gluon jets where the parton has a pT >100 GeV
  • MultiCandGenEvtSelector - A particle type, status, pt and η are specified along with a minimum number. If the required number of this type of particle is found in the event, the GenEvtSelector returns true.
    • Example scenario: Dimuons within detector acceptance

How to run

Since GenEvtSelectors are integrated into the generator interface (for the supported generators), using them simply involves adding extra parameters (described in the section below) to the generator module in your configuration file. It is often convenient to combine these extra parameters into a PSet (parameter set), which can then be added as a single line.

For example the PSet ecalTrigPt100 is defined in GeneratorInterface/HiGenCommon/python/ecalTrigSettings_cff.py:

ecalTrigPt100 = cms.PSet(filterType = cms.untracked.string("EcalGenEvtSelector"),
                         etaMax = cms.double(3),
                         partons = cms.vint32(1,2,3,4,5,6,21,22),
                         partonStatus = cms.vint32(2,2,2,2,2,2,2,1),
                         partonPt = cms.vdouble(38.5,38.5,38.5,38.5,38.5,38.5,38.5,38.5),
This PSet is then included in the PYQUEN generator module in GeneratorInterface/PyquenInterface/python/pyquenEcalTrig_cfi.py:

from GeneratorInterface.HiGenCommon.ecalTrigSettings_cff import *

generator = cms.EDFilter("PyquenGeneratorFilter",
                         doQuench = cms.bool(True),
                         doIsospin = cms.bool(True),

Parameter settings

For EcalGenEvtSelector:
Parameter type Parameter name Description
vector<int> partons PDG ID codes for partons (positive values only; absolute value of candidate parton's id is taken)
vector<int> partonStatus Status code (1=stable, 2=decayed etc)
vector<double> partonPt Minimum pt of parton
vector<int> particles PDG ID codes for particles (positive values only; absolute value of candidate particle's id is taken)
vector<int> particleStatus Status code (1=stable, 2=decayed etc)
vector<double> particlePt Minimum pt of particle
double etaMax |η| < etaMax for all partons and particles

For MultiCandGenEvtSelector:

Parameter type Parameter name Description
double ptMin Minimum pt of particle
double etaMax |η| < etaMax for all particles
int pdg PDG ID codes for particles (positive values only; absolute value of candidate particle's id is taken)
int status Status code (1=stable, 2=decayed etc)
int minimumCandidates Minimum number of particles in event which satisfy the above conditions

Implementation details

This section describes how GenEvtSelectors are implemented for PYQUEN, currently the only supported generator.

  • The type of selector and its parameters are passed to the PyquenGeneratorFilter module, e.g. as in pyquenEcalTrig_cfi.py:
generator = cms.EDFilter("PyquenGeneratorFilter",
                     filterType = cms.untracked.string("EcalGenEvtSelector"),
                     etaMax = cms.double(3),

  • A specific GenEvtSelector inherits from BaseHiGenEvtSelector (see e.g. EcalGenEvtSelector.h and EcalGenEvtSelector.cc), and implements the details of the selection in the function filter. The BaseHiGenEvtSelector has a filter function which always returns true, so that no selection is performed if filterType = 'None' as mentioned above.

  • In PyquenHadronizer::generatePartonsAndHadronize(), generation of an event takes place within a while loop. Once an event has been generated the HepMC::GenEvent is passed to the GenEvtSelector. If it returns true the program exits the loop, otherwise another event is generated until one is found which satisfies the GenEvtSelector.


Review status

Reviewer/Editor and Date Comments
PhilipAllfrey - 21 Dec 2009 Added details for GenEvtSelectors
PhilipAllfrey - 4 Dec 2009 created page as part of documentation review

Responsible: YetkinYilmaz

Edit | Attach | Watch | Print version | History: r3 < r2 < r1 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r3 - 2009-12-22 - PhilipAllfrey
    • 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-2021 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback