Updated version of the Bari code to work with the HEAD. A new test macros has also...
[u/mrichter/AliRoot.git] / ITS / README
1 1. Introduction
2 ---------------
3
4 Dear ITS (and ALICE) user,
5
6      This is a short help on how to run the ITS simulation/reconstruction code 
7 within the AliRoot framework. It is NOT intended as a comprehensive user's 
8 guide and eventually it will be updated in the ITS Manual which is on its way 
9 to be written. What follows requires that the you already know how to download,
10 install and compile the AliRoot package. This file explains how to set the 
11 proper ITS geometry and how to tun the test macros contained under the 
12 directory ITS in order to compare your own installation with the standard one 
13 looking at some distributions/histograms.
14         Any difference between what is described here and what you really get
15 when you  run the code on your computer must be reported either to Roberto
16 Barbera at roberto.barbera@ct.infn.it or to Bjorn Nilsen at
17 nilsen@mps.ohio-state.edu. Please note that all the tests described here have
18 been done on a PC running Linux RedHat 6.1, gcc 2.95.2, and Root 3.00/06. If
19 you have different hardware/software configuration, please add it to all bug
20 reports.
21
22
23 2. Set the ITS geometry you want to use
24 ---------------------------------------
25
26 In order to set one of the many ITS geometries available, you have to modify 
27 the ITS part in the file Config.C under the directory macros (you have to
28 modify the file ConfigPPR.C if you want to run full 'PPR' events). The default
29 ITS part of Config.C (or ConfigPPR.C) is reported here:
30
31   if(iITS) {
32
33 //=================== ITS parameters ============================
34     //
35     // As the innermost detector in ALICE, the Inner Tracking System "impacts"
36     // on almost all other detectors. This involves the fact that the ITS
37     // geometry  still has several options to be followed in parallel in order
38     // to determine the best set-up which minimizes the induced background. All
39     // the geometries available to date are described in the following. Read
40     // carefully the comments and use the default version (the only one
41     // uncommented) unless you are making comparisons and you know what you are
42     // doing. In this case just uncomment the ITS geometry you want to use and
43     // run Aliroot.
44     //
45     // Detailed geometries:         
46     //
47     //
48     //AliITS *ITS  = new AliITSv5symm("ITS","Updated ITS TDR detailed version with symmetric services");
49     //
50     AliITS *ITS  = new AliITSv5asymm("ITS","Updates ITS TDR detailed version with asymmetric services");
51     //
52     //AliITSvPPRasymm *ITS  = new AliITSvPPRasymm("ITS","New ITS PPR detailed version with asymmetric services");
53     //ITS->SetMinorVersion(2);
54     //ITS->SetReadDet(kFALSE);
55     //ITS->SetWriteDet("$ALICE_ROOT/ITS/ITSgeometry_vPPRasymm2.det");
56     //ITS->SetThicknessDet1(300.);   // detector thickness on layer 1 must be in the range [100,300]
57     //ITS->SetThicknessDet2(300.);   // detector thickness on layer 2 must be in the range [100,300]
58     //ITS->SetThicknessChip1(300.);  // chip thickness on layer 1 must be in the range [150,300]
59     //ITS->SetThicknessChip2(300.);  // chip thickness on layer 2 must be in the range [150,300]
60     //ITS->SetRails(1);            // 1 --> rails in ; 0 --> rails out
61     //ITS->SetCoolingFluid(1);     // 1 --> water ; 0 --> freon
62     //
63     //AliITSvPPRsymm *ITS  = new AliITSvPPRsymm("ITS","New ITS PPR detailed version with symmetric services");
64     //ITS->SetMinorVersion(2);                                      
65     //ITS->SetReadDet(kFALSE);
66     //ITS->SetWriteDet("$ALICE_ROOT/ITS/ITSgeometry_vPPRsymm2.det");
67     //ITS->SetThicknessDet1(300.);   // detector thickness on layer 1 must be in the range [100,300]
68     //ITS->SetThicknessDet2(300.);   // detector thickness on layer 2 must be in the range [100,300]
69     //ITS->SetThicknessChip1(300.);  // chip thickness on layer 1 must be in the range [150,300]
70     //ITS->SetThicknessChip2(300.);  // chip thickness on layer 2 must be in the range [150,300]
71     //ITS->SetRails(1);              // 1 --> rails in ; 0 --> rails out
72     //ITS->SetCoolingFluid(1);       // 1 --> water ; 0 --> freon
73     //
74     //
75     // Coarse geometries (warning: no hits are produced with these coarse geometries and they unuseful 
76     // for reconstruction !):
77     //                                                     
78     //
79     //AliITSvPPRcoarseasymm *ITS  = new AliITSvPPRcoarseasymm("ITS","New ITS coarse version with asymmetric services");
80     //ITS->SetRails(1);                // 1 --> rails in ; 0 --> rails out
81     //ITS->SetSupportMaterial(0);      // 0 --> Copper ; 1 --> Aluminum ; 2 --> Carbon
82     //
83     //AliITS *ITS  = new AliITSvPPRcoarsesymm("ITS","New ITS coarse version with symmetric services");
84     //ITS->SetRails(1);                // 1 --> rails in ; 0 --> rails out
85     //ITS->SetSupportMaterial(0);      // 0 --> Copper ; 1 --> Aluminum ; 2 --> Carbon
86     //                      
87     //
88     //
89     // Geant3 <-> EUCLID conversion
90     // ============================
91     //
92     // SetEUCLID is a flag to output (=1) or not to output (=0) both geometry
93     // and  media to two ASCII files (called by default ITSgeometry.euc and
94     // ITSgeometry.tme) in a format understandable to the CAD system EUCLID.
95     // The default (=0) means that you dont want to use this facility.
96     //
97     ITS->SetEUCLID(0);  
98   }
99   
100 As you can see looking at the uncommented line, the present default is
101
102     AliITS *ITS  = new AliITSv5asymm("ITS","Updates ITS TDR detailed version with
103 asymmetric services"); 
104     
105 which is the TDR detailed geometry with asymmetric services. If you want to run
106 the TDR detailed version with symmetric services, You have to uncomment this
107 line and comment out the line above.
108
109     AliITS *ITS  = new AliITSv5symm("ITS","Updated ITS TDR detailed version with
110 symmetric services");
111
112 If you want to run the new PPR coarse geometry with asymmetric services, You
113 have to uncomment this line and comment out the line above.
114
115     AliITSvPPRcoarseasymm *ITS  = new AliITSvPPRcoarseasymm("ITS","New ITS coarse
116 version with asymmetric services");
117     ITS->SetRails(1);                // 1 --> rails in ; 0 --> rails out
118     ITS->SetSupportMaterial(0);      // 0 --> Copper ; 1 --> Aluminum ; 2 --> Carbon
119
120 There are two functions shown above. The first set the ITS rails in (=1) or out
121 (=0) (the default is in). If the switch for rails is different from 0 and 1 a
122 warning message is printed out and the default (rails in) is used. The second
123 changes the material of the supports to the ITS services': copper (=0, which is
124 the default), aluminum (=1), and  carbon (=2). If the switch of the support
125 material is different from 0, 1 and 2, a warning message is printed out and the
126 default (copper) is used. Note the the thickness of the supports is always the
127 same so the situation is completely unrealistic. This is because there has been
128 no attempt to change the geometry of this material as would be needed for the
129 support to realy support the serveces. The possibility to  change this material
130 has been explicitly requested by the PMD group to allow them to study the
131 effect of this material on their detector.
132
133 If you want to run the new PPR coarse geometry with symmetric services, you
134 have to uncomment these lines and comment out the above lines.
135
136     AliITS *ITS  = new AliITSvPPRcoarsesymm("ITS","New ITS coarse version with
137 symmetric services");
138     ITS->SetRails(1);                // 1 --> rails in ; 0 --> rails out
139     ITS->SetSupportMaterial(0);      // 0 --> Copper ; 1 --> Aluminum ; 2 --> Carbon
140
141 The two additional functions are just the same of those described above.
142
143     If you want to run the new PPR detailed geometry with asymmetric services,
144 you have to uncomment these lines and comment out the above lines.
145
146     AliITSvPPRasymm *ITS  = new AliITSvPPRasymm("ITS","New ITS PPR detailed version
147 with asymmetric services");
148     ITS->SetMinorVersion(2);
149     ITS->SetReadDet(kFALSE);
150     ITS->SetWriteDet("$ALICE_ROOT/ITS/ITSgeometry_vPPRasymm2.det");
151     ITS->SetThicknessDet1(300.);   // detector thickness on layer 1 must be in the
152 range [100,300]
153     ITS->SetThicknessDet2(300.);   // detector thickness on layer 2 must be in the
154 range [100,300]
155     ITS->SetThicknessChip1(300.);  // chip thickness on layer 1 must be in the range
156 [150,300]
157     ITS->SetThicknessChip2(300.);  // chip thickness on layer 2 must be in the range
158 [150,300]
159     ITS->SetRails(1);              // 1 --> rails in ; 0 --> rails out
160     ITS->SetCoolingFluid(1);       // 1 --> water ; 0 --> freon
161
162     The first three functions are reserved to the ITS developpers and their
163 values must not be modified at any time. The next four functions allow the user
164 to  change the thickness of detectors and chips in the two SPD layers
165 separately.  Detector thicknesses can go from 100 microns (TDR value) to 300
166 microns (present default value). If a value outside this range is set a warning
167 message is printed out and the default value (300 microns) is used. Chip
168 thicknesses can go from 150 (TDR value) to 300 (present default value)
169 microns. If a value outside this range is set a warning message is printed out
170 and the default value (300 microns) is used. The last two function allow people
171 to set the ITS rails in (=1) and out (=0) (the default is in) and the cooling
172 fluid as water (=1, which is the default) or freon (=0). If the switch for
173 rails is different from 0 and 1 a warning message is printed out and the
174 default (rails in) is used. If the switch of the cooling fluid is different
175 from 0 and 1 a warning message is printed out and the default (water) is used.
176
177      If you want to run the new PPR detailed geometry with symmetric services,
178 the only uncommented lines must be:
179
180     AliITSvPPRsymm *ITS  = new AliITSvPPRsymm("ITS","New ITS PPR detailed version
181 with symmetric services");
182     ITS->SetMinorVersion(2);                                      
183     ITS->SetReadDet(kFALSE);
184     ITS->SetWriteDet("$ALICE_ROOT/ITS/ITSgeometry_vPPRsymm2.det");
185     ITS->SetThicknessDet1(300.);   // detector thickness on layer 1 must be in the
186 range [100,300]
187     ITS->SetThicknessDet2(300.);   // detector thickness on layer 2 must be in the
188 range [100,300]
189     ITS->SetThicknessChip1(300.);  // chip thickness on layer 1 must be in the range
190 [150,300]
191     ITS->SetThicknessChip2(300.);  // chip thickness on layer 2 must be in the range
192 [150,300]
193     ITS->SetRails(1);              // 1 --> rails in ; 0 --> rails out
194     ITS->SetCoolingFluid(1);       // 1 --> water ; 0 --> freon
195
196 The functions are the same as in the asymmetric services' geometry. For their
197 explanation and use see above.
198
199
200 3. Simulation
201 -------------  
202
203      In order to run an event with a given ITS geometry put yourself in the
204 directory macros and do the following:
205
206 - interactive run: start aliroot and the type the command "gAlice->Run()". 
207   At the end of the run exit from aliroot with the command ".q".
208 - batch run: type the shell command "aliroot -q -b grun.C >& fileout &" where 
209   fileout is a name at your choice of the file where you want to store output 
210   and error messages.
211
212 In principle there is another way to run aliroot using the script alirun but
213 this is not described here. Aliroot creates an output root file called
214 galice.root (this can be changed from within the Config.C file). If you want to
215 run the ITS reconstruction code, copy/move this file in the directory ITS and
216 read the following instructions.
217
218 4. Cluster finding (fast)
219 -------------------------
220
221         Reconstructed points can be created quickly by smearing the Geant3 
222 hits according with the various detector resolutions and applying the 
223 thresholds for all detectors (fast reconstruction or, for short, "fast
224 points"), or slowly, in more detail, by performing a cluster finding after the
225 detector digitization (slow reconstruction or, for short, "slow points"). Fast
226 point creation is described here while slow point one is described in sections
227 5 and 6. From now on, we assume that you are under the directory ITS or that
228 the $ALICE_ROOT/ITS is in your .rootrc MacroPath. If it is the case you can do
229 the following, otherwise copy these macros to you local directory or prefix
230 $ALICE_ROOT/ITS/ to the front of the macro names.
231
232 - interactive run: start aliroot and type the command 
233   ".x ITSHitsToFastPoints.C".
234   At the end of the run exit from aliroot with the command ".q".
235 - batch run: type the shell command 
236   "aliroot -q -b ITSHitsToFastPoints.C >& fileout &"
237   where fileout is a name at your choice of the file where you want to store
238   output and error messages.
239  
240     Fast points are written in the same galice.root file as you can see issuing
241 the shell command "ls -l galice.root" before and after their creation and
242 looking at the size of the root file. 
243 By default, fast points are created for all kind of ITS subdetectors (SPD, SDD,
244 and SSD). This is done with the function call
245
246   ITS->HitsToFastRecPoints(ev,bgr_ev,size," ","All"," ");
247
248 in the macro ITSHitsToFastPoints.C. If you want to create fast points only for
249 one type of subdectors you have to substitute the string "All" in the above 
250 function call with "SPD", "SDD", or "SSD". Normal users are, however, strongly
251 encouraged to create the "fast points" for all subdetectors at once not
252 touching the macro ITSHitsToFastPoints.C. Fast points are intended only for
253 tests. Normal users are also strongly  encouraged to run the complete ITS
254 reconstruction described in the next two sections. 
255
256   
257 5. Digitization
258 ---------------
259
260         The so called "Slow simulation" realy takes two parts. First digits are
261 created (Digitization) and then these digits are read back in and are
262 reconstructed to form RecPoints (Cluster finding). In order to run the ITS
263 digitization, put yourself in ITS directory, or if you have the ITS directory
264 in your .rootrc MacroPath, a working directory and do thefollowing:
265
266 - interactive run: start aliroot and type the command 
267   ".x ITSHitsToDigits.C".
268   At the end of the run exit from aliroot with the command ".q".
269 - batch run: type the shell command 
270   "aliroot -q -b ITSHitsToDigits.C >& fileout &" 
271   where fileout is a name at your choice of the file where you want to store
272   output and error messages.
273
274 Digits are written in the same galice.root file as you can see issuing the
275 shell command "ls -l galice.root" before and after their creation and looking
276 at the size of the root file. By default, digits are created for all kind of
277 ITS subdetectors (SPD, SDD, and SSD). This is done with the function call:
278
279   ITS->HitsToDigits(nev,nbgr_ev,size," ","All"," "); 
280
281 in the macro ITSHitsToDigits.C. If you want to create digits only for
282 one type of subdectors you have to substitute the string "All" in the above 
283 function call with "SPD", "SDD", or "SSD". Normal users are, however, strongly
284 encouraged to run the ITS digitization for all subdetectors at once not
285 touching the macro ITSHitsToDigits.C. By default the so-called "Dubna
286 simulation" of the pixel detectors is performed. In order to run the "Bari
287 simulation" of the pixel detectors (waiting for the merging of the two) you
288 have to use the macro ITSHitsToDigitsBari.C.
289
290
291 6. Cluster finding (slow)
292 -------------------------
293
294 In order to perform the cluster finding and create the "slow points", do the
295 following:
296
297 - interactive run: start aliroot and the type the command 
298   ".x ITSDigitsToClusters.C".
299   At the end of the run exit from aliroot with the command ".q".
300 - batch run: type the shell command 
301   "aliroot -q -b ITSDigitsToClusters.C >& fileout &" 
302   where fileout is a name at  your choice of the file where you want to store
303   output and error messages.
304
305 Slow points are written in the same galice.root file as you can see issuing the
306 shell command "ls -l galice.root" before and after their creation and looking
307 at the size of the root file. By default, slow points are created for all kind
308 of ITS subdetectors (SPD, SDD, and SSD). This is done with the function call:
309
310   ITS->DigitsToRecPoints(nev,last_entry,"All"); 
311
312 in the macro ITSDigitsToClusters.C. If you want to create slow points only for
313 one type of subdectors you have to substitute the string "All" in the above 
314 function call with "SPD", "SDD", or "SSD". Normal users are, however, strongly
315 encouraged to create the slow points for all subdetectors at once not touching
316 the macro ITSDigitsToClusters.C. By default the so-called "Dubna
317 reconstruction" of the pixel detectors is performed. In order to run the "Bari
318 reconstruction" of the pixel detectors (waiting for the merging of the two) you
319 have to use the macro ITSDigitsToClustersBari.C.
320
321
322 7. Useful test macros
323 ---------------------
324
325         Once you have created digits and slow points, you can now run some
326 useful test macros. They can also be used as useful starting point to
327 understand how to read hits, digits and points back from the galice.root
328 file. The macros are listed below together with some help on their use. Some of
329 the macros produce graphical output, so the suggestion is to run them
330 interactively from within aliroot by then typing a command like ".x macro.C" at
331 the aliroot prompt.
332
333 - new TBrower();
334   This isn't a macro, so you just type it at the aliroot prompt. From here you
335 can open up root files and view some of what they contain. This is done by
336 cliking on a root file, and then cliking on the different "folders" withing
337 that root file. Data kept in TTrees can be histogramed symply by double cliking
338 on the appropreate data member. Other parts of the root file can also be
339 inspected in a simular way, right butting cliking for example.
340
341 - SPDclusterTest.C:
342   This macro opens the galice.root file, reads the reconstructed points and
343 plots the SPD resolution both for layer 1 and 2, in Z and Rphi
344 direction. Moreover, it creates the Root file SPD_his.root which contains
345 some useful histograms and nt-uples which can be read back with the macro
346 SPD_ntuple.C. 
347
348 - SPDclusterTestBari.C:
349   This macro opens the galice.root file, reads the reconstructed points and
350 plots several distributions relative to the Bari simulation of the SPD. 
351 Moreover, it creates the Root file SPD_his_bari.root which contains some useful
352 histograms and nt-uples. This macro should also work with both SPD simulations.
353
354 - ITSreadClustTestSPD.C:
355   This macros opens the galice.root, reads SPD digits and prints them on the 
356 screen.
357
358 - ITSsddanalysis.C:
359   This macro opens the galice.root file, performs some analysis of the 
360 drift detectors and creates the Root output file SDD_histos_test.root. This 
361 output file can then be read by the macro ITSsddtest.C which create some 
362 PostScript file containing reference histograms.
363
364 - SSDrecpointTest.C:
365   This macro opens the galice.root file, reads the reconstructed points and 
366 plots the SSD resolution both for layer 5 and 6, in Z and Rphi direction. 
367 Moreover, it creates the Root file SSD_his.root which contains some useful 
368 histograms and nt-uples which can be read back with the macro SSD_ntuple.C.
369
370 - ITSreadRecPointsTest.C:
371   This macro opens the galice.root file, reads the reconstructed points and 
372 prints them on the screen for all ITS modules. For each reconstructed point 
373 the following quantities are printed: the recpoint index in the module 
374 (0, 1, 2, ...), the X coordinate in the local reference system of the
375 module, the Z coordinate in the local reference system of the module, three
376 integers indicating the id numbers of the tracks contributing to that
377 reconstructed point. Only positive numbers, of course, are real tracks. 
378 Negative numbers (-1 for SPD, -3 for SDD, and -2 for SSD) are just there to 
379 fill the vector of track id's associated to a given reconstructed point.
380
381 - ITSgeoplot.C:
382   This macro opens the galice.root file, reads hits, digits and recpoint for 
383 SPD, SDD and SSD and plots them in the global reference system.
384
385 - ITSReadPlotData.C:
386   This macros opens the galice.root file and then prompts the user for an ITS 
387 module identified by layer, ladder and detector or by the unique ID. That 
388 module is then searched for hits, digits and reconstructed points and they 
389 are plotted in the local reference frame of the module with different symbols.
390
391
392 8. Occupancy
393 ------------
394
395         ITS occupancy can be evaluated by the macro ITSOccupancy.C which opens
396 the galice.root files, reads the number of digits for all subdetectors, and
397 calculate the occupancy as the ratio of the "fired" digits over the total
398 number of digits. Plots are also created showing the occupancy as a function of
399 the Z coordinate along the beams' axis. In order to increase the speed of the 
400 calculation the macro is compilable. See the comments in the code about how to 
401 run it.
402
403
404 9. Primary vertex
405 -----------------
406
407         The ITS code contains a full 3D primary vertex finder. The relative
408 class is AliITSVertex and an example of its use is contained in the test macro
409 VertexMacro.C. The output of the primary vertex finder will eventually be 
410 incorporated in the tracking algorithms.
411