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.

For Run2-CMSSW_8_0_X

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")

Next block in the configuration file that will be of interest to you is the one that starts with

process.generator = cms.EDFilter("Pythia8GeneratorFilter",

• 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).

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')

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)

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
...                                  

Review status

Responsible: JuliaYarba
Last reviewed by: DanielElvira - 15 Nov 2006

6.2 Generating Events

Goals of this page

• 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
• Event Generation Software and Existing Applications
• Related Software Components
  • Event Loop Drivers: the Sources
  • Particle Property Table
  • Random number generator initialization
• Generator Dataformat
• Sample Configuration Files for the Particle Gun
• Sample Configuration File for Pythia8 Event generation
• Sample Configuration for Processing MadGraph Events with Pythia8
• Sample Configuration for Creating Powheg Events and Processing them with Pythia8
• Accessing particle level MC data
• Filtering generator events
• Further Documentation

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')

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 

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",

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
),

this paper

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)

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')
)

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:

• Madgraph5_aMCatNLO
• POWHEG

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

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"     

• • 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:

• https://github.com/cms-sw/cmssw github allows to browse the code
• https://cmssdt.cern.ch/SDT/doxygen/ Doxygen provides a basic documentation of the code itself

Review status

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
• Simulation Software and Existing Applications
  • How to Find and Run Example Simulation Application
  • How to Compose a Simulation Application Using Standard Utilities
  • Walk-through Configuration File: Simulation Related Steps and Components
    • Random Number Engine and Seed Settings
    • Add Vertex Smearing
    • Geometry and Magnetic Field
    • Detector Simulation Module: OscarProducer
    • Modeling Detector Response
      • PileUp Simulation: Mixing Module
      • Tracker Digitization
      • Calorimeter Digitization
      • Muon System Digitization
• Output Data Format
• Additional How-To's
  • Change Some of the OscarProducer's Parameters
  • Configure Simulation Messages in the MessageLogger
  • Configure Event Output
  • Reproduce Simulated Events
  • View the Simulated Events
• Further Documentation
• Review Status

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.

cmsrel CMSSW_X_Y_Z
cd CMSSW_X_Y_Z/src
cmsenv

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')

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")

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')

from SimG4Core.Configuration.SimG4Core_cff import *

from SimG4Core.Application.g4SimHits_cfi import *

SimG4Core/Application/python/g4SimHits_cfi.py

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')

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 *

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 *

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 *

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

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 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)
    )

   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')

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:

• http://cms.cern.ch/iCMS/jsp/page.jsp?mode=cms&action=url&urlkey=CMS_OFFLINE CMS Offline Page
• [[https://github.com/cms-sw/cmssw/tree/CMSSW_10_2_X] WebGIT allows to browse the code
• http://cmsdoc.cern.ch/cms/cpt/Software/html/General/gendoxy-doc.php Doxygen provides a basic documentation of the code itself

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

Reviewer/Editor and Date (copy from screen)	Comments
ElizaMelo - Dec 2019	Major update towards CMSSW_10_2_X
ElizaMelo - 30 Aug 2017	Major update towards CMSSW_9_X_X
JuliaYarba - 24 Aug 2009	Major update towards CMSSW_3_X_X
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

Responsible: JuliaYarba
Last reviewed by: FilippoAmbroglini - 26 Feb 2008

---

---

6.4 The Standard Reconstruction procedure

Complete:
Detailed Review status

Newsbox
To be updated with material in http://indico.cern.ch/getFile.py/access?contribId=3&resId=0&materialId=slides&confId=65275.

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
• Description: Used packages and configuration files
  • Reconstructing events to the level of candidates
• Running the example
• Conclusion and Outlook
• Review status

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

Reviewer/Editor and Date (copy from screen)	Comments
ElizaMelo - Sept 2019	Included instructions for CMSSW_10_2_Y
ElizaMelo - Sept 2017	Included instructions for CMSSW_9_X_Y
FreyaBlekman - 10 Oct 2007	Update to more general tutorial using default .cfg files and CMSSW_1_6_0
FreyaBlekman - 25 Jan 2007	Included instructions for CMSSW_1_2_0
JennyWilliams - 05 Dec 2006	Put all links explicit for PRINT variable
FreyaBlekman - 14 Nov 2006	Upgraded to CMSSW_1_0_6
FreyaBlekman - 21 Sep 2006	Upgraded to CMSSW_1_0_0
FreyaBlekman - 24 Jun 2006	created tutorial for CMSSW 0_7_0

Responsible: JeanRochVlimant
Last reviewed by: AndreaRizzi - 27 Feb 2008

---

---

6.5 Simulating and Reconstructing events with Fast Simulation

• Find the FastSim users guide here: SWGuideFastSimulation (public)
• Find the general FastSim start page here: FastSim (CMS only)
• The outdated workbook page has been moved to WorkBookFastSimulationArchive (public)

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