Pile-Up Events (PileUpProducer or MixingModule)

Complete: 5


The (in-time) pile-up mechanism can potentially be simulated in two ways in FastSimulation.

Internal pile-up mixing, aka PileUpProducer (default)

The first method consists in reading from files minimum bias pre-generated events, concatenating them with the generated signal event, and processing all generated particles (signal and pile-up events) through the FastSimulation to produce SimHits, RecHits, etc... This first method is available for use now. Instructions for use are given below.

Mixing module (optional)

The second method consists in using the MixingModule, which is meant at reading from files minimum bias pre-simulated events, in which object at generation / simulation / digitization / reconstruction level were previously saved, and adding this information to the signal simulated event. This second method is still under development. In the specific Fast Simulation use case, we use minimum bias samples at generator-level: there would be little gain by recycling the simulated information, being quick to redo, and we prefer not to have to reproduce the entire centrally-produced statistics of minimum bias events every time the simulation is modified (GEN information is normally more stable with time; moreover, the GEN part of the Full Simulation samples of minimum bias can be used).

The PileUpProducer is faster than the mixing module (3 ms versus 13 ms in a ttbar sample with "2012 pileup" superimposed), but this has anyway a small impact on the overall timing (for comparison, the generator step for the same sample takes 11 ms with Pythia.)

Moreover, work is ongoing in Fast Simulation to properly treat out-of-time particles, but there are no plans to include out-of-time pileup in the PileUpProducer, while it is automatically taken into account by the mixing module.


The following documentation is valid for CMSSW_4_2_0 and later versions.


The famosPileUp production occurs through the PileUpProducer modulem, and produces, from pre-generated minimum bias event files (see below how to produce these files), a edm::HepMCProduct with

  • As many primary vertices (GenVertex) as pile-up events to be later superimposed to the signal events;
  • For each of these vertices, a list a undecayed primary particles (GenParticle) to be later decayed and propagated through the detector material;

The relevant configuration fragment (cff) is:


This cff configuration file is itself included in FastSimulation/Configuration/python/FamosSequences_cff.py, so it's enought to have the following line in the job configuration:


Steering options

Options of the pile-up simulation are steered from the aforementioned PileUpProducer_cff.py file, the content of which is

import FWCore.ParameterSet.Config as cms

# Copied here so python will auto-translate the names
# Now beta function vertex smearing
from FastSimulation.Event.Early10TeVCollisionVertexGenerator_cfi import *
# 14 TeV pile-up files
#from FastSimulation.PileUpProducer.PileUpSimulator_cfi import *
# 10 TeV pile-up files
from FastSimulation.PileUpProducer.PileUpSimulator10TeV_cfi import *
# 7 TeV pile-up files
#from FastSimulation.PileUpProducer.PileUpSimulator7TeV_cfi import *
# Gaussian or flat or no primary vertex smearing
# include "FastSimulation/Event/data/GaussianVertexGenerator.cfi"
# include "FastSimulation/Event/data/FlatVertexGenerator.cfi"
# include "FastSimulation/Event/data/NoVertexGenerator.cfi"
famosPileUp = cms.EDProducer("PileUpProducer",
    # The conditions for pile-up event generation
    VertexGenerator = cms.PSet(

Vertex smearing

The vertex smearing uses the same primary vertex generator code as the famosSimHits module (see the famosSimHits documentation), and the parameters can be changed following the same instructions. For example, the resolution along the Z direction can be modified with the usual replace statement, e.g.,

process.famosPileUp.VertexGenerator.SigmaZ = 5.3
(NB: beam spot position is used consistently in both pileup and primary interactions, so that changing vertex position, like this - process.famosPileUp.VertexGenerator.X0 = 0.0 will not work!) Of course, any change of the vertex smearing in the famosPileUp module must be set identically in the famosSimHit module for internal consistency.

Center-of-mass energy

There are several minimum bias files already produced, stored in directory /afs/cern.ch/cms/data/CMSSW/FastSimulation/PileUpProducer/data/ (to create new ones, have a look at the cfg files in FastSimulation/PileUpProducer/test), corresponding to several center-of-mass energies.

Have a look at the PileUp options in the aforementioned PileUpProducer_cff.py and change the default if needed.

For most options, the PileUp files are available in the release area and one needs only to comment/uncomment the appropriate lines in the config file above, while 14 TeV files are not available in the release area and have to be copied into FastSimulation/PileUpProducer/data area in two steps:
(1) replacing the content of download.url with the following 10 lines:

(2) copying the files locally
cat download.url | xargs wget

The PileUpSimulator.cfi file (14TeV) contains the following ParameterSet:

PileUpSimulatorBlock = cms.PSet(
    PileUpSimulator = cms.PSet(
        # The file with the last minimum bias events read in the previous run
        # to be put in the local running directory (if desired)
        inputFile = cms.untracked.string('PileUpInputFile.txt'),
        # Special files of minimum bias events (generated with 
        # cmsRun FastSimulation/PileUpProducer/test/producePileUpEvents_cfg.py)
        fileNames = cms.untracked.vstring(
        averageNumber = cms.double(0.0)

The default configuration for all center-of-mass energy options is the simulation without pile-up:

process.famosPileUp.PileUpSimulator.averageNumber = 0.0
See sub-section below to know how to change this setting.

The files CMS.MinBias_*.root just contain the undecayed primary particle momenta (px,py,pz,m,id) for one million minimum bias events, produced, e.g., by Pythia, with the FastSimulation/PileUpProducer/test/producePileUpEvents.cfg configuration file at 14TeV. Primary particles with |eta| smaller than 7.0 and primary protons with energy in excess of 5TeV are kept for each minimum bias event.

The N requested events are read randomly from any of the files for each new signal event, their primary vertices are smeared with the aforementioned internal vertex smearer (the parameters of which must therefore be identical to those of the VtxSmeared module) and the corresponding particles are added to the SimTrack (and SimVertex) containers, and then decayed and propagated as any other particle of the signal event.

The last line of the above parameter list deserves some more comments. Indeed, the minimum bias events are read sequentially from each of the above files. The file choice and the first event to be read in each files are randomly chosen. This technique, as smart as it is, breaks however the random reproducibility of the simulation. For example, if the Fast Simulation experiences a crash at event #43687, that the user would like to reproduce without having to simulate again the 43686 first events, it would not work because the pile-up sequence would not be reproduced. For this reason, a file named PileUpOutputFile.txt is saved in the local directory after each simulated event, with the current pointers in each of the files. Renaming this file to PileUpInputFile.txt would cause the next Fast Simulation job to start from these pointers, hence reproduce the crash of event #43687 directly (provided that the proper sequence of random numbers for all modules is also (i) saved and (ii) restored, which the RandomNumberGeneratorService is not yet able to do...)

Setting the pile-up distribution

The number N of in-time pile-up events to be superimposed to a bunch crossing can be chosen to be Poisson distributed around averageNumber (default option before 4_2_0_pre3), or the user can provide an arbitrary distribution, in the form of a vector, through the configuration file.

Poisson distribution

An example can be found here:

from FastSimulation.Configuration.RandomServiceInitialization_cff import *
from FastSimulation.PileUpProducer.PileUpSimulator7TeV_cfi import *
from FastSimulation.Configuration.FamosSequences_cff import famosPileUp
famosPileUp.PileUpSimulator = PileUpSimulatorBlock.PileUpSimulator
famosPileUp.PileUpSimulator.usePoisson = True
famosPileUp.PileUpSimulator.averageNumber = 25.400000

The parameter averageNumber is the mean of the Poisson distribution.

Arbitrary distribution

An example can be found here:

from FastSimulation.Configuration.RandomServiceInitialization_cff import *
from FastSimulation.PileUpProducer.PileUpSimulator7TeV_cfi import *
from FastSimulation.Configuration.FamosSequences_cff import famosPileUp
famosPileUp.PileUpSimulator = PileUpSimulatorBlock.PileUpSimulator
famosPileUp.PileUpSimulator.usePoisson = False
famosPileUp.PileUpSimulator.probFunctionVariable = (0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34)
famosPileUp.PileUpSimulator.probValue = (0.0109502,0.0263612,0.0456977,0.0641918,0.0781419,0.0861372,0.0886327,0.0869205,0.0823245,0.0758551,0.0681988,0.0598428,0.0511919,0.0426258,0.0344998,0.0271142,0.0206807,0.0153064,0.0109952,0.00766947,0.00519823,0.00342629,0.00219819,0.00137404,0.000837631,0.000498498,0.000289907,0.000164916,9.18504e-05,5.01304e-05,2.68344e-05,1.40992e-05,7.27646e-06,7.26061e-06,0)

The vector probFunctionVariable gives the values of N (number of superimposed pile-up interactions) for which the probability is not 0.
The vector probValue gives the corresponding probabilities. The user has to make sure that this vector is normalized.
Both parameters are ignored if usePoisson is set to True.

The example configuration above is intended to reproduce the actual pileup distribution inferred from the data taken in 2011 (full 2011 dataset).
In general you can create such a distribution by yourself by using the estimatePileup.py script, documented here, to extrapolate the "true" distribution of N from the observed number of primary vertices in whatever bunch of data you want to compare to, and plug this number in the probValue parameter.

Creating new PU input files locally

Until now, centrally-produced PU files have been shipped around with CMSSW releases, and therefore most users didn't have to worry. However, there are many possible use cases for creating them from scratch: if you want more PU statistics, or if you want a center-of-mass energy for which no PU file is centrally available, or if you want to change the Pythia tune of the minimum bias events, etc.

In these cases, just take the example files producePileUpEvents*TeV_cfg.py stored in FastSimulation/PileUpProducer/test and execute them with cmsRun, after having edited the number of desired events or having changed any parameter that you wish, like center of mass energy of Pythia parameters.

Access to the true pile-up distribution, and reweighting

Since 4_2_4_patch1/4_3_0_pre7/4_4_0_pre1, a PileupSummaryInfo object is saved for each event, as in full simulation, allowing the access of the MC truth and the use of the same reweighting tools as in full simulation.

Instructions (not specific of FastSim) can be found at the following locations: PileupInformation, PileupMCReweightingUtilities, PileupReweighting.


To learn how to define a specific pile-up scenario, have a look at this talk.

MixingModule at GEN level

This option has been deployed in CMSSW_6_0_0, but never made default.

Two pileup scenarios with this mixing have been available since then: mix_2012_Startup_inTimeOnly and mix_2012_Summer_inTimeOnly.

A relval sample that used this pileup mixing scheme has been routinely produced in all releases of the 6_0_X, 6_1_X and 6_2_X series.

Minimum bias files

The user can produce very quickly a large statistics with the following command:

cmsDriver.py MinBias_8TeV_cfi  --conditions auto:startup -s GEN --datatier GEN -n 10000  --eventcontent RAWSIM

When running on the GRID, the user can also access the GEN information of the existing minimum bias datasets used for pileup in Full Simulation.

MixingModule at SIM/RECO level

This option is work in progress since the early prereleases of the 6_2_X series.

Minimum bias files

The idea is, eventually, to use the official FullSim minimum bias files as input. So far minimum bias production has been split in two steps, like all FullSim workflows, with the consequence that SIM and RECO informations are not available in the same file. This is going to be requested to change as soon as this pileup mixing option will be ready to be officially deployed.

In the meantime, the user can produce a private sample with the following single-step command (without HLT):

cmsDriver.py MinBias_8TeV_cfi  -s GEN,SIM,DIGI,L1,DIGI2RAW,RAW2DIGI,RECO --pileup=NoPileUp --conditions auto:startup_GRun --eventcontent=RECOSIM --datatier GEN-SIM-RECO -n 10 --no_exec

Review status

Reviewer/Editor and Date (copy from screen) Comments
Andrea Giammanco - 8 June 2011 update
Andrea Giammanco - 24 May 2011 major update
Salavat Abdoulline - 6 April 2010 update
Florian Beaudette - 6 August 2008 major update
PatrickJanot - 31 October 2007 created template page and write documentation

Responsible: AndreaPerrotta

Last reviewed by: Reviewer

Edit | Attach | Watch | Print version | History: r20 < r19 < r18 < r17 < r16 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r20 - 2014-03-25 - AndreaGiammanco

    • 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