Correct initialization of optical properties needed by Geant4 (Andrei)

[u/mrichter/AliRoot.git] / HMPID / api.txt

How to open session:
	use static method  AliRunLoader::Open("galice.root","AlicE","update") or just AliRunLoader::Open() for defaults. 
        Returns pointer to AliRunLoader on success or fatal termination on error
How to get total number of events in galice.root:
	AliRunLoader::GetNumberOfEvents()  (or AliRun::GetEventsPerRun() using f.e. gAlice deprecated)
How to get pointer to HMPID:
        AliRunLoader()->GetAliRun()->GetDetector("HMPID") but before one needs to AliRunLoade()->Set
How to avoid using gAlice:
	detector->GetLoader()->GetRunLoader()->GetAliRun() returns gAlice global pointer.
How to retrieve pointer to alice run loader:
        use pHMPID->GetLoader()->GetRunLoader() (all detector classes inherit from AliDetector which has GetLoader())
	use method AliRun::GetRunLoader for gAlice (deprecated)
How to get pointers to different root trees:
	TreeE belongs to AliRunLoader, available after AliRunLoader::LoadHeader()
	TreeK belongs to AliRunLoader, available after AliRunLoader::LoadKinematics()
	TreeH belongs to AliLoader   , available after AliLoader::LoadHits()
	TreeS belongs to AliLoader   , available after AliLoader::LoadSDigits()
	TreeD belongs to AliLoader   , available after AliLoader::LoadDigits()
	TreeR belongs to AliLoader   , available after AliLoader::LoadRecPoints()
        all methods return 0 on success. 
How to get event of interest:
	AliRunLoader::GetEvent(event_number) returns 0 on success
How to deal with the stack of particles?
        - first of all, the stack includes primary as well as secondary particles
	- pointer to the stack is taken:
          	AliRunLoader::Stack() but before one needs to load event header by AliRunLoader::LoadHeader() otherwise both methods return 0.
          	Moreover loading header gives the information about number of particles only. 
          	To retrieve the list of particle one also needs to load kinematics by AliRunLoader::LoadKinematics()        
	- total amount of particles in stack for a given event:        
         	AliStack::GetNtrack() 
	- total amount of primary particles in stack for a given event (after LoadHeader()): 
        	AliStack::GetNprimary() 
How to retrieve hits:
	Hits are stored on primary by primary basis. Hits for the given primary is TClonesArray.
   	To retrieve all hits one needs to do:
     	-initialize the root tree and containers:   pRich->GetLoader()->LoadHits();  (AliLoader::LoadHits() returns 0 on success)
     	-read number of entries in TreeH:           pRich->GetLoader()->TreeH()->GetEntries()
     	-then for each entry:                       pRich->GetLoader()->TreeH()->GetEntry(i)	
How to retrieve sdigits? 
	Sdigits stored in tree S with the branch of TClonesArray, all sdigits in a single TClonesArray
	So the tree has only one entry.
	One needs to say:
	-pRich->GetLoader()->LoadSDigits(); this one open file, get the tree and invoke AliHMPID::SetTreeAddress()    
How to retrieve digits? 
	Digits stored in tree D with the 7 branches of TClonesArray, one per chamber, all digits of a given chamber in a single TClonesArray
	So the tree has only one entry.
	-One needs to say:
	  pRich->GetLoader()->LoadDigits(); this one opens file, gets the tree and invoke AliHMPID::SetTreeAddress() which in turn corresponds 
          branches of the tree to the digits containers in memory. There are 7 containers, one per chamber, all of them belong to AliHMPID.
	-Then one needs to take the tree entry (only one) to the memory:
          pRich->GetLoader()->TreeD()->GetEntry(0) 
	-Finally pRich->Digits(chamber_number) returns the pointer to TClonesArray of AliHMPIDdigit          
What are the debug methods avail:
        AliLog::SetGlobalDebugLevel(AliLog::kDebug)
How to get info for a given particle number:
	Header and Kinematics trees must be loaded, then possible to retrieve pointer to Stack of particles
	Int_t AliRunLoader::LoadHeader(); Int_t AliRunLoader::LoadKinematics()
	AliStack *AliRunLoader::Stack()
	TParticle *AliStack::Particle(tid)
	TParticle::Print()
How to deal with AliRunDigitizer:
	AliRunDigitizer::Exec() just call AliRunDigitizer::Digitize()	
What are the meanings of different VMC flags:         
	gMC->IsTrackAlive()
	gMC->IsTrackStop()
	gMC->IsTrackDisappeared()
How to get pad number for a local position:
	use static TVector AliHMPIDParam::Loc2Pad(TVector2 position);
Why list of chambers belongs to AliHMPIDParam:

How to check if a given stack particle is primary:
	Stack is TClonesArray of TParticle. TParticle::GetMother(0) returns -1 if it's primary (no mother)         
How to loop over all possible object:         
  for(Int_t iEventN=0;iEventN < GetLoader()->GetRunLoader()->GetAliRun()->GetEventsPerRun();iEventN++){//events loop
    for(Int_t iEntryN=0;iEntryN < GetLoader()->TreeH()->GetEntries();iEntryN++){//TreeH loop
      GetLoader()->TreeH()->GetEntry(iEntryN);//get current entry (prim)  
      for(Int_t iHitN=0;iHitN<Hits()->GetEntries();iHitN++){//hits loop
        AliVHMPIDHit *pHit=(AliVHMPIDHit*)Hits()->At(iHitN);//get current hit 
        
      }//hits loop
    }//TreeH loop
  }//events loop


HMPID full simulation-reconstruction sequence

hits->sdigit:
	Responsible method is AliHMPID::Hits2SDigits
	One hit may affect one or more pads.
        Hit position is taken on the anode wires plane as the most of avalanche is developed there.
        This position is not directly available, track intersections with entrance and exit of amplification gap are only stored.
        So the position in the middle of the gap is calculated as average out of pHit->In() and pHit->Out() positions.
        Then, total charge collected for this hit is calculated by AliHMPIDParam::Hit2Qdc.    
        Area of disintegration is a list of pads affected by current hit. This is a parameter of Mathienson    
sdigits->digits:
	The necessety of sdigits is dictated by the fact that transport engine transports tracks in a continuous sequence track by track. 
  It means that it may happen that the same pad is affected by few tracks. But this might be known only after the transport of full event is finished. 

digits->clusters
	A set of neighboring digits compose cluster. The aim of this transformation is to construct a list of clusters out of digits list.
  The calling sequence is:
  AliReconstruction::Run()
  
  	AliHMPIDReconstructor::Reconstruct() creates an empty clusters list,  loops on chambers, retrieves a list of digits for a given chamber, gives it to the method Dig2Clu() and finally serializes
                                        the list 
                                        
    	AliHMPIDReconstructor::Dig2Clu() which knows no details about 


clusters+tracks->theta cerenkov 

	
	
	
How to get correct magnetic field:
	mag field is needed for simulation as well as reconstruction
        






Generalized structure of AliReconstruction:

Run()
{
  if(there is galice.root)                                        <-|
    AliRunLoader::Open(....)                                        | 
  else                                                              | this is done in InitRunLoader()
    if(raw data process requested)                                  |
      create galice.root on the base of AliRawReader::NextEvent   <-|   
  
  for(all detectors){                                             <-|
   if(detector not selected to run) skip this detector              | this is done in RunLocalReconstruction()
   reconstructor=get detector's reconstructor                       | 
                                                                    |   
   if(detector HasLocalReconstruction) skip this detector           | IMPORTANT! if HasLocalReconstruction() returns YES use RunLocalEventReconstruction instead
   if(run upon raw data)                                            |  
     reconstructor->Reconstruct(fRunLoader, fRawReader);            |   
   else                                                             | <- this approach is currently used by HMPID as all branches are mounted in AliHMPID.cxx
     reconstructor->Reconstruct(fRunLoader);                        |
  }                                                               <-|  

  for(all events){                                                      
  
    for(all detectors){                                                 |            
      if(detector not selected to run) skip this detector               |
      reconstructor=get detector's reconstructor                        | 
      loader=get detector's loader                                      | this is done in RunLocalEventReconstruction()
      if(raw data process requested and detector HasDigitConversion){   | 
        loader->LoadDigits("update");                                   | open file and invoke  detector->SetTreeAddress();
        loader->CleanDigits();                                          |   
        loader->MakeDigitsContainer();                                  | create tree
        reconstructor->Reconstruct(fRawReader,loader->TreeD());         | expected to fill TreeD out of raw reader
        loader->WriteDigits("overwrite");                               | 
        loader->UnloadDigits();                                         |  
      }                                                                 |
      if(detector do not HasLocalReconstruction) skip this detector     | IMPORTANT! assumed that this detector is already processed in RunLocalReconstruction()
      loader->LoadRecPoints("update");                                  |
      loader->CleanRecPoints();                                         |
      loader->MakeRecPointsContainer();                                 | 
      if(fRawReader && reconstructor do not HasDigitConversion()){      | 
        reconstructor->Reconstruct(fRawReader, loader->TreeR());        | expected to fill TreeR out of raw reader
      }else{                                                            |
        loader->LoadDigits("read");                                     |
        reconstructor->Reconstruct(loader->TreeD(),loader->TreeR());    | the only operations inside are pDigTree->GetEntry(0) and pCluTree->Fill();
        loader->UnloadDigits();                                         | 
      }                                                                 |
      loader->WriteRecPoints("OVERWRITE");                              |
      loader->UnloadRecPoints();                                        |
    }//detectors loop                                                   |
    
  }//events loop 
}


HMPID calibration and alignment.

Abstract
HMPID calibration and alignment strategy is described with emphasis put on those aspects of the procedure which are relevant for reconstruction and thus the final detector
figure of merit. In particular, the refractive index calibration technique based on mass plot shifts analysis and chamber alignment with respect to core detectors 
are explained in details. External sources of calibration and alignment data are also mentioned as well as the way HMPID intends to handle those data, including initial CDB
creator. 

Calibration. 
Looking on HMPID chamber structure, full description of which is available elsewhere (ref RichTDR), easy to compile the table of all possible parameters affecting reconstruction.
The first one of major importance is a freon refractive index. Although the full optical path visible by photons includes freon vessel, proximity and amplification gaps filled 
with methane and quartz window separating above mentioned volumes, only freon refractive index is subject for calibration.  Refractive index of SiO2 window is not practically 
affected by any external parameters, while influence of methane temperature to it's refractive index is negligible. So it's enough to measure there optical curves just once.
In the rest, the only changeable parameter is refractive index of freon. Temperature influence on freon refractive index was measured experimentally. The parametrization 
found to be:
  n=n0-0.0005(T-20)                        where T is freon temperature in degrees Celsius
  n0=Sqrt(1+ 0.554*lamda^2/(lamda^2-5796)) where lamda is photon wavelength in nm taken at 20 degrees Celsius
Preliminary, the parametrization itself is considered to be permanent one. The only parameter to store and retrieve is freon temperature. Since this value is available from
DCS DB and expected to be served by a SHUTTLE program which is not yet ready, the following temporarily solution has been adopted.
In local CDB storage (default directory is $ALICE_ROOT) two versions of freon refractive index are written by external macro RichCdb.C :
Run0_0_v0_s0.root contains DiMauro's parametrization and the temperature is set to 20 degrees. To be used as default for simulation and reconstruction.
Run0_0_v0_s1.root contains DiMauro's parametrization and the temperature is set to 50 degrees. To be used in special uncalibrated reconstruction to test calibration procedure. 
Both of them are valid in run range from run number 0 to run number 0, thus in no way affecting any normal operations.   

Refractive index of freon (C6F14) is taken in AliHMPIDRecon for 3 different photon energies by means of 2 methods: Set



Alignment.
Information about detector position and orientation is needed during reconstruction phase. This information affects track-cluster matching procedure, the relevant peace of 
code comes to AliHMPIDTracker::PropogateBack(). Matching procedure consists in prolongation of the track reconstructed in core detectors up to each HMPID chamber plane in 
a sequence. The plane used is the entrance to HMPID radiators. If the intersection exists and inside the sensitive area, the point of intersection is to be transformed to HMPID
local reference system. Note, that in this check, the dead zones in-between radiators are not taken into account. This operation requiring MARS to LORS transformations is done
in AliHMPIDHelix::RichIntersection(). Plane to be intersected is defined by a point belonging to that plane served by AliHMPIDParam::Center(ChamberNumber) and a vector normal 
to the plane served by AliHMPIDParam::Norm(ChamberNumber). Transformations itself are done in AliHMPIDParam::Mars2Lors() and AliHMPIDParam::Lors2Mars(). Internaly in AliHMPIDParam, 
each chamber is represented by TGeoHMatrix. It's worth to stress again that geometry related operations are needed to be done for 3 different planes per chamber, namely entrance 
to radiator, anode wires plane and photocathode plane. So AliHMPIDParam sustains 7*3=21 planes. Also important to say, that direct usage of TGeoHMatrix::MasterToLocal() 
and vice versa is not possible due to special nature of HMPID LORS. According to the decision made about 3 years ago, HMPID local reference system is centered in low left
hand corner of the chamber if one looks from outside to direction pointing to intersection point.
So the most obvious candidate for alignable objects to be stored are these 21 TGeoHMatrix objects. 
The approach suggested in AliAlignObj is not quite feasible mainly due to the fact it relays on incrementing procedure using import from geometry.root. HMPID geometry is defined 
in a way that there is no volumes exactly corresponding to the HMPID planes. 

Geometry of HMPID chambers.
After the decision to rotate the whole HMPID setup from 12 o'clock position to 2 o'clock position we have the following situation:

Theta = 109.5 degrees for chambers 1,3
Theta =  90.0 degrees for chambers 2,4,6
Theta =  70.5 degrees for chambers 5,7

Phi   =  50.0 degrees for chambers 6,7 
Phi   =  30.0 degrees for chambers 3,4,5 
Phi   =  10.0 degrees for chambers 1,2 


Old parametrization by AliHMPIDChamber:
HMPID chamber 1 (454.877118 ,  80.207109 , -163.565361)(rho,theta,phi)=(490.0,109.5,10.0)
HMPID chamber 2 (482.555799 ,  85.087607 ,    0.000000)(rho,theta,phi)=(490.0, 90.0,10.0)
HMPID chamber 3 (400.012224 , 230.947165 , -163.565361)(rho,theta,phi)=(490.0,109.5,30.0)
HMPID chamber 4 (424.352448 , 245.000000 ,    0.000000)(rho,theta,phi)=(490.0, 90.0,30.0)
HMPID chamber 5 (400.012224 , 230.947165 ,  163.565361)(rho,theta,phi)=(490.0, 70.5,30.0)
HMPID chamber 6 (314.965929 , 375.361777 ,    0.000000)(rho,theta,phi)=(490.0, 90.0,50.0)
HMPID chamber 7 (296.899953 , 353.831585 ,  163.565361)(rho,theta,phi)=(490.0, 70.5,50.0)

New parametrization by TGeoHMatrix:  perfect geometry, no misalignment
HMPID 0
 -0.328736   -0.173648    0.928321    Tx = 454.877118
 -0.057965    0.984808    0.163688    Ty =  80.207109
 -0.942641    0.000000   -0.333807    Tz = -163.565361
HMPID 1
  0.000000   -0.173648    0.984808    Tx = 482.555799
  0.000000    0.984808    0.173648    Ty =  85.087607
 -1.000000    0.000000    0.000000    Tz =   0.000000
HMPID 2
 -0.289085   -0.500000    0.816351    Tx = 400.012224
 -0.166903    0.866025    0.471321    Ty = 230.947165
 -0.942641    0.000000   -0.333807    Tz = -163.565361
HMPID 3
  0.000000   -0.500000    0.866025    Tx = 424.352448
  0.000000    0.866025    0.500000    Ty = 245.000000
 -1.000000    0.000000    0.000000    Tz =   0.000000
HMPID 4
  0.289085   -0.500000    0.816351    Tx = 400.012224
  0.166903    0.866025    0.471321    Ty = 230.947165
 -0.942641    0.000000    0.333807    Tz = 163.565361
HMPID 5
  0.000000   -0.766044    0.642788    Tx = 314.965929
  0.000000    0.642788    0.766044    Ty = 375.361777
 -1.000000    0.000000    0.000000    Tz =   0.000000
HMPID 6
  0.214567   -0.766044    0.605918    Tx = 296.899953
  0.255711    0.642788    0.722105    Ty = 353.831585
 -0.942641    0.000000    0.333807    Tz = 163.565361