SiDigitization
--------------------
Extra changes to use the pile-up tools. (Jan 26th 2004)
- SiChargedDiodeCollection has a container behaviour
- In SiDigitization. digitize() became digitizeElement()
- The clients (Pixel and SCT_ Digitization) should call digitizeElement recursively till .false. is returned
    also they have to create and own the SiChargedDiodeCollection

-------------------
I restructured the package and commited the changes in CVS on April 3rd 2003.
Rather than describing what I changed I describe here what the package does.


Basic Idea

The digitization is performed by one main algorithm which can be PixelDigitization or SCT_Digitization, depending on the detector we are dealing with. A base class for those algorithms is provided by SiDigitization which is described in this page.
The input to the digitization is a container of hits. A container containes a bunch of hits collections. Each hit collection is a list of hits released in a single silicon wafer. The digitization proceeds collection by collection, so it is performed wafer by wafer. For every wafer a collection of Raw Data Objects (RDO) and of Simulation Data Objects (SDO) is created and stored in StoreGate for furher processing.

The main data object for the digitization is the SiChargedDiode. A SiChargedDiode (see later for a technical description) can be seen as a single read-out cell of the detector, and it is the place where all the temporary information from the digitization is stored. A collection of SiChargedDiodes is a map of charged diodes. Methods are provided to write out the RDO and SDO for the wafer.

The first step is to convert the simulation hits into charges on the Si surface, this is performed by a SurfaceChargesGenerator. Both the pixel and SCT digitization should provide one, and the SiDigitization package provides a base class. This is the place where the physics of the propagation of the charges in the wafer is described.
The surface charges are then collected into SiChargedDiodes and a further processing is then performed by means of SiChargedDiodesProcessors. Some processors are general purpose and are common for the Pixel and the SCT and are provided in the SiDigitization package.
Finally, after all the processing, the information is compacted and stored in StoreGate in the ATLAS standard format provided by the RDO and SDO.


Classes:
                               -  SiCellDiscriminator : SiChargedDiodesProcessor
                              -  SiCellNoiseGenerator : SiChargedDiodesProcessor
                              -  SiRandomDisabledCellGenerator : SiChargedDiodesProcessor
                              -  SiThermalDiodeNoiseGenerator : SiChargedDiodesProcessor SiDigitization : Algorithm:

SiDigitization is the algorith (in the athena sense) to be used for the digitization. It is a base class for PixelDigitization and SCT_Digitization, and provides a few methods which are intended to be used both by the Pixel and the SCT. In the initialize(), execute() and finalize() documentation instructions are provided on what the corresponding methods for the derived classes should do.


StatusCode initialize()

A few member of the SiDigitization algorithm have to be initialized to run digitization. This is  done in the initialize() methods of the PixelDigitization and SCT_Digitization algorithms. What needs to be created and stored in SiDigitization is:
- one instance of SiSurfaceChargeGenerator
- a list of instances of SiChargedDiodeProcessors
- one instance of SiRelativeBunchCalculator
- one instance of an ID helper (AtlasDetectorID). Can be either PixelID or SCT_ID

Once these classes are instantiated, a pointer should be stored in SiDigitization data members by calling the SiDigitization::store method

The PixelDigitization and the SCT_Digitization will have to call the SiDigitization::initialize() method which will check that all the objects needed are instantiated properly and that digitization can be  run.

The initialize method of the derived classes should do the following: (in addition of course of detector specific tasks)
- instantiate a SiSurfaceChargeGenerator and store it
- get an IdHelper from the DetectorStore and store it (or from the InDetMgr, we still have to clarify this issue with RD)
- instantiate the SiChargedDiodesProcessors needed and store them
- If a SiRelativeBunchCalculator is needed by one of the processors instantiate and store it as well
- call the SiDigitization::initialize() method for checking


StatusCode execute()

No execute() method is provided by SiDigitization. It is provided by the derived classes, they should do:
- create an RDO container and register it to StoreGate
- create an SDO container and register it to storeGate (SDO container is a std::map<Identifier32, InDetSimData> )
- get the hit container (getNextEvent method)
- loop over the hit collections (getNextCollection method)
- digitize the collection (digitize method. NOTE: digitize() is now a method of SiDigitization, so the call should be this->digitize() )
- create the RDO collection and record it to StoreGate (the createRDO method HAS to be provided by the derived classes, I didn't find a way to enforce it by adding a pure virtual method to SiDigitization, I need to talk to some c++ expert)
- create the SDO collection(addSDO method )

StatusCode finalize()

The finalize method is deleting all the instances that have been created AND stored previously
No action is required in the finalze() method of the derived classes

void store(....)

The store method is used to "store" the objects needed to run digitization. It has to be called by the derived classes in order to save the information of the objects needed. Four different overloaded store methods are provided:
  void store(SiSurfaceChargesGenerator *p_generator);
  void store(SiChargedDiodesProcessor *p_processor);
  void store(SiRelativeBunchCalculator *p_calculator);
  void store(const AtlasDetectorID *p_helper);

private StatusCode getNextEvent()

gets the container from StoreGate. The container is a member object of SiDigitization
This is called by getNextCollection() when a new event is read in

SiTrackerHitCollection* getNextCollection()
REMOVED on 1/26/03
Get next hit collection. This is performed by the TimedHitPtrCollection->nextDetectorElement, instead

bool endOfHits()
REMOVED on 8/18/03
Check if the list of collection is over

SiChargedDiodeCollection *digitize(const std::list<SiHit*> &hits);
REMOVED on 1/26/04
Input a HitCollection, outputs a SiChargedDiodeCollection (see later for information on this class)
Use digitizeElement instead.
 
bool digitizeElement(SiChargedDiodeCollection* );
Passes a pointer to a SiChargedDiodeCollection. The method fills the collection with the ChargedDiodes for the
next detector element. When there are no more hits false is returned


void addSDO(std::map<Identifier32, InDetSimData> *sdo_Map,SiChargedDiodeCollection* collection);

Adds SDO to a map of SDOs starting from a hit collection. It adds to the map the SDOs correspoding to the Si wafer which has just been digitized

InDetRawDataCollection<...> createRDO(SiChargedDiodeCollection*)

creates a RDO collection. This method is provided by the derived classes.
We need to enforce it in SiDigitization
Note: while creating an RDO, we need to look at the Simulation data word to see if the ChargedDiode is disconnected/disabled, if this is the case the RDO shouldn't be added to the collection.

SiChargedDiode

The SiChargedDiode is the object where the information is stored during the digitization.
The private data members are:
- a pointer to a SiDiode (SiTrackerDetDescr),
- a SiTotalCharge (SiTrackerEvent),
- a pointer to SiReadoutCell (SiTrackerDetDescr)
- a data word used to store the simulation information, and designed to be copied into the SDO data word.

Most of the methods are just read/write of the private data members, and I won't describe them:


SiChargedDiode(const SiDiode*, int flag=0)

This is the only constructor provided. The SiDiode comes from the Detector Description.

SiReadoutCell *getReadOutCell()

Returns the readout cell of the diode

void add(const SiCharge)

adds a SiCharge (defined in SiTrackerEvent) to the SiChargedDiode.

double charge()

returns the total charge contained in this diode.

SiChargedDiodeCollection : Identifiable

The SiChargedDiodeCollection is a collection of SiChargedDiodes. It is Identifiable, as it has to have an identify() method to return the identifier of the collection, eg the id of the Si wafer the collection belongs to.
The private data members are:
 -  std::map<Identifier32,SiChargedDiode>, a  map of SiChargedDiodes with the compact ID
 - const SiDetectorElement; The detector element to be used

typedef std::map<Identifier32,SiChargedDiode>::iterator SiChargedDiodeIterator;

is defined for user convenience. IMPORTANT::
the iterators are map iterators, by dereferencing them the type is
pair<Identifier32,SiChargedDiode>, to get the SiChargedDiode out of an iterator the following syntax is required:
(*iter).second
(*iter).first is the compact ID of the SiChargedDiode.

Notable methods are:
 
bool add(const SiDiode *p_diode,const SiCharge &charge);

adds a Charge deposited in a SiDiode to the collection, if a SiChargedDiode corresponding to the argument SiDiode is already in the collection the charge is added to it. Otherwise a new SiChargedDiode is created.
The return bool is true if the SiChargedDiode already exists, meaning that the ownership of the SiDiode has not been taken and is caller responsibility to delete it.

bool AlreadyHit(Identifier32);

returns true if the SiChargedDiode corresponding to a given compact ID has already been hit

SiChargedDiodeIterator begin()

Returns the begin iterator of the map.

SiChargedDiodeIterator end();

Returns the end iterator of the map.

void create(const SiTrackerHitCollection, const SiSurfaceChargesGenerator);
REMOVED on 1/26/04
the iteration on the hits has to be done in the SiFigitization. This is to give to the SiChargedDiodeContainer a
data class behaviour.
create a new collection from a HitCollection, by using th e physics described in the SiSurfaceChargesGenerator.


SiChargedDiodesProcessor

This is the base class for the processors. A processor is looping on a collection of ChargedDiodes and making some action on them (e.g. add noise).

virtual void process(SiChargedDiodeCollection) const =0;

this is the main (and only method). It is pure virtual as every single processor is required to have it.

Some processors are provided by the SiDigitization package and are:
          -  SiCellDiscriminator (Simualtes the cell discriminator for Pixel/SCT uses SiRelativeBunchCalculator)
          -  SiCellNoiseGenerator (Generates gaussian noise)
          -  SiThermalDiodeNoiseGenerator (Generates thermal noise, it could be probably merged with the CellNoiseGenerator)
          -  SiRandomDisabledCellGenerator. Disables a cell. The simulation data word is modified by the pointer function of the SiHelper                                     passed. Example: to disconnect a cell, the constructor should be:
                   new SiRandomDisabledCellGenerator(m_noBumpProb,SiHelper::disconnected);

Other processors may be defined by the Pixel and SCT for their needs.



this page is maintained by DC
Last Updated Jan 26th 2004