4.4 Generator event format in AOD

Complete:
Detailed Review status

Goals of this page:

This page documents the event generator format stored in AOD.

Contents

• Introduction
• GenParticle: Generator Particle Candidate
• Generator Particles Collections
• GenParticle Conversion from HepMCProduct
• Decay Tree Drawing Utilities
• Particle List Utility
• Related Documents
• Review Status

Introduction

Generator event in AOD takes about half the size of native HepMC events. This is done using a particle representation that inherits from reco::Candidate.

GenParticle: Generator Particle Candidate

Generator particles are represented by the classes GenParticle which inherit from reco::Candidate It contains a four-momentum, charge, vertex and:

• a PDG identifier (pdg_id() in HepMC::GenParticle)
• a status code (status() in HepMC::GenParticle). Standard status codes are described in HepMC manual, and have the following convention in Pythia6 (see below):

  0	null entry
  1	particle not decayed or fragmented, represents the final state as given by the generator
  2	decayed or fragmented entry (i.e. decayed particle or parton produced in shower.)
  3	identifies the "hard part" of the interaction, i.e. the partons used in the matrix element calculation, including immediate decays of resonances. (documentation entry, defined separately from the event history. "This includes the two incoming colliding particles and partons produced in hard interaction." [ * ])
  4-­10	undefined, reserved for future standards
  11-­200	at the disposal of each model builder equivalent to a null line
  201-...­	at the disposal of the user, in particular for event tracking in the detector

IMPORTANT: Other generators have other conventions. (e.g. Those for Pythia8 are described in the documentation for the statusHepMC function in EventRecord.html . They mainly differ from the Pythia6 ones in that status = 3 is no longer used.). The only thing you can really rely on is that 'stable' particles (=those handed over to Geant or fastsim in the simulation which are those with decay length > 2cm) have status=1.

For some other generators' conventions, see for instance:

• Herwig
• Pythia8

Generator Particles Collections

The default generator particle collection is reco::GenParticleCollection, which is a typedef for std::vector<reco::GenParticle>.

Generator particles contain mother and daughter links to particles in the same collection, as sketched below.

An example to access this collection is the following analyzer code fragment:

#include "DataFormats/HepMCCandidate/interface/GenParticle.h"
using namespace reco;

void MyModule::analyze(const edm::Event & iEvent, ...) {
   Handle<GenParticleCollection> genParticles;
   iEvent.getByLabel("genParticles", genParticles);
   for(size_t i = 0; i < genParticles->size(); ++ i) {
     const GenParticle & p = (*genParticles)[i];
     int id = p.pdgId();
     int st = p.status();  
     const Candidate * mom = p.mother();
     double pt = p.pt(), eta = p.eta(), phi = p.phi(), mass = p.mass();
     double vx = p.vx(), vy = p.vy(), vz = p.vz();
     int charge = p.charge();
     int n = p.numberOfDaughters();
     for(size_t j = 0; j < n; ++ j) {
       const Candidate * d = p.daughter( j );
       int dauId = d->pdgId();
       // . . . 
     }
     // . . . 
   }
}

Up-to-date code examples can be searched by using link

GenParticle Conversion from HepMCProduct

GenParticles are saved by default in FEVT, RECO and AOD.

If you run the generator yourself, you may need to convert the output of the generator in the HepMC format to the AOD format using the module GenParticleProducer.

You need to add the following configuration files to your script:

include "SimGeneral/HepPDTESSource/data/pythiapdt.cfi"
include "CMS.PhysicsTools/HepMCCandAlgos/data/genParticles.cfi"

and remember to add at the beginning of your path the module:

• genParticles

Decay Tree Drawing Utilities

The modules ParticleTreeDrawer and ParticleDecayDrawer print the generated decay tree to provide a visual inspection. The modules can be configured with different options to print different levels of details. More information in the page below:

• ParticleTreeDrawer
• ParticleDecayDrawer

Particle List Utility

The module ParticleListDrawer dumps the fully generated event in a way similar to the command PYLIST in Pythia. More information in the page below:

• ParticleListDrawer

#New Dataset Format

New Dataset Format

At the end of Run 1, a new format reducing the event size by one order of magnitude with respect to AOD was designed, with little impact on physics analyses. This format is known to be MiniAOD. The space consumed per event is even more reduced with the new dataset format called NanoAOD, to 1-2 kB per event. It is around 20 times smaller than the miniAOD data format and it is going to be used as a default data format for Run 3. It is not a CMSSW EDM file but several EDM features are available. NanoAOD is based on bare ROOT TTrees, similar to the format of user ntuples. It is compact enough to be produced easily on large datasets without event preselection. The time needed for a full set of NANOAOD samples to be produced from existing MINIAOD is expected to be the order of 1 week for 1 year of data, approximately about 10 billion events.

The names of physics objects are the root part of all branch names. Each branch has built-in documentation, to get the description of the content of a branch. You can access the description easily:

Events->GetBranch("Electron_pt")->GetTitle()

The example list of branches and short descriptions are available here.

A set of tools has also been created to further processing of NANOAOD files, keeping the same format in input and output - nanoAOD tools. For working with NanoAOD tools only Python and ROOT are required but not CMSSW. The script to run the post-processing step is scripts/nano_postproc.py. It is possible to import modules that will be run on each entry passing the event selection, and can be used to calculate new variables that will be included in the output tree (both in friend and full mode) or to apply event filter decisions - python/postprocessing/examples/exampleModule.py.

The event interface is defined in PhysicsTools.NanoAODTools.postprocessing.framework.datamodule. It allows to dynamically construct views of objects organized in collections:

electrons = Collection(event, "Electron")
if len(electrons)>1: print electrons[0].someVar+electrons[1].someVar
electrons_highpt = filter(lambda x: x.pt>50, electrons)

Event variables can be accessed simply by event.someVar, for instance, event.rho.

Related Documents

• MC Truth Matching Tools Workbook Section
• Particle Candidates Workbook Section

Review status

Reviewer/Editor and Date (copy from screen)	Comments
Main.Aresh - 21 Feb 2008	changed the title chapter (the number was 4.4 instead of being 4.5)
LucaLista - 27 Mar 2007	author
JennyWilliams - 11 Dec 2006	Moved to workbook, added contents, added review info

Responsible: LucaLista
Last reviewed by: PetarMaksimovic - 28 Feb 2008