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 when you
  15 run the code on your computer must be reported to Roberto Barbera at
  16 roberto.barbera@ct.infn.it. Please note that all the tests described here have
  17 been done on a PC running Linux RedHat 6.1, gcc 2.95.2, and Root 3.00/06.
  18 If you have different hardware/software configuration, please add it to all bug
  19 reports.
  20
  21
  22 2. Set the ITS geometry you want to use
  23 ---------------------------------------
  24
  25 In order to set one of the many ITS geometries available, you have to modify
  26 the ITS part in the file Config.C under the directory macros (you have to modify
  27 the file ConfigPPR.C if you want to run full 'PPR' events). The default ITS
  28 part 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
 101 As 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
 105 which is the TDR detailed geometry with asymmetric services.
 106 If you want to run the TDR detailed version with symmetric services, the only
 107 uncommented line must be:
 108
 109     AliITS *ITS  = new AliITSv5symm("ITS","Updated ITS TDR detailed version with symmetric services");
 110
 111 If you want to run the new PPR coarse geometry with asymmetric services, the
 112 only 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
 118 If you want to run the new PPR coarse geometry with symmetric services, the
 119 only 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
 125 If you want to run the new PPR detailed geometry with asymmetric services, the
 126 only 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
 139 If you want to run the new PPR detailed geometry with symmetric services, the
 140 only 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
 154 3. Simulation
 155 -------------
 156
 157 In order to run an event with a given ITS geometry put yourself in the directory
 158 macros 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
 166 In principle there is another way to run aliroot using the script alirun but
 167 this is not described here.
 168 Aliroot creates an output root file always called galice.root. If you want to
 169 run the ITS reconstruction code, copy/move this file in the directory ITS and
 170 read the following instructions.
 171
 172
 173 4. Cluster finding (fast)
 174 -------------------------
 175
 176 Reconstructed points in the space can be calculated either smearing the Geant3
 177 hits according with the various detector resolutions and applying the
 178 thresholds for all detectors (fast reconstruction or, for short, "fast points"),
 179 or performing a cluster finding after the detector digitization (slow
 180 reconstruction or, for short, "slow points"). Fast point creation is described
 181 here while slow point one is described in sections 5 and 6.
 182 From now on, we assume that you are under the directory ITS. If it is the case
 183 you 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
 192 Fast points are written in the same galice.root file as you can see issuing the
 193 shell command "ls -l galice.root" before and after their creation and looking at
 194 the size of the root file.
 195 By default, fast points are created for all kind of ITS subdetectors (SPD, SDD,
 196 and SSD). This is done with the function call:
 197
 198   ITS->HitsToFastRecPoints(ev,bgr_ev,size," ","All"," ");
 199
 200 in the macro ITSHitsToFastPoints.C. If you want to create fast points only for
 201 one type of subdectors you have to substitute the string "All" in the above
 202 function call with "SPD", "SDD", or "SSD". Normal users are, however, strongly
 203 encouraged to create the "fast points" for all subdetectors at once not touching
 204 the macro ITSHitsToFastPoints.C.
 205 Fast points are intended only for tests. Normal users are also strongly
 206 encouraged to run the complete ITS reconstruction described in the next two
 207 sections.
 208
 209
 210 5. Digitization
 211 ---------------
 212
 213 In order to run the ITS digitization, put yourself under ITS and do the
 214 following:
 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
 223 Digits are written in the same galice.root file as you can see issuing the
 224 shell command "ls -l galice.root" before and after their creation and looking at
 225 the size of the root file.
 226 By default, digits are created for all kind of ITS subdetectors (SPD, SDD,
 227 and SSD). This is done with the function call:
 228
 229   ITS->HitsToDigits(nev,nbgr_ev,size," ","All"," ");
 230
 231 in the macro ITSHitsToDigits.C. If you want to create digits only for
 232 one type of subdectors you have to substitute the string "All" in the above
 233 function call with "SPD", "SDD", or "SSD". Normal users are, however, strongly
 234 encouraged to run the ITS digitization for all subdetectors at once not touching
 235 the macro ITSHitsToDigits.C.
 236 By default the so-called "Dubna simulation" of the pixel detectors is
 237 performed. In order to run the "Bari simulation" of the pixel detectors (waiting
 238 for the merging of the two) you have to use the macro ITSHitsToDigitsBari.C.
 239
 240
 241 6. Cluster finding (slow)
 242 -------------------------
 243
 244 In order to perform the cluster finding and create the "slow points", do the
 245 following:
 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
 254 Slow points are written in the same galice.root file as you can see issuing the
 255 shell command "ls -l galice.root" before and after their creation and looking at
 256 the size of the root file.
 257 By default, slow points are created for all kind of ITS subdetectors (SPD, SDD,
 258 and SSD). This is done with the function call:
 259
 260   ITS->DigitsToRecPoints(nev,last_entry,"All");
 261
 262 in the macro ITSDigitsToClusters.C. If you want to create slow points only for
 263 one type of subdectors you have to substitute the string "All" in the above
 264 function call with "SPD", "SDD", or "SSD". Normal users are, however, strongly
 265 encouraged to create the slow points for all subdetectors at once not touching
 266 the macro ITSDigitsToClusters.C.
 267 By default the so-called "Dubna reconstruction" of the pixel detectors is
 268 performed. 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
 270 ITSDigitsToClustersBari.C.
 271
 272
 273 7. Useful test macros
 274 ---------------------
 275
 276 Once you have created digits and slow points, you can now run some useful test
 277 macros. They can also be used as useful starting point to understand how to read
 278 hits, digits and points back from the galice.root file. The macros are listed
 279 below together with some help on their use. Some of the macros produce output
 280 graphics, so the suggestion is to run them interactively starting aliroot and
 281 then typing the command ".x macro.C" at the aliroot prompt.
 282
 283 - SPDclusterTest.C: this macro opens the galice.root file, reads the
 284 reconstructed points and plots the SPD resolution both for layer 1 and 2, in Z
 285 and Rphi direction. Moreover, it creates the Root file SPD_his.root which
 286 contains some useful histograms and nt-uples which can be read back with the
 287 macro SPD_ntuple.C.
 288
 289 - ITSreadClustTestSPD.C: this macros opens the galice.root, reads SPD digits and
 290 prints them on the screen.
 291
 292 - ITSsddanalysis.C: this macro opens the galice.root file, performs some
 293 analysis of the drift detectors and creates the Root output file
 294 SDD_histos_test.root. This output file can then be read by the macro
 295 ITSsddtest.C which create some PostScript file containing reference histograms.
 296
 297 - SSDrecpointTest.C: this macro opens the galice.root file, reads the
 298 reconstructed points and plots the SSD resolution both for layer 5 and 6, in Z
 299 and Rphi direction. Moreover, it creates the Root file SSD_his.root which
 300 contains some useful histograms and nt-uples which can be read back with the
 301 macro SSD_ntuple.C.
 302
 303 - ITSreadRecPointsTest.C: this macro opens the galice.root file, reads the
 304 reconstructed points and prints them on the screen for all ITS modules. For each
 305 reconstructed point the following quantities are printed: the recpoint index in
 306 the module (0, 1, 2, ...), the X coordinate in the local reference system of the
 307 module, the Z coordinate in the local reference system of the module, three
 308 integers indicating the id numbers of the tracks contributing to that
 309 reconstructed point. Only positive numbers, of course, are real tracks. Negative
 310 numbers (-1 for SPD, -3 for SDD, and -2 for SSD) are just there to fill the
 311 vector 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
 314 recpoint 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
 317 user for an ITS module identified by layer, ladder and detector or by the unique
 318 ID. That module is then searched for hits, digits and
 319 reconstructed points and they are plotted in the local reference frame of the
 320 module with different symbols.
 321
 322
 323 8. Occupancy
 324 ------------
 325
 326 ITS occupancy can be evaluated by the macro ITSOccupancy.C which opens the
 327 galice.root files, reads the number of digits for all subdetectors, and
 328 calculate the occupancy as the ratio of the "fired" digits over the total number
 329 of digits. Plots are also created showing the occupancy as a function of the Z
 330 coordinate along the beams' axis. In order to increase the speed of the
 331 calculation the macro is compilable. See the comments in the code about how to
 332 run it.
 333