Memory leak corrected (M.Bondila)
[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
15when you run the code on your computer must be reported either to Roberto
16Barbera at roberto.barbera@ct.infn.it or to Bjorn Nilsen at
17nilsen@mps.ohio-state.edu. Please note that all the tests described here have
18been done on a PC running Linux RedHat 6.1, gcc 2.95.2, and Root 3.00/06. If
19you have different hardware/software configuration, please add it to all bug
39b38887 20reports.
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 //
43c39b72 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.
39b38887 44 //
45 // Detailed geometries:
46 //
47 //
39b38887 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]
43c39b72 60 //ITS->SetRails(1); // 1 --> rails in ; 0 --> rails out
61 //ITS->SetCoolingFluid(1); // 1 --> water ; 0 --> freon
39b38887 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 //
39b38887 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 //
43c39b72 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
39b38887 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
100As you can see looking at the uncommented line, the present default is
101
43c39b72 102 AliITS *ITS = new AliITSv5asymm("ITS","Updates ITS TDR detailed version with
103asymmetric services");
39b38887 104
43c39b72 105which is the TDR detailed geometry with asymmetric services. If you want to run
106the TDR detailed version with symmetric services, You have to uncomment this
107line and comment out the line above.
39b38887 108
43c39b72 109 AliITS *ITS = new AliITSv5symm("ITS","Updated ITS TDR detailed version with
110symmetric services");
39b38887 111
43c39b72 112If you want to run the new PPR coarse geometry with asymmetric services, You
113have to uncomment this line and comment out the line above.
39b38887 114
43c39b72 115 AliITSvPPRcoarseasymm *ITS = new AliITSvPPRcoarseasymm("ITS","New ITS coarse
116version with asymmetric services");
39b38887 117 ITS->SetRails(1); // 1 --> rails in ; 0 --> rails out
118 ITS->SetSupportMaterial(0); // 0 --> Copper ; 1 --> Aluminum ; 2 --> Carbon
119
43c39b72 120There 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
122warning message is printed out and the default (rails in) is used. The second
123changes the material of the supports to the ITS services': copper (=0, which is
124the default), aluminum (=1), and carbon (=2). If the switch of the support
125material is different from 0, 1 and 2, a warning message is printed out and the
126default (copper) is used. Note the the thickness of the supports is always the
127same so the situation is completely unrealistic. This is because there has been
128no attempt to change the geometry of this material as would be needed for the
129support to realy support the serveces. The possibility to change this material
130has been explicitly requested by the PMD group to allow them to study the
131effect of this material on their detector.
132
133If you want to run the new PPR coarse geometry with symmetric services, you
134have to uncomment these lines and comment out the above lines.
135
136 AliITS *ITS = new AliITSvPPRcoarsesymm("ITS","New ITS coarse version with
137symmetric services");
39b38887 138 ITS->SetRails(1); // 1 --> rails in ; 0 --> rails out
139 ITS->SetSupportMaterial(0); // 0 --> Copper ; 1 --> Aluminum ; 2 --> Carbon
140
43c39b72 141The 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,
144you have to uncomment these lines and comment out the above lines.
39b38887 145
43c39b72 146 AliITSvPPRasymm *ITS = new AliITSvPPRasymm("ITS","New ITS PPR detailed version
147with asymmetric services");
39b38887 148 ITS->SetMinorVersion(2);
149 ITS->SetReadDet(kFALSE);
150 ITS->SetWriteDet("$ALICE_ROOT/ITS/ITSgeometry_vPPRasymm2.det");
43c39b72 151 ITS->SetThicknessDet1(300.); // detector thickness on layer 1 must be in the
152range [100,300]
153 ITS->SetThicknessDet2(300.); // detector thickness on layer 2 must be in the
154range [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
39b38887 161
43c39b72 162 The first three functions are reserved to the ITS developpers and their
163values must not be modified at any time. The next four functions allow the user
164to change the thickness of detectors and chips in the two SPD layers
165separately. Detector thicknesses can go from 100 microns (TDR value) to 300
166microns (present default value). If a value outside this range is set a warning
167message is printed out and the default value (300 microns) is used. Chip
168thicknesses can go from 150 (TDR value) to 300 (present default value)
169microns. If a value outside this range is set a warning message is printed out
170and the default value (300 microns) is used. The last two function allow people
171to set the ITS rails in (=1) and out (=0) (the default is in) and the cooling
172fluid as water (=1, which is the default) or freon (=0). If the switch for
173rails is different from 0 and 1 a warning message is printed out and the
174default (rails in) is used. If the switch of the cooling fluid is different
175from 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,
178the only uncommented lines must be:
179
180 AliITSvPPRsymm *ITS = new AliITSvPPRsymm("ITS","New ITS PPR detailed version
181with symmetric services");
39b38887 182 ITS->SetMinorVersion(2);
183 ITS->SetReadDet(kFALSE);
184 ITS->SetWriteDet("$ALICE_ROOT/ITS/ITSgeometry_vPPRsymm2.det");
43c39b72 185 ITS->SetThicknessDet1(300.); // detector thickness on layer 1 must be in the
186range [100,300]
187 ITS->SetThicknessDet2(300.); // detector thickness on layer 2 must be in the
188range [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]
39b38887 193 ITS->SetRails(1); // 1 --> rails in ; 0 --> rails out
194 ITS->SetCoolingFluid(1); // 1 --> water ; 0 --> freon
195
43c39b72 196The functions are the same as in the asymmetric services' geometry. For their
197explanation and use see above.
198
39b38887 199
2003. Simulation
201-------------
202
43c39b72 203 In order to run an event with a given ITS geometry put yourself in the
204directory macros and do the following:
39b38887 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
212In principle there is another way to run aliroot using the script alirun but
43c39b72 213this is not described here. Aliroot creates an output root file called
214galice.root (this can be changed from within the Config.C file). If you want to
39b38887 215run the ITS reconstruction code, copy/move this file in the directory ITS and
43c39b72 216read the following instructions.
39b38887 217
2184. Cluster finding (fast)
219-------------------------
220
43c39b72 221 Reconstructed points can be created quickly by smearing the Geant3
39b38887 222hits according with the various detector resolutions and applying the
43c39b72 223thresholds for all detectors (fast reconstruction or, for short, "fast
224points"), or slowly, in more detail, by performing a cluster finding after the
225detector digitization (slow reconstruction or, for short, "slow points"). Fast
226point creation is described here while slow point one is described in sections
2275 and 6. From now on, we assume that you are under the directory ITS or that
228the $ALICE_ROOT/ITS is in your .rootrc MacroPath. If it is the case you can do
229the 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".
39b38887 235- batch run: type the shell command
43c39b72 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
241the shell command "ls -l galice.root" before and after their creation and
242looking at the size of the root file.
243By default, fast points are created for all kind of ITS subdetectors (SPD, SDD,
244and SSD). This is done with the function call
245
246 ITS->HitsToFastRecPoints(ev,bgr_ev,size," ","All"," ");
39b38887 247
248in the macro ITSHitsToFastPoints.C. If you want to create fast points only for
249one type of subdectors you have to substitute the string "All" in the above
250function call with "SPD", "SDD", or "SSD". Normal users are, however, strongly
43c39b72 251encouraged to create the "fast points" for all subdetectors at once not
252touching the macro ITSHitsToFastPoints.C. Fast points are intended only for
253tests. Normal users are also strongly encouraged to run the complete ITS
254reconstruction described in the next two sections.
39b38887 255
256
2575. Digitization
258---------------
259
43c39b72 260 The so called "Slow simulation" realy takes two parts. First digits are
261created (Digitization) and then these digits are read back in and are
262reconstructed to form RecPoints (Cluster finding). In order to run the ITS
263digitization, put yourself in ITS directory, or if you have the ITS directory
264in your .rootrc MacroPath, a working directory and do thefollowing:
39b38887 265
43c39b72 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".
39b38887 269- batch run: type the shell command
43c39b72 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
39b38887 274Digits are written in the same galice.root file as you can see issuing the
43c39b72 275shell command "ls -l galice.root" before and after their creation and looking
276at the size of the root file. By default, digits are created for all kind of
277ITS subdetectors (SPD, SDD, and SSD). This is done with the function call:
39b38887 278
279 ITS->HitsToDigits(nev,nbgr_ev,size," ","All"," ");
280
281in the macro ITSHitsToDigits.C. If you want to create digits only for
282one type of subdectors you have to substitute the string "All" in the above
283function call with "SPD", "SDD", or "SSD". Normal users are, however, strongly
43c39b72 284encouraged to run the ITS digitization for all subdetectors at once not
285touching the macro ITSHitsToDigits.C. By default the so-called "Dubna
286simulation" of the pixel detectors is performed. In order to run the "Bari
287simulation" of the pixel detectors (waiting for the merging of the two) you
288have to use the macro ITSHitsToDigitsBari.C.
39b38887 289
290
2916. Cluster finding (slow)
292-------------------------
293
294In order to perform the cluster finding and create the "slow points", do the
295following:
296
297- interactive run: start aliroot and the type the command
43c39b72 298 ".x ITSDigitsToClusters.C".
299 At the end of the run exit from aliroot with the command ".q".
39b38887 300- batch run: type the shell command
43c39b72 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
39b38887 305Slow points are written in the same galice.root file as you can see issuing the
43c39b72 306shell command "ls -l galice.root" before and after their creation and looking
307at the size of the root file. By default, slow points are created for all kind
308of ITS subdetectors (SPD, SDD, and SSD). This is done with the function call:
39b38887 309
310 ITS->DigitsToRecPoints(nev,last_entry,"All");
311
312in the macro ITSDigitsToClusters.C. If you want to create slow points only for
313one type of subdectors you have to substitute the string "All" in the above
314function call with "SPD", "SDD", or "SSD". Normal users are, however, strongly
315encouraged to create the slow points for all subdetectors at once not touching
43c39b72 316the macro ITSDigitsToClusters.C. By default the so-called "Dubna
317reconstruction" of the pixel detectors is performed. In order to run the "Bari
318reconstruction" of the pixel detectors (waiting for the merging of the two) you
319have to use the macro ITSDigitsToClustersBari.C.
39b38887 320
321
3227. Useful test macros
323---------------------
324
43c39b72 325 Once you have created digits and slow points, you can now run some
326useful test macros. They can also be used as useful starting point to
327understand how to read hits, digits and points back from the galice.root
328file. The macros are listed below together with some help on their use. Some of
329the macros produce graphical output, so the suggestion is to run them
330interactively from within aliroot by then typing a command like ".x macro.C" at
331the aliroot prompt.
332
333- new TBrower();
334 This isn't a macro, so you just type it at the aliroot prompt. From here you
335can open up root files and view some of what they contain. This is done by
336cliking on a root file, and then cliking on the different "folders" withing
337that root file. Data kept in TTrees can be histogramed symply by double cliking
338on the appropreate data member. Other parts of the root file can also be
339inspected 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
343plots the SPD resolution both for layer 1 and 2, in Z and Rphi
344direction. Moreover, it creates the Root file SPD_his.root which contains
345some useful histograms and nt-uples which can be read back with the macro
346SPD_ntuple.C.
347
348- SPDclusterTestBari.C:
349 This macro opens the galice.root file, reads the reconstructed points and
350plots several distributions relative to the Bari simulation of the SPD.
351Moreover, it creates the Root file SPD_his_bari.root which contains some useful
352histograms 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
356screen.
357
358- ITSsddanalysis.C:
359 This macro opens the galice.root file, performs some analysis of the
360drift detectors and creates the Root output file SDD_histos_test.root. This
361output file can then be read by the macro ITSsddtest.C which create some
362PostScript file containing reference histograms.
363
364- SSDrecpointTest.C:
365 This macro opens the galice.root file, reads the reconstructed points and
366plots the SSD resolution both for layer 5 and 6, in Z and Rphi direction.
367Moreover, it creates the Root file SSD_his.root which contains some useful
368histograms 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
372prints them on the screen for all ITS modules. For each reconstructed point
373the following quantities are printed: the recpoint index in the module
374(0, 1, 2, ...), the X coordinate in the local reference system of the
39b38887 375module, the Z coordinate in the local reference system of the module, three
376integers indicating the id numbers of the tracks contributing to that
43c39b72 377reconstructed point. Only positive numbers, of course, are real tracks.
378Negative numbers (-1 for SPD, -3 for SDD, and -2 for SSD) are just there to
379fill the vector of track id's associated to a given reconstructed point.
39b38887 380
43c39b72 381- ITSgeoplot.C:
382 This macro opens the galice.root file, reads hits, digits and recpoint for
383SPD, SDD and SSD and plots them in the global reference system.
39b38887 384
43c39b72 385- ITSReadPlotData.C:
386 This macros opens the galice.root file and then prompts the user for an ITS
387module identified by layer, ladder and detector or by the unique ID. That
388module is then searched for hits, digits and reconstructed points and they
389are plotted in the local reference frame of the module with different symbols.
39b38887 390
391
3928. Occupancy
393------------
394
43c39b72 395 ITS occupancy can be evaluated by the macro ITSOccupancy.C which opens
396the galice.root files, reads the number of digits for all subdetectors, and
397calculate the occupancy as the ratio of the "fired" digits over the total
398number of digits. Plots are also created showing the occupancy as a function of
399the Z coordinate along the beams' axis. In order to increase the speed of the
39b38887 400calculation the macro is compilable. See the comments in the code about how to
401run it.
402
43c39b72 403
4049. Primary vertex
405-----------------
406
407 The ITS code contains a full 3D primary vertex finder. The relative
408class is AliITSVertex and an example of its use is contained in the test macro
409VertexMacro.C. The output of the primary vertex finder will eventually be
410incorporated in the tracking algorithms.
411