Vertex Smearing Software in CMSSW


Complete: 3

Goal of the page

Goal of this page is to describe the software that is available within CMSSW for modeling the Interaction Region (IR) spread.
A user will learn:
  • What shapes of the IR and/or beam profile can be simulated
  • What module to pick up to simulate one or another IR shape
  • What are the algorithms one or another module is based on
  • How to configure one or another Vertex Smearing module


  • To be named...


By default the nominal vertex of an event is (0,0,0). However, the Interaction Region (IR) is not point-like, but instead an beam-beam collision happens within a certain volume that extends significantly along the Z-axis. To reflect this fact we have implemented specialized software that allows to model the size of the IR and several hypothesis of the collision probability within the IR volume.
The software consist of several modules, each to represent one or another hypothesis, and is located in the IOMC/EventVertexGenerator package.

The IR modeling is done as a separate step in the event processing chain.

One can apply vertex smearing in the same job that does event generation, or one can apply it when reading previously generated events from an external file.
However, it may be applied ONLY ONCE to a given generated sample (i.e. the module will internally block up any attempt to re-apply).
Each module comes with pre-defined and validated standard configuration. If you intend to compose a production-type application, we advised you NOT to modify the parameters. But for those user who need to compose a custom applications for special studies, we will provide instructions and tips.

Input and Output

Each of the Vertex Smearing modules takes edm::HepMCProduct on input. As a result of the Vertex Smearing module execution, the edm::HepMCProduct will be modified, i.e. primary generated generated vertex will be shifted from its nominal (0,0,0) position, and all the subsequent generated vertices will be consistently shifted as well. This is only software in CMSSW where a major exception is allowed: modification of an existing edm::Event branch.

For more details on the edm::HepMCProduct please visit SWGuideDataFormatGeneratorInterface.

Algorithms and Modules

The interaction region spread (Vertex Smearing) can be simulated as flat, Gaussian, based on beta-function, or for test beam applications there is a module that simulates beam profile.

The recommended algorithm is the beta-function smearing (BetafuncEvtVtxGenerator). This algorithm is based in the beta function and produces a more realistic beam spot than the other algorithms. In the case of a beam configuration with crossing angles, this smearing also take into account the transverse boost induced by the crossing angles.

Standard CMS approved configurations for all the modules, implemented as "building blocks", are collectively placed in a single configuration include IOMC/EventVertexGenerators/python/

Schematic configuration will look like:

VtxSmeared = cms.EDFilter("XXXEvtVtxGenerator",
where XXX is name of the desired distribution.

Common configuration parameter (implement as a block) for all modules is:

VtxSmearedCommon = cms.PSet(
    src = cms.InputTag("generator")
This means that each module will take on input the edm::HepMCProduct (see above) previously produced by the component labeled "generator".

Other parameters for specific modules are described below.

BetafuncEvtVtxGenerator (Default)

This algorithm simulates a realistic luminous region. The transverse beam width is modeled by the beta function as a function of the Z position. In the case of the LHC, the beam optics is such as the beam width is almost constant near the IP, the hour-glass effect is very small for the LHC compared with the Tevatron for example. The beam width depends on the emittance and beta-star beam parameters. These parameters change depending of the beam scenarios and beam energy. We have taken the estimated LHC beam parameters for 450 GeV, 3.5 TeV, 5 TeV, and 7 TeV beam collisions and defined in the configuration file IOMC/EventVertexGenerators/python/ The beam width at Z=0 is equal to the square root of the emittance times beta-star. For example, the 10TeV collision scenario has the following values:

# 10 TeV collisions, transverse beam size = 46 microns
Early10TeVCollisionVtxSmearingParameters = cms.PSet(
    Phi = cms.double(0.0),
    BetaStar = cms.double(300.0),
    Emittance = cms.double(7.03e-08),
    Alpha = cms.double(0.0),
    SigmaZ = cms.double(3.8),
    TimeOffset = cms.double(0.0),
    Y0 = cms.double(0.0),
    X0 = cms.double(0.0322),
    Z0 = cms.double(0.0)

In the case of collisions with crossing angles, this algorithm in addition to smear the vertices of the generated particles also smear the momenta of the particles by applying a Lorentz boost given by the crossing angle in the transverse plane. The total boost in the event is of about a few GeV.

The time of the generated particles is also smeared by default using a simple gaussian distribution with sigma equal to the "SigmaZ" which is the RMS of the luminous region or also equal to sqrt(2) of the bunch length (for symmetric beams). Notice that the units of the generated particles are given by HepMC so the time component is given in mm/c. A time offset has also been included in this algorithm however this option has not been tested extensively and is optional. This offset moves the mean of the gaussian distribution for time.


Example configuration parameters for this module are:

FlatVtxSmearingParameters = cms.PSet(
    MaxZ = cms.double(5.3),
    MaxX = cms.double(0.0015),
    MaxY = cms.double(0.0015),
    MinX = cms.double(-0.0015),
    MinY = cms.double(-0.0015),
    MinZ = cms.double(-5.3),
    TimeOffset = cms.double(0.0)

The IR is assumed to be a rectangular volume that extends within MinX to MaxX, MinY to MaxY, and MinZ to MaxZ. Collision may randomly happen anywhere within this volume, with equal probability.


Example configuration parameters for this module are:

GaussVtxSmearingParameters = cms.PSet(
    MeanX = cms.double(0.0),
    MeanY = cms.double(0.0),
    MeanZ = cms.double(0.0),
    SigmaY = cms.double(0.0015),
    SigmaX = cms.double(0.0015),
    SigmaZ = cms.double(5.3),
    TimeOffset = cms.double(0.0)

The IR region is assumed to be centered on the (MeanX,MeanY,MeanZ). A collision happens at a point (X,Y,Z) that may deviate from the nominal center of the IR. The deviations are calculated separately for X, Y, and Z, according to the Gaussian distribution with SigmaX, SigmaY, and SigmaZ respectively.


To be added shortly.

Review status

Reviewer/Editor and Date (copy from screen) Comments
JuliaYarba - 27 Aug 2009 collect/move basic info from other docs, like WB/Sim and SWGuideSim
KatiLassilaPerini - 13 Feb 2008 created template page

Responsible: JuliaYarba (ad interim)
Last reviewed by: Most recent reviewer

Edit | Attach | Watch | Print version | History: r6 < r5 < r4 < r3 < r2 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r6 - 2009-09-09 - FranciscoYumiceva
    • 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-2023 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