Updated to calculate the total number of digits each time in order to avoid inconsist...
[u/mrichter/AliRoot.git] / ITS / README
CommitLineData
39b38887 11. Introduction
2---------------
3
4Dear ITS (and ALICE) user,
5
6this is a short help on how to run the ITS simulation/reconstruction code
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
9to be written. What follows requires that the you already know how to download,
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
13looking at some distributions/histograms.
14Any difference between what is described here and what you really get when you
15run the code on your computer must be reported to Roberto Barbera at
16roberto.barbera@ct.infn.it. Please note that all the tests described here have
17been done on a PC running Linux RedHat 6.1, gcc 2.95.2, and Root 3.00/06.
18If you have different hardware/software configuration, please add it to all bug
19reports.
20
21
222. Set the ITS geometry you want to use
23---------------------------------------
24
25In order to set one of the many ITS geometries available, you have to modify
26the ITS part in the file Config.C under the directory macros (you have to modify
27the file ConfigPPR.C if you want to run full 'PPR' events). The default ITS
28part of Config.C (or ConfigPPR.C) is reported here:
29
30 if(iITS) {
31
32//=================== ITS parameters ============================
33 //
34 // As the innermost detector in ALICE, the Inner Tracking System "impacts" on
35 // almost all other detectors. This involves the fact that the ITS geometry
36 // still has several options to be followed in parallel in order to determine
37 // the best set-up which minimizes the induced background. All the geometries
38 // available to date are described in the following. Read carefully the comments
39 // and use the default version (the only one uncommented) unless you are making
40 // comparisons and you know what you are doing. In this case just uncomment the
41 // ITS geometry you want to use and run Aliroot.
42 //
43 // Detailed geometries:
44 //
45 //
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 //
80 //AliITSvPPRcoarseasymm *ITS = new AliITSvPPRcoarseasymm("ITS","New ITS coarse version with asymmetric services");
81 //ITS->SetRails(1); // 1 --> rails in ; 0 --> rails out
82 //ITS->SetSupportMaterial(0); // 0 --> Copper ; 1 --> Aluminum ; 2 --> Carbon
83 //
84 //AliITS *ITS = new AliITSvPPRcoarsesymm("ITS","New ITS coarse version with symmetric services");
85 //ITS->SetRails(1); // 1 --> rails in ; 0 --> rails out
86 //ITS->SetSupportMaterial(0); // 0 --> Copper ; 1 --> Aluminum ; 2 --> Carbon
87 //
88 //
89 //
90 // Geant3 <-> EUCLID conversion
91 // ============================
92 //
93 // SetEUCLID is a flag to output (=1) or not to output (=0) both geometry and
94 // media to two ASCII files (called by default ITSgeometry.euc and
95 // ITSgeometry.tme) in a format understandable to the CAD system EUCLID.
96 // The default (=0) means that you dont want to use this facility.
97 //
98 ITS->SetEUCLID(0);
99 }
100
101As you can see looking at the uncommented line, the present default is
102
103 AliITS *ITS = new AliITSv5asymm("ITS","Updates ITS TDR detailed version with asymmetric services");
104
105which is the TDR detailed geometry with asymmetric services.
106If you want to run the TDR detailed version with symmetric services, the only
107uncommented line must be:
108
109 AliITS *ITS = new AliITSv5symm("ITS","Updated ITS TDR detailed version with symmetric services");
110
111If you want to run the new PPR coarse geometry with asymmetric services, the
112only uncommented lines must be:
113
114 AliITSvPPRcoarseasymm *ITS = new AliITSvPPRcoarseasymm("ITS","New ITS coarse version with asymmetric services");
115 ITS->SetRails(1); // 1 --> rails in ; 0 --> rails out
116 ITS->SetSupportMaterial(0); // 0 --> Copper ; 1 --> Aluminum ; 2 --> Carbon
117
118If you want to run the new PPR coarse geometry with symmetric services, the
119only uncommented lines must be:
120
121 AliITS *ITS = new AliITSvPPRcoarsesymm("ITS","New ITS coarse version with symmetric services");
122 ITS->SetRails(1); // 1 --> rails in ; 0 --> rails out
123 ITS->SetSupportMaterial(0); // 0 --> Copper ; 1 --> Aluminum ; 2 --> Carbon
124
125If you want to run the new PPR detailed geometry with asymmetric services, the
126only uncommented lines must be:
127
128 AliITSvPPRasymm *ITS = new AliITSvPPRasymm("ITS","New ITS PPR detailed version with asymmetric services");
129 ITS->SetMinorVersion(2);
130 ITS->SetReadDet(kFALSE);
131 ITS->SetWriteDet("$ALICE_ROOT/ITS/ITSgeometry_vPPRasymm2.det");
132 ITS->SetThicknessDet1(300.); // detector thickness on layer 1 must be in the range [100,300]
133 ITS->SetThicknessDet2(300.); // detector thickness on layer 2 must be in the range [100,300]
134 ITS->SetThicknessChip1(300.); // chip thickness on layer 1 must be in the range [150,300]
135 ITS->SetThicknessChip2(300.); // chip thickness on layer 2 must be in the range [150,300]
136 ITS->SetRails(1); // 1 --> rails in ; 0 --> rails out
137 ITS->SetCoolingFluid(1); // 1 --> water ; 0 --> freon
138
139If you want to run the new PPR detailed geometry with symmetric services, the
140only uncommented lines must be:
141
142 AliITSvPPRsymm *ITS = new AliITSvPPRsymm("ITS","New ITS PPR detailed version with symmetric services");
143 ITS->SetMinorVersion(2);
144 ITS->SetReadDet(kFALSE);
145 ITS->SetWriteDet("$ALICE_ROOT/ITS/ITSgeometry_vPPRsymm2.det");
146 ITS->SetThicknessDet1(300.); // detector thickness on layer 1 must be in the range [100,300]
147 ITS->SetThicknessDet2(300.); // detector thickness on layer 2 must be in the range [100,300]
148 ITS->SetThicknessChip1(300.); // chip thickness on layer 1 must be in the range [150,300]
149 ITS->SetThicknessChip2(300.); // chip thickness on layer 2 must be in the range [150,300]
150 ITS->SetRails(1); // 1 --> rails in ; 0 --> rails out
151 ITS->SetCoolingFluid(1); // 1 --> water ; 0 --> freon
152
153
1543. Simulation
155-------------
156
157In order to run an event with a given ITS geometry put yourself in the directory
158macros and do the following:
159
160- interactive run: start aliroot and the type the command "gAlice->Run()".
161 At the end of the run exit from aliroot with the command ".q".
162- batch run: type the shell command "aliroot -q -b grun.C >& fileout &" where
163 fileout is a name at your choice of the file where you want to store output
164 and error messages.
165
166In principle there is another way to run aliroot using the script alirun but
167this is not described here.
168Aliroot creates an output root file always called galice.root. If you want to
169run the ITS reconstruction code, copy/move this file in the directory ITS and
170read the following instructions.
171
172
1734. Cluster finding (fast)
174-------------------------
175
176Reconstructed points in the space can be calculated either smearing the Geant3
177hits according with the various detector resolutions and applying the
178thresholds for all detectors (fast reconstruction or, for short, "fast points"),
179or performing a cluster finding after the detector digitization (slow
180reconstruction or, for short, "slow points"). Fast point creation is described
181here while slow point one is described in sections 5 and 6.
182From now on, we assume that you are under the directory ITS. If it is the case
183you can do the following:
184
185- interactive run: start aliroot and the type the command
186 ".x ITSHitsToFastPoints.C". At the end of the run exit from aliroot with the
187 command ".q".
188- batch run: type the shell command
189 "aliroot -q -b ITSHitsToFastPoints.C >& fileout &" where fileout is a name at
190 your choice of the file where you want to store output and error messages.
191
192Fast points are written in the same galice.root file as you can see issuing the
193shell command "ls -l galice.root" before and after their creation and looking at
194the size of the root file.
195By default, fast points are created for all kind of ITS subdetectors (SPD, SDD,
196and SSD). This is done with the function call:
197
198 ITS->HitsToFastRecPoints(ev,bgr_ev,size," ","All"," ");
199
200in the macro ITSHitsToFastPoints.C. If you want to create fast points only for
201one type of subdectors you have to substitute the string "All" in the above
202function call with "SPD", "SDD", or "SSD". Normal users are, however, strongly
203encouraged to create the "fast points" for all subdetectors at once not touching
204the macro ITSHitsToFastPoints.C.
205Fast points are intended only for tests. Normal users are also strongly
206encouraged to run the complete ITS reconstruction described in the next two
207sections.
208
209
2105. Digitization
211---------------
212
213In order to run the ITS digitization, put yourself under ITS and do the
214following:
215
216- interactive run: start aliroot and the type the command
217 ".x ITSHitsToDigits.C". At the end of the run exit from aliroot with the
218 command ".q".
219- batch run: type the shell command
220 "aliroot -q -b ITSHitsToDigits.C >& fileout &" where fileout is a name at
221 your choice of the file where you want to store output and error messages.
222
223Digits are written in the same galice.root file as you can see issuing the
224shell command "ls -l galice.root" before and after their creation and looking at
225the size of the root file.
226By default, digits are created for all kind of ITS subdetectors (SPD, SDD,
227and SSD). This is done with the function call:
228
229 ITS->HitsToDigits(nev,nbgr_ev,size," ","All"," ");
230
231in the macro ITSHitsToDigits.C. If you want to create digits only for
232one type of subdectors you have to substitute the string "All" in the above
233function call with "SPD", "SDD", or "SSD". Normal users are, however, strongly
234encouraged to run the ITS digitization for all subdetectors at once not touching
235the macro ITSHitsToDigits.C.
236By default the so-called "Dubna simulation" of the pixel detectors is
237performed. In order to run the "Bari simulation" of the pixel detectors (waiting
238for the merging of the two) you have to use the macro ITSHitsToDigitsBari.C.
239
240
2416. Cluster finding (slow)
242-------------------------
243
244In order to perform the cluster finding and create the "slow points", do the
245following:
246
247- interactive run: start aliroot and the type the command
248 ".x ITSDigitsToClusters.C". At the end of the run exit from aliroot with the
249 command ".q".
250- batch run: type the shell command
251 "aliroot -q -b ITSDigitsToClusters.C >& fileout &" where fileout is a name at
252 your choice of the file where you want to store output and error messages.
253
254Slow points are written in the same galice.root file as you can see issuing the
255shell command "ls -l galice.root" before and after their creation and looking at
256the size of the root file.
257By default, slow points are created for all kind of ITS subdetectors (SPD, SDD,
258and SSD). This is done with the function call:
259
260 ITS->DigitsToRecPoints(nev,last_entry,"All");
261
262in the macro ITSDigitsToClusters.C. If you want to create slow points only for
263one type of subdectors you have to substitute the string "All" in the above
264function call with "SPD", "SDD", or "SSD". Normal users are, however, strongly
265encouraged to create the slow points for all subdetectors at once not touching
266the macro ITSDigitsToClusters.C.
267By default the so-called "Dubna reconstruction" of the pixel detectors is
268performed. In order to run the "Bari reconstruction" of the pixel detectors
269(waiting for the merging of the two) you have to use the macro
270ITSDigitsToClustersBari.C.
271
272
2737. Useful test macros
274---------------------
275
276Once you have created digits and slow points, you can now run some useful test
277macros. They can also be used as useful starting point to understand how to read
278hits, digits and points back from the galice.root file. The macros are listed
279below together with some help on their use. Some of the macros produce output
280graphics, so the suggestion is to run them interactively starting aliroot and
281then typing the command ".x macro.C" at the aliroot prompt.
282
283- SPDclusterTest.C: this macro opens the galice.root file, reads the
284reconstructed points and plots the SPD resolution both for layer 1 and 2, in Z
285and Rphi direction. Moreover, it creates the Root file SPD_his.root which
286contains some useful histograms and nt-uples which can be read back with the
287macro SPD_ntuple.C.
288
289- ITSreadClustTestSPD.C: this macros opens the galice.root, reads SPD digits and
290prints them on the screen.
291
292- ITSsddanalysis.C: this macro opens the galice.root file, performs some
293analysis of the drift detectors and creates the Root output file
294SDD_histos_test.root. This output file can then be read by the macro
295ITSsddtest.C which create some PostScript file containing reference histograms.
296
297- SSDrecpointTest.C: this macro opens the galice.root file, reads the
298reconstructed points and plots the SSD resolution both for layer 5 and 6, in Z
299and Rphi direction. Moreover, it creates the Root file SSD_his.root which
300contains some useful histograms and nt-uples which can be read back with the
301macro SSD_ntuple.C.
302
303- ITSreadRecPointsTest.C: this macro opens the galice.root file, reads the
304reconstructed points and prints them on the screen for all ITS modules. For each
305reconstructed point the following quantities are printed: the recpoint index in
306the module (0, 1, 2, ...), the X coordinate in the local reference system of the
307module, the Z coordinate in the local reference system of the module, three
308integers indicating the id numbers of the tracks contributing to that
309reconstructed point. Only positive numbers, of course, are real tracks. Negative
310numbers (-1 for SPD, -3 for SDD, and -2 for SSD) are just there to fill the
311vector of track id's associated to a given reconstructed point.
312
313- ITSgeoplot.C: this macro opens the galice.root file, reads hits, digits and
314recpoint for SPD, SDD and SSD and plots them in the global reference system.
315
316- ITSReadPlotData.C: this macros opens the galice.root file and then prompts the
317user for an ITS module identified by layer, ladder and detector or by the unique
318ID. That module is then searched for hits, digits and
319reconstructed points and they are plotted in the local reference frame of the
320module with different symbols.
321
322
3238. Occupancy
324------------
325
326ITS occupancy can be evaluated by the macro ITSOccupancy.C which opens the
327galice.root files, reads the number of digits for all subdetectors, and
328calculate the occupancy as the ratio of the "fired" digits over the total number
329of digits. Plots are also created showing the occupancy as a function of the Z
330coordinate along the beams' axis. In order to increase the speed of the
331calculation the macro is compilable. See the comments in the code about how to
332run it.
333