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