To go to the calorimetry packages page, click here.

1- Introduction

    CalorObjects is one of the four packages of Calor prefix. CalorMods contains in particular the CalorimetryModule that
    transforms the D banks coming from the raw data into CalData objects, the storable object containing the information
    of the towers. You can find in the Calor package utilities that are used to manipulate towers. For example, that's where
    the four vectors of the jets and towers are calculated. Finally, CalorObjects is where "container classes" can be found,
    e.g. CalData, CalTower,  PhysicsTowerData and PhysicsTower.

    In this page, we will describe the tower classes that can be found in the CalorObjects package. The classes we
    describe here are what we believe to be the most useful ones, from a user point of view.

    Note: The documentation on the central pre-shower detector, plug pre-shower, central preradiator and shower max
    detector are found in the following locations:

   - Central preshower detector
     -  Plug preshower detector
    - Central preradiator
    - Shower max detector

2- CalData

    To describe CalData and CalTower classes, we follow an example that can be found in the CalorMods package:
   CalorExampleModule. To run the example, first create your own test release if you don't have one, addpkg CalorMods,
    compile and run:

     > setup cdfsoft2
     > newrel -t  3.18.0 myRelease
           > cd myRelease
           > addpkg CalorMods
           > gmake CalorMods.lib
           > gmake CalorMods.tbin
           > bin/$BFARCH/CalorExample CalorMods/test/run_CalorExample.tcl

    where in this example, we create a release version 3.18.0. The .cc file of this example can be find in
   CalorMods/src/CalorExampleModule.cc and the .hh file with the same name in the CalorMods/CalorMods/
    directory. We will refer to this example all along the CalData and CalTower description.
 

i - Accessing the tower information

    The first thing is to declare a CalData handle in your analysis program. In CalorExampleModule, the first important
    line of code in the CalorExampleModule::event function is (line 86):

            CalData_ch data;

            typedef Handle<CalData> CalData_h;

    and

            typedef ConstHandle<CalData> CalData_ch;

    To fill the CalData handle, use the function find of CalData . It's the next step in CalorExampleModule (line 90):

            CalData::Error result = CalData::find(data);

    The function find returns an object of type CalData::Error, which equals to OK if the function was able to find the
    CalData in the event or ERROR it was not. It may prudent to put a if before manipulating over CalData to warn if the
     find function failed, as in CalorExampleModule.cc (line 92):

            if(result != CalData::OK){
                cout << "could not find CalData in the event" << endl;
                // return OK for now...
                return(AppResult::OK) ;
           }

    The CalData object data contains now the information of all the towers of the event.

ii - Printing the contents

    In some circumstances, you may want to print a tower's information, e.g. if you want the number of towers with non-zero
    energy, the total electromagnetic, hadronic and total energy registered by the calorimeter to be printed, use the function
      printSummary() of CalData (line 100 of CalorExampleModule.cc):

            data->printSummary();

    When you run your program, the output for each event will look like:

            CalData contains 400 towers:   total EM energy 353.907   total HAD energy 165.208   TOTAL energy 519.115

    If you want to have the information of each tower, use the function print. This is done in CalorExampleModule by
    setting the verbose parameter to true or false in the run_CalorExample.tcl. So, in CalorExampleModule:

            if (_verbose.value()) data->print(cout);

    If verbose was set to true, the following type of output will be printed for each tower with energy:

            Type: 6
            ieta: 6 iphi: 14
            validation code: 0
            EM energy (GeV): 0.352 Hadronic energy (GeV): 0
            EM phi: 3.79609 Hadronic phi: 3.79609
            PPR energy : 0
            PEM energy : 0.352
            PHA energy : 0
            PHA time: 0
 

iii - Iterating on the CalTower's

    You can now iterate over the towers (with non-zero energy) declaring an object of type CalData::ConstIterator or
   CalData::Iterator, like in CalorExampleModule in a for loop (line 112):

            for(CalData::ConstIterator tower= data->begin(); tower != data->end(); ++tower){

    At this point in the example, you can access the function members of the class CalTower from the object
    CalData::ConstIterator tower, for example, you can do directly tower->energy() to know the energy of the
    tower. The function members of CalTower are described here .

    (In CalData.hh):

            class ConstIterator
              {
               public:
                ...
               CalTower* operator->() const;
                ...

iv - Accessing a specific tower

    This can be done via the CalData object with the function tower(UChar_t iEta, UChar_t iPhi), where the two arguments
    of tower are the ieta index and iphi index, respectively. The function returns a const CalTower*, for example (not in
    CalorExampleModule.cc):

            const CalTower* myTower = data->tower(4,0);

   myTower will be the tower at ieta = 4 and iphi = 0. For a list of the correspondance between the ieta and iphi indices
    and the towers, see the calorimetry packages page .
 

3- CalTower

    CalTower is the class for individual towers while CalData was the class that contains all the towers of one event.

i - CalTower vs TowerType

    The TowerType classes, which go from TowerType0 to TowerType8, all inherit from the CalTower type
    class (they are defined in the CalorObjects package in the file TowerType.hh). In practical terms, that means
    that some values which are specific to each type of tower, like the hadronic energy for example, are calculated
    differently within each TowerType class, but the result will be accessible via a CalTower object by the
    same  function add Energy. For a definition of each of the TowerType, going from 0 to 8,
    see calorimtery packages page .

ii - CalTower vs PhysicsTower

    There are two C++ classes of towers in the CDF software, CalTower and PhysicsTower. The CalTowers are
    the "experimental "towers, i.e. they contain the information that was read by the photomultiplier tubes, while
    the PhysicsTowers have their transverse energies calculated from a specific vertex and have a four vector
    associated to them. Thererfore, a CalTower will contain in particular the energy information, but not the
    Et information that depends on the vertex. On the other hand, a PhysicsTower will contain the Et information,
    and will also have a 4-momentum vector associated to them.

    In practical terms, the CalTowers are used to create the PhysicsTowers via CalData, and the PhysicsTowers
    are used to form the jets, the missing Et and the electron objects. For a description of PhysicsTower, go
    directly here.   Note that one can create a set of PhysicsTowers (PhysicsTowerData) from Monte Carlo
    particles or just plain four-vectors.

iii - Member functions

   We give here the description of the functions accessible from a CalTower object that are useful for a user.

   General function:

        - valcode_t validCode() const;        -> Not yet completely defined. Will return 0 if the tower is OK, something else
                                                              if there is an hardware problem with the tower.
        - float emCOGPhi() const;               -> Value between 0 and 1. It characterizes how much the energy is measured by
                                                              one of the two pmt in the em component relative to the other pmt (e.g., it returns
                                                              0.0 if the energy is only read by pmt 0, 1.0 if it is only in pmt 1)
        - float hadCOGPhi() const;              -> Same as above for hadronic component.
        - float energy() const;                        -> em energy + had energy
        - float emEnergy() const;                 -> Energy in the em part of the tower
        - float hadEnergy() const;                -> Energy in the hadronic part of the tower
        - UChar_t iEta() const;                     -> eta indice of the tower  (a "UChar_t" is equivalent to a 1 byte integer)
        - UChar_t iPhi() const;                      -> phi indice of the tower
        - UChar_t myType() const;             -> Type of the tower (from 0 to 8)

    Access to raw data:

        - virtual int nEmPmt() const =0;         -> Number of pmts in em part of the tower.
        - virtual int nHadPmt() const =0;        -> Same thing as above for hadronic part of the tower.
        - virtual uint2 emPmt(int ipmt) const =0;   -> Number of ADC counts for em part for the pmt ipmt.
                                                                                               a "uint2" is a 2-byte unsigned integer
        - virtual uint2 hadPmt(int ipmt) const =0;  -> Same as above for hadronic part.
        - virtual uint2 pmtData(CellKey& cKey, size_t ipmt) const = 0; -> Number of ADC counts for the pmt ipmt of the
                                                                detector identified by cKey (click here for info. about CellKey and ipmt)
        - virtual uint2 emData() const = 0;        -> Number of ADC counts for the em part of the tower.
        - virtual uint2 hadData() const = 0;        -> Same as above for hadronic part.
        - virtual uint2 totData() const = 0;        -> Sum of the two previous values.

    Access to calibrated data:

        - virtual float emPhi() const = 0;         -> Returns the phi of the CalTower, calculated using the emCOGPhi information.
                                                                (That means it is not the phi of the center of the tower but it takes into
                                                                 account the energy distribution in the tower).
        - virtual float hadPhi() const = 0;        -> Same as above for hadronic component.

    Miscellaneous:

        - virtual int time(CellKey& cKey) const = 0;    ->  Returns the time when the energy is deposited in the tower
                                                                               in relation with the beam crossing.
        - virtual float pmtEnergy(CellKey& cKey, size_t ipmt) const = 0;  -> Energy in the pmt ipmt of the detector identified
                                                                                                    by ckey (click here for info. about CellKey and ipmt)
        - virtual bool  includesDetector(Detector iDet) const = 0 ;   -> Return true if the detector iDet is included in the tower,
                                                                                                false if not. See an example in this section.
        - virtual bool hasTiming() const = 0;                  -> Return true if the tower is equipped to return a time value (see above).
        - virtual void detectors(DetList& dl) const=0;     -> Fills the DetList& dl with the lists of detectors in the tower.
                                                                                  See this section for an example of use of this function.

iv - Iterating on the detectors

    A CDF tower is made of different detectors, with at least one hadronic and one electromagnetic component. For a list of the
    possible detectors in the calorimeter, see the calorimetry packages page. To iterate on the detectors of a tower, first declare
    a list of detectors, like at line 108 of CalorExampleModule.cc:

            DetList caloList;

            typedef std::vector<Detector> DetList;

    Thus you need to include CalTower.hh in your analysis module in order to use this type, and the type Detector itself
    is simply defined as a list of names for each calorimeter (in CalorGeometry/CalConstants.hh):

            typedef enum { CEM, PEM, CHA, WHA, PHA, STRIP, CRACK, PPR, MPC,
        DEFAULT, ERR } Detector;

    Then fill the list of detectors with the detectors function (line 139):

            tower->detectors(caloList);

    and loop over the detectors (line 142):

            for(DetList::iterator calIter = caloList.begin(); calIter != caloList.end(); ++calIter){

v - Accessing the different detectors

    The CalorExample module goes on by building a Cellkey that will allow you to access the pmt energy of a specific detector
    of a specific tower defined by a ieta and iphi. (CellKey is also an argument of the pmtData and time functions of CalTower):

            CellKey key(ieta,iphi,*calIter);

            float pmtE0 = tower->pmtEnergy(key, 0);
            float pmtE1 = tower->pmtEnergy(key, 1);

    You can use the identity of a Detector in the following ways (line 161 + of CalorExampleModule.cc):

           if((*calIter) == PEM){
                if(pmtE0 !=0) cout << "PEM " << "pmt0 energy = "<<pmtE0<< endl;;
           }
       if((*calIter) == CHA){
                if(pmtE1 !=0) cout << "CHA " << "pmt1 energy = "<<pmtE1 << endl;
          }

          if(tower->includesDetector(MPC)){
                 // No simulation of miniplug yet
                cout << "Miniplug tower (type 7 or 8)" << endl;
          }
 

4- The PhysicsTower classes

   The PhysicsTowers are towers whose quantities are calculated from a specific vertex. See here for an explanation of the
   difference between PhysicsTower and CalTower.

i - Accessing the PhysicsTower in an event: the PhysicsTowerData class

    The way to access the PhysicsTower's is to use the PhysicsTowerData class. PhysicsTowerData is the analog of
    CalData for PhysicsTower. From the point of view of the Event Data Model, PhysicsTowerData is the storable object
    for PhysicsTower.

    To get started, declare a handle of PhysicsTowerData in your program and fill it. (Note: This is done exactly the same
    way than for CalData.) Let's do an example with a constant handle:

            PhysicsTowerData_ch myHandle;

     typedef Handle<PhysicsTowerData> PhysicsTowerData_h;

    and

     typedef ConstHandle<PhysicsTowerData> PhysicsTowerData_ch; 

    To fill the PhysicsTowerData handle, use the function find of PhysicsTowerData . To follow the example:

            std::string description = "JetCluPTD";
     PhysicsTowerData::Error result = PhysicsTowerData::find(myHandle, description);

    The function find will try to find PhysicsTower under the name JetCluPTD, that is the PhysicsTowerData used
    by  JetCluModule. The function find returns an object of type PhysicsTowerData::Error, which equals OK if the
    function was able to find the PhysicsTowerData in the event or ERROR it was not. It may prudent to put a if
    before manipulating over PhysicsTowerData to warn you if the find function failed:

    if(result != PhysicsTowerData::OK){
                cout << "could not find PhysicsTowerData in the event" << endl;
                return(AppResult::OK) ;
               }

    The PhysicsTowerData object data contains now the information of all the PhysicsTowers of the event.
 

ii - Iterating on the PhysicsTower's

    This is also done in complete analogy with CalData section iii. Refer to that section with replacing the word CalData by
    PhysicsTowerData.
 

iii - Accessing a specific PhysicsTower

    This can be done via the PhysicsTowerData object with the function tower(size_t iEta, size_t iPhi), where the two
    arguments of tower are the ieta indices and iphi indices respectively. The function returns a const PhysicsTower*.
    To follow our previous example:

     const PhysicsTower* myTower = myHandle->tower(4,0);

   myTower will be the tower at ieta = 4 and iphi = 0. (For a list of the correspondance between the ieta and iphi indices
    and the towers, see the calorimetry packages page.)

    The function tower is overdefined and can be used under the form: const PhysicsTower* tower(TowerKey tKey) const;.
    TowerKey is a simple utility class that contains the knowledge of the neighbors of one tower (Here is a link to the .hh
    file in the code browser). You can use it to access the neighbors of a tower. To do the same thing than in the previous
    example:

            TowerKey myKey(4,0);
            const PhysicsTower* myTower = myHandle->tower(myKey);
 

*iv - Accessing the PhysicsTower parameters

    In some particular case, you may want to access the parameters that were used to build the PhysicsTowerData
    object. To do that, use the function parameters:

         PhysicsTowerData_ch myHandle;
            ...
            PhysicsTowerParams myParams = myHandle->parameters();

   myParams is an object of the PhysicsTowerParams class, from which you can access the following information:

            myParams.inputType()                          -> Returns 0 for a CalData input, 1 for a HEPG input.
            myParams.calculatorType()                -> Returns 0 for StandardCalculator, 1 for FourVectorCalculator and 2
                                                                   for MetCalculator.
                                                                  These calculators are used to make the PhysicsTowers from CalData or HEPG,
                                                                  the way to do this is described in the Calor documentation.
            myParams.calcThreshold()                 -> Returns the minimal energy to consider a tower.
            myParams.vertex()                                -> Returns the z vertex used to make PhysicsTowerData.

*v - How to create and use a customized collection of PhysicsTowerData

    This is not yet implemented. It will be possible soon to choose which PhysicsTowerData you want a calorimeter module,
    like a jet algorithm or electron clustering module, to use as input. For example, you may have your own module for finding
    the primary vertex, and you want your jet algorithm to use this new vertex. One way to do that would be the following:

    First, your .cc file correspond to AppUserBuild would look like this:

       AppUserBuild::AppUserBuild( AppFramework* theFramework )
                    : AppBuild( theFramework )
            {

               ...

               AppModule* aModule;

                aModule = new MyVertexFindingModule( "MyVertexFindingModule",  "Where the primary vertex is calculated" );
                add( aModule );

                aModule = new JetCluModule( "JetCluModule",  "Default Jet Clustering Algorithm" );
                add( aModule );

                aModule = new MyJetAnalysisModule( "MyJetAnalysisModule",  "Where the new jets are analyzed" );
                add( aModule );
            }

    where MyVertexFindingModule is your module that finds the vertex and MyJetAnalysisModule will be the module where
    you analyze the new jets found with JetCluModule.

    In MyVertexFindingModule, when the vertex is calculated, declare a PhysicsTowerParams with argument the new vertex:

           float theNewPrimaryVertex;

            // Piece of code where you find the vertex

            PhysicsTowerParams myParams( 0, 0, 0.150, theNewPrimaryVertex);

            // The prototype is: PhysicsTowerParams( int inputType , int calculatorType, float calcThreshold, float vertex);. Here
            // you chose a threshold of 150 MeV.

    And then you create the new PhysicsTowerData using an object of the class PhysicsTowerDataMaker that can be find
    in the Calor package. In particular, use the function create of this class:

       PhysicsTowerDataMaker theMaker;
            PhysicsTowerData_ch theHandle;
            std::string description = "newPTD";

            theHandle = theMaker.create(theEvent, myParams, newPTD);

            // the protype: PhysicsTowerData_ch create(AbsEvent* anEvent, PhysicsTowerParams& params, const std::string&
            // description);

    You name your own PhysicsTowerData "newPTD". MyVertexFindingModule is now finished. The part that
    is not implemented has to do with the fact that there not yet parameters of JetCluModule or any other module
    that allows one to choose the PhysicsTowerData you want. When this will be implemented, you will set this
    parameter to "newPTD" when talking to the JetCluModule in the .tcl file.

    Finally, in the module MyJetAnalysisModule, you would get the PhysicsTowerData you created with this line:

           PhysicsTowerData_ch myHandle;
           std::string description = "newPTD";
     PhysicsTowerData::Error result = PhysicsTowerData::find(myHandle, description);
 

*vi - Other functions of PhysicsTowerData

    Two other functions can be useful for a user:

    1) int size() const: Return the number of towers in PhysicsTowerData with energy.
    2) float threshold() const: Return the threshold energy that was used to create the collection of PhysicsTower.
 

vii - Description of PhysicsTower functions

    Now that you have iterated on the PhysicsTower of PhysicsTowerData, for example:

            for(PhysicsTowerData::ConstIterator tower= data->begin(); tower != data->end(); ++tower){

    You can now access the following tunctions with the operator -> of the object tower in the example:

   Same functions than for CalTower: These will return the same value as the associated CalTower function
                                                         (for description of CalTower function, click here):

            - float totEnergy() const;
            - float emEnergy() const;
            - float hadEnergy() const;
            - float emPhi() const;
            - float hadPhi() const;
            - size_t iEta() const;
            - size_t iPhi() const;

   Calculated by a specific calculator: These functions are the ones that depend on the vertex. They are calculated by the
                                                      FourVectorCalCulator, StandardCalculator, or MetCalculator. See Calor documentation
                                                      to know how the calculator calculates in their own way each of these functions.

            - float emEt() const;
            - float hadEt() const;
            - float totEt() const;
            - float emEta() const;
            - float hadEta() const;
            - float totEta() const;
            - float totPhi() const;
            - float px() const;
            - float py() const;
            - float pz() const;
            - HepLorentzVector fourMomentum() const;

   Miscellaneous:

            - TowerKey key() const;        -> Return the TowerKey of the PhysicsTower. (TowerKey can be used to access
                                                           the neighbors of a tower. See TowerKey.hh in the code browser to see how).
            - Index index() const;            -> Return the Index of the PhysicsTower. (Index is a simple class that holds an
                                                           eta-phi index. See Index.hh in the code browser).
            - float dR(float eta, float phi) const;      -> Gives the distance between the tower and the point given by eta and phi
                                                                      in the eta-phi plan.
            - float dRsquared(float eta,float phi) const;     -> Same as above ^2.
 

viii - Correspondance PhysicsTower -> CalTower

   There is no direct way to do that right now. The quickest way is to ask for the ieta and iphi of the physics tower, declare a
    CalData in your program and use the function tower of CalData with the corresponding ieta and iphi in argument (like in
    the previous example here).
 

To go to the Calor user's guide page, click here.
 

Page maintained by Jean-Francois Arguin (UofT)
Last update: September 26, 2001