Heavy Ion PAT

Complete: 1

Goal of this page

The aim of this page is to document the Physics Analysis Toolkit (PAT) sequence developed for use with heavy ion events—where the code lives, how to run it, the input and output, and details of the implementation. This page assumes that the reader has a basic familiarity with PAT. Details and tutorials on the basic use of the PAT can be found at SWGuidePAT, WorkBookPATTupleCreationExercise, WorkBookPATTutorial, and WorkBookAnalysisStarterKit.

Code and tags

The configuration files containing the heavy-ions PAT sequences live in the directory CMS.PhysicsTools/PatAlgos/python/producersHeavyIons.

The configuration file which runs the heavy-ions PAT sequence lives one directory up, CMS.PhysicsTools/PatAlgos/python/patHeavyIonSequences_cff.py

The plugin which produces the pat::HeavyIon object (see below) lives in CMS.PhysicsTools/PatAlgos/plugins/PATHeavyIonProducer.cc, while the pat::HeavyIon object itself is defined in the package DataFormats/HeavyIonEvent.

From CMSSW 3_4_0 onwards, heavy ion PAT sequences will be in the official release. For 3_3_X you need to check out the HEAD versions of the following packages from CVS:

cvs co RecoHI/HiJetAlgos
cvs co RecoHI/HiEgammaAlgos/python
cvs co PhysicsTools/PatAlgos/python/producersHeavyIons
then recompile scramv1 b

Quick running instructions

PAT requires RECO-level objects as input. If the events you're interested in are not yet reconstructed, run the reconstruction using Configuration/StandardSequences/python/ReconstructionHeavyIons_cff.py.

If you already have a reco file for input, then in your configuration file (cfg)

  • load the file containing the PAT sequence:

  • add a path to run the sequence:
process.producePat = cms.Path(process.patHeavyIonDefaultSequence)

  • load the file to define the PAT event content
from CMS.PhysicsTools.PatAlgos.patEventContent_cff import patEventContent

  • add the predefined event content patHiEventContent and patHiExtraAodEventContent to your output module, as in the example below.
process.out = cms.OutputModule("PoolOutputModule",
                               fileName = cms.untracked.string('HeavyIonPat.root'),
                               SelectEvents   = cms.untracked.PSet( SelectEvents = cms.vstring('producePat') ),
                               outputCommands = cms.untracked.vstring('drop *', *patHiEventContent, *patHiExtraAodEventContent ) 
NB: the * in front of patHiEventContent and patHiExtraAodEventContent is necessary to unpack the array of commands contained within them.


Just as the p+p PAT takes the standard RECO or AOD as input, the heavy-ion PAT takes the output of the standard heavy-ion reconstruction as input. The modules which are run for the heavy-ion reconstruction can be found in the configuration file RecoHI/Configuration/python/Reconstruction_HI_cff.py. The corresponding event content can be obtained from the configuration files included in RecoHI/Configuration/python/RecoHI_EventContent_cff.py.


The objects that are produced by the heavy-ion PAT sequences are given in the table below. This list is defined in patHiEventContent.
Product type Module label
std::vector<pat::Muon> selectedlayer1Muons
std::vector<pat::Photon> selectedlayer1Photons
std::vector<pat::Jet> selectedlayer1Jets
pat::HeavyIon heavyIon

An additional set of objects is defined in patHiExtraAodEventContent. These are objects which are not produced by PAT (hiSelectedTracks, hiGenParticles), or are produced only for MC and thus would not be produced for data (hiGenParticles, iterativeCone5HiGenJets).

Product type Module label
reco::TrackCollection hiSelectedTracks
reco::GenParticleCollection hiGenParticles
reco::GenJetCollection iterativeCone5HiGenJets


This object is only produced by the heavy-ion PAT sequence. One pat::HeavyIon object per event is produced, which contains the heavy-ion specific GEN level information, the CentralityCollection and the EvtPlaneCollection for the event. The automatically-generated documentation for this class can be found at pat::HeavyIon; a short description of each element is given below.

Heavy Ion MC information

In the case of a Monte Carlo event, the pat::HeavyIon object contains the generated values of heavy-ion specific parameters. The functions use to retrieve them are listed in the table below. For a real data event, the values of the parameters are set to -99 or false for isMC().
Data type Function Description
double generatedB () Impact parameter in fm
double generatedEvtPlane () Event plane angle in radians
int generatedNcoll () Number of nucleon-nucleon collisions
int generatedNhard () Number of hard parton interactions
int generatedNpart () Number of participant nucleons
bool isMC () Flag indicating whether the event is a Monte Carlo simulation or not

Centrality information

Data type Function Description
const reco::CentralityCollection getCentralityCollection () Get CentralityCollection

Within the pat::HeavyIon object, centrality information is kept in a reco::CentralityCollection. Please refer to SWGuideHeavyIonCentrality for more details on how to access the centrality information, and instructions on how to use the HeavyIon object to bin a sample.

Event Plane information

Within the pat::HeavyIon object, event plane information is kept in a reco::EvtPlaneCollection. Please refer to SWGuideHeavyIonEvtPlaneReco for more details on how to access the event plane information.

Example of accessing the PAT Objects

Basic examples for p+p PAT can be found at WorkBookPATAccessExercise and WorkBookPATExampleFWLite. More examples can be found at WorkBookPATTutorial. Jets, muons and photons within the heavy-ion PAT can be accessed in exactly the same way as in these examples. The pat::HeavyIon object can be accessed in an analogous way, though it is slightly different, in that it is not just a std::vector of one type of object. The following code fragment shows how to access some of the information in the pat::HeavyIon object within the framework of the example in WorkBookPATAccessExercise.

#include "DataFormats/HeavyIonEvent/interface/HeavyIon.h"
PatBasicAnalyzer::analyze(const edm::Event& iEvent, const edm::EventSetup& iSetup)
  // get HeavyIon object
  edm::Handle<pat::HeavyIon>  heavyIonHandle;
  iEvent.getByLabel("heavyIon", heavyIonHandle);

   // Check if there was a problem accessing the HeavyIon object
   if( !heavyIonHandle.isValid() ){
     cout << "Error! Can't get heavyIon object!" << endl;
     return ;

  // For Monte-Carlo events
  if(heavyIonhandle->isMC() ){
    cout << "Monte Carlo event. Generated impact parameter is " << heavyIonHandle->generatedB()
           <<  ", generated event plane angle is " << generatedEvtPlane () << endl;

  // get raw Centrality values
  const reco::CentralityCollection centcoll = heavyIonHandle->getCentralityCollection ();
  for(reco::CentralityCollection::const_iterator cent = centcoll->begin(); cent != centcoll->end(); cent++){
    cout << cent->label() << " " << cent->raw() << endl;

  //No getter function yet for EvtPlaneCollection !

Implementation details

The diagram below shows the relationships between the configuration files and sequences which comprise the heavy ion PAT sequence. Most of these files reside in CMS.PhysicsTools/PatAlgos/python or its subdirectories. Red boxes indicate heavy-ion specific files or sequences. Clicking on the box will take you to the CVS version of the corresponding configuration file.

digraph G { node [shape="none"] graph [rankdir=LR, size="9.5,7.5" ]

heavyIonGenJetCleaner [label="producersHeavyIons/heavyIonGenJetCleaner_cfi" color="red" shape="box" URL="http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/CMS.PhysicsTools/PatAlgos/python/producersHeavyIons/heavyIonGenJetCleaner_cfi.py"]

importJetProducer [label="producersLayer1/jetProducer_cff" shape="box" URL="http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/CMS.PhysicsTools/PatAlgos/python/producersLayer1/jetProducer_cff.py"]

subgraph cluster_jets { graph [label="producersHeavyIons/heavyIonJets_cff" color="red" URL="http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/CMS.PhysicsTools/PatAlgos/python/producersHeavyIons/heavyIonJets_cff.py"] makeHeavyIonJets [label="\nmakeHeavyIonJets = cms.Sequence(\n jetCorrFactors *\n heavyIonCleanedGenJets *\n jetGenJetMatch *\n allLayer1Jets )"] }

heavyIonGenJetCleaner->makeHeavyIonJets; importJetProducer->makeHeavyIonJets;

importMuonProducer [label="producersLayer1/muonProducer_cff" shape="box" URL="http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/CMS.PhysicsTools/PatAlgos/python/producersLayer1/muonProducer_cff.py"]

subgraph cluster_muons { graph [label="producersHeavyIons/heavyIonMuons_cff" color="red" URL="http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/CMS.PhysicsTools/PatAlgos/python/producersHeavyIons/heavyIonMuons_cff.py"] makeHeavyIonMuons [label="makeHeavyIonMuons = cms.Sequence(\n muonMatch *\n allLayer1Muons\n )"] } importMuonProducer->makeHeavyIonMuons;

importPhotonProducer [label="producersLayer1/photonProducer_cff" shape="box" URL="http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/CMS.PhysicsTools/PatAlgos/python/producersLayer1/photonProducer_cff.py"] importIso [label="RecoHI/HiEgammaAlgos/python/HiEgammaIsolation_cff" shape="box" color="red" URL="http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/RecoHI/HiEgammaAlgos/python/HiEgammaIsolation_cff.py"]

subgraph cluster_photons { graph [label="producersHeavyIons/heavyIonPhotons_cff" color="red" URL="http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/CMS.PhysicsTools/PatAlgos/python/producersHeavyIons/heavyIonPhotons_cff.py"] makeHeavyIonPhotons [label="makeHeavyIonPhotons = cms.Sequence(\n hiEgammaIsolationSequence *\n patPhotonIsolation *\n photonMatch *\n allLayer1Photons )"] } importPhotonProducer->makeHeavyIonPhotons; importIso->makeHeavyIonPhotons;

heavyIonProducer [label="producersHeavyIons/heavyIonProducer_cfi" color="red" shape="box" URL="http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/CMS.PhysicsTools/PatAlgos/python/producersHeavyIons/heavyIonProducer_cfi.py"]

subgraph cluster_objects { graph [label="producersHeavyIons/heavyIonObjects_cff.py" color="red" URL="http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/CMS.PhysicsTools/PatAlgos/python/producersHeavyIons/heavyIonObjects_cff.py"] heavyIonObjects [label="heavyIonObjects = cms.Sequence(\n heavyIon +\n makeHeavyIonJets +\n makeHeavyIonPhotons +\n makeHeavyIonMuons )" shape="none"] } heavyIonProducer->heavyIonObjects; makeHeavyIonJets->heavyIonObjects; makeHeavyIonMuons->heavyIonObjects; makeHeavyIonPhotons->heavyIonObjects;

selectedLayer1Objects [label="selectionLayer1/selectedLayer1Objects_cff" URL="http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/CMS.PhysicsTools/PatAlgos/python/selectionLayer1/selectedLayer1Objects_cff.py" shape="box"]

subgraph cluster_sequence { graph [label="patHeavyIonSequences_cff" color="red" URL="http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/CMS.PhysicsTools/PatAlgos/python/patHeavyIonSequences_cff.py"] patHeavyIonDefaultSequence [label="patHeavyIonDefaultSequence = cms.Sequence(\n heavyIonObjects * \n selectedLayer1Jets *\n selectedLayer1Muons *\n selectedLayer1Photons )"] } heavyIonObjects->patHeavyIonDefaultSequence; selectedLayer1Objects->patHeavyIonDefaultSequence;

subgraph cluster_content{ graph [label="patEventContent_cff" color="red" URL="http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/CMS.PhysicsTools/PatAlgos/python/patEventContent_cff.py"] patHiEventContent [label="patHiEventContent = [\n 'keep patPhotons_selected*_*_*',\n 'keep patMuons_selected*_*_*',\n 'keep patJets_selected*_*_*',\n 'keep patHeavyIon_heavyIon_*_*' ]"]

patHiExtraAodEventContent [label="patHiExtraAodEventContent = [\n 'keep recoGenParticles_hiGenParticles_*_*',\n 'keep recoGenJets_iterativeCone5HiGenJets_*_*',\n 'keep recoTracks_hiSelectedTracks_*_*' ]"] } {rank=same; patHeavyIonDefaultSequence; patHiEventContent; patHiExtraAodEventContent} }

The main sequence, patHeavyIonDefaultSequence (bottom right box) creates the PAT objects, then runs the standard PAT selection for the jets, muons and photons. (Note that it does not run the "cleaners".) The list of objects to keep is defined in the file patEventContent_cff.py. The sequences to create the individual objects are defined in another set of configuration files (second column). These sequences in turn use the standard PAT layer1 producers with no modifications (for muons), with heavy-ion specific isolation criteria (photons) or with a heavy-ion version of generator-level jet reconstruction (jets). The pat::HeavyIon object is obviously not produced by the standard p+p PAT sequences; instead the file producersHeavyIons/heavyIonProducer_cfi.py specifies a PATHeavyIonProducer.

Further Information


Review status

Reviewer/Editor and Date Comments
EricAppelt - 10 Aug 2009 created page as part of documentation review
YetkinYilmaz - 28-Oct-2009 updated to 3_4_X implementations
PhilipAllfrey - 12-Nov-2009 Added input, output, example and implementation details

Responsible: YetkinYilmaz

Edit | Attach | Watch | Print version | History: r17 < r16 < r15 < r14 < r13 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r17 - 2013-09-05 - JianSun
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    CMSPublic All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2021 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback