Chapter 6: Event Generation and Simulation
6.1 Thirty-Minute Introduction to Generation and Simulation
Complete:
Detailed Review status
Goals of this page
This page provides an entry point to the physics event generation and detector simulation in CMSSW.
It should serve as a jump-start for people who will need to prepare configuration application for central production of the Monte Carlo samples, as representatives of their Physics groups.
Another group of people we aim onto are those who will need to produce their Monte Carlo samples on a private basis, i.e. outside of central production.
Contents
Introduction
Physics event generation and detector simulation are the earliest steps in the event processing chain that leads to producing a Monte Carlo samples suitable for physics analysis.
An ample variety of the Monte Carlo samples for various types of physics analysis are
produced and distributed centrally. They can be found via
the DAS page
(
https://cmsweb.cern.ch/das/
).
However, if you can not find the event sample you would like to use (or compatible with the CMSSW version that you are using), you may want to produce your own Monte Carlo samples ("private samples").
In this section we will present several How-To's on the most often used features and utilities, will show several examples, and will provide links to more detailed documents.
In general, a user should assume
CMSSW_10_2_X and higher release cycle. Where necessary, we'll provide specific tips, especially for most recent releases.
At the same time, we would like to mention that newer developments have happened in more recently released, and imposed modifications of certain details. We will provide specific comments and suggestions when applicable.
Generation of high-energy-physics events, i.e. sets of outgoing particles produced in the interactions between two incoming particles,
must be the first step in the Monte Carlo event processing chain.
In CMSSW we have interfaces to many physics event generators that are of interest to the collaboration. In this writeup, we will present an example that will use Pythia8 event generator, as it has been most heavily used in production so far.
The following step(s) can be either:
- Simulation and Digitization, whereby the newly generated particles are run through detailed, Geant4-based simulation of the CMS detector, and detector electronics response is modelled. After this step, you need more (reconstruction, AOD and possibly MINIAOD) in order to get samples actually comparable with data.
- Fast Simulation, which uses a parametric approach to simulate and reconstruct events with the CMS detector; the concept of FastSim is to reduce the CPU time overhead, while still benefiting from an accurate simulation of the detector effects, in view of doing physics analysis, develop and tune reconstruction algorithms, design detector upgrades, etc. This step produces files already comparable with data.
CMSSW offers a large collection of software tools, utilities, scripts, and pre-fabricated configuration application fragments. Thus, in most cases, a user will only need to know how to find the right components, to compose them together, and to execute - this will be the focus of this section.
The tips we offer here have been tested on the LXPLUS cluster at CERN. We have also tested on remote sites as well and will provide remarks and additional guidance as needed.
Running generation and simulation in CMSSW
Running the event generation and simulation in CMSSW means running a
framework job with the
usual syntax:
cmsRun <My configuration file>
Here
cmsRun
is the principal CMSSW executable that gets configured to do one or another type of job by the input
<My configuration file>, where a user specifies desired CMSSW software components and the order of their execution.
In order to "find"
cmsRun
and to be able to run it, you will need to have it in your PATH, which will be done by setting up your run time environment. A quick sketch of doing so is given below:
cmsrel CMSSW_X_Y_Z
cd CMSSW_X_Y_Z/src
cmsenv
(of course, in this sketch X_Y_Z is a "generic" form that means one or another CMSSW release).
When it comes to the configuration input file, one needs to remember that a step in the event processing chain may create event data (
edm::Event
) that will serve as an input to the subsequent steps, thus it is important to properly order the sequence of steps for execution. One also need to know that some software components may need other "helper" software, thus those services and modules also need to be present in the configuration file.
However, most users will not need to worry about such details as in CMSSW there are utilities which will ensure that all service software is included, and the sequence of steps in the event processing chain is correct.
We would like to offer an
example configuration card (rename to .py only), which is similar to those used in central production and can be directly executed with
cmsRun
in CMSSW_5_3_26. It configures
cmsRun
to generate an RS graviton G(1
TeV) decaying to ZZ. Then it processes the Higgs events through Geant4-based detector simulation, digitization, reconstruction etc. At the end of the job, it writes out an output file. You can copy these configuration files into your work area and execute
cmsRun
on it.
Below we will provide tips on how you can compose your own configuration application, for both Full or Fast Simulation.
Composing Full Simulation Configuration Application
Later in this document, we will offer a quick walk-through the
example configuration card,
and will point your attention to details that are specific to event generation and simulation.
Here we would like to stress that this configuration application has been composed via
standard CMSSW utility called
cmsDriver.py
. This utility will appear in your PATH once you setup your run time CMSSW environment (just like
cmsRun
). More detailed information on
cmsDriver.py
can be found in the
cmsDriver documentation.
In this document we will offer
quick tips on the
cmsDriver.py
usage. You can re-create this configuration application by executing the following commands:
To use fragments from the repository one can browse the repository on the web and copy or download the fragment with curl, e.g.
curl -s https://github.com/cms-sw/genproductions/blob/master/python/ThirteenTeV/RSGraviton/RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_cfi.py --retry 2 --create-dirs -o Configuration/GenProduction/python/ThirteenTeV/RSGraviton/RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_cfi.py
scram b
Otherwise, you can create a new empty directory and clone the full repository
mkdir -p Configuration/GenProduction/
git clone git@github.com:cms-sw/genproductions.git Configuration/GenProduction/
cd Configuration/GenProduction/python/ThirteenTeV/RSGraviton/
scram b
CMSSW_7_0_X
cmsDriver.py Configuration/GenProduction/python/ThirteenTeV/RSGraviton/RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_cfi.py --fileout file:RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_FULLSIM.root --mc --eventcontent AODSIM --datatier GEN-SIM --conditions auto:mc --beamspot Realistic8TeVCollision --step GEN,SIM,DIGI,L1,DIGI2RAW,HLT:GRun,RAW2DIGI,L1Reco,RECO --python_filename RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_FULLSIM_cfg.py --no_exec --customise Configuration/DataProcessing/Utils.addMonitoring -n 64
CMSSW_9_2_X
cmsDriver.py Configuration/GenProduction/python/ThirteenTeV/RSGraviton/RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_cfi.py --fileout file:RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_GEN-SIM.root -s GEN,SIM --mc --datatier GEN-SIM --beamspot Realistic25ns13TeVEarly2017Collision --conditions auto:phase1_2017_realistic --eventcontent RAWSIM --era Run2_2017 --python_filename RSGravitonToZZ_kMpl01_M_1000_pythia8_GEN-SIM_Run2_2017_cfg.py --no_exec -n 50
CMSSW_9_3_X
cmsDriver.py Configuration/GenProduction/python/ThirteenTeV/RSGraviton/RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_cfi.py --fileout file:RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_GEN-SIM.root -s GEN,SIM --mc --datatier GEN-SIM --beamspot Realistic25ns13TeVEarly2017Collision --conditions auto:phase1_2017_realistic --eventcontent RAWSIM --era Run2_2017 --python_filename RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_GEN-SIM_cfg.py --no_exec -n 50
step1:DIGI2RAW-HLT (DR)
cmsDriver.py -s DIGI,L1,DIGI2RAW,HLT --datatier GEN-SIM-RAW --conditions auto:phase1_2017_realistic --eventcontent RAWSIM --era Run2_2017 --filein file:RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_GEN-SIM.root --fileout file:RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_GEN-SIM-RAW.root --python_filename RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_FULLSIM_GEN_SIM_RAW_cfg.py -n -1 --no_exec
step2:RECO
cmsDriver.py -s RAW2DIGI,L1Reco,RECO --datatier RECO --conditions auto:phase1_2017_realistic --eventcontent AODSIM --era Run2_2017 --filein file:RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_GEN-SIM-RAW.root --fileout file:RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_GEN-SIM-RAW-RECO.root --python_filename RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_FULLSIM_GEN_SIM_RAW_RECO_cfg.py -n -1 --no_exec
For Run2
step0 : GEN-SIM
setenv SCRAM_ARCH slc7_amd64_gcc700
source /cvmfs/cms.cern.ch/cmsset_default.csh
scram p CMSSW CMSSW_10_2_15_patch1
cd CMSSW_10_2_15_patch1/src
eval `scram runtime -csh`
curl -s --insecure https://cms-pdmv.cern.ch/mcm/public/restapi/requests/get_fragment/BPH-RunIIFall18GS-00170 --retry 2 --create-dirs -o Configuration/GenProduction/python/BPH-RunIIFall18GS-00170-fragment.py
[ -s Configuration/GenProduction/python/BPH-RunIIFall18GS-00170-fragment.py ]
scram b
cmsDriver.py Configuration/GenProduction/python/BPH-RunIIFall18GS-00170-fragment.py --fileout file:BPH-RunIIFall18GS.root --mc --eventcontent RAWSIM --datatier GEN-SIM --conditions 102X_upgrade2018_realistic_v11 --beamspot Realistic25ns13TeVEarly2018Collision --step GEN,SIM --geometry DB:Extended --era Run2_2018 --python_filename BPH-RunIIFall18GS_cfg.py --no_exec --customise Configuration/DataProcessing/Utils.addMonitoring --customise_commands process.source.numberEventsInLuminosityBlock="cms.untracked.uint32(1408450)" -n 10000
cmsRun BPH-RunIIFall18GS_cfg.py
step1:DIGI2RAW-HLT (DR)
voms-proxy-init
cmsDriver.py step1 --filein file:BPH-RunIIFall18GS.root --fileout file:BPH-RunIIAutumn18DR_step1.root --pileup_input "dbs:/MinBias_TuneCP5_13TeV-pythia8/RunIIFall18GS-102X_upgrade2018_realistic_v9-v1/GEN-SIM" --mc --eventcontent FEVTDEBUGHLT --pileup "AVE_25_BX_25ns,{'N': 20}" --datatier GEN-SIM-DIGI-RAW --conditions 102X_upgrade2018_realistic_v15 --step DIGI,L1,DIGI2RAW,HLT:@relval2018 --nThreads 8 --geometry DB:Extended --era Run2_2018 --python_filename BPH-RunIIAutumn18DR_cfg.py --no_exec --customise Configuration/DataProcessing/Utils.addMonitoring -n 100
cmsRun BPH-RunIIAutumn18DR_cfg.py
step2: RECO
cmsDriver.py step2 --filein file:BPH-RunIIAutumn18DR_step1.root --fileout file:BPH-RunIIAutumn18DR_step2.root --mc --eventcontent AODSIM --runUnscheduled --datatier AODSIM --conditions 102X_upgrade2018_realistic_v15 --step RAW2DIGI,L1Reco,RECO,RECOSIM,EI --nThreads 8 --geometry DB:Extended --era Run2_2018 --python_filename BPH-RunIIAutumn18DR_2_cfg.py --no_exec --customise Configuration/DataProcessing/Utils.addMonitoring -n 100
cmsRun -e -j BPH-RunIIAutumn18DR_2_rt.xml BPH-RunIIAutumn18DR_2_cfg.py
Step3: MiniAODSIM
cmsDriver.py step1 --filein file:BPH-RunIIAutumn18DR_step2.root --fileout file:BPH-RunIIAutumn18MiniAOD.root --mc --eventcontent MINIAODSIM --runUnscheduled --datatier MINIAODSIM --conditions 102X_upgrade2018_realistic_v15 --step PAT --nThreads 8 --geometry DB:Extended --era Run2_2018 --python_filename BPH-RunIIAutumn18MiniAOD_cfg.py --no_exec --customise Configuration/DataProcessing/Utils.addMonitoring -n 100
curl (like wget) just fetches an input file from a web location (in this case we used
this fragment
) and places it in a "fake" CMS package creating a directory structure like those of the CMS packages. NOTE THAT Configuration/GenProduction IS NOT A PART OF CMSSW.
Now let us briefly review the input arguments to
cmsDriver.py
utility.
- The first - and mandatory - input argument to
cmsDriver.py
is configuration fragment that determines what physics event generator you wish to use and what topology you intend to generate. In this example we use a pre-fabricated fragment
which is originally located in the genproductions area. For the majority of applications for producing Monte Carlo samples the only difference will be this generator-level configuration fragment, while other conditions and steps will be standard. This is a great benefit of using cmsDriver.py
for composing applications for Monte Carlo production, as it will ensure that most current setups and conditions will be employed.
- The
-s
field contains the sequence of event processing steps. In the above example the chain starts with the GEN(eration), including necessary filters to select events of users specific interest where applicable, following with SIM(ulation), DIGI(tization), L1 trigger emulation, conversion of the simulated DIGI2RAW (raw data format), and H(igh)L(evel)T(triggers) simulation and RECO(nstruction). The last steps are not a part of the event generation and simulation domain, but this is how the event processing chain in composed in production of the Monte Carlo samples. The last steps are also performed on real data. If you wish to terminate your chain at the generation level, you may use "-s GEN". However, if you intend to run "private production" we suggest that you compose the chain up to the last step.
- Details of the
--conditions
field can be found in the Software Guide on the FrontierConditions. Notice that the choice --conditions auto:mc
chooses the best conditions for a given release.
- To select the content of the
--datatier
field plese view the documentation on the allowed Data Tiers.
- Content of the
--eventcontent
field is described in great details in the SWGuideDataFormatTable.
- In the
-n
field you will specify how many events you want to generate, simulate, etc.
- The
--no_exec
argument tells cmsDriver.py
to write out the configuration file. If you do not specify this argument, cmsDriver.py
will proceed to executing cmsRun
.
- The
--python_filename
and --fileout
define the output configuration file and the output root file after cmsRun
, respectively
- The customization part is not important for private production and may be skipped
Composing Fast Simulation Configuration Application
From the Generator point of view, Fast Simulation is identical to the Full Simulation both in usage of single-particle gun and one of the multi-purpose event generators as described above.
However, when using
cmsDriver.py
command for Fast Simulation there are some differences compared to the Full Simulation case described above:
- First of all, Fast Simulation job runs in one go both Simulation and Reconstruction
- Second, the syntax of
cmsDriver.py
command is somewhat different.
If we consider a particular generator fragment, the configuration is:
cmsDriver.py Configuration/GenProduction/python/ThirteenTeV/RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_cfi.py --fileout file:RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_FASTSIM.root --mc --eventcontent AODSIM --datatier GEN-SIM --conditions auto:mc --beamspot Realistic8TeVCollision --step GEN,FASTSIM,HLT:GRun --python_filename RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_FASTSIM_cfg.py --no_exec --customise Configuration/DataProcessing/Utils.addMonitoring -n 64
You can see the change in the "-s" and "datatier" options. For the rest all the above applies.
For Run2-CMSSW_8_0_X
cmsDriver.py Configuration/GenProduction/python/ThirteenTeV/RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_cfi.py --conditions auto:run2_mc --fast -n 10 --era Run2_2016 --eventcontent AODSIM --relval 100000,1000 -s GEN,SIM,RECOBEFMIX,DIGI:pdigi_valid,L1,DIGI2RAW,L1Reco,RECO,EI,HLT:@relval2016, --datatier AODSIM --beamspot Realistic50ns13TeVCollision
For Run2-CMSSW_10_2_X
cmsDriver.py Configuration/GenProduction/python/BPH-RunIIFall18GS-00170-fragment.py --fileout file:BsToPhiMuMuRunIIAutumn18FSPremix.root --mc --eventcontent FASTPU --fast --datatier GEN-SIM-RECO --conditions 102X_mc2017_realistic_v5 --beamspot Realistic25ns13TeVEarly2018Collision --step GEN,SIM,RECOBEFMIX --datamix PreMix --era Run2_2018 --python_filename:BsToPhiMuMuRunIIAutumn18FSPremix_cfg.py --no_exec --customise Configuration/DataProcessing/Utils.addMonitoring -n 10000
cmsRun BsToPhiMuMuRunIIAutumn18FSPremix_cfg.py
Walk-through Example Full Simulation Configuration File
If you wish to learn details about
CMSSW configuration language in general, please visit the
corresponding section in this WorkBook.
In this document, we will provide a partial walk-through the
example configuration,
concentrating on details that are specific to event generation and detector simulation.
First of all, please notice this line:
process.source = cms.Source("EmptySource")
You will need to use EmptySource if you wish to generate events "from scratch", using one of the multi-purpose event generators. There are several types of "Sources" in CMSSW, that are useful for other types of event generation, or for processing pre-generated events through further steps.
Next block in the configuration file that will be of interest to you is the one that starts with
process.generator = cms.EDFilter("Pythia8GeneratorFilter",
followed by a long string of configuration commands. This is the software module of CMSSW that interfaces Pythia8 multi-purpose event generator. It contains:
- blocks of commands which are the default for all MC samples (pythia8CommonSettings and pythia8CUEP8M1Settings): the former defines common parameters for running Pythia8, the latter defines the underlying event tune.
- a block of command (process parameters) which are specific to this process. In the case of the graviton, the five strings in order: 1) enables the production of G, 2) defines the kappa parameter in RS theory, 3) sets the G mass to 1 TeV and 4) 5) switches off all G decays except those containing a Z (i.e. ZZ only).
Please note that in the event processing chain this module is labeled as "generator". Please note that "generator" is a single label to apply to the event generation step, no matter what event generator you choose to employ. It is by this particular label that subsequent steps in the event processing chain will find generator-level particles for further processing.
Towards the beginning of the configuration file you will see other topics of interest to you:
process.load('Configuration.StandardSequences.SimIdeal_cff')
process.load('Configuration.StandardSequences.Digi_cff')
The first one is a "master" configuration fragment for Geant4-based detector simulation, and the second one brings together several software components to model electronics response in all parts of the CMS detector. The step that simulates passage of particles through CMS detector is labeled "psim". The sequence of steps to perform digitization is collectively labeled "pdigi".
Towards the end of the configuration file you will notice how these labels are used to include these software in the processing chain:
process.simulation_step = cms.Path(process.psim)
process.digitisation_step = cms.Path(process.pdigi)
and ordered for execution:
process.schedule = cms.Schedule(...,process.simulation_step,process.digitisation_step,...)
Please be advised that there are other software components needed to properly run CMS detector simulation and digitization, that are also included in the example configuration file. We will cover more details in the
WorkBookSimDigi and its daughter materials.
Please note that these are pre-fabricated "building blocks" that are available as part of the
Configuration/StandardSequences
package of CMSSW. In its turn each configuration fragment uses other
standard, pre-fabricated configuration includes and fragments, in order to configure CMSSW simulation and digitization software with the
CMS-approved setting. If you wish to learn more details about the underlying software components or how to reconfigure one or another module to your specific needs, please visit
WorkBookSimDigi and its daughter materials.
Walk-through Example Fast Simulation Configuration File
Generator-wise the content of the Fast Simulation configuration file is very much similar to what is described in a previous chapter for Full Simulation configuration.
In this case the only module performing Simulation and Digitization together is:
process.load('FastSimulation.Configuration.FamosSequences_cff')
There are also several explicit replacements of the default parameters, which set number of in-time pileup events, misalignment options, switch on/off particular subdetector simulation etc.
process.famosPileup.PileUpSimulator.averageNumber = 0
process.famosSimHits.SimulateCalorimetry = True
...
And at the end of the configuration file, a sequence of modules execution is defined with the job schedule commands (
process.schedule...
), so that generation and simulation parts are executed first, then follows a trigger part, and finally reconstruction and output ones.
Review status
ElizaMelo - 2019-09-30 |
Instructions for Run2 (CMSSW102X) added. |
ElizaMelo - 2017-08-20 |
Instructions for Run2 added and updated for latest releases . |
RobertoCovarelli - 2015-03-03 |
Major rewrite for Run2. |
AnneHeavey - 15 Sep 2006 |
Separated this content out from the generation page, per Julia's request. |
Responsible:
JuliaYarba
Last reviewed by: DanielElvira - 15 Nov 2006
6.2 Generating Events
Goals of this page
When you finish this page, you should:
- Have a general idea of what types of generators are available to CMS
- Know where to find more detailed documentation on one or another generator of use to CMS
- Know where the generator software is located in CMSSW
- Know where to find pre-fabricated configuration fragments for several generators, and how to use them
- Have a general idea how a generator can be included in the CMSSW event processing chain, what additional software is needed, and what their output format is
- Be able to compose your configuration applications for selected generators, following provided examples and tips
- Know how to view the results of the event generation
Contents
Introduction
Monte Carlo Event Generators are used to generate high-energy-physics events, that in the end will be a set of outgoing particles produced in the interactions between two incoming particles (mostly proton-proton).
An impressive collection of physics event generators are interfaced to CMSSW.
- They include several general-purpose generators, such as Pythia8 and Herwig++ and other specific to some processes like EvtGen and Tauola. The objective of general-purpose event generators is to provide as accurate as possible a description of what happens end-to-end in a hadron collision. They contain theory models for a number of physics aspects, such as hard and soft interactions, parton distributions, initial and final state parton showers, multiple interactions, fragmentation and decay.
- Also of great interest to CMS are Matrix Element (ME) calculators, such as Powheg, MadGraph5_aMCatNLO, Algpen etc. They deliver an event at the parton level, and one or another multi-purpose generator can further be used to develop a fully hadronized event.
- In addition, we have several specific generators for diffractive physics, cosmic muon generators, heavy ions and so on.
- For the software testing purposes and acceptance studies, there is also a collection of simpler tools, so-called particle guns, that allow generating one or many individual particles of the user-specified kinematics.
For more detailed information on the generators of use to CMS please visit the following documents:
- CMS.GeneratorTaskList - for a complete list of generators of use in CMS, status and plans, and links to generator-specific materials, including non-CMS.
- GeneratorMain for all other information
Here we would like to stress that there is
not a single recipe for running one or another generator with CMSSW. For example, multi-purpose generators or simple particle guns execute entirely within CMSSW. It means that for a user it is enough to find an existing generator-level configuration include or to compose one of her/his choices and to process it through
cmsDriver.py
utility, as already shown in the
previous section. However, one should bear in mind that running a ME generator may require a pre-CMSSW step, which will be followed by a CMSSW run to deliver
fully hadronized event (and perform subsequent steps, if selected by a user).
In this tutorial we will provide several examples, to demonstrate how one can compose an application for:
- multi-purpose generator
- simple particle gun
- processing parton-level events generated with a ME tool
In this tutorial, we will refer to Pythia8 multi-purpose generator, both for full event generation or for hadronization of a parton-level event generated with a ME tool. However, rules for using other multi-purpose generators will be similar for most cases.
In general, these instructions presume the use of
CMSSW_10_2_X and higher, although many tips are applicable to releases as early as 5_3_X.
Event Generation Software and Existing Applications
The Software within CMSSW
In general, software that interfaces CMSSW to a variety of generators belongs to the
GeneratorInterface
subsystem.
A table of the supported MC generators is available in the
CMS.GeneratorTaskList document, as already mentioned above. The tables feature the link to the original MC page, the link to the CMSSW interface in the git repository, the link to the CMS Documentation twiki, the name of the CMS contact persons and a brief description of the status of the implementation.
In addition, simple
particle guns are available in the
IOMC/ParticleGuns
package. Those tools are mostly used for software testing purposes or for special-purpose simulation, for example, for test beam studies.
A user needs to know that each generator
directly interfaced to CMSSW is implemented as an individual module labeled "generator" that one can plug into the
cmsRun
executable.
Exceptions are ME generators that will be described separately.
Some of the packages under the
GeneratorInterface
will have only one such "plugin", while others (such as Pythia6Interface)
will have several modules.
Matrix Element Generators
ME generators are available in various forms, ranging from totally independent of CMSSW to those installed as external packages to CMSSW to those incorporated within CMSSW. However, they share one common feature: they are built as binary executable independent of principal CMSSW executable (
cmsRun
), and they are executed as a separate step. Two possibilities are foreseen:
- The generator is run to produces events prior to
cmsRun
. In this case the output of an ME generator is typically an ASCII file. The main format of this ASCII file is the Les Houches event (LHE) record, but at present at least one more format (Algpen) is supported. Thus, the procedure becomes a 2-step one, as partons from ME generators are developed into final state particles with the use of one or another multi-purpose generator, within a cmsRun
process. In this case, ME generator will be executed manually by experts/users, and the output will be recorded with the dedicated storage (the EOS system at CERN, under /eos/cms/store/lhe
). The parton-level samples will then be processed through a standard CMSSW chain, to develop fully hadronized events and run the following steps as desired.
- The generator is run prior to
cmsRun
only to produce ancillary files (like pre-computed amplitudes, phase space MC grids etc.) which make initialization faster. Then the actual production of the LHE events is done within CMSSW using a module called externalLHEProducer
. The output of this step is already ad edm-format file, which basically contains the LHE file in a CMSSW-readable format. This file can be equally processed through a standard CMSSW chain, to develop a fully hadronized event and run the following steps as desired. This second way is the recommended one for private and official MC production
Including a Generator in the CMSSW Event Processing Chain
It is important to remember that a
single label "generator" must be used in production applications, whatever CMSSW event
generation module a user decides to employ; no other labels are allowed. It is by this label that the subsequent event processing steps will locate the generator's output in the
edm::Event
tree. We have already mentioned this aspect in the
previous material but we would like to stress it here again and again.
Please be advised that several additional CMSSW components are needed to properly run (any) CMSSW event generation module. They are covered
later in this document.
Existing Applications
As already mentioned earlier, many examples of Pythia6 or ParticleGuns configuration cards can be found in the
/python
directory of the
Configuration/Generator
package, in a form of pre-fabricated configuration includes (these are used for so called Release Validation runs but are also good for private generation).
Notice that these cards cannot be used in a cmsRun
command before running cmsDriver.py
.
, For this reason, they are called generator "fragments".
An additional collection of generator-level configuration fragments can be found in the
/python
subdirectory of the
genproductions
external github area. They are meant for current production, or other Monte Carlo productions in the future.
Names of the files should be self-explanatory. For example, PYTHIA6 means usage of Pythia6 generator.
Please be advised that the
genproductions
package is
NOT distributed as part of CMSSW. Users should be able to view applications via github browser, or to be able to clone the package in git and into their local scram CMSSW project, as already explained in
other documents and to use any of the pre-fabricated configurations. However, we advise you that pre-fabricated configuration includes or fragments can be cross-used only within this package. Please see
SWGuidePythia8Interface for more details.
We believe that many users will be able to find the configuration for the event topology of their interest in one of the above two packages or at least
use these offered examples as inspirations.
All configuration fragments can be directly used with
cmsDriver.py
utility.
Later in this document, we will explicitly exemplify the usage of several existing configurations and will point your attention to important details.
Related Software Components
A user should bear in mind that the following software components are
mandatory for running event generation with CMSSW:
- (ExternalInput) Source
- Particle Property Table
- Random Number Generator Service
cmsDriver.py
will automatically decide what Source to use, based on the input arguments that a user passes to it. We will give more details in the following subsection.
The other two components will be included automatically if you use
cmsDriver.py
utility to compose your configuration.
This is done (directly or indirectly) via inclusion of a single pre-fabricated
standard configuration fragment
Configuration/StandardSequences/python/Services_cff.py
.
In the
example configuration
that we have already reviewed in the
previous section, you may notice
towards the beginning of the file the following include:
process.load('Configuration.StandardSequences.Services_cff')
(
/python
subdirectory is default, thus it is omitted)
The Sources
There are several types of Sources (see also
SWGuideEDMParametersForModules#SWGuideInputSources) that may be of use for event generation procedure in CMSSW:
- EmptySource - is a general-purpose Framework Source, that drives event loop and defines
edm::Event
principal, but does not add any branches to the edm::Event
. Use case: any multi-purpose event generator, to generate full event, or particle guns. Example usage is already covered in the previous material, but we will revisit it later in this document.
- LHESource - is a special-purpose Source that is a part of the GeneratorInterface/LHEInterface package. It reads externally generated parton record in the ASCII Les Houches format (LHE file), and in addition to creating event principal, it converts parton-level event to the
edm::Event
compatible format, that can be later recognized by subsequent event processing steps. It is used to process the output of ME generators, for example, the MadGraph events. Use case: you plan to run your private production manually, i.e. the output of your ME generator is a local file on disk, and you plan to immediately process it through cmsRun
to hadronize parton-level events and to run subsequent steps, as desired. We will show its usage later in this document. For detailed information please visit the dedicated SWGuideLHEInterface documentation.
- AlgpenSource - is a special-purpose Source that belongs to the GeneratorInterface/AlpgenInterface packag. It converts Alpgen-generated partons to the
edm::Event
compatible format. We will not show its usage in this document but detailed information can be found in the dedicated SWGuideAlpgenInterface documentation.
- PoolSource - is a general-purpose Framework Source that can read the content of a previously produced
edm::Event
file. Use case: you have generated your parton-level events with an ME tool, then have used LHESource to convert to the edm::Event
compatible format, and have written an EDM output file; later on you can read these parton-level events with a PoolSource, and proceed to develop a fully hadronized event, followed by subsequent steps, as you choose. This scheme will also be the case in central production. Thus, if your intend to prepare cmsDriver.py
compatible configuration fragments for central production, for processing ME partons, you will need to explicitly put PoolSource in your fragment (the exact input file to PoolSource will be specified via input argument to cmsDriver.py
, detailes later or elsewhere).
Particle Property Table
Particle Property Table is implemented with the use of the
LCG version of HepPDT
external software, which is interfaced to CMSSW via
SimGeneral/HepPDTESSource
package.
SimGeneral/HepPDTESSource/python/pythiapdt_cfi.py
is currently considered
standard and is used in production.
For details please visit
SWGuideParticleDataTable.
Random number generator initialization
In CMSSW all modules that need a random seed pick it up from a single
Service called
RandomNumberGeneratorService.
The complete configuration of the service is defined in the
standard configuration include:
IOMC/RandomEngine/python/IOMC_cff.py
.
A minimal configuration needed to event
generation only will look like follows:
RandomNumberGeneratorService = cms.Service("RandomNumberGeneratorService",
generator = cms.PSet(
initialSeed = cms.untracked.uint32(123456789),
engineName = cms.untracked.string('HepJamesRandom')
)
)
As shown, the seed is defined by the
initialSeed parameter, in the
PSet generator.
Please
note that the random engine specification is optional, but the seed must be present
and to be unique for a given generation job.
In general, we suggest the use
Configuration/StandardSequences/python/Services_cff.py
,
which is the
cmsDriver.py
standard, but we explicitly show the above details with regards to the following
important aspect:
In production, a large Monte Carlo sample is typically done by splitting the desired statistics into a number of smaller jobs processed in parallel, and their outputs
are then merged together. A
single configuration file serves as a
template for those parallel jobs. However, a user should
not worry about
the random seed to remain the same, because the production machinery automatically takes care of replacing the "default seed" for each individual job.
However, if you choose to generate your samples
manually, you will need to take care of each job to have a unique seed for your generator
(a module labeled "generator"), or you will risk generating identical samples. You can manually change the default seed by placing the following statement
in your configuration file, anywhere
after the inclusion of
Services_cff.py
, as shown below:
process.RandomNumberGeneratorService.generator.initialSeed = YOURSEED
where YOURSEED is any
positive integer of your choice.
The same is true for each module you choose to include in your event processing chain.
For more details on the RandomNumberGeneratorService, please follow the dedicated link:
https://twiki.cern.ch/twiki/bin/view/CMS/SWGuideEDMRandomNumberGeneratorService
Examples that show how to store and restore random seeds for the modules used in the event processing chain will be given in the
Detector Simulation and Digitization section.
Generator Data formats
Multi-purpose event generators and simple particle guns are entirely executed within CMSSW, and deliver an event in a form of final state particles.
These generators creates in memory a
HepMCProduct
, as a branch in the
edm::Event
. The
HepMCProduct
is a wrapper around generator particles information recorded in the
HepMC format
(
HepMC::GenEvent
). Please be aware that this branch is only kept in certain data tiers. But due to its double-precision nature and out of event size considerations, in many samples suitable for final analysis it is replaced by a "lighter" versions (
genParticles
) that is described in the
WorkBookGenParticleCandidate.
Multi-purpose generators also create in the
edm::Event
an additional branch,
GenEventInfoProduct
, that carries such event characteristics as weight(s), scale, PDFs, etc. This branch is always kept in the event.
In addition, milti-purpose generators create an
edm::Run
type product in the output,
GenRunInfoProduct
. Additional information can be found in the
SWGuideDataFormatGeneratorInterface.
The ME generators deliver parton-level event record that is output in an ASCII form. Via one or another dedicated Source (described above), parton-level events get converted into
EDM-compatible form, and become an
LHEEventProduct
branch in the
edm::Event
. The branch is always kept in the event.
Run-specific information for the ME generators is recorded in a form of
LHERunInfoProduct
.
We remind that there are two ways to obtain these products. If the products come from a "translation" of a physical LHE file these products are
labeled "source"., being produced by a Source, rather than a wrapper to one or another multi-purpose generator. While if the LHE are directly produced within CMSSW, then
the products are
labeled "externalLHEProducer".
Both products are C++ implementation of the
Les Houches Accord format
(the products sort of "mimic" the concept of the HEPRUP and HEPEUP Fortran common blocks).
Both products are always kept in the
edm::Event
, in case events need to be re-processed. It is important to keep parton-level events, since producing them with ME tools is often resource-expensive.
All these data formats belong to the
SimDataFormats/GeneratorProducts
package.
Sample Configuration for the Particle Gun
As an example configuration application for a
flat-pt gun
one can use one of the pre-fabricated fragments,
Configuration/Generator/python/SingleElectronPt10_cfi.py
.
If you wish to give it a try, you can
run it through cmsDriver.py
utility, as already discussed
in the previous material (assuming your
run time environment is set).
If you are interested only in generating events event and not the subsequent steps in the event processing chain, you can limit the steps
to the
-s GEN
, as shown below:
cd <your CMSSW area>/src
cmsenv
cmsDriver.py Configuration/Generator/python/SingleElectronPt10_cfi.py -s GEN --conditions auto:mc --datatier 'GEN-SIM-RAW' --eventcontent RAWSIM -n 10 --no_exec --python_filename SingleElectronPt10_cfi_py_GEN_IDEAL.py
- Note:Please note that
--conditions auto:mc
represent rather common choice in Monte Carlo production runs with the most recent CMSSW release cycles. Please visit Software Guide on the FrontierConditions for more details.
Here we need to note that the --conditions
are not relevant to the event generation step, but cmsDriver.py
expects
this argument anyway (for consistency), thus we advise you to follow the convention. Same is true for all generator level examples, listed here or in other related materials; however, we'll occasionally repeat this, just as a reminder.
The resulting configuration file,
SingleElectronPt10_cfi_py_GEN_IDEAL.py
, can be fed on input to
cmsRun
:
cmsRun SingleElectronPt10_cfi_py_GEN_IDEAL.py
You are welcome to examine the contents of the offered configuration fragment:
- the EmptySource - as already mentioned above
- FlatRandomPtGunProducer - configured to generate an electron of user-specified kinematics; it also adds to the event a positron of the "opposite" kinenatics (see configuration parameter
AddAntiParticle=cms.bool(True)
)
Other particle guns, including a detailed explanation of configuration parameters, are covered in the
SWGuideEventGeneration document and its daughter materials.
Sample Configuration File for Pythia8 Event generation
In general, not all possible configurations can be found in the CMSSW package
Configuration/Generator
as in the example above because their updates are more frequent than the CMSSW release schedule. For this reason, a separate repository located under
genproductions/python
is kept up to date. When the fragment is taken from this area, additional steps are needed to get the fragment.
One can download the full repository using git:
cd <your CMSSW area>/src
cmsenv
mkdir -p Configuration
cd Configuration
git clone git@github.com:cms-sw/genproductions.git GenProduction
Or you get the single file via curl:
cd <your CMSSW area>/src
cmsenv
curl -s --insecure https://raw.githubusercontent.com/cms-sw/genproductions/master/python/ThirteenTeV/RSGravitonRSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_cfi.py --retry 2 --create-dirs -o Configuration/GenProduction/python/RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8-fragment.py [ -s Configuration/GenProduction/python/RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_cfi.py ]
curl (like wget) just fetches an input file from a web location (in this case we used
this fragment
, which is RS graviton G(1TeV) -> ZZ), and places it in a "fake" CMS package creating a directory structure like those of the CMS packages. NOTE THAT Configuration/GenProduction IS NOT A PART OF CMSSW.
In this case you need to compile the python scripts:
scram b
cmsDriver.py Configuration/GenProduction/python/RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8-fragment.py --fileout file:RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8.root --mc --eventcontent AODSIM --datatier GEN-SIM --conditions auto:mc --step GEN --python_filename RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_cfg.py --no_exec -n 5000
We show here additional input arguments to
cmsDriver.py
utility.
- The first - and mandatory - input argument to
cmsDriver.py
is configuration fragment that determines what physics event generator you wish to use and what topology you intend to generate. In this example we use a pre-fabricated fragment
which is originally located in the genproductions area.
- The
-s
or --step
field contains the sequence of event processing steps. If you wish to terminate your chain at the generation level, you may use "-s GEN"
- Details of the
--conditions
field can be found in the Software Guide on the FrontierConditions. Notice that the choice --conditions auto:mc
chooses the best conditions for a given release.
- To select the content of the
--datatier
field plese view the documentation on the allowed Data Tiers.
- Content of the
--eventcontent
field is described in great details in the SWGuideDataFormatTable.
- In the
-n
field you will specify how many events you want to generate, simulate, etc.
- The
--no_exec
argument tells cmsDriver.py
to write out the configuration file. If you do not specify this argument, cmsDriver.py
will proceed to executing cmsRun
.
- The
--python_filename
and --fileout
define the output configuration file and the output root file after cmsRun
, respectively. If not specified, the default names are composed by the fragment name, plus the steps separated by an underscore, plus .py/.root respectively
- The customization part is not important for private production and may be skipped
Then you can use
cmsRun
normally.
Sample Configuration for Processing MadGraph Events with Pythia8
As already mentioned above, multi-purpose generators can also be used to develop a fully hadronized event starting from partons generated with a ME tool. Here we would like to show how one can compose an application for processing a MadGraph sample (in LHE form) with Pythia8. The example given below is for W+jets production.
Please review pre-fabricated generator-level configuration fragment
Configuration/Generator/python/Hadronizer_TuneCUETP8M1_13TeV_MLM_5f_max4j_LHE_pythia8_cff.py
.
The name contains already a lot of information: the UE tune, the energy, the matching scheme (see below) and the maximum number of partons generated by the ME.
In the fragment, there will be several details of interest for you.
The aspect of your first interest is this:
generator = cms.EDFilter("Pythia8HadronizerFilter",
it means that we use Pythia8-based module that is dedicated to processing externally generated partons, rather than Pythia8GeneratorFilter shown in previous examples.
This example configuration also includes usage of the dedicated Madgraph parton-shower matching algorithm, to decide on the event internal validity, or to veto events of incorrect topology:
JetMatchingParameters = cms.vstring(
'JetMatching:setMad = off',
'JetMatching:scheme = 1',
'JetMatching:merge = on',
'JetMatching:jetAlgorithm = 2',
'JetMatching:etaJetMax = 5.',
'JetMatching:coneRadius = 1.',
'JetMatching:slowJetPower = 1',
'JetMatching:qCut = 20.', #this is the actual merging scale
'JetMatching:nQmatch = 5', #4 corresponds to 4-flavour scheme (no matching of b-quarks), 5 for 5-flavour scheme
'JetMatching:nJetMax = 4', #number of partons in born matrix element for highest multiplicity
'JetMatching:doShowerKt = off', #off for MLM matching, turn on for shower-kT matching
),
Please note that the use of matching procedure is
optional; Pythia8HadronizerFilter may operate without it. However, if the ME includes
merging of different parton multiplicities in the same sample, the result without matching will be physically incorrect. If you would like to learn more about parton-shower matching basics, you might find interesting
this paper
and the refferenced materials.
If you choose to use parton-shower matching, you will need to remember that in case an event is vetoed, the EDFilter will return a
false code, and the
HepMCProduct
will be empty. Those event will be filtered out of the output, because event generation step is included in the "production filtering sequence":
ProductionFilterSequence = cms.Sequence(generator)
(which will later on will be reflected in the PoolOutputModule configuration, if you process the fragment through
cmsDriver.py
).
You can process the configuration fragment through
cmsDriver.py
as shown below:
cmsDriver.py Configuration/Generator/python/Hadronizer_TuneCUETP8M1_13TeV_MLM_5f_max4j_LHE_pythia8_cff.py -s GEN --conditions auto:mc --filein /store/lhe/12821/ascii_dump.lhe --datatier 'GEN-SIM-RAW' --eventcontent RAWSIM -n 1000 --no_exec
Please note that
we could omit the notation Configuration/Generator/python in the path to the pre-fabricated configuration include, because it is
the default for
cmsDriver.py
. However, if your configuration include/fragment is located in a different python area, you will need to specify it in the following format: Subsystem/Package/python.
The event loop is driven by a special purpose LHESource (rather than EmptySource)
process.source = cms.Source("LHESource",
fileNames = cms.untracked.vstring('/store/lhe/12821/ascii_dump.lhe')
)
which is fed with the parton-level MadGraph sample. In the logging of the run you can see that you have a printout of the
matching efficiency which is below 100%.
In general, it's the extension
.lhe
that tells the
cmsDriver.py
to use
LHESource and to feed it with the LHE file of your choice (extension
.lhef
is also recognized). In addition, you can use
--filetype LHE
to force the creation of a LHE source.
Please be advised that in this example we refer to a "private" sample that is normally used for debugging by developers. Normally LHE files are generated automatically in CMSSW (see next section).
Another detail that you need to know is the following:
If in your generator-level configuration fragment you
explicitly include a cms.Source (as do earlier revisions of the provided cff),
cmsDriver.py
may NOT override the name of the files on input. Thus, it is better NOT to include
any cms.Source in your generator-level fragment.
Sample Configuration for Creating Powheg Events and Processing them with Pythia8
The most complex case is when you need to create LHE files and hadronize them with Pythia8 which can be done in a single step. We will show this for search for a second Higgs to 4l H(190). First of all, a
gridpack, i.e. a package containing all the information to run a certain process in Powheg or MadGraph must be created
before moving to the CMSSW step.
Instructions to produce those gridpakcs can be found at:
In practice only MC experts deal with these complicated instructions. So we will use here a pre-defined gridpack.
The card to be used in this case is
test_PowhegPythiaH190_cff.py.txt. Please download it and place it in Configuration/GenProduction/python as in the Pythia example above. Then cmsDriver.py will be called as:
cmsDriver.py Configuration/GenProduction/python/test_PowhegPythiaH190_cff.py -s LHE,GEN --conditions auto:mc --datatier 'GEN-SIM-RAW' --eventcontent RAWSIM -n 1000 --no_exec --fileout file:PythiaH190ZZ4mu_cfi_py_GEN.root
A few comments:
- The fragment now has two steps: externalLHEProducer is needed to produce LHE files from the pre-defined gridpack. Immediately after Pythia8 is used to hadronize them. In this two-step approach you actually see only the final result and save space. As a consequence two steps are defined in the command above:
LHE
and GEN
.
- The structure of the externalLHEProducer module is quite standard. All the physics information, NLO production of H(190) in this case, is contained in the tar archive (gridpack) as the first argument. The module is a "fake" CMSSW step in the sense that actually no C++ code is called, but just the execution of the script inside which uncompresses the tar archive and runs it.
- The structure of the generator module is very similar to the MadGraph example above. "Emission veto" is a sort of equivalent of matching in Powheg. In addition, commands starting with 25: and 23: redefine the mass and decay modes of H and Z.
While running with
cmsRun
the resulting python config you see that many things happen in cascade:
- Gridpack is dowloaded and uncompressed
- Powheg runs in default mode, and then several other times to compute weights for alternative hypotheses of QCD scales and PDFs.
- Pythia8 runs on the LHE events
Accessing particle level MC data
We provide, under the
/test
subdirectory of the
GeneratorInterface/Pythia6Interface
package,
a "starter kit" for simple analysis of the generator information.
cd <your CMSSW area>/src
cmsenv
git-cms-addpkg GeneratorInterface/Pythia6Interface
scram b
cd GeneratorInterface/Pythia6Interface/test
Please keep in mind that the examples do not pretend to be sophisticated. We expect that the users will extend and improve
them while customizing to their needs, and will contribute their feedback.
The "starter kit" includes the following:
- configuration file H190ZZ4muHepMCAnalysis_cfg.py
that reads in, via PoolSource, the EDM ROOT file PythiaH190ZZ4mu_cfi_py_GEN.root produced in the previous exercise, and runs the HZZ4muExampleAnalyzer
(it's an EDAnalyzer; the actual name of the class is HZZ4muAnalyzer, but the plug-in module is named HZZ4muExampleAnalyzer). Before run H190ZZ4muHepMCAnalysis_cfg.py please perform:
edmDumpEventContent PythiaH190ZZ4mu_cfi_py_GEN.root
You should see:
Type Module Label Process
---------------------------------------------------------------------------------------------
GenEventInfoProduct "generator" "" "GEN"
LHEEventProduct "externalLHEProducer" "" "GEN"
edm::HepMCProduct "generatorSmeared" "" "GEN"
edm::RandomEngineStates "randomEngineStateProducer" "" "GEN"
edm::TriggerResults "TriggerResults" "" "GEN"
vector<int> "genParticles" "" "GEN"
vector<reco::GenJet> "ak4GenJets" "" "GEN"
vector<reco::GenJet> "ak4GenJetsNoNu" "" "GEN"
vector<reco::GenJet> "ak8GenJets" "" "GEN"
vector<reco::GenJet> "ak8GenJetsNoNu" "" "GEN"
vector<reco::GenMET> "genMetCalo" "" "GEN"
vector<reco::GenMET> "genMetTrue" "" "GEN"
vector<reco::GenParticle> "genParticles" "" "GEN"
Please verify the module label at HZZ4muAnalyzer.cc before run the config file.
The analyzer, in its turn produces a plain ROOT
histogram file
TestH190ZZ4muMass.root
; the histograms in this file are sample Z and Higgs mass spectra.
Please note that the configuration file we offer here is NOT made with
cmsDriver.py
, but is a "handmade" one - just to illustrate the case.
The
analyze()
method of the analyzer will show you how to:
-
- access HepMCProduct
- "walk through" the
HepMC::GenEvent
record
- analyze in a very simplified way the generator information: extract muons of interest and reconstruct the Higgs invariant mass.
- In your ROOT Canvas window you should see sample Z- and Higgs-mass plots similar to these below:
Filtering generator events
Users who want to select events that satisfy particular criteria at the generation level, i.e. based on the content of the HepMC event,
are welcome to visit dedicated guide
SWGuideGenFilters.
Further documentation
For general information on the CMSSW framework see
WorkBookCMSSWFramework for an introduction and in the following page:
http://cms.cern.ch/iCMS/jsp/page.jsp?mode=cms&action=url&urlkey=CMS_OFFLINE
many useful links can be found:
Review status
Reviewer/Editor and Date (copy from screen) |
Comments |
ElizaMelo - 2017-08-27 |
Some cleanups and updates, to better match 8XX releases. |
RobertoCovarelli - 2015-03-04 |
Major rewrite for Run2 |
JuliaYarba - 21 March 2011 |
Various cleanups and updates, to better match late 3xx and current 4XX releases (incl. instructions for cmsDriver use) |
JuliaYarba - 11 June 2009 |
Bring up to date with 31x or above; incorporate suggestions from Review by User Support |
JuliaYarba - 17 Sept 2008 |
Transition to python configuration files |
JuliaYarba - 3 Jan 2008 |
Add Pythia-gun example, restore HepMC analysis examples |
PaoloBartalini - 24 Aug 2007 |
Pythia part updated for latest releases |
Main.fmoortga - 05 Dec 2006 |
Updated for latest releases |
JennyWilliams - 16 Aug 2006 |
Moved out of Gen+Sim+Digi page, tweaked |
JuliaYarba, Main.Anne Heavey - 15 Jun 2006 |
Update it for Jun 06 tutorial |
FabioCossutti - 08 May 2006 |
wrote original tutorial for May 2006 CPT week |
Last reviewed by:
RobertoChierici - 27 Feb 2008
6.3 How to Configure and Run Detector Simulation and Digitization
Goals of this page:
The purpose of this document is to quickly enable the CMSSW framework users to produce simulated event samples that can be used for physics studies.
You'll learn:
- What steps and software components are involved in the detector simulation
- How to run centrally-provided configurations
- How to make some simple customizations according to your needs
Contents
Introduction
This document
continues from the WorkBook
Event Generation page, and focuses on the steps that compose
modeling of the Interaction Region (IR) and full-scale CMS Detector simulation.
By default, the nominal vertex of a generated event is (0,0,0). However, in the real-life the IR is not point-like, thus a specialized software,
also called Vertex Smearing, has been introduced to model the spread.
The full-scale simulation of the CMS detector is based on the Geant4 toolkit. It relies on a fairly detailed description of the hierarchy of volumes and materials, and knowing which parts are "sensitive detector" (i.e., furnished with a readout) as opposed to "dead materials".
This step follows immediately after the Vertex Smearing.
The next step in the process is reproducing the response of the detector readout electronics, which is also known as Digitization.
More
detailed information on the software, including description of algorithms where applicable, is given in the
SWGuideSimulation
(WARNING: materials under development !).
As with all CMSSW components, the software involved in the detector simulation process is configurable at run time.
In this document, we will offer a walk-through of a pre-fabricated example configuration application, which is composed of the use of
standard,
CMS-approved settings.
We'll point you to fragments and modules that are related to the IR modeling and detector simulation. We'll also provide some tips on how to
change some configuration parameters, in case your study calls for custom configuration rather than the use of default settings.
In general, we assume the use of the
CMSSW_10_2_X cycle. However, many tips are still valid for many earlier releases. We'll provide additional, release-specific tips where necessary.
Simulation Software and Existing Applications
The software that is related to the IR modeling and detector simulation, including related components, is quite extensive and
resides in several subsystems:
IOMC
,
SimGeneral
,
SimG4Core
,
SimG4CMS
,
SimTracker
,
SimCalo
,
SimMuon
.
The simulation part in the event processing chain is performed by several CMSSW modules, that need to be composed in the
specific order in the
configuration application, as each module in the chain will require certain output
from an earlier step, performed by another module. Also, these modules need to be assigned certain labels, because it that by the
label that each module will access necessary information delivered into
edm::Event
.
In the earlier section of this chapter,
WorkBookGenIntro, we have already pointed at the
existing pre-fabricated example,
and have provided brief information about its "building blocks".
In this document we offer more details about services and steps involved in the detector simulation procedure.
Instructions are also provided on how one can configure such applications, starting from a generator-level configuration fragment and using CMSSW
utilities and standard settings.
In addition, we will explain how to change some of the standard settings, as we presume some tasks may need that.
How to Find and Run an Example Simulation Application
Although we have
already explained in the earlier materials how to setup the environment for running an application,
we repeat it here for clarity:
cmsrel CMSSW_X_Y_Z
cd CMSSW_X_Y_Z/src
cmsenv
step0:GEN-SIM
cmsDriver.py Configuration/GenProduction/python/ThirteenTeV/RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_cfi.py --fileout file:RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_GEN-SIM.root -s GEN,SIM --mc --datatier GEN-SIM --beamspot Realistic25ns13TeV2016Collision --conditions auto:phase1_2017_realistic --eventcontent RAWSIM --era Run2_2017 --python_filename RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_GEN-SIM_cfg.py --no_exec -n 50
step1:DIGI2RAW-HLT
cmsDriver.py -s DIGI,L1,DIGI2RAW,HLT --datatier GEN-SIM-RAW --conditions auto:phase1_2017_realistic --eventcontent RAWSIM --era Run2_2017 --filein file:RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_GEN-SIM.root --fileout file:RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_GEN-SIM-RAW.root --python_filename RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_FULLSIM_GEN_SIM_RAW_cfg.py -n -1 --no_exec
step2:RECO
cmsDriver.py -s RAW2DIGI,L1Reco,RECO --datatier RECO --conditions auto:phase1_2017_realistic --eventcontent AODSIM --era Run2_2017 --filein file:RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_GEN-SIM-RAW.root --fileout file:RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_GEN-SIM-RAW-RECO.root --python_filename RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_FULLSIM_GEN_SIM_RAW_RECO_cfg.py -n -1 --no_exec
How to Find and Run an Example Simulation Application
Although we have
already explained in the earlier materials how to setup the environment for running an application,
we repeat it here for clarity:
cmsrel CMSSW_X_Y_Z
cd CMSSW_X_Y_Z/src
cmsenv
step0:GEN-SIM
cmsDriver.py Configuration/GenProduction/python/BPH-RunIIFall18GS-00170-fragment.py --fileout file:BPH-RunIIFall18GS.root --mc --eventcontent RAWSIM --datatier GEN-SIM --conditions 102X_upgrade2018_realistic_v11 --beamspot Realistic25ns13TeVEarly2018Collision --step GEN,SIM --geometry DB:Extended --era Run2_2018 --python_filename BPH-RunIIFall18GS_cfg.py --no_exec --customise Configuration/DataProcessing/Utils.addMonitoring --customise_commands process.source.numberEventsInLuminosityBlock="cms.untracked.uint32(1408450)" -n 10000
step1:DIGI2RAW-HLT
voms-proxy-init
cmsDriver.py step1 --filein file:BPH-RunIIFall18GS.root --fileout file:BPH-RunIIAutumn18DR_step1.root --pileup_input "dbs:/MinBias_TuneCP5_13TeV-pythia8/RunIIFall18GS-102X_upgrade2018_realistic_v9-v1/GEN-SIM" --mc --eventcontent FEVTDEBUGHLT --pileup "AVE_25_BX_25ns,{'N': 20}" --datatier GEN-SIM-DIGI-RAW --conditions 102X_upgrade2018_realistic_v15 --step DIGI,L1,DIGI2RAW,HLT:@relval2018 --nThreads 8 --geometry DB:Extended --era Run2_2018 --python_filename BPH-RunIIAutumn18DR_cfg.py --no_exec --customise Configuration/DataProcessing/Utils.addMonitoring -n 100
step2:RECO
cmsDriver.py step2 --filein file:BPH-RunIIAutumn18DR_step1.root --fileout file:BPH-RunIIAutumn18DR_step2.root --mc --eventcontent AODSIM --runUnscheduled --datatier AODSIM --conditions 102X_upgrade2018_realistic_v15 --step RAW2DIGI,L1Reco,RECO,RECOSIM,EI --nThreads 8 --geometry DB:Extended --era Run2_2018 --python_filename BPH-RunIIAutumn18DR_2_cfg.py --no_exec --customise Configuration/DataProcessing/Utils.addMonitoring -n 100
How to Compose a Simulation Application Using Standard Utilities
In most cases, simulation applications will only differ by the topology of the physics events want wants to study, i.e. the differences are
at the
Generator level only, while steps related to IR modeling and detector simulation can be added via use
of pre-fabricated,
standard (CMS-approved) configuration fragments.
The most reliable and safe way of composing a
standard simulation chain is with the use of the
cmsDriver.py
utility.
This utility is distributed together with CMSSW releases, and will automatically appear in your PATH upon setting up CMSSW run time environment,
i.e. execution of
cmsenv
script (see above). It produces a framework .cfg file that you can run with
cmsRun
.
Detailed information on the
cmsDriver.py
is provided in the
dedicated documentation. We have also offered some
tips and shortcuts in the
earlier part of this chapter. There are also up-to-date cmsDriver statements
inside of the files contained in the
Configuration/PyReleaseValidation/data
directory; these can be used as templates for making your own statements.
Obviously, before executing
cmsDriver.py
a user must choose a configuration fragment that will define the event topology to be generated.
In the
Event Generation part of this chapter, we point users to a large collection of pre-fabricated generator level
fragments one can use. In case a configuration for a topology of the user's interest is not readily available within CMSSW, we also offer there
a variety of instructions and pointers to related materials, to help users compose their own applications.
Once you have selected your generator level configuration fragment, you can compose your application like this:
cmsDriver.py PATH/To/Your/GenFragment.py -s GEN,SIM --mc --datatier GEN-SIM --beamspot Realistic25ns13TeVEarly2018Collision --conditions 102X_upgrade2018_realistic_v11 --eventcontent RAWSIM --era Run2_2018 --no_exec -n 50
Of course, in the example above
PATH/To/Your/GenFragment.py
is a generic form. If you place your generator-level configuration fragment
into
Coonfiguration/Generator/python
directory, you will only need to specify the file name.
i.e. you can omit
Configuration/Generator/python
portion, as it is default in
cmsDriver.py
.
But if you place your generator level fragment into another package under your local CMSSW area, you will need to specify more details, i.e. provide it
in the format that can be schematically described as
Subsystem/Package/python/YourFile
.
Walk-through a Configuration File: Simulation Related Steps and Components
In the
earlier section of this chapter we have already pointed users to some of the top-level "building blocks" of the detector
simulation application.
In this document we would like to provide more information, including some of the details on the lower-level fragments the "building blocks" are made of.
Random Number Engine and Seed Settings
All modules that are involved in the IR modeling and detector simulation need to be given an initial random seed and, optionally, an engine.
In CMSSW all modules that need a random seed pick it up from a single
Service called
RandomNumberGeneratorService.
The complete configuration of the service is defined in the
standard configuration include:
IOMC/RandomEngine/python/IOMC_cff.py
.
This gets included in the application configuration via this statement that you can see in the config file created in the step 1.
process.load('Configuration/StandardSequences/Services_cff')
which in turn imports the standard settings:
from IOMC.RandomEngine.IOMC_cff import *
Please note that when you use
cmsDriver.py
to compose your application, the
Services_cff.py
will be included by default.
Later in this document, we will also show how one can alter the default seed for one or another module if this is needed.
Add Vertex Smearing
As already mentioned above, the vertex smearing software allows accounting for the actual dimensions of the IR, which is not point-like at (0,0,0).
The software is located in the package
IOMC/EventVertexGenerators
.
We have modules for modeling several hypothesis of the IR spread. Currently, we assume that the most realistic model is based on the beta-function
smearing. For this option, we have defined several beam configuration scenarios according to the latest LHC simulations.
This configuration is included in the example application via this statement:
process.load("Configuration.StandardSequences.VtxSmearedRealistic25ns13TeVEarly2018Collision_cfi")
which in turn imports the standard settings:
from IOMC.EventVertexGenerators.VtxSmearedRealistic25ns13TeV2017Collision_cfi import *
Users are welcome to examine the settings:
IOMC/EventVertexGenerators/python/VtxSmearedRealistic25ns13TeVEarly2018Collision_cfi.py
.
Other options and various details are described in the
dedicated Vertex Smearing guide.
The IR modeling operates on the generator particles. Obviously, this needs to be applied before the detector simulation can come into play.
Users should bear in mind that a
single label "VtxSmeared" should be used in all production applications, regardless of what IR modeling module a user decides to employ. It is by this label that the IR modeling step will be included in the event processing chain.
Please note that even if we consider IR modeling together with the detector simulation procedure, the
cmsDriver.py
utility includes it via the
GEN:ProductionFilterSequence
argument in the
-s
field (together with it also get included several other modules of the Physics Analysis domain, that operate on generator's particles).
Geometry and Magnetic Field
In order to run, the CMS detector simulation application requires 2 common-use components - descriptions of
the
Detector Geometry and of the Magnetic Field. Both are service-type components, i.e. they are not
steps in the event processing chain, but they deliver mandatory information that is necessary for the detector simulation software.
The detector simulation is loaded via the following instruction:
process.load("Configuration.StandardSequences.Geometry_cff")
This is the configuration that should be used in the production applications.
In a private configuration, one can replace the official cfi/cff file for a specific studies.
However, we suggest that you modify the official complete geometry with your private geometry only if
you know what you are doing!
Another mandatory inclusion is the magnetic field record:
process.load("Configuration.StandardSequences.MagneticField_cff")
Please note that the magnetic field record must be present for the proper initialization of your
Geant4-based detector simulation job, due to how the hierarchy of volumes with/without magnetic
field is coded.
Later in this document we will explain how to switch off the magnetic field, if this is needed for a specific study.
If you use
cmsDriver.py
utility to compose your simulation application, both standard configurations will be loaded by default.
Detector Simulation Module : OscarProducer
The full-scale simulation of the CMS detector is based on the Geant4 toolkit.
It relies on a fairly detailed description of the hierarchy of volumes and materials,
and knowing which parts are "sensitive detector" (i.e., furnished with a readout) as opposed to "dead materials".
It takes as input
generated particles (vertex smearing included), traces them through the hierarchy of volumes and materials, and models physics processes that accompany particle passage through matter. Results of each particle's interactions with matter are recorded in the form of
simulated hits. An example of a simulated hit can be energy loss by a given particle within a "sensitive volume" of one of the subdetectors, stored along with several other characteristics of the interaction. Particles can be either
"primary" (generated particle) or "secondary" (a result of Geant4-modeled interactions of a primary particle with matter).
The software is quite extensive and is located in the
SimG4Core
and
https://github.com/cms-sw/cmssw/tree/CMSSW_10_2_X/SimG4CMS
subsystems.
Altogether it is composed in a single module called
OscarProducer.
The top-level "building block" that brings detector simulation into the event
processing chain is
Configuration/StandardSequences/python/Sim_cff.py
.
The detector simulation is loaded via the following instruction:
process.load('Configuration/StandardSequences/SimIdeal_cff')
It brings in an intermediate level:
from SimG4Core.Configuration.SimG4Core_cff import *
which in turn imports the actual settings of the
OscarProducer:
from SimG4Core.Application.g4SimHits_cfi import *
These are the
standard, CMS-approved settings, and users are welcome to examine them:
SimG4Core/Application/python/g4SimHits_cfi.py
.
Later in this document we will show how to change some of the settings, that we think could be of interest to end-users.
The module is labeled
"g4SimHits", and is included in the event processing chain by this label.
It is important to remember that this label is mandatory in the production applications because the subsequent components will need it
to look up for the simulation output in the
edm::Event
.
The inclusion of this software in the event processing chain corresponds to the
SIM
argument in the
cmsDriver.py -s
field.
More details can be found in the
SWGuideSimulation and its daughter materials.
Modeling Detector Response: Digitization
The CMS detector simulation process is wrapped up by modeling the response of detector readout electronics. Corresponding to the CMS detector structure,
the software is subdivided into 3 domains:
SimTracker
,
SimCalorimetry
, and
SimMuon
. In turn, each subsystem is
composed of several subdetectors, thus the software is a collection of several independent modules.
However, all these modules have one thing in common: they all must operate AFTER the module that simulates the PileUp.
We are providing more a few more tips below; detailed information can be found in
SWGuideSimulation (WARNING: materials under constructions !).
As already pointed out earlier, the digitization is collectively brought into the config file via this statement:
process.load('Configuration/StandardSequences/Digi_cff')
The whole sequence of steps is collectively labeled
"pdigi"; it is by this label the digitization gets included in the production chain.
Collectively, the inclusion of this software in the event processing chain corresponds to the
DIGI
argument in the
cmsDriver.py -s
field.
Below we'll provide a few more details on what this top-level fragment
Configuration/StandardSequences/python/Digi_cff.py
is composed of.
PileUp Simulation: MixingModule
PileUp simulation relates to the effect of more that one physics interaction per beam crossing, due to high concentration of particles in a bunch, and/or the effect
of the electronics signal spill-over from the previous bunch crossings (may be >1) into the current crossing (event), due to the fact that the bunch spacing (time
between collisions) is often shorter than the duration of an electronic signal in one or another subdetector.
The PileUp can be
optionally simulated by the CMSSW component called
MixingModule. The software is located in the
https://github.com/cms-sw/cmssw/tree/CMSSW_10_2_X/SimGeneral/MixingModule][SimGeneral/MixingModule]]
package.
Detailed information on the
MixingModule can be found in the
MixingModule manual.
As already stated above, the
MixingModule must be present in the chain, at least in the zero-pileup mode, if a user needs to digitize simulated hits in the CMS detector subsystems. This is due to the implementation details of the digitization software. In the config file it is included via the following statement:
process.load('Configuration/StandardSequences/MixingNoPileUp_cff')
Additional pre-fabricated configuration fragments for that users can use in their production applications for the PileUp simulation is the following:
Configuration/StandardSequences/python/Mixing.py
All pileup scenarios available for FullSim are automatically available for FastSim.Pileup scenarios are defined in
Configuration/StandardSequences/python/Mixing.py
. For each available pileup option
X
there is a line
addMixingScenario("X","Y")
, where
Y
points to the configuration file or provides parameters that define the pileup scenario.==addMixingScenario("FS_X","Y")==, where
Y
points to the configuration file or provides parameters that define the pileup scenario.See
PdmVPileUpDescription to find out which PU scenario is used in which production campaign.
If you browse through the fragments, you'll notice that, in turn, they import
standard, CMS-approved configurations of the
MixingModule
from the package area.
We
strongly recommend that you use these fragments, rather than configure
MixingModule explicitly.
If you wish to modify any parameter, please use the
replace option.
Coming soon: Samples generated with the
DataMixingModule, which can overlay collision data on simulated events. Extensive documentation can be found in the Offline Simulation guide
SWGuideSimulation.
Tracker Digitization
Tracker digitization software belongs to the
SimTracker
subsystem of CMSSW.
It is imported into
Digi_cff.py
via the following statement:
from SimTracker.Configuration.SimTracker_cff import *
(collectively labeled as "trDigi"). It is composed of 2 fairly independent steps: Pixel digitization and silicon strips digitization. You can find more information in the
SWGuideSimulation and its daughter materials (under construction).
Calorimeter Digitization
Calorimetry digitization software belongs to the
SimSimCalorimetry
subsystem of CMSSW.
It is imported into
Digi_cff.py
via the following statement:
from SimCalorimetry.Configuration.SimCalorimetry_cff import *
(collectively labeled as "calDigi"). It made of 2 independent steps: Electromagnetic Calorimeter (ECAL ) digitization and Hadronic Calorimeter (HCAL) digitization. You can find more information in the
SWGuideSimulation and its daughter materials (under construction).
Muon System Digitization
Muon system digitization software belongs to the
SimMuon
subsystem of CMSSW.
It is imported into
Digi_cff.py
via the following statement:
from SimMuon.Configuration.SimMuon_cff import *
(collectively labeled as "muonDigi"). It is composed of 3 steps: digitization of the CSC, DT, and RPC subdetectors. You can find more information in the
SWGuideSimulation and its daughter materials (under construction).
Output Data Formats
Of many
edm::Event
data products, only two branches are of general interest to most of the end users: container of
simulated Track objects
and
SimDataFormat/Vertex
packages, (see also
SimDataFormats/Track/interface/SimTrackContainer.h
and
SimDataFormats/Vertex/interface/SimVertexContainer.h
).
Both branches are
labeled "g4SimHits".
Please note that, in the official production, these branches are kept in certain samples but not in all of them.
You may find additional details in the
SWGuideDataFormatSimG4Core document.
Other
edm::Event
branches produced by various modules involved in the detector simulation chain typically serve as input for the subsequent steps and are not of interest to the majority of end-users. They are excluded from the output in the official production. Additional information on configuring output, if needed for specific studies, are provided
later in this document.
Additional How-To's
Change Some of the OscarProducer's Parameters
The default (standard CMS-approved) configuration of the
ParameterSet for the
OscarProducer module is given in the following configuration include:
SimG4Core/Application/python/g4SimHits_cfi.py
A user can modify/replace the default parameters if a specific task calls for such change. However, we suggest that you make changes only if you're really familiar with the software, and you will know what you do.
If you decide to change some of the parameters, you can place it it fairly anywhere in your configuration, as long as it's done
after the inclusion of
process.load("Configuration.StandardSequences.Simulation_cff")
Detailed information about
OscarProducer configuration parameters can be found in
SWGuideSimulation and its daughter materials.
Here we would like to point at several parameters that we believe are of primary interest for the end-user:
...
G4EventManagerVerbosity = cms.untracked.int32(0),
G4StackManagerVerbosity = cms.untracked.int32(0),
G4TrackingManagerVerbosity = cms.untracked.int32(0),
UseMagneticField = cms.bool(True)
...
The first three (
untracked ...
) will determine the amount of information printed out while Geant4 performs tracing of each particle, primary or secondary. Turning them on may be useful for testing/debugging purposes;
for a generic simulation job, they need to stay off (0).
The fourth parameter in the list (
bool ...
) allows you to turn the magnetic field on/off,
depending on the type of the simulation study.
If you use standard cfi but you wish to modify, for example, the magnetic field switch, you can do it like this:
process.g4SimHits.UseMagneticField = False # this is your "replace" statement
Modeling of the physics processes that happen along the particle's path can be chosen
via this subset of the configuration cards:
Physics = cms.PSet(
.....
# NOTE : if you want EM Physics only,
# please select "SimG4Core/Physics/DummyPhysics" for type
# and turn ON DummyEMPhysics
#
type = cms.string('SimG4Core/Physics/QGSP_BERT_EML'),
DummyEMPhysics = cms.bool(False),
CutsPerRegion = cms.bool(True),
DefaultCutValue = cms.double(1.0), ## cuts in cm
G4BremsstrahlungThreshold = cms.double(0.5), ## cut in GeV
Verbosity = cms.untracked.int32(0),
# 1 will print cuts as they get set from DD
# 2 will do as 1 + will dump Geant4 table of cuts
.......
)
Here the QGSP_BERT_EML is the physics list based on the Bertini cascade model (in the intermediate energy
range) and on the quark-gluon string model (on the high energy end). Other available physics lists can be,
for example, LHEP (formerly known as Gheisha code) that is extensively based on the parametrization of
the experimental data for calorimeters. For testing purposes, some may employ so-called DummyPhysics lists that only know how to treat e- and mu- through matter.
For example, if you wish to select LHEP physics list over the default one (QGSP_BERT_EML), you can add the following statement:
process.g4SimHits.Physics.type = "SimG4Core/Physics/LHEP"
If you wish to select for Geant4 tracing to be done for only certain generated particles in a specific
kinematic region, you can apply the cuts to the generator's input; its default configuration is shown
below:
Generator = cms.PSet(
HectorEtaCut,
HepMCProductLabel = cms.string('generator'),
ApplyPCuts = cms.bool(True),
MinPCut = cms.double(0.04), ## the pt-cut is in GeV (CMS conventions)
MaxPCut = cms.double(99999.0), ## the ptmax=99.TeV in this case
ApplyEtaCuts = cms.bool(True),
MinEtaCut = cms.double(-5.5),
MaxEtaCut = cms.double(5.5),
ApplyPhiCuts = cms.bool(False),
MinPhiCut = cms.double(-3.14159265359), ## in radians
MaxPhiCut = cms.double(3.14159265359), ## according to CMS conventions
RDecLenCut = cms.double(2.9), ## the minimum decay length in cm (!) for mother tracking
Verbosity = cms.untracked.int32(0)
)
For example, if you wish to narrow the eta-range of interest from the default -/+5.5 to -/+1.5,
and raise the minimum P cut from 40MeV to 1GeV,
you can do so by adding the following statements:
process.g4SimHits.Generator.MinEtaCut = -1.5
process.g4SimHits.Generator.MaxEtaCut = 1.5
process.g4SimHits.Generator.MinPCut = 1. # in GeV
Configure Simulation Messages in the MessageLogger
At runtime, the level of verbosity of the simulation code can be controlled through a general service
of the framework called
MessageLogger. Different levels of verbosity (
DEBUG,
INFO,
WARNING,
ERROR) can be selected by the user, as well as output streams to which to send different messages
(
cout,
cerr, external files of user's choice). A minimalist example of use of
MessageLogger
is given in the detector simulation configuration files, suppressing essentially all the messages
(a limit on the number of messages can be set, and this limit can depend on the category of the
messages):
process.MessageLogger = cms.Service("MessageLogger",
cout = cms.untracked.PSet(
default = cms.untracked.PSet(
limit = cms.untracked.int32(0) ## kill all messages in the log
),
FwkJob = cms.untracked.PSet(
limit = cms.untracked.int32(-1) ## but FwkJob category - those unlimited
),
SimG4CoreApplication = cms.untracked.PSet(
limit = cms.untracked.int32(-1)
)
),
categories = cms.untracked.vstring('FwkJob', 'SimG4CoreApplication'),
destinations = cms.untracked.vstring('cout')
)
For a detailed explanation of all the features please see
SWGuideMessageLogger.
Configure Event Output
Event output, which is is performed the
PoolOutputModule module into a ROOT, may contain all persistent objects produced and stored in the event, or a selected subset of branches.
As already
pointed out earlier, with the use of
cmsDriver.py
utility the output is formed via the
--eventcontent
field.
For most production applications the subset called
RAWSIM is used.
Detailed description of the data formats/contents adopted in CMS is available in the
Data Format Table.
If you browse through config file from step 1, we will notice this statement:
process.load('Configuration/EventContent/EventContent_cff')
which brings in the top-level configuration fragment where various
b> subsets are "declared", although the actual "definitions" of what branches are included in one or another subset are distributed over many packages.
Once you specify to the cmsDriver.py
which of the standard event content you desire, it'll automatically compose PoolOutputModule for your application.
In our particular example you may notice the outputCommands
parameter it in the configuration:
process.RAWSIMoutput = cms.OutputModule("PoolOutputModule",
...
fileName = cms.untracked.string('file:RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_GEN-SIM-RAW.root'),
outputCommands = process.RAWSIMEventContent.outputCommands,
...
)
Note that if the outputCommands
is not provided, PoolOutputModule will write out the entire event content, which can be of a very large size.
In case your task calls for it, you can manually configure PoolOutputModule to write out only branches of interest to you; detailed information is provided in the SWGuideSelectingBranchesForOutput.
However, we would like to warn that you should understand very well what modules add one or another branch to the edm::Event
and how those branches are labeled.
Reproduce Simulated Events
Coming shortly
View the Simulated Events
The output of the simulation job is a ROOT file, and it can be easily browsed by the standard ROOT browser. But of course, for a more sophisticated analysis, you have to rely either on ROOT macros that load libFWCoreFWLite
, e.g.,
gSystem->Load("libFWCoreFWLite");
AutoLibraryLoader::enable() ;
or on the full power of the framework by writing your own EDAnalyzer module.
Detailed information is provided in the chapter 4 of the WorkBook, dedicated to Analysis and related materials.
Further Documentation
For general information on the CMSSW framework see WorkBookCMSSWFramework for an introduction.
Many useful links can be found:
The simulation development information is given in the hypernews
forum:
https://hypernews.cern.ch/HyperNews/CMS/get/simDevelopment.html
e-mail address: hn-simDevelopment@cern.ch
Questions related to the simulation should be sent to this forum.
Review status
Responsible: JuliaYarba
Last reviewed by: FilippoAmbroglini - 26 Feb 2008
6.4 The Standard Reconstruction procedure
Complete:
Detailed Review status
Goals of this page
This page explains how to run the standard reconstruction procedure after having generated and simulated
the events as explained in the previous chapters.
Note that if you just want to access the
already available samples, there is no need to run the reconstruction process again. It will only be necessary if you generate a sample of your own, or if you want to make modifications to the standard reconstruction.
Instructions
To run the standard CMS reconstruction, it's best to use the cmsDriver.py tool to generate a configuration file, which you can modify at will afterward.
Back/Forward Compatibility
Raw data is compatible with a large range of CMSSW versions. Therefore, in principle, you don't have to know what CMSSW version was used during data-taking to perform reconstruction from raw data. However, reconstruction from data is not supported in every CMSSW release.
Forward compatibility is not necessarily promised.
Global Tag
One important input to reconstruction is the global tag, which contains calibration, alignment, constants needed for reconstruction. (a link to global tag documentation). The global tags are softly tied to the release version (there might be compatibility problems due to change of formats of the data base content), so, one has to know what is the global tag certified for data reconstruction: check on SWGuideFrontierConditions.
cmsDriver Command
Simulation
cmsDriver.py reco -s RAW2DIGI,RECO --filein anInputRawFile.root --fileout anOutputFileName.root --globalTag GT::All
Data
Collision data
cmsDriver.py reco -s RAW2DIGI,RECO --filein anInputRawFile.root --fileout anOutputFileName.root --globalTag GT::All
Cosmic data
cmsDriver.py reco -s RAW2DIGI,RECO --data --scenario cosmics --filein anInputRawFile.root --fileout anOutputFileName.root --globalTag GT::All
The generated configuration file can then be tailored for other purposes or for crab job.
More... Close
Contents
Introduction
The algorithms that make up the CMS event reconstruction software build physics objects (e.g.,
muons, electrons, jets) from the raw data recorded by the detector. All events collected by the CMS
trigger system are reconstructed by the CMS prompt reconstruction system soon after being collected.
Description of the packages and configuration files
Reconstructing events to the level of candidates
There is a dedicated setup that provides a configuration file that contains standard definitions of the common and checked reconstructed objects, as supplied by the authors and PRS groups. Obviously there are many different settings in this file, so it is very advisable to take some time to study the settings for the objects you intend to use. Again, this file can be included like this:
include "Configuration/StandardSequences/data/Reconstruction.cff"
The output file
The Reconstruction.cff
does all reconstruction, but most users probably only want high-level reconstruction objects. This can be done by including
include "Configuration/EventContent/data/EventContent.cff"
Finally, to produce output you need to tell CMSSW to write everything to a file. This is done in the PoolOutput
module. This is also where you control what is written to file, it is very advisable to include only the information you need, this can be done with the drop
and keep
commands, see the documentation in https://twiki.cern.ch/twiki/bin/view/CMS/WorkBookWriteFrameworkModule#WritE.
Run the example
First, set up the CMS environment. The following works on lxplus.cern.ch
, but should work on any computer that has CVS and the CMS software installed.
cmsrel CMSSW_10_2_Y
cd CMSSW_10_2_Y/src
cmsenv
Now check out the page in Generation in this document to see the previous steps need to run before the step RECO.
cmsDriver.py step2 --filein file:BPH-RunIIAutumn18DR_step1.root --fileout file:BPH-RunIIAutumn18DR_step2.root --mc --eventcontent AODSIM --runUnscheduled --datatier AODSIM --conditions 102X_upgrade2018_realistic_v15 --step RAW2DIGI,L1Reco,RECO,RECOSIM,EI --nThreads 8 --geometry DB:Extended --era Run2_2018 --python_filename BPH-RunIIAutumn18DR_2_cfg.py --no_exec --customise Configuration/DataProcessing/Utils.addMonitoring -n 100
Conclusion and Outlook
This page explains how to run a very simple analysis, all the way from event generation to the analysis of reconstructed objects
Review status
Responsible: JeanRochVlimant
Last reviewed by: AndreaRizzi - 27 Feb 2008
6.5 Simulating and Reconstructing events with Fast Simulation
Recipe for 13TeV (CMSSW_9_2_X)
Please check with your PAG/POG if they require specific conditions.
cmsrel CMSSW_9_2_10
cd CMSSW_9_2_10/src
cmsenv
No packages need to be checked, but for the sake of being more organized, you can create and work within FastSimulation/GenProduction
.
For simulating a MinBias sample with no PU, use the following cmsDriver command. You always can replace the MinBias generator fragment with your favorite fragment.
SIMULATION WITHOUT PU:
cmsDriver.py MinBias_13TeV_pythia8_TuneCUETP8M1_cfi --conditions auto:run2_mc --fast -n 1000 --era Run2_25ns --eventcontent AODSIM -s GEN,SIM,RECOBEFMIX,DIGI:pdigi_valid,RECO --datatier GEN-SIM-DIGI-RECO --beamspot Realistic25ns13TeVEarly2017Collision
To simulate physics samples with PU we show the standard mixing method and we need a MinBias sample to proceed with this example. In the meanwhile private MinBias samples can be generated using the example below.
cmsDriver.py MinBias_13TeV_pythia8_TuneCUETP8M1_cfi --conditions auto:run2_mc --fast -n 1000 --era Run2_25ns --eventcontent FASTPU \
-s GEN,SIM,RECOBEFMIX,DIGI:pdigi_valid,RECO --datatier GEN-SIM-RECO --beamspot Realistic25ns13TeVEarly2017Collision
SIMULATION WITH PU:
cmsDriver.py MinBias_13TeV_pythia8_TuneCUETP8M1_cfi --conditions auto:run2_mc --fast -n 100 --eventcontent AODSIM -s GEN,SIM,RECOBEFMIX,DIGI:pdigi_valid,RECO --datatier AODSIM --beamspot Realistic25ns13TeVEarly2017Collision --era Run2_25ns --pileup_input file:MinBias_13TeV_pythia8_TuneCUETP8M1_cfi_GEN_SIM_RECOBEFMIX_DIGI_RECO.root --pileup AVE_35_BX_25ns
-- LukasVanelderen - 08 Jul 2014
-- ElizaMelo - 04 Oct 2017