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 Mariana Bondila at
  17 mariana.bondila@cern.ch or to Bjorn Nilsen at nilsen@mps.ohio-state.edu.
  18 Please note that all the tests described here have been done on a PC running
  19 Linux RedHat 6.1, gcc 2.95.2, and Root 3.00/06. If you have different
  20 hardware/software configuration, please add it to all bug 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" 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.
  43     //
  44     // Detailed geometries:
  45     //
  46     //
  47     //AliITS *ITS  = new AliITSv5symm("ITS","Updated ITS TDR detailed version with symmetric services");
  48     //
  49     //AliITS *ITS  = new AliITSv5asymm("ITS","Updates ITS TDR detailed version with asymmetric services");
  50     //
  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
  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]
  59     ITS->SetRails(1);          // 1 --> rails in ; 0 --> rails out
  60     ITS->SetCoolingFluid(1);     // 1 --> water ; 0 --> freon
  61     //
  62     //AliITSvPPRsymm *ITS  = new AliITSvPPRsymm("ITS","New ITS PPR detailed version with symmetric services");
  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
  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]
  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     //
  78     //AliITSvPPRcoarseasymm *ITS  = new AliITSvPPRcoarseasymm("ITS","New ITS PPR coarse version with asymmetric services");
  79     //ITS->SetRails(1);                // 1 --> rails in ; 0 --> rails out
  80     //ITS->SetSupportMaterial(0);      // 0 --> Copper ; 1 --> Aluminum ; 2 --> Carbon
  81     //
  82     //AliITS *ITS  = new AliITSvPPRcoarsesymm("ITS","New ITS PPR coarse version with symmetric services");
  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     //
  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
  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
  99 As you can see looking at the uncommented lines, the present default is the new
 100 PPR 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
 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]
 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
 114 values must not be modified at any time. The next four functions allow the user
 115 to  change the thickness of detectors and chips in the two SPD layers
 116 separately.  Detector thicknesses can go from 100 microns (TDR value) to 300
 117 microns (present default value). If a value outside this range is set a warning
 118 message is printed out and the default value (200 microns) is used. Chip
 119 thicknesses can go from 150 (TDR value) to 300 (present default value)
 120 microns. If a value outside this range is set a warning message is printed out
 121 and the default value (200 microns) is used. The last two function allow people
 122 to set the ITS rails in (=1) and out (=0) (the default is in) and the cooling
 123 fluid as water (=1, which is the default) or freon (=0). If the switch for
 124 rails is different from 0 and 1 a warning message is printed out and the
 125 default (rails in) is used. If the switch of the cooling fluid is different
 126 from 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,
 129 the 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
 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]
 139     ITS->SetRails(1);              // 1 --> rails in ; 0 --> rails out
 140     ITS->SetCoolingFluid(1);       // 1 --> water ; 0 --> freon
 141
 142 The two additional functions are just the same of those described above.
 143
 144 If you want to run the old detailed version of the ITS the only uncommented
 145 line must be:
 146
 147     AliITS *ITS  = new AliITSv5asymm("ITS","Updates ITS TDR detailed version with asymmetric services");
 148
 149 which is the TDR detailed geometry with asymmetric services. If you want to run
 150 the TDR detailed version with symmetric services, you have to uncomment this
 151 line and comment out the line above.
 152
 153     AliITS *ITS  = new AliITSv5symm("ITS","Updated ITS TDR detailed version with
 154 symmetric services");
 155
 156 If you want to run the new PPR coarse geometry with asymmetric services, you
 157 have to uncomment this line and comment out the line above.
 158
 159     AliITSvPPRcoarseasymm *ITS  = new AliITSvPPRcoarseasymm("ITS","New ITS coarse
 160 version with asymmetric services");
 161     ITS->SetRails(1);                // 1 --> rails in ; 0 --> rails out
 162     ITS->SetSupportMaterial(0);      // 0 --> Copper ; 1 --> Aluminum ; 2 --> Carbon
 163
 164 There 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
 166 warning message is printed out and the default (rails in) is used. The second
 167 changes the material of the supports to the ITS services': copper (=0, which is
 168 the default), aluminum (=1), and  carbon (=2). If the switch of the support
 169 material is different from 0, 1 and 2, a warning message is printed out and the
 170 default (copper) is used. Note the the thickness of the supports is always the
 171 same so the situation is completely unrealistic. This is because there has been
 172 no attempt to change the geometry of this material as would be needed for the
 173 support to realy support the serveces. The possibility to  change this material
 174 has been explicitly requested by the PMD group to allow them to study the
 175 effect of this material on their detector.
 176
 177 If you want to run the new PPR coarse geometry with symmetric services, you
 178 have to uncomment these lines and comment out the above lines.
 179
 180     AliITS *ITS  = new AliITSvPPRcoarsesymm("ITS","New ITS coarse version with
 181 symmetric services");
 182     ITS->SetRails(1);                // 1 --> rails in ; 0 --> rails out
 183     ITS->SetSupportMaterial(0);      // 0 --> Copper ; 1 --> Aluminum ; 2 --> Carbon
 184
 185 The two additional functions are just the same of those described above.
 186
 187
 188 3. Simulation
 189 -------------
 190
 191      In order to run an event with a given ITS geometry put yourself in the
 192 directory macros and do the following:
 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
 200 In principle there is another way to run aliroot using the script alirun but
 201 this is not described here. Aliroot creates an output root file called
 202 galice.root (this can be changed from within the Config.C file). If you want to
 203 run the ITS reconstruction code, copy/move this file in the directory ITS and
 204 read the following instructions.
 205
 206 4. Cluster finding (fast)
 207 -------------------------
 208
 209         Reconstructed points can be created quickly by smearing the Geant3
 210 hits according with the various detector resolutions and applying the
 211 thresholds for all detectors (fast reconstruction or, for short, "fast
 212 points"), or slowly, in more detail, by performing a cluster finding after the
 213 detector digitization (slow reconstruction or, for short, "slow points"). Fast
 214 point creation is described here while slow point one is described in sections
 215 5 and 6. From now on, we assume that you are under the directory ITS or that
 216 the $ALICE_ROOT/ITS is in your .rootrc MacroPath. If it is the case you can do
 217 the 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".
 223 - batch run: type the shell command
 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
 229 the shell command "ls -l galice.root" before and after their creation and
 230 looking at the size of the root file.
 231 By default, fast points are created for all kind of ITS subdetectors (SPD, SDD,
 232 and SSD). This is done with the function call
 233
 234   ITS->HitsToFastRecPoints(ev,bgr_ev,size," ","All"," ");
 235
 236 in the macro ITSHitsToFastPoints.C. If you want to create fast points only for
 237 one type of subdectors you have to substitute the string "All" in the above
 238 function call with "SPD", "SDD", or "SSD". Normal users are, however, strongly
 239 encouraged to create the "fast points" for all subdetectors at once not
 240 touching the macro ITSHitsToFastPoints.C. Fast points are intended only for
 241 tests. Normal users are also strongly  encouraged to run the complete ITS
 242 reconstruction described in the next two sections.
 243
 244
 245 5. Digitization
 246 ---------------
 247
 248         The so called "Slow simulation" realy takes two parts. First digits are
 249 created (Digitization) and then these digits are read back in and are
 250 reconstructed to form RecPoints (Cluster finding). In order to run the ITS
 251 digitization, put yourself in ITS directory, or if you have the ITS directory
 252 in your .rootrc MacroPath, a working directory and do thefollowing:
 253
 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".
 257 - batch run: type the shell command
 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
 262 Digits are written in the same galice.root file as you can see issuing the
 263 shell command "ls -l galice.root" before and after their creation and looking
 264 at the size of the root file. By default, digits are created for all kind of
 265 ITS subdetectors (SPD, SDD, and SSD). This is done with the function call:
 266
 267   ITS->HitsToDigits(nev,nbgr_ev,size," ","All"," ");
 268
 269 in the macro ITSHitsToDigits.C. If you want to create digits only for
 270 one type of subdectors you have to substitute the string "All" in the above
 271 function call with "SPD", "SDD", or "SSD". Normal users are, however, strongly
 272 encouraged to run the ITS digitization for all subdetectors at once not
 273 touching the macro ITSHitsToDigits.C. By default the so-called "Bari/Salerno
 274 simulation" of the pixel detectors is performed. In order to run the "Dubna
 275 simulation" of the pixel detectors you have to use the macro
 276 ITSHitsToDigitsDubna.C.
 277
 278
 279 6. Cluster finding (slow)
 280 -------------------------
 281
 282 In order to perform the cluster finding and create the "slow points", do the
 283 following:
 284
 285 - interactive run: start aliroot and the type the command
 286   ".x ITSDigitsToClusters.C".
 287   At the end of the run exit from aliroot with the command ".q".
 288 - batch run: type the shell command
 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
 293 Slow points are written in the same galice.root file as you can see issuing the
 294 shell command "ls -l galice.root" before and after their creation and looking
 295 at the size of the root file. By default, slow points are created for all kind
 296 of ITS subdetectors (SPD, SDD, and SSD). This is done with the function call:
 297
 298   ITS->DigitsToRecPoints(nev,last_entry,"All");
 299
 300 in the macro ITSDigitsToClusters.C. If you want to create slow points only for
 301 one type of subdectors you have to substitute the string "All" in the above
 302 function call with "SPD", "SDD", or "SSD". Normal users are, however, strongly
 303 encouraged to create the slow points for all subdetectors at once not touching
 304 the macro ITSDigitsToClusters.C. By default the so-called "Bari/Salerno
 305 reconstruction" of the pixel detectors is performed. In order to run the
 306 "Dubna reconstruction" of the pixel detectors you have to use the macro
 307 ITSDigitsToClustersDubna.C.
 308
 309
 310 7. Useful test macros
 311 ---------------------
 312
 313         Once you have created digits and slow points, you can now run some
 314 useful test macros. They can also be used as useful starting point to
 315 understand how to read hits, digits and points back from the galice.root
 316 file. The macros are listed below together with some help on their use. Some of
 317 the macros produce graphical output, so the suggestion is to run them
 318 interactively from within aliroot by then typing a command like ".x macro.C" at
 319 the aliroot prompt.
 320
 321 - new TBrower();
 322   This isn't a macro, so you just type it at the aliroot prompt. From here you
 323 can open up root files and view some of what they contain. This is done by
 324 cliking on a root file, and then cliking on the different "folders" withing
 325 that root file. Data kept in TTrees can be histogramed symply by double cliking
 326 on the appropreate data member. Other parts of the root file can also be
 327 inspected in a simular way, right butting cliking for example.
 328
 329 - SPDclusterTestDubna.C:
 330   This macro opens the galice.root file, reads the reconstructed points and
 331 plots the SPD resolution both for layer 1 and 2, in Z and Rphi
 332 direction following the Dubna model. Moreover, it creates the Root file
 333 SPD_his.root which contains some useful histograms and nt-uples which can be
 334 read back with the macro SPD_ntuple_dubna.C.
 335
 336 - SPDclusterTest.C:
 337   This macro opens the galice.root file, reads the reconstructed points and
 338 plots several distributions relative to the Bari/Salerno simulation of the SPD.
 339 Moreover, it creates the Root file SPD_his.root which contains some useful
 340 histograms 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
 344 screen.
 345
 346 - ITSsddanalysis.C:
 347   This macro opens the galice.root file, performs some analysis of the
 348 drift detectors and creates the Root output file SDD_histos_test.root. This
 349 output file can then be read by the macro ITSsddtest.C which create some
 350 PostScript file containing reference histograms.
 351
 352 - SSDrecpointTest.C:
 353   This macro opens the galice.root file, reads the reconstructed points and
 354 plots the SSD resolution both for layer 5 and 6, in Z and Rphi direction.
 355 Moreover, it creates the Root file SSD_his.root which contains some useful
 356 histograms 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
 360 prints them on the screen for all ITS modules. For each reconstructed point
 361 the following quantities are printed: the recpoint index in the module
 362 (0, 1, 2, ...), the X coordinate in the local reference system of the
 363 module, the Z coordinate in the local reference system of the module, three
 364 integers indicating the id numbers of the tracks contributing to that
 365 reconstructed point. Only positive numbers, of course, are real tracks.
 366 Negative numbers (-1 for SPD, -3 for SDD, and -2 for SSD) are just there to
 367 fill the vector of track id's associated to a given reconstructed point.
 368
 369 - ITSgeoplot.C:
 370   This macro opens the galice.root file, reads hits, digits and recpoint for
 371 SPD, SDD and SSD and plots them in the global reference system.
 372
 373 - ITSReadPlotData.C:
 374   This macros opens the galice.root file and then prompts the user for an ITS
 375 module identified by layer, ladder and detector or by the unique ID. That
 376 module is then searched for hits, digits and reconstructed points and they
 377 are plotted in the local reference frame of the module with different symbols.
 378
 379
 380 8. Occupancy
 381 ------------
 382
 383         ITS occupancy can be evaluated by the macro ITSOccupancy.C which opens
 384 the galice.root files, reads the number of digits for all subdetectors, and
 385 calculate the occupancy as the ratio of the "fired" digits over the total
 386 number of digits. Plots are also created showing the occupancy as a function of
 387 the Z coordinate along the beams' axis. In order to increase the speed of the
 388 calculation the macro is compilable. See the comments in the code about how to
 389 run it.
 390
 391
 392 9. Primary vertex
 393 -----------------
 394
 395         The ITS code contains a full 3D primary vertex finder. The relative
 396 class is AliITSVertex and an example of its use is contained in the test macro
 397 VertexMacro.C. The output of the primary vertex finder will eventually be
 398 incorporated in the tracking algorithms.
 399
 400
 401 10. ITS tracking version 1
 402 --------------------------
 403
 404         In order to run the TPC-ITS track matching version 1 you have to
 405 execute the script ITStestV1.sh. At the end of the procedure you can use the
 406 macro ITSPlotTracks.C to show plots of efficiency and track parameter
 407 resolution. An example of read-out of track parameters can be found in the
 408 macro ReadITSTracks.C. Specific questions about tracking V1 and its use/results
 409 must be addresses to Angela Badala' (angela.badala@ct.infn.it) and Giuseppe
 410 Pappalardo (giuseppe.s.pappalardo@ct.infn.it).
 411
 412
 413 11. ITS tracking version 2
 414 --------------------------
 415
 416      In order to run the TPC-ITS track matching version 2 you have two
 417 possibilities:
 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
 435 Specific questions about tracking V2 and its use/results must be addresses to
 436 Iouri Belikov (jouri.belikov@cern.ch).