9.1 Overview of ECAL Objects and Software

Complete: 5
Detailed Review status

Goals of this page:

Learn to access and analyse ECAL objects in the CMSSW framework. This first section gives a basic overview of ECAL objects, and how to interact with them. Practical exercises with expected output are presented in the next section, SWGuideEcalRecoTutorials.


This tutorial will contain a brief introduction to ECAL objects and software within CMSSW.

ECAL software in CMSSW

DetId objects

Each component of the CMS detctor, ranging from one subdetector (HCAL, TK et cetera) to one of its component (e.g. a crystal of ECAL, a supercrystal in the ECAL barrel) is identified by a dedicated data type called a DetId object.

A DetId holds, among its data members, a 32-bit unsigned integer which uniquely identifies each part of CMS. Together with the 32-bit unsigned integer, the DetId has methods which provide different sets of coordinates pertaining to CMS sub-portion being considered, for instance the iphi or ieta of a given ECAL barrel crystal. The most significant bits identify the subdetector of CMS, while the following bits refer to parts within the subdetectors, as shown in the image below.


Within the electromagnetic calorimeter, the following subdetectors are identified:

  • EB (Barrel)
  • EE (Endcap)
  • ES (Preshower)
  • EcalTriggerPrimitives (the trigger data produced summing the transverse energy of the crystals in a trigger tower)

The DetId 's of the calorimeters, ECAL and HCAL, have been designed to match the topology of the detector in a natural and useful way, using polar (ieta/iphi) or cartesian (x/y) coordinates as appropriate. For example, the ecal barrel (EB) is an eta/phi grid with the ranges

  • IETA: -85 --> +85
    • with no crystal at IETA=0
  • IPHI: 1 --> 360
whereas the ecal endcap (EE) is represented by an X/Y grid where
  • X and Y run from 1 to 100
  • Note: many X/Y pairs don't map to any existing crystal since the centre of the endcap is void to admit the beampipe and since the endcap has a circular profile while the used coordinates naturally describe a square.

The ECAL barrel is divided in two parts along the CMS z direction (parallel to the beamline): the positive (EB+) and negative (EB-) part of the barrel. Both such halves are divided in 18 phi wedges covering 20 degrees, each wedge being named with an integer following the EB+ or EB- prefixes (EB+07, EB-11). Such wedges, referred to as supermodules, have been built all the same and represent one readout unit from the data acquisition point of view. Each of the two ECAL endcaps consist of two halves separated by a vertical sect, each half being referred to as one Dee. Each endcap is subdivided in 9 readout sectors.

Often ECAL channels are also identified using an index which is local to the readout unit. Commonly used, in the case of the Ecal Barrel (EB), is:

  • the crystal number ic, which ranges from 1 to 1700 inside each of the 36 supermodules of the barrel, together with
  • an index which identifies the supermodule.
For more details on ECAL channel numbering see CMS IN-2006/027 - CMS ECAL Endcap Channel Numbering and CMS IN-2005/021 - CMS ECAL Barrel Channel Numbering.


Data tiers within the calorimetry software

The data read data from the detector and Monte Carlo data are both stored in 5 layers within the ECAL software, each representing a different step in the heirarchy of the reconstruction. This is illustrated in the diagram, and explained in more detail below:


Data Layer 0 - The RAW data
All of the CMS detector components use the same class (FEDRawData) to hold the raw data which is read out from each FED (front end digitizer). Note that each subdetector in CMS has multiple FEDs, ECAL has 54, 9 in each endcap and 36 in the barrel. The raw data can be seen as an array of formatted 64-bit unsigned integers which are read from the detector front end electronics and saved to persistency by the data acquisition (DAQ) system. The data for many channels is bundled together according to the raw data format schema. Looking directly at the hexadecimal codes of the raw data is useful to the experts when there are problems with the readout which violate the data format rules. For usage of most of the people, the raw data is parsed and converted into digis (layer 1 objects) in the Raw2Digi (or unpacking process).

Monte Carlo Layer 0 - Sim Hits (SimDataHit/CaloHit objects)
The simulation process begins with an event generator followed by the Geant-based simulation of the interactions between the particles and the detector. The output of the simulation is a set of simulated energy deposits (with deposit times) in detector channels. These energy deposits are stored in the event as SimHits. The SimHits are labelled by DetIds and are analogous to real data "RAW data". SimHits are converted into digis (layer 1 objects, the same as for real data) in the electronics simulation or "digitization process". In order to simulate the pileup at CMS, the digitization process can superimpose to the generated events SimHits from "minimum-bias" previously generated .

Layer 1 - Digis
Digis are the per-channel data from the detector. Each is labeled by a DetId. For the crystals in EB and EE, a digi is a set of ADC readings for a given event. In normal conditions, there are 10 time samples for each of the channels which are readout: 3 readings before the triggered bunch-crossing and 7 readings containing the maximum pulse. Each sample consists of an ADC word (12 bits) and to bits used to encode the gain (x12, x6 and x1 are the gains available). Digis show the pulse shape of the detector and are used to reconstruct the energy and time of the hit in the calorimeter.

Layer 2 - UncalibratedRecHit
UncalibratedRecHits are used to store the quantities reconstructed starting from the digis (each UncalibratedRecHit is identified by the same DetId as the digi it comes from). For ECAL the quantities are four: amplitude (the peak of the pulse shape), pedestal (the baseling), jitter (the time when the maximum of the pulse shape occurs) and chi2. There are different algorithms to produce UncalibratedRecHit's which will be described in the following.

Layer 3 - RecHits
RecHits are obtained from UncalibratedRecHits by:
  • applying a global scale factor ADCtoGeV which turns the ADC counts into GeV;
  • applying the calibration constants.

Layer 4 - Composite Hits or Clusters
these are the first stage of higher level reconstructed objects which are built combining groups of detector objects identified as coming from the same physics object. These are the objects used in basic data analysis projects, examples being EcalClusters (built from a group of RecHits) or CaloTowers (which combined ECAL and HCAL RecHits)

Practical details on how to access each of the 4 layers here described and used them for analysis is given in the ECAL Reconstruction Tutorials page.


Test Beam specific data formats

In the test beam environment, there are pieces of hardware such as:

  • hodoscopes (tracking chamber built with scintillating fibers available at the CERN H4 test beam line to give the position of the incoming particles before they hit the crystals)
  • scintillators (providing the trigger and timing measurements)
  • table holding the ECAL: providing the position of the crystals with respect to the beam line
  • scalers: counters for various quantities, e.g. the total number of particles impinging on the detectors
which can provide raw data data. Since they are not foreseen in the CMS standard environment, dedicated objects are needed to handle the information they provide. These objects are generally TBDataFormats or EcalObjects. Specific data formats for the test beam which have been implemented in CMSSW in 2006 and used since then include:

  • Layer 1 data formats (digis)
    • EcalTBHodoscopeRawInfo
    • EcalTBTDCRawInfo
  • Layer 2 data formats (reco objects)
    • EcalTBHodoscopeRecInfo
    • EcalTBTDCRecInfo
  • Additional information concerning beam energy, crystals in the beam path, event type/trigger,...
    • EcalTBEventHeader

Input sources

The first ingredient to every analysis job is the primary input source. This primary input source imports at every step of the loop over the events the initial information on top of which the analysis is built (for the full details see CMSSW Application Framework). In practical terms the source can:

  • provide raw data, e.g. if you are doing a low level analysis or running a reconstruction job
  • provide RecHits and Clusters, from a pre-processed data file, e.g. if you are doing an analysis starting from centrally reconstructed data
  • provide MC events/simhits from a file if you want to analyze simulated events have already been generated/simulated and saved
  • be a Monte Carlo generator itself and provide on the fly MC events if instead you are analyzing events which you also generate
  • be an online data stream in the case of online processes such as the HLT or DQM applications.

More specifically, the main sources are available up to now are:

read events from POOL/ROOT (.root) file containing data already in POOL format as written by CMSSW. This is how the raw and reconstructed data are distributed ijn CMS, as well as the way how simulated data are saved. This is source which is used in analysis to the largest extent.
StreamSource (NewEventStreamFileReader)
reads data which have been logged by the DAQ in .dat format. The .dat format has better performances in in I/O than the .root has, which is why is used by the DAQ. On the other hand, it is not guaranteed to be readable across different version of CMSSW, which is which all the CMS data get immediately converted into .root format at T0.
Particle guns and Pythia source
to produce MC events. There are several guns for different purposes.
to produce fake events. Mainly used for testing.
EcalTBInputService (IORawData/EcalTBInputService)
to read ECAL raw data written in binary format. Supports both ASCII and hexadecimal raw files. Note that this format is no longer being used by the DAQ to log raw data, thus the EcalTBInputService needs only be used to access data from the h4 cosmics calibration stand.
Ecal2004TBInputService (IORawData/Ecal2004TBInputService)
Read events from 2004 h4ana RRF file. Read also hodoscope and TDC information.

Structure of the CMSSW code: Algorithms and modules

CMS code is structured in terms of a overall framework into which different modules are plugged. The modules contain various algorithms which to the actual work.

do the hard work of converting on object into another. For example, reconstructing a Digi into a RecHit. Generally algorithms need some input information, like calibration constants or weights. Algorithms are conceptually generic, and should not depend on the framework directly.

are the plugins to the framework. They own the algorithms. They are used to carry out a specific task - to extract the right information from the CMSSW Event and EventSetup. Modules put the results of the calculation back into the CMSSW Event (for an introduction to the CMSSW Event, see The Event Data Model).

This structure allows a decoupling of the algorithms from the framework itself give the possibility to run algorithms in a "standalone" way (if needed).

Processing ECAL data between different data layers

Converting Raw to Digi format

Data is converted from the raw format (getting the FEDRawData from the CMSSW Event) into Digis for crystals data, PN diode data and trigger primitive data.

At present, code for raw to digi conversion is mantained in CMS.EventFilter/EcalRawToDigiDev. The specific unpacking code for the test beam raw data (hodoscope, TDC, table position, beam information) is available instead in EcalTBRawToDigi, which also provides unpacking for one fed of the barrel and the two EE matrices which were used for the test beam 2007.

To add raw to digi step to the configuration file of your process you need to include:

  • for CMS raw data:
    include "CMS.EventFilter/EcalRawToDigiDev/data/EcalUnpackerData.cfi"
    include "CMS.EventFilter/EcalRawToDigiDev/data/EcalUnpackerMapping.cfi"
  • while for the test beam data:
    include "CMS.EventFilter/EcalTBRawToDigi/data/EcalUnpackerData.cfi
to load the the raw data unpacking modules in your process. In either case, you also have to add:
 path p = {ecalEBunpacker}
to your path so that the unpacking actually scheduled for execution at every event (just having loaded the modules is not sufficient).

Converting Digi to RecHit format

Code for digi to RecHit conversion is maintained in RecoLocalCalo/EcalRecProducers (modules), while the algorithms that perform the reconstruction are maintained in RecoLocalCalo/EcalRecAlgos (algorithms). This is the step where energy and time of the hit is reconstructed. It is done in the ECAL in two steps:

  1. Conversion from digis to UncalibratedRecHits (amplitude, jitter, chi2, pedestal reconstrunction)
  2. Conversion from uncalibrated hits to EcalRecHit objects(intercalibration, global scale, laser correction)

Four algorithms have been developed so far for the production of UncalibratedRecHits. Note that, for full functionality the producers of UncalibratedRecHits need to be provided with conditions such as gain ratio (gain12/gain6, gain6/gain1) and the pedestal (for gain6 and gain1, in which case the pedeestal cannot be measured event-by-event using the 3 presamples) for each channel. You can see the parameters used to configure each of the four producers by clicking on them:

  • Standard CMS Weight Method
    • Reconstruction is done by calculating a linear combination of the samples with weights. There are two distinct sets of weights for amplitude and timing.
    • Needs well tuned weights to give meaningful results
    • Standard method for CMS synchronous running (using weights only for one single TDC bin). Note that for non synchronous data, weights provide a poor amplitude reconstruction and an unreliable timing reconstruction.
  • Fixed shape analytic fit:
    • the Amplitudes and timing are computed fitting a pulse shape (Alpha and Beta are two shape parameters) to the ten samples. If the amplitude is below 8 ADC counts fitting turns difficult, so the sixth sample i assumed to be the peak of the shape and used to reconstruct the amplitude.
    • Pedestal is computed from the three presamples (in gain12)
    • This method is useful for asynchronous data (such as the cosmic rays data) and not intended to be the standard CMS amplitude reconstruction method
    • Slower if compared to weight method
  • MAX-min method:
    • the Amplitudes is estimated as the difference between the sample with MAX value and the sample with min value. The timing is the number of sample with the maximum.
    • crude and biased (both for amplitude and timing), but useful for data collected while the latencies are being set and the pulse shape may be only partly contained in the 10-samples readout window.
  • Weight Method for test beam (asynchronous running)
    • Uses phase (as reconstructed using TDC information) between the arrival of the impinging particle and the sampling 40MHz clock, and assigns a TDC bin (typically 25 bins). Within each TDC bin, dedicated weights are used as in the standard weights method.

To load the modules which produce UncalibRecHit in your process, you need to include one of the following cfi files:

    include "RecoLocalCalo/EcalRecProducers/data/ecalWeightUncalibRecHit.cfi"
    include "RecoLocalCalo/EcalRecProducers/data/ecalFixedAlphaBetaFitUncalibRecHit.cfi"
    include "RecoLocalCalo/EcalRecProducers/data/ecalMaxSampleUncalibRecHit.cfi"
    include "RecoTBCalo/EcalTBRecProducers/data/ecal2006TBWeightUncalibRecHit.cfi"

You also need to add the UncalibRecHit producer you have chosen to your path, so that the production of UncalibRecHit is actually executed at all events. For each of the four producers, respectively:

path p = {ecalEBunpacker, ecalWeightUncalibRecHit, ...}
path p = {ecalEBunpacker, ecal2006TBWeightUncalibRecHit, ...}
path p = {ecalEBunpacker, ecalMaxSampleUncalibRecHit, ...}
path p = {ecalEBunpacker, ecal2006TBWeightUncalibRecHit, ...}

Test Beam Hodoscope reconstruction

This section deals with the code in


which is the module which converts EcalTBHodoscopeRawInfo into EcalTBHodoscopeRecInfo, reconstructing x and y position/slope of the beam (in the transverse plane to the beam direction). The code in this module has been mostly directly taken from earlier code in h4ana.

There are three possible methods to retrieve positions (all configurable in the config file):

  • method 0 : straight line between the plane 1 & 3 (x position) and 2 &4 (y position)
  • method 1 : measure only position using plane 1 (x) & plane 2 (y)
  • method 2 : meausre only position using plane 3 (x) & plane 4 (y)

To retrieve the positions requires fiber geometry, though for the moment hard-coded geometry is being used, with positions taken from h4ana 2004 analysis code

Additionally, accurate position information needs hodoscope plane misalignments and z positions (along the beam line).

Values are configurable via the config file:

module hodoscopeReco = EcalTBHodoscopeRecInfoProducer
  {  string rawInfoProducer   = "Ecal2004TBSource"
     string rawInfoCollection = ""
     string recInfoCollection  = "EcalTBHodoscopeRecInfo"
     int32 fitMethod = 0
     vdouble planeShift = { 0.0, 0.0, 0.4633, 0.1000 }
     vdouble zPosition = { -3251.0, -2881.0, -751.0, -381.0 } } 

TB TDC reconstruction

This section deals with test beam time to digital converter reconstruction code in


This module reconstructs the TDC offset (creating from EcalTBTDCRawInfo an EcalTBTDCRecInfo object). This code needs direct porting direct porting from h4ana into CMSSW.

Needed parameters are timing information indentifying the min and max raw TDC value for different trigger types (beam, laser...). For the time parameters in the config file (mainly for the analysis of 2004 TB data in CMSSW) are bieng used. These values will eventually be moved into the conditions database.

The values are presently configurable via the config file:

module tdcReco = EcalTBTDCRecInfoProducer
  { string rawInfoProducer   = "Ecal2004TBSource"
     string rawInfoCollection = ""
     string eventHeaderProducer   = "Ecal2004TBSource"
     string eventHeaderCollection = ""
     string recInfoCollection  = "EcalTBTDCRecInfo"
     int32 fitMethod = 0
     vint32 tdcMin = { 430 ,  400,  400,  400,  400 }
     vint32 tdcMax = { 958 ,  927,  927,  927,  927 } } 

Detector Calibration Data

The CMS Offline Conditions Database (ECAL elements)

The conditions database holds time-valued parameter describing the state of the detector, including features such as precise component positions, voltages, status of crystals... Conditions are associated to a certain IOV (Interval of Validity).

Presently, ECAL objects stored in the offline condition DB include:

  • EcalWeights
  • EcalIntercalibrations
  • EcalLaserCorrections
  • EcalGainRatios
  • EcalGlobalADCToGeVScale
  • EcalPedestals
  • EcalXtalGroupId

Definitions of ECAL Condition DB objects can be found in


Conditions can be retrieved from a DB, using different backend supported by the Offline Condition DB mechanism (ORACLE, SQLLite..).

The EventSetup mechanism will automatically handle the retrieval of conditions for a certain IOV (e.g. Run number) Alternatively to the retrieval from the DB, there is the possibility for ECAL to retrieve hardcoded/default conditions. This can be done using an ad-hoc EcalTrivialConditionRetriever (used for example for digitization and reconstruction of simulated data).

Code for configuring access to the conditions DB is presented in the following image (click on image to see larger version):

Code for setting up input source in config file

Hardcoded/default conditions


es_source = EcalTrivialConditionRetriever {}

you can load hardcoded/default conditions for

  • Pedestals
  • Intercalibration
  • Weights
  • Default gain ratios
  • (Endcap - coming soon)

All values are configurable in the config file, which contains data members:

double adcToGeVEBConstant 
double intercalibConstant(Mean,Sigma) 
double pedMean(X12,X6,X1) 
double pedRMS(X12,X6,X1)
double gainRatio12over6 
double gainRatio6over1 
std::vector<double> amplWeights 
std::vector<double> pedWeights 
std::vector<double> jittWeights  


These objects have new features:

  • The possibility to group crystals into the same group (for example with similar timing properties) in order to reduce the number of needed parameters
  • a newnew identifier EcalXtalGroupId has been introduced for groups of crystals. This gives the ability to store groups into the ConditionDB
  • Standard weight Cond DB object is keyed only by GroupId
EcalTBWeights for asynchronous running), keyed by GroupId and TimeId (EcalTDCId)

Geometry and Topology

associates basic detector objects, DetIds to their global position in the CMS detector
fixes the relations between DetIds, e.g. adjacent DetIds in a certain direction)

CaloGeometry and CaloTopology objects accessing this geometry and topology information are retrieved via the EventSetup method with code:

void CaloGeometryAnalyzer::analyze( const edm::Event& iEvent, const edm::EventSetup& iSetup ) {
edm::ESHandle<CaloGeometry> pG; 

Geometry is constructed using the SWGuideDetectorDescription xml files or via a DB (as it was in ORCA), while Topology is constructed using the Geometry record (hence dynamically from xml). For the moment misalignments are not considered in the reconstruction geometry

The basic code of the CaloGeometry interface is here, while the basic code of the CaloTopology interface can be found here.

Some examples of how to use the Geometry and Topology

First of all to use geometry/topology you need to have in your config file:

# XML ideal geometry description
include "Geometry/CMSCommonData/data/cmsIdealGeometryXML.cfi"
# Calo geometry service model
   include "Geometry/CaloEventSetup/data/CaloGeometry.cfi"
# Calo topology service model
   include "Geometry/CaloEventSetup/data/CaloTopology.cfi"

  • Access the CaloGeometry

void CaloGeometryAnalyzer::analyze( const edm::Event& iEvent, const edm::EventSetup& iSetup ) {
edm::ESHandle<CaloGeometry> pG; 

  • Access CaloTopology

        edm::ESHandle<CaloTopology> theCaloTopology;

  • To access list of valid DetIds and CaloCellGeometry from CaloGeometry:

void CaloGeometryAnalyzer::build(const CaloGeometry& cg, DetId::Detector det, int subdetn) {
  const CaloSubdetectorGeometry* geom=cg.getSubdetectorGeometry(det,subdetn);
  std::vector<DetId> ids=geom->getValidDetIds(det,subdetn);
  for (std::vector<DetId>::iterator i=ids.begin(); i!=ids.end(); i++) {
    const CaloCellGeometry* cell=geom->getGeometry(*i);


The RecoCaloTools package contains useful and common tools for the physics analyst to use to access and manipulate data.

For the moment these tools are implemented only navigators code

  • Navigators will be able to move given a certain DetId in north/south east/west directions as it is navigating through a 2D map
  • In the next iteration selectors will also be implemented, e.g. to act on a collection to retrieve the RecHits in a 3x3 matrix around a central DetId
  • Other tools will be added based on feedback and requests from users.

For an example of how to use navigators, click on the image to enlarge it:

Navigating about the geometry of the ECAL

Walk-throughs using ECAL objects

The following WorkBook section SWGuideEcalRecoTutorials gives practical guides to carrying out various common tasks involving the ECAL CMSSW software.

Correlated noise analysis

The ECNA framework to study correlated electronics noise of the ECAL is described in CMS.EcalCorrelatedNoiseAnalysis.

Information Sources

Review status

Original Author: Paolo Meridiani - INFN Roma 1

Reviewer/Editor and Date (copy from screen) Comments
BernardFabbro - 07 Feb 2014 added link to ECNA
PhilippeGras - 04 Jul 2009 added detid section marker to include this section in the new EcalIndices twiki
JennyWilliams - 27 Jun 2006 created page from ECAL CMSSW tutorial
PaoloMeridiani - 27 Nov 2006  
JennyWilliams - 14 Dec 2006 general tidying

Responsible: PaoloMeridiani
Last reviewed by: ChrisSeez - 13 Dec 2006

Topic attachments
I Attachment History Action Size Date Who Comment
GIFgif Ecal_geometry.gif r1 manage 41.9 K 2006-06-27 - 14:14 UnknownUser  
GIFgif detid.gif r2 r1 manage 6.5 K 2006-06-28 - 13:10 UnknownUser  
GIFgif ecal_calogeometry.gif r2 r1 manage 8.4 K 2006-06-28 - 13:40 UnknownUser  
GIFgif ecal_calotopology.gif r2 r1 manage 15.4 K 2006-06-28 - 13:39 UnknownUser  
GIFgif ecal_conddb_access.gif r1 manage 16.2 K 2006-06-27 - 22:31 UnknownUser  
GIFgif ecal_configfile_source.gif r2 r1 manage 8.9 K 2006-06-28 - 13:04 UnknownUser  
GIFgif ecal_data_tiers.gif r2 r1 manage 6.6 K 2006-06-28 - 13:12 UnknownUser  
JPEGjpg ecal_data_tiers.jpg r1 manage 44.6 K 2006-06-28 - 13:09 UnknownUser  
GIFgif ecal_digi_rechit.gif r2 r1 manage 12.4 K 2006-06-28 - 13:28 UnknownUser  
GIFgif ecal_navigators.gif r2 r1 manage 9.7 K 2006-06-28 - 13:48 UnknownUser  
GIFgif ecal_retrievedata.gif r2 r1 manage 10.6 K 2006-06-28 - 13:15 UnknownUser  
Edit | Attach | Watch | Print version | History: r21 < r20 < r19 < r18 < r17 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r21 - 2018-06-06 - MohammadAbrarWadud
    • 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