Heavy Ion PAT
Complete:
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:
process.load("CMS.PhysicsTools.PatAlgos.patHeavyIonSequences_cff")
- 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.
Input
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
.
Output
The objects that are produced by the heavy-ion PAT sequences are given in the table below. This list is defined in
patHiEventContent
.
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
).
pat::HeavyIon
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
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"
...
void
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
- For further information on PAT in general, see
- HeavyIonPatCompatibility - initial list of which existing PAT components worked in heavy ion events
- HeavyIonPatDevelopment - June 2009 statement about status and plans for PAT in heavy ion events.
Contact
- Hypernews fora:
- Contacts/Developers: Edward Wenger, Yen-Jie Lee, Yetkin Yilmaz, Eric Appelt
Review status
Responsible:
YetkinYilmaz