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 of 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
• Multithreading in generators
• 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 produce 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 /genfragments 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 the 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 you 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: RandomNumberGeneratorService

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 create 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 "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 you 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_pythia8_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

curl -s --insecure https://raw.githubusercontent.com/cms-sw/cmssw/CMSSW_10_2_X/Configuration/Generator/python/SingleElectronPt10_pythia8_cfi.py --retry 2 --create-dirs -o Configuration/GenProduction/python/SingleElectronPt10_pythia8_cfi.py [ -s Configuration/GenProduction/python/SingleElectronPt10_pythia8_cfi.py ]

scram b

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/genfragments 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/genfragments/ThirteenTeV/RSGraviton/RSGravitonToZZ_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 https://raw.githubusercontent.com/cms-sw/genproductions/master/genfragments/ThirteenTeV/RSGraviton/RSGravitonToZZ_kMpl01_M_1000_TuneCUETP8M1_13TeV_pythia8_cfi.py, 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 a 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 a 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 the 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 referenced 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 events will be filtered out of the output because the event generation step is included in the "production filtering sequence":

ProductionFilterSequence = cms.Sequence(generator)

(which will, later on, 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:

• 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. 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 the 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 downloaded 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.

Multithreading in generators

A variety of multi-thread methods are introduced in the generation step since CMSSW_10_6_X to benefit the ultra-legacy reprocessing and the future event production. They are designed to cooperate with many different types of generators.

The event production speed and CPU efficiency can be significantly improved after enabling these multi-thread methods in the fragment. For detailed documentation, please visit the guide WorkBookGenMultithread.

Further documentation

For general information on the CMSSW framework see WorkBookCMSSWFramework for an introduction and on 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

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 an original tutorial for May 2006 CPT week

Last reviewed by: RobertoChierici - 27 Feb 2008