Deleted wrong file
[u/mrichter/AliRoot.git] / HMPID / api.txt
1 How to open session:
2         use static method  AliRunLoader::Open("galice.root","AlicE","update") or just AliRunLoader::Open() for defaults. 
3         Returns pointer to AliRunLoader on success or fatal termination on error
4 How to get total number of events in galice.root:
5         AliRunLoader::GetNumberOfEvents()  (or AliRun::GetEventsPerRun() using f.e. gAlice deprecated)
6 How to get pointer to HMPID:
7         AliRunLoader()->GetAliRun()->GetDetector("HMPID") but before one needs to AliRunLoade()->Set
8 How to avoid using gAlice:
9         detector->GetLoader()->GetRunLoader()->GetAliRun() returns gAlice global pointer.
10 How to retrieve pointer to alice run loader:
11         use pHMPID->GetLoader()->GetRunLoader() (all detector classes inherit from AliDetector which has GetLoader())
12         use method AliRun::GetRunLoader for gAlice (deprecated)
13 How to get pointers to different root trees:
14         TreeE belongs to AliRunLoader, available after AliRunLoader::LoadHeader()
15         TreeK belongs to AliRunLoader, available after AliRunLoader::LoadKinematics()
16         TreeH belongs to AliLoader   , available after AliLoader::LoadHits()
17         TreeS belongs to AliLoader   , available after AliLoader::LoadSDigits()
18         TreeD belongs to AliLoader   , available after AliLoader::LoadDigits()
19         TreeR belongs to AliLoader   , available after AliLoader::LoadRecPoints()
20         all methods return 0 on success. 
21 How to get event of interest:
22         AliRunLoader::GetEvent(event_number) returns 0 on success
23 How to deal with the stack of particles?
24         - first of all, the stack includes primary as well as secondary particles
25         - pointer to the stack is taken:
26                 AliRunLoader::Stack() but before one needs to load event header by AliRunLoader::LoadHeader() otherwise both methods return 0.
27                 Moreover loading header gives the information about number of particles only. 
28                 To retrieve the list of particle one also needs to load kinematics by AliRunLoader::LoadKinematics()        
29         - total amount of particles in stack for a given event:        
30                 AliStack::GetNtrack() 
31         - total amount of primary particles in stack for a given event (after LoadHeader()): 
32                 AliStack::GetNprimary() 
33 How to retrieve hits:
34         Hits are stored on primary by primary basis (hits corresponding to primary particles stored in a single entry; total number of entries in hits tree equals
35         to number of primaries; order of primaries is not preserved). Hits for the given primary is TClonesArray.
36         To retrieve all hits one needs to do:
37         -initialize the root tree and containers:   pRich->GetLoader()->LoadHits();  (AliLoader::LoadHits() returns 0 on success)
38         -read number of entries in TreeH:           pRich->GetLoader()->TreeH()->GetEntries()
39         -then for each entry:                       pRich->GetLoader()->TreeH()->GetEntry(i)    
40 How to retrieve sdigits? 
41         Sdigits stored in tree S with the branch of TClonesArray, all sdigits in a single TClonesArray
42         So the tree has only one entry.
43         One needs to say:
44         -pRich->GetLoader()->LoadSDigits(); this one open file, get the tree and invoke AliHMPID::SetTreeAddress()    
45 How to retrieve digits? 
46         Digits stored in tree D with the 7 branches of TClonesArray, one per chamber, all digits of a given chamber in a single TClonesArray
47         So the tree has only one entry.
48         -One needs to say:
49           pRich->GetLoader()->LoadDigits(); this one opens file, gets the tree and invoke AliHMPID::SetTreeAddress() which in turn corresponds 
50           branches of the tree to the digits containers in memory. There are 7 containers, one per chamber, all of them belong to AliHMPID.
51         -Then one needs to take the tree entry (only one) to the memory:
52           pRich->GetLoader()->TreeD()->GetEntry(0) 
53         -Finally pRich->Digits(chamber_number) returns the pointer to TClonesArray of AliHMPIDdigit          
54 What are the debug methods avail:
55         AliLog::SetGlobalDebugLevel(AliLog::kDebug)
56 How to get info for a given particle number:
57         Header and Kinematics trees must be loaded, then possible to retrieve pointer to Stack of particles
58         Int_t AliRunLoader::LoadHeader(); Int_t AliRunLoader::LoadKinematics()
59         AliStack *AliRunLoader::Stack()
60         TParticle *AliStack::Particle(tid)
61         TParticle::Print()
62 How to deal with AliRunDigitizer:
63         AliRunDigitizer::Exec() just call AliRunDigitizer::Digitize()   
64 What are the meanings of different VMC flags:         
65         gMC->IsTrackAlive()
66         gMC->IsTrackStop()
67         gMC->IsTrackDisappeared()
68 How to get pad number for a local position:
69         use static TVector AliHMPIDParam::Loc2Pad(TVector2 position);
70
71 How to check if a given stack particle is primary:
72         Stack is TClonesArray of TParticle. TParticle::GetMother(0) returns -1 if it's primary (no mother)         
73 How to loop over all possible object:         
74   for(Int_t iEventN=0;iEventN < GetLoader()->GetRunLoader()->GetAliRun()->GetEventsPerRun();iEventN++){//events loop
75     for(Int_t iEntryN=0;iEntryN < GetLoader()->TreeH()->GetEntries();iEntryN++){//TreeH loop
76       GetLoader()->TreeH()->GetEntry(iEntryN);//get current entry (prim)  
77       for(Int_t iHitN=0;iHitN<Hits()->GetEntries();iHitN++){//hits loop
78         AliHMPIDHit *pHit=(AliHMPIDHit*)Hits()->At(iHitN);//get current hit 
79         
80       }//hits loop
81     }//TreeH loop
82   }//events loop
83
84
85 HMPID full simulation-reconstruction sequence
86
87 hits creation:
88         HMPID uses 2 types fo hits: MIP hit and photon hit. Both types are implemented in the same class AliHMPIDHit.
89         The difference in ctor patterns is only in energy variable: for photon it is full energy, whereas for MIP it's energy lost in amplification gap gas.
90         Hit for photon is created when photon enters the volume representing a single pad of segmeneted photocathode and survives QE test.
91         Hit for MIP is created when MIP exits amplification gap (or disappired for whatever reason). The responsible code is AliHMPIDv1::StepManager().
92         Internally in ctor, the energy is converted to the total charge accamulated for this hit expressed in QCD channels. This is done in a honest manner for photon:
93         photon always produces a single electron, and the response of the chamber to a single electron pulse is parametrized out of test beam data for few HV sets.
94         For MIP the same procedure is generally wrong: the total energy lost by particle is devided by ionization potential, this value is interpreted as number of electrons
95         created, then each electon contribution is sampled according to puasonian distribution with the same single electron pulse mean as fro photons. The final charge is
96         then a sum of all single electon's contributions, it substitutes the value of energy.
97 hits->sdigit:
98         Due to segmented photocathode, single hit might affect few neighboring pads (up to 9 in our default parametrization). The total charge collected by a single pad
99         is the answer to electrostatic problem solved in article by Mathieson (see ref ???). Actual disintegration is implemented in AliHMPIDHit::Hit2Sdi().
100         The implementation creates by default sdigits only for closest neighbours of a pad containing hit positon (further neighbours might also be checked subject to
101         parameterization flag ?????? but the contribution to them from single hit is such a tiny that only large nubmer of close hits may provide something not negligable). 
102 sdigits->digits:
103         The necessety of sdigits is dictated by the fact that transport engine transports tracks in a continuous sequence track by track. 
104         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. 
105         So the task of this convertion is to collect all the sdigits for the same pad and sum them up. This is done in AliHMPIDDigitizer::Exec(). This technique also provides
106         the possibility to mix events from seperate simulations facilitating studies of rare signals on top of huge background.
107 digits->clusters
108         The aim of this conversion is to try to reconstruct the initial position of hits.
109         This it done by 2 steps procedure. On first step so called raw cluster is formed as a composition of all neighboring pads (diagonal pads are not allowed).
110         Then center of gravity of the cluster is calculated and used as a naive estimate of hit position. 
111         On second step, the code tries to improve the hit position  knowledge by fitting by local maxima number of Mathieson shapes. If the procedure failes, the cog
112         position is preserved as hit position.
113 clusters+tracks->theta cerenkov 
114
115         
116         
117         
118 How to get correct magnetic field:
119         mag field is needed for simulation as well as reconstruction
120         
121
122
123
124
125
126
127 Generalized structure of AliReconstruction:
128
129 Run()
130 {
131   if(there is galice.root)                                        <-|
132     AliRunLoader::Open(....)                                        | 
133   else                                                              | this is done in InitRunLoader()
134     if(raw data process requested)                                  |
135       create galice.root on the base of AliRawReader::NextEvent   <-|   
136   
137   for(all detectors){                                             <-|
138    if(detector not selected to run) skip this detector              | this is done in RunLocalReconstruction()
139    reconstructor=get detector's reconstructor                       | 
140                                                                     |   
141    if(detector HasLocalReconstruction) skip this detector           | IMPORTANT! if HasLocalReconstruction() returns YES use RunLocalEventReconstruction instead
142    if(run upon raw data)                                            |  
143      reconstructor->Reconstruct(fRunLoader, fRawReader);            |   
144    else                                                             | <- this approach is currently used by HMPID as all branches are mounted in AliHMPID.cxx
145      reconstructor->Reconstruct(fRunLoader);                        |
146   }                                                               <-|  
147
148   for(all events){                                                      
149   
150     for(all detectors){                                                 |            
151       if(detector not selected to run) skip this detector               |
152       reconstructor=get detector's reconstructor                        | 
153       loader=get detector's loader                                      | this is done in RunLocalEventReconstruction()
154       if(raw data process requested and detector HasDigitConversion){   | 
155         loader->LoadDigits("update");                                   | open file and invoke  detector->SetTreeAddress();
156         loader->CleanDigits();                                          |   
157         loader->MakeDigitsContainer();                                  | create tree
158         reconstructor->Reconstruct(fRawReader,loader->TreeD());         | expected to fill TreeD out of raw reader
159         loader->WriteDigits("overwrite");                               | 
160         loader->UnloadDigits();                                         |  
161       }                                                                 |
162       if(detector do not HasLocalReconstruction) skip this detector     | IMPORTANT! assumed that this detector is already processed in RunLocalReconstruction()
163       loader->LoadRecPoints("update");                                  |
164       loader->CleanRecPoints();                                         |
165       loader->MakeRecPointsContainer();                                 | 
166       if(fRawReader && reconstructor do not HasDigitConversion()){      | 
167         reconstructor->Reconstruct(fRawReader, loader->TreeR());        | expected to fill TreeR out of raw reader
168       }else{                                                            |
169         loader->LoadDigits("read");                                     |
170         reconstructor->Reconstruct(loader->TreeD(),loader->TreeR());    | the only operations inside are pDigTree->GetEntry(0) and pCluTree->Fill();
171         loader->UnloadDigits();                                         | 
172       }                                                                 |
173       loader->WriteRecPoints("OVERWRITE");                              |
174       loader->UnloadRecPoints();                                        |
175     }//detectors loop                                                   |
176     
177   }//events loop 
178 }
179
180
181 HMPID calibration and alignment.
182
183 Abstract
184 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
185 figure of merit. In particular, the refractive index calibration technique based on mass plot shifts analysis and chamber alignment with respect to core detectors 
186 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
187 creator. 
188
189 Calibration. 
190 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.
191 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 
192 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 
193 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.
194 In the rest, the only changeable parameter is refractive index of freon. Temperature influence on freon refractive index was measured experimentally. The parametrization 
195 found to be:
196   n=n0-0.0005(T-20)                        where T is freon temperature in degrees Celsius
197   n0=Sqrt(1+ 0.554*lamda^2/(lamda^2-5769)) where lamda is photon wavelength in nm taken at 20 degrees Celsius
198 Preliminary, the parametrization of refractive index versus temperature and photon energy is considered to be permanent. 
199 As the reconstruction itself is only interested in mean refractive index Nmean C6F14, the most elegant solution is to store in OCDB this value, prcalculated in 
200 AliHMPIDPrecprocessor. 2 measurements of temperature is avaiable from DCS: for inlet and outlet. They come in form of TObjArray of AliDCSValue, where AliDCSValue
201 holds the value of temperature plus a time stamp at wich the value was taken. Due to organization of DCS, it's not possible to implay that all the points are taken at the same 
202 time, hence marked with the same time stamp. So the mean temperature are not calculable from inlet-outlet pair. Instead each sperate temperature data points are fitted.
203 The resulting functions provide mean temperature function.
204
205
206
207 In local CDB storage (default directory is $ALICE_ROOT) two versions of freon refractive index are written by external macro RichCdb.C :
208 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.
209 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. 
210 Both of them are valid in run range from run number 0 to run number 0, thus in no way affecting any normal operations.   
211
212 Refractive index of freon (C6F14) is taken in AliHMPIDRecon for 3 different photon energies by means of 2 methods: Set
213
214
215
216 Alignment.
217 Information about detector position and orientation is needed during reconstruction phase. This information affects track-cluster matching procedure, the relevant peace of 
218 code comes to AliHMPIDTracker::PropogateBack(). Matching procedure consists in prolongation of the track reconstructed in core detectors up to each HMPID chamber plane in 
219 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
220 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
221 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 
222 to the plane served by AliHMPIDParam::Norm(ChamberNumber). Transformations itself are done in AliHMPIDParam::Mars2Lors() and AliHMPIDParam::Lors2Mars(). Internaly in AliHMPIDParam, 
223 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 
224 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() 
225 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
226 hand corner of the chamber if one looks from outside to direction pointing to intersection point.
227 So the most obvious candidate for alignable objects to be stored are these 21 TGeoHMatrix objects. 
228 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 
229 in a way that there is no volumes exactly corresponding to the HMPID planes. 
230
231 Geometry of HMPID chambers.
232 After the decision to rotate the whole HMPID setup from 12 o'clock position to 2 o'clock position we have the following situation:
233
234 Theta = 109.5 degrees for chambers 1,3
235 Theta =  90.0 degrees for chambers 2,4,6
236 Theta =  70.5 degrees for chambers 5,7
237
238 Phi   =  50.0 degrees for chambers 6,7 
239 Phi   =  30.0 degrees for chambers 3,4,5 
240 Phi   =  10.0 degrees for chambers 1,2 
241
242
243 Old parametrization by AliHMPIDChamber:
244 HMPID chamber 1 (454.877118 ,  80.207109 , -163.565361)(rho,theta,phi)=(490.0,109.5,10.0)
245 HMPID chamber 2 (482.555799 ,  85.087607 ,    0.000000)(rho,theta,phi)=(490.0, 90.0,10.0)
246 HMPID chamber 3 (400.012224 , 230.947165 , -163.565361)(rho,theta,phi)=(490.0,109.5,30.0)
247 HMPID chamber 4 (424.352448 , 245.000000 ,    0.000000)(rho,theta,phi)=(490.0, 90.0,30.0)
248 HMPID chamber 5 (400.012224 , 230.947165 ,  163.565361)(rho,theta,phi)=(490.0, 70.5,30.0)
249 HMPID chamber 6 (314.965929 , 375.361777 ,    0.000000)(rho,theta,phi)=(490.0, 90.0,50.0)
250 HMPID chamber 7 (296.899953 , 353.831585 ,  163.565361)(rho,theta,phi)=(490.0, 70.5,50.0)
251
252 New parametrization by TGeoHMatrix:  perfect geometry, no misalignment
253 HMPID 0
254  -0.328736   -0.173648    0.928321    Tx = 454.877118
255  -0.057965    0.984808    0.163688    Ty =  80.207109
256  -0.942641    0.000000   -0.333807    Tz = -163.565361
257 HMPID 1
258   0.000000   -0.173648    0.984808    Tx = 482.555799
259   0.000000    0.984808    0.173648    Ty =  85.087607
260  -1.000000    0.000000    0.000000    Tz =   0.000000
261 HMPID 2
262  -0.289085   -0.500000    0.816351    Tx = 400.012224
263  -0.166903    0.866025    0.471321    Ty = 230.947165
264  -0.942641    0.000000   -0.333807    Tz = -163.565361
265 HMPID 3
266   0.000000   -0.500000    0.866025    Tx = 424.352448
267   0.000000    0.866025    0.500000    Ty = 245.000000
268  -1.000000    0.000000    0.000000    Tz =   0.000000
269 HMPID 4
270   0.289085   -0.500000    0.816351    Tx = 400.012224
271   0.166903    0.866025    0.471321    Ty = 230.947165
272  -0.942641    0.000000    0.333807    Tz = 163.565361
273 HMPID 5
274   0.000000   -0.766044    0.642788    Tx = 314.965929
275   0.000000    0.642788    0.766044    Ty = 375.361777
276  -1.000000    0.000000    0.000000    Tz =   0.000000
277 HMPID 6
278   0.214567   -0.766044    0.605918    Tx = 296.899953
279   0.255711    0.642788    0.722105    Ty = 353.831585
280  -0.942641    0.000000    0.333807    Tz = 163.565361
281
282
283
284 Manual:
285 Diclaimer: We call the operator any persons who wants "to operate" HMPID that is to do something reasonalbe to understand current perfomance coming from the detector. 
286 This person is not necesarelly an expert in HMPID hardware and or software. 
287 Be also aware that analysis of HMPID data can only be perfomed from AliESD (taking also into acount some info which is not specific to HMPID). The task to plot something from
288 hits, digits or clusters is called quality assesment.
289
290 From operator point of view, one needs to do 3 different tasks with HMPID: simulation, reconstruction and QA.
291
292
293
294
295