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.

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

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

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

[ps]

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
  • SWGuidePAT
  • WorkBookPATTupleCreationExercise
  • WorkBookPATTutorial, and
  • WorkBookAnalysisStarterKit.
• 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:
  • Software issues: https://hypernews.cern.ch/HyperNews/CMS/get/hiswDevelopment.html, (hn-cms-hiswDevelopment@cernNOSPAMPLEASE.ch)
  • General heavy ions issues https://hypernews.cern.ch/HyperNews/CMS/get/hi.html, (hn-cms-hi@cernNOSPAMPLEASE.ch)
• Contacts/Developers: Edward Wenger, Yen-Jie Lee, Yetkin Yilmaz, Eric Appelt

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