ec958e92e7cda45e2cce68f581ef1ddb60186017
[u/mrichter/AliRoot.git] / RICH / api.txt
1 How to open session:
2         use static method  AliRunLoader::Open("galice.root","AlicE","update")
3 How to get total number of events in galice.root:
4         use AliRun::GetEventsPerRun()  or AliRunLoader::GetNumberOfEvents()      
5 How to avoid using gAlice:
6         detector->GetLoader()->GetRunLoader()->GetAliRun() returns gAlice global pointer.
7 How to retrieve pointer to alice run loader:
8         use pRICH->GetLoader()->GetRunLoader() (all detector classes inherit from AliDetector which has GetLoader())
9         use method AliRun::GetRunLoader for gAlice (deprecated)
10 How to get pointers to different root trees:
11         TreeE belongs to AliRunLoader, available after AliRunLoader::LoadHeader()
12         TreeK belongs to AliRunLoader, available after AliRunLoader::LoadKinematics()
13         TreeH belongs to AliLoader   , available after AliLoader::LoadHits()
14         TreeS belongs to AliLoader   , available after AliLoader::LoadSDigits()
15         TreeD belongs to AliLoader   , available after AliLoader::LoadDigits()
16         TreeR belongs to AliLoader   , available after AliLoader::LoadRecPoints()
17         all methods return 0 on success. 
18 How to get event of interest:
19         AliRunLoader::GetEvent(event_number) returns 0 on success
20 How to deal with the stack of particles?
21         - first of all, the stack includes primary as well as secondary particles
22         - pointer to the stack is taken:
23                 AliRun::Stack() (global gAlice of type AliRun - deprecated way to do)
24                 AliRunLoader::Stack() but before one needs to load event header by AliRunLoader::LoadHeader() otherwise both methods return 0.
25                 Moreover loading header gives the information about number of particles only. 
26                 To retrieve the list of particle one also needs to load kinematics by AliRunLoader::LoadKinematics()        
27         - total amount of particles in stack for a given event:        
28                 AliStack::GetNtrack() 
29                 AliRun::GetEvent() (after LoadHeader())
30         - total amount of primary particles in stack for a given event (after LoadHeader()): 
31                 AliStack::GetNprimary() 
32 How to retrieve hits:
33         Hits are stored on primary by primary basis. Hits for the given primary is TClonesArray.
34         To retrieve all hits one needs to do:
35         -initialize the root tree and containers:   pRich->GetLoader()->LoadHits();  (AliLoader::LoadHits() returns 0 on success)
36         -read number of entries in TreeH:           pRich->GetLoader()->TreeH()->GetEntries()
37         -then for each entry:                       pRich->GetLoader()->TreeH()->GetEntry(i)
38 How to retrieve sdigits? 
39         Sdigits stored in tree S with the branch of TClonesArray, all sdigits in a single TClonesArray
40         So the tree has only one entry.
41         One needs to say:
42         -pRich->GetLoader()->LoadSDigits(); this one open file, get the tree and invoke AliRICH::SetTreeAddress()    
43 How to retrieve digits? 
44         Digits stored in tree D with the 7 branches of TClonesArray, one per chamber, all digits of a given chamber in a single TClonesArray
45         So the tree has only one entry.
46         -One needs to say:
47           pRich->GetLoader()->LoadDigits(); this one opens file, gets the tree and invoke AliRICH::SetTreeAddress() which in turn corresponds 
48           branches of the tree to the digits containers in memory. There are 7 containers, one per chamber, all of them belong to AliRICH.
49         -Then one needs to take the tree entry (only one) to the memory:
50           pRich->GetLoader()->TreeD()->GetEntry(0) 
51         -Finally pRich->Digits(chamber_number) returns the pointer to TClonesArray of AliRICHdigit          
52 What are the debug methods avail:
53         AliLog::SetGlobalDebugLevel(AliLog::kDebug)
54 How to get info for a given particle number:
55         Header and Kinematics trees must be loaded, then possible to retrieve pointer to Stack of particles
56         Int_t AliRunLoader::LoadHeader(); Int_t AliRunLoader::LoadKinematics()
57         AliStack *AliRunLoader::Stack()
58         TParticle *AliStack::Particle(tid)
59         TParticle::Print()
60 How to deal with AliRunDigitizer:
61         AliRunDigitizer::Exec() just call AliRunDigitizer::Digitize()   
62 What are the meanings of different VMC flags:         
63         gMC->IsTrackAlive()
64         gMC->IsTrackStop()
65         gMC->IsTrackDisappeared()
66 How to get pad number for a local position:
67         use static TVector AliRICHParam::Loc2Pad(TVector2 position);
68 Why list of chambers belongs to AliRICHParam:
69
70 How to check if a given stack particle is primary:
71         Stack is TClonesArray of TParticle. TParticle::GetMother(0) returns -1 if it's primary (no mother)         
72 How to loop over all possible object:         
73   for(Int_t iEventN=0;iEventN < GetLoader()->GetRunLoader()->GetAliRun()->GetEventsPerRun();iEventN++){//events loop
74     for(Int_t iEntryN=0;iEntryN < GetLoader()->TreeH()->GetEntries();iEntryN++){//TreeH loop
75       GetLoader()->TreeH()->GetEntry(iEntryN);//get current entry (prim)  
76       for(Int_t iHitN=0;iHitN<Hits()->GetEntries();iHitN++){//hits loop
77         AliVHMPIDHit *pHit=(AliVHMPIDHit*)Hits()->At(iHitN);//get current hit 
78         
79       }//hits loop
80     }//TreeH loop
81   }//events loop
82
83
84 RICH full simulation-reconstruction sequence
85
86 hits->sdigit:
87         Responsible method is AliRICH::Hits2SDigits
88         One hit may affect one or more pads.
89         Hit position is taken on the anode wires plane as the most of avalanche is developed there.
90         This position is not directly available, track intersections with entrance and exit of amplification gap are only stored.
91         So the position in the middle of the gap is calculated as average out of pHit->In() and pHit->Out() positions.
92         Then, total charge collected for this hit is calculated by AliRICHParam::Hit2Qdc.    
93         Area of disintegration is a list of pads affected by current hit. This is a parameter of Mathienson    
94 sdigits->digits:
95         The necessety of sdigits is dictated by the fact that trasport engine transports tracks in a continious sequence track by track. 
96   It means that it may happen that the same pad is affected by few tracks. But this might be known only after the trasport of full event is finished. 
97
98 digits->clusters
99         A set of neighbouring digits compose cluster. The aim of this trasformation is to construct a list of clusters out of digits list.
100   The calling sequence is:
101   AliReconstruction::Run()
102   
103         AliRICHReconstructor::Reconstruct() creates an empty clusters list,  loops on chambers, retrives a list of digits for a given chamber, gives it to the methode Dig2Clu() and finally serializes
104                                         the list 
105                                         
106         AliRICHReconstructor::Dig2Clu() which knows no details about 
107
108
109 clusters+tracks->theta cerenkov 
110
111         
112         
113         
114
115
116
117
118
119
120
121 Generalized structure of AliReconstruction:
122
123 Run()
124 {
125   if(there is galice.root)                                        <-|
126     AliRunLoader::Open(....)                                        | 
127   else                                                              | this is done in InitRunLoader()
128     if(raw data process requested)                                  |
129       create galice.root on the base of AliRawReader::NextEvent   <-|   
130   
131   for(all detectors){                                             <-|
132    if(detector not selected to run) skip this detector              | this is done in RunLocalReconstruction()
133    reconstructor=get detector's reconstructor                       | 
134                                                                     |   
135    if(detector HasLocalReconstruction) skip this detector           | IMPORTANT! if HasLocalReconstruction() returns YES use RunLocalEventReconstruction instead
136    if(run upon raw data)                                            |  
137      reconstructor->Reconstruct(fRunLoader, fRawReader);            |   
138    else                                                             | <- this approach is currently used by RICH as all branches are mounted in AliRICH.cxx
139      reconstructor->Reconstruct(fRunLoader);                        |
140   }                                                               <-|  
141
142   for(all events){                                                      
143   
144     for(all detectors){                                                 |            
145       if(detector not selected to run) skip this detector               |
146       reconstructor=get detector's reconstructor                        | 
147       loader=get detector's loader                                      | this is done in RunLocalEventReconstruction()
148       if(raw data process requested and detector HasDigitConversion){   | 
149         loader->LoadDigits("update");                                   | open file and invoke  detector->SetTreeAddress();
150         loader->CleanDigits();                                          |   
151         loader->MakeDigitsContainer();                                  | create tree
152         reconstructor->Reconstruct(fRawReader,loader->TreeD());         | expected to fill TreeD out of raw reader
153         loader->WriteDigits("overwrite");                               | 
154         loader->UnloadDigits();                                         |  
155       }                                                                 |
156       if(detector do not HasLocalReconstruction) skip this detector     | IMPORTANT! assumed that this detector is already processed in RunLocalReconstruction()
157       loader->LoadRecPoints("update");                                  |
158       loader->CleanRecPoints();                                         |
159       loader->MakeRecPointsContainer();                                 | 
160       if(fRawReader && reconstructor do not HasDigitConversion()){      | 
161         reconstructor->Reconstruct(fRawReader, loader->TreeR());        | expected to fill TreeR out of raw reader
162       }else{                                                            |
163         loader->LoadDigits("read");                                     |
164         reconstructor->Reconstruct(loader->TreeD(),loader->TreeR());    | the only operations inside are pDigTree->GetEntry(0) and pCluTree->Fill();
165         loader->UnloadDigits();                                         | 
166       }                                                                 |
167       loader->WriteRecPoints("OVERWRITE");                              |
168       loader->UnloadRecPoints();                                        |
169     }//detectors loop                                                   |
170     
171   }//events loop 
172 }
173
174
175 RICH calibration and alignment.
176
177 Abstract
178 RICH calibrartion and alignment strategy is described with emphasis put on those aspects of the procedure which are relevant for reconstruction and thus the final detector
179 figure of merit. In particulare, the refractive index calibration tecknique based on mass plot shifts analisys and chamber alignment with respect to core detectors 
180 are explained in details. External sources of calibration and alignment data are aslo mentioned as well as the way RICH intends to handle those data, including initial CDB
181 creater. 
182
183 Calibration. 
184 Looking on RICH chamber structure, full description of which is availbale elsewhere (ref RichTDR), easy to compile the table of all possible parameters affecting reconstruction.
185 The first one of major importance is a freon refractive index. Although the full optical path visiable by photons includes freon vessel, proximity and amplification gaps filled 
186 with methane and quartz window seperating above mentioned volumes, only freon refractive index is subject for calibration.  Refractive index of SiO2 window is not practically 
187 affected by any external parameters, while influence of methane temperature to it's refractive index is negligable. So it's enough to measure there optical curves just once.
188 In the rest, the only changable parameter is refractive index of freon. Temperature influence on freon refractive index was measured experimentally. The parametrization 
189 found to be:
190   n=n0-0.0005(T-20)                        where T is freon temperature in degrees Celsius
191   n0=Sqrt(1+ 0.554*lamda^2/(lamda^2-5796)) where lamda is photon wavelength in nm taken at 20 degress Celsius
192 Preliminary, the parametrization itself is considered to be permamnent one. The only parameter to store and retrieve is freon temperature. Since this value is available from
193 DCS DB and expected to be served by a SHUTTLE program which is not yet ready, the following temporaroly solution has been adopted.
194 In local CDB storage (deafult directory is $ALICE_ROOT) two versions of freon refractive index are written by external macro RichCdb.C :
195 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.
196 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. 
197 Both of them are valid in run range from run number 0 to run number 0, thus in no way affecting any normal operations.   
198
199 Refractive index of freon (C6F14) is taken in AliRICHRecon for 3 different photon energies by means of 2 methodes: Set
200
201
202
203 Alignment.
204 Information about detector position and orientation is needed during reconstruction phase. This information affects track-cluster matching procedure, the relevant peace of 
205 code comes to AliRICHTracker::PropogateBack(). Matching precedure consists in prolongation of the track reconstructed in core detectores up to each RICH chamber plane in 
206 a sequenmce. The plane used is the entrance to RICH radiators. If the intersection exists and inside the sensitive area, the point of intersection is to be tranformed to RICH
207 local reference system. Note, that in this check, the dead zones inbetween radiators are not taken into account. This operation requiring MARS to LORS transformations is done
208 in AliRICHHelix::RichIntersection(). Plane to be intersected is defined by a point beloging to that plane served by AliRICHParam::Center(ChamberNumber) and a vector normal 
209 to the plane served by AliRICHParam::Norm(ChamberNumber). Transformations itself are done in AliRICHParam::Mars2Lors() and AliRICHParam::Lors2Mars(). Internaly in AliRICHParam, 
210 each chamber is reresented by TGeoHMatrix. It's worth to stress again that geometry related operations are needed to be done for 3 different planes per chamber, namly entrance 
211 to radiator, anod wires plane and photocathode plane. So AliRICHParam sustains 7*3=21 planes. Also important to say, that direct usage of TGeoHMatrix::MasterToLocal() 
212 and virce versa is not possible due to special nature of RICH LORS. According to the decision made about 3 years ago, RICH local reference system is centered in low left
213 hand corner of the chamber if one looks from outside to direction pointing to interection point.
214 So the most obvious candidate for alignable objects to be stored are thess 21 TGeoHMatrix objects. 
215 The approach suggested in AliAlignObj is not quite feasable mainly due to the fact it relays on incrementing procedure using import from geometry.root. RICH geometry is defined 
216 in a way that there is no volumes exactly corresponding to the RICH planes. 
217
218 Geometry of RICH chambers.
219 After the decision to rotate the whole RICH setup from 12 o'clock position to 2 o'clock position we have the following situtation:
220
221 Theta = 109.5 degress for chambers 1,3
222 Theta =  90.0 degress for chambers 2,4,6
223 Theta =  70.5 degress for chambers 5,7
224
225 Phi   =  50.0 degress for chambers 6,7 
226 Phi   =  30.0 degress for chambers 3,4,5 
227 Phi   =  10.0 degress for chambers 1,2 
228
229
230 Old parametrisation by AliRICHChamber:
231 RICH chamber 1 (454.877118 ,  80.207109 , -163.565361)(rho,theta,phi)=(490.0,109.5,10.0)
232 RICH chamber 2 (482.555799 ,  85.087607 ,    0.000000)(rho,theta,phi)=(490.0, 90.0,10.0)
233 RICH chamber 3 (400.012224 , 230.947165 , -163.565361)(rho,theta,phi)=(490.0,109.5,30.0)
234 RICH chamber 4 (424.352448 , 245.000000 ,    0.000000)(rho,theta,phi)=(490.0, 90.0,30.0)
235 RICH chamber 5 (400.012224 , 230.947165 ,  163.565361)(rho,theta,phi)=(490.0, 70.5,30.0)
236 RICH chamber 6 (314.965929 , 375.361777 ,    0.000000)(rho,theta,phi)=(490.0, 90.0,50.0)
237 RICH chamber 7 (296.899953 , 353.831585 ,  163.565361)(rho,theta,phi)=(490.0, 70.5,50.0)
238
239 New parametrization by TGeoHMatrix: 
240 RICH 1
241  -0.328736   -0.173648    0.928321    Tx = 454.877118
242  -0.057965    0.984808    0.163688    Ty =  80.207109
243  -0.942641    0.000000   -0.333807    Tz = -163.565361
244 RICH 2
245   0.000000   -0.173648    0.984808    Tx = 482.555799
246   0.000000    0.984808    0.173648    Ty =  85.087607
247  -1.000000    0.000000    0.000000    Tz =   0.000000
248 RICH 3
249  -0.289085   -0.500000    0.816351    Tx = 400.012224
250  -0.166903    0.866025    0.471321    Ty = 230.947165
251  -0.942641    0.000000   -0.333807    Tz = -163.565361
252 RICH 4
253   0.000000   -0.500000    0.866025    Tx = 424.352448
254   0.000000    0.866025    0.500000    Ty = 245.000000
255  -1.000000    0.000000    0.000000    Tz =   0.000000
256 RICH 5
257   0.289085   -0.500000    0.816351    Tx = 400.012224
258   0.166903    0.866025    0.471321    Ty = 230.947165
259  -0.942641    0.000000    0.333807    Tz = 163.565361
260 RICH 6
261   0.000000   -0.766044    0.642788    Tx = 314.965929
262   0.000000    0.642788    0.766044    Ty = 375.361777
263  -1.000000    0.000000    0.000000    Tz =   0.000000
264 RICH 7
265   0.214567   -0.766044    0.605918    Tx = 296.899953
266   0.255711    0.642788    0.722105    Ty = 353.831585
267  -0.942641    0.000000    0.333807    Tz = 163.565361